base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Record ReleaseKit adoption review findings

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-08 17:02:19 +00:00
parent c0c03285f7
commit 05a5bbb3e2
1 changed files with 97 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

341
docs/roadmap/remediation.md
View File

@@ -1,271 +1,124 @@
# Documentation reconciliation work
# ReleaseKit adoption review findings
Status: all twelve documentation remediation units complete.
Status: two remediation items pending; implementation not changed by this review.
Date: 2026-10-07.
Date: 2026-10-08.
## Purpose and authority
## Review scope and authority
This checklist replaces the completed code-remediation record with the
documentation update work agreed after the documentation audit. Use the current
implementation, accepted ADRs, and [architecture policy](../policy/architecture.md)
to reconcile stale status statements and superseded plans. The
[documentation policy](../policy/documentation.md) assigns canonical owners.
Reviewed CommandKit at `c0c03285f7beac3e96f1708b655c1eb2add35e79`, covering the
six adoption commits from `ada2021` through `c0c0328` against the
[ReleaseKit target](releasekit.md), [implementation plan](implementation.md),
and applicable policies. The previously completed documentation reconciliation
record remains available in
[Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/remediation.md).
Retain completed plans as clearly labeled historical records, preserve genuine
deferrals, and direct implemented contracts to their current owners. Exact Go
contracts belong in declarations and GoDoc; operator contracts belong in the
[CLI reference](../cli.md); package inventory belongs in the
[internal overview](../internal/overview.md). Roadmaps retain planning history,
implementation status, and future work. Historical proposals must not read as
current requirements.
The target adoption is present: a released Go tool selection, minimal source-only
profile, native launcher, fast subprocess tests, opt-in local publication
exercise, and implemented runbook/navigation. The commits do not change
production Go source or public declarations. Package dependency inspection found
no ReleaseKit, Goldmark, or `golang.org/x/mod` runtime dependency in the root
library or internal Cobra adapter. `scripts` contains external test files only.
Check each item when its documentation changes and review are complete.
The remaining findings concern test maintainability and ambiguous normative
wording. Neither establishes a missing production feature or a demonstrated
publication failure. Fix them within the existing target; do not add release
gates, new public contracts, or additional publisher machinery.
## D-01: reconcile the CLI proposal
## R-01: avoid making bootstrap command details test contracts
Owner: [01-cli-plan.md](01-cli-plan.md).
**Priority:** low. **Category:** code quality and unintended test constraints.
- [x] Replace the status claiming that no commands are implemented. Identify
implemented operations, superseded proposals, and deferred features.
- [x] Reconcile configuration scope defaults: every implemented configuration
operation defaults to `app`; aggregate validation/display requires explicit
`--scope all`. Retire the recommendation and rationale for validation defaulting
to `all`.
- [x] Replace singleton-repetition rejection with the selected last-occurrence
rule, including conversion of every supplied occurrence. Remove repetition
from the list of usage failures and label the old alternative as superseded.
- [x] Replace obsolete `--prompt-version` examples and descriptions with the
implemented `--version` spelling.
- [x] Retire the upstream redaction prerequisite for rich profile reports.
Record that effective `ExtraParams` is included using the current public
PromptKit API, without introducing additional redaction requirements.
- [x] Remove CommandKit mandates for application root paths, rejection of empty
config values, overlay interpretation, and propagation from one application
root into PromptKit. Values and presence reach application callbacks; those
callbacks own their interpretation and acquisition paths.
- [x] Reconcile aggregate validation output: completed scope records may already
have been written when a later acquisition or output fails. Retire the claim
that failure always produces no success report.
- [x] Reconcile native display syntax: `config show --format yaml` is accepted.
Link to the current framing contract rather than maintaining another report
reference.
- [x] Retire the proposed scope inventory fields for descriptions/default
indicators and the proposed source-table presentation as current expectations.
Link to implemented scope/source report shapes in the CLI reference.
- [x] Remove the claim that root `app --version` is supported. Reconcile identity
presentation with the implemented version command, optional text revision, and
explicit YAML fields.
- [x] Distinguish a missing definition ID operand from an explicitly blank ID:
missing is usage failure; blank values reach the owning inspection API and
produce operational results.
- [x] Remove promises of automatic shared dependency reuse or mandatory
acquisition coordination. Describe application-composed loading and optional
invocation-local caching as consumer integration patterns.
- [x] Keep diff and PromptKit catalogs explicitly deferred. Retire completed
dispatch/report implementation tasks and the obsolete profile-report upstream
dependency. Keep consumer migrations separate from library implementation.
- [x] Label superseded alternatives and dated sibling-checkout evidence clearly.
Replace duplicated current contracts with concise summaries and canonical links.
**Location:** [scripts/release_test.go](../../scripts/release_test.go),
`TestReleaseLauncherDelegatesPublication`, `assertNativeBootstrap`
(lines 222–260), and `fakeGo` (lines 363–397).
**Completion:** Retired completed CLI work and reconciled obsolete choices;
current contracts link to their owners and future work remains explicit.
The assertion compares the entire build argument vector, including flag order
and the absolute spelling of the output path. It also requires the two exact
`env GOHOSTOS` and `env GOHOSTARCH` query forms. The executable double supplies
only the first requested environment value, so a combined query would fail even
if the launcher parsed both host values correctly.
## D-02: reconcile dispatcher planning
The publication assertion similarly compares a complete argument vector,
requiring `--repo` to precede `--config` even though the upstream CLI accepts
either order before the version operand.
Owner: [02-dispatch.md](02-dispatch.md).
For example, reordering build flags, using a relative output path resolved from
the already verified repository root, or combining host queries can preserve
the selected behavior while failing these tests. The target requires native
bootstrap from the module-selected package, readonly metadata, the selected
toolchain/workspace settings, and the intended executable destination. It does
not make these equivalent command spellings permanent contracts.
- [x] Remove the pending status and claims that the registry, typed inputs,
constructors, binding/group APIs, handler signatures, and outcomes are absent
or unresolved.
- [x] Retire completed API design, implementation sequence, and evidence tasks.
Clearly label retained illustrations as historical; the public `Supplied`
type is now implemented.
- [x] Link current API usage to Go declarations/GoDoc and the
[consumer guide](../consumers/guide.md), and current mechanics to the internal
overview. Preserve application migration work as separate future work.
The [testing policy](../policy/testing.md#test-behavior-not-implementation) and
[agent policy](../policy/agents.md#implementation-discipline) call for protecting
those selected behaviors without elevating implementation details.
**Completion:** Replaced pending dispatcher work with a completed planning
record and links to implemented API, consumer, and internal owners.
Required work:
## D-03: reconcile backend planning
- [ ] Assert the required build settings, selected package, and resolved output
destination without requiring one incidental flag ordering or path spelling.
- [ ] Make host-query fixture handling and assertions reflect the requested
host values rather than requiring separate subprocess query forms. Keep the
fixture small; a complete Go command emulator is unnecessary.
- [ ] Check the publication command, option values, version operand, and
argument boundaries without fixing the order of independent options. Retain
the upstream requirement that options precede the version.
- [ ] Preserve checks for wrong native target, missing readonly mode, incorrect
package/output, workspace or toolchain mistakes, failed bootstrap, and
publication status/stream propagation.
Owner: [03-backend.md](03-backend.md).
Completion evidence: focused launcher checks still detect the selected failures
and accept an equivalent bootstrap form. This is a test correction, not a
requirement to refactor the working launcher or add a release-time check.
- [x] Remove claims that the module dependencies, adapter, and invocation behavior
are unimplemented. Link dependency facts to [go.mod](../../go.mod) and notices to
[attribution](../oss/attribution.md).
- [x] Remove the unresolved singleton-rejection discussion and reconcile it with
accepted repetition semantics.
- [x] Retire completed version-selection, translation, parsing/help, integration,
and evidence tasks. Link current behavior to its owners; retain backend
replacement and consumer adoption only as future work where applicable.
## R-02: clarify optional diagnostic validation in the runbook
**Completion:** Recorded the implemented backend, retired completed adaptation
tasks, and replaced singleton-rejection proposals with canonical references.
**Priority:** low. **Category:** potentially strengthened prohibition.
## D-04: reconcile facade planning
**Location:** [docs/release.md](../release.md), lines 76–77.
Owner: [04-facade.md](04-facade.md).
The instruction “Do not require a separate `check` before `publish` or repeat
the same suite” combines the intended rule against mandatory duplicate
validation with wording that can be read as prohibiting an operator from
voluntarily rerunning diagnostics.
- [x] Remove the pending status and claims that public declarations,
implementation packages, the adapter, and dependency versions do not exist.
- [x] Retire the illustrative `internal/engine` and `internal/command` layout as
an active implementation target. Link to the actual root and internal adapter
inventory without creating another maintained package reference.
- [x] Retire completed API/boundary design and documentation tasks. Preserve
legitimate future backend replacement considerations.
- [x] Keep old automated boundary-checker suggestions clearly historical or
optional; do not turn them into a new implementation requirement.
The [release policy](../policy/release.md#candidate-validation) permits a
validation-only diagnostic command and says it must not be a required
prerequisite before publication repeats the checks. Avoiding automatic duplicate
validation does not establish a blanket prohibition on optional diagnostic runs.
The launcher correctly delegates once; this finding concerns the runbook's
description, not its executable behavior.
**Completion:** Recorded facade completion, retired illustrative extra
packages, and preserved backend replacement and proportionate-check
considerations.
Required work:
## D-05: close the preparation checklist
- [ ] Say explicitly that `check` is optional for diagnosis and is not a
required step before `publish`.
- [ ] Scope the duplicate-validation instruction to the automated publication
workflow and configured additional checks. Preserve operator discretion to
investigate or rerun a check.
- [ ] Retain the single publication command and its own final-candidate suite;
do not add a required preliminary check or an extra confirmation.
Owner: [initial-plan.md](initial-plan.md).
Completion evidence: document review confirms the runbook distinguishes an
optional diagnostic action from a release requirement and agrees with the
existing policy. No implementation change is needed for this item.
- [x] Mark roadmap preparation and implementation-plan handoff complete.
- [x] Remove claims that exact declarations still await specification and that
the staged plan is the next deliverable. Link to the completed plan and current
API owners.
- [x] Check the completed final handoff item and label the preparation process
and recommended outline as historical planning material.
## Review evidence and limits
**Completion:** Closed the planning handoff, checked its final item, and
labeled the retained process and outline as historical.
- Read the adoption diffs, launcher/profile, new test functions and fixtures,
runbook, policy edits, historical navigation changes, and completion records.
- Inspected package dependencies with offline module access and confirmed the
production boundary and tests-only `scripts` package. Verified the committed
launcher mode and ignored local executable storage.
- Reviewed what the tests actually assert, including the local fixture's exact
tag-object comparison, candidate commit, one suite marker, clean worktree, and
endpoint-mismatch preflight behavior. The completion record reports earlier
successful default and opt-in runs; this review did not rerun those tests or
attempt publication.
- No other adoption gap, newly imposed release gate, public API expansion, or
runtime publication-code defect was identified in the reviewed changes.
## D-06: clarify completed feature and implementation records
Owners: [initial.md](initial.md) and the
[completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md).
- [x] Replace ownership statements written in future tense in the feature roadmap with
links to the existing GoDoc and CLI reference. Clearly identify detailed
specifications as the completed design baseline.
- [x] Label the implementation plan as a completed execution record and explain
that subsequent fixes were committed after its original completion.
- [x] Reconcile the statement that definition commands have no `--scope` flag:
they have no built-in configuration-scope selection, but application-declared
context selectors may use that name when it does not collide.
- [x] Preserve the explicitly labeled “At planning time” baseline as historical
context. Keep diff/catalog and other genuine deferrals visible; completed
design records must not become competing current API/CLI references.
**Completion:** Labeled feature specifications and staged instructions as
completed history, linked current owners, and recorded later code fixes and
selector-name behavior.
## D-07: correct the current CLI reference
Owner: [cli.md](../cli.md).
- [x] Correct aggregate YAML framing prose: scope comments can precede an inline
document-start marker; they are not always after the marker. Preserve the
native content and one YAML document per scope.
- [x] Qualify engine acquisition/construction wording. Standard handlers invoke
registered inspection callbacks; the bundled helper acquires an engine through
the application loader. Direct callbacks retain their own implementation and
lifecycle rather than guaranteeing fresh engine construction.
- [x] Describe the absence of execution/provider/credential operations as the
behavior of CommandKit's inspection path, preserving application callback
ownership of its effects.
- [x] Correct cancellation attribution: cancellation can be detected at
CommandKit's standard-handler boundaries as well as returned by PromptKit.
Preserve supported error identity and operational classification.
**Completion:** Corrected native marker/comment placement, qualified callback
and engine lifecycle claims, and reconciled cancellation attribution.
## D-08: remove stale policy status statements
Owners: [testing.md](../policy/testing.md) and [oss.md](../policy/oss.md).
- [x] Remove the testing policy's claim that there is currently no Go suite.
Keep concrete validation commands in the developer guide.
- [x] Remove the OSS policy's claim that Cobra/pflag are not incorporated and
that their notices still await introduction. Link to existing attribution;
keep version inventories out of the policy.
- [x] Preserve policy rules and upstream provenance while correcting local
implementation status. This work does not add testing or licensing gates.
**Completion:** Removed stale Go-suite and dependency-status claims while
preserving policy rules, adopted versions, and upstream provenance.
## D-09: correct the internal bridge description
Owner: [internal/overview.md](../internal/overview.md).
- [x] Correct the claim that application callbacks cross the adapter bridge.
Handler callbacks and typed invocation coordination remain in the root;
the adapter exchanges neutral metadata and parse results.
- [x] Keep inventory/mechanics here and normative responsibility boundaries in
the architecture policy.
**Completion:** Corrected neutral metadata/results flow and root callback
ownership; distinguished adapter help rendering from standard inspection
reports.
## D-10: reconcile navigation and reading guidance
Owners: [development.md](../development.md) and [README.md](../../README.md).
- [x] Route current implementation work to GoDoc, consumer guidance, CLI
reference, internal overview, and applicable ADRs/policies.
- [x] Label the older numbered roadmaps as completed/historical planning rather
than the active source of unresolved implementation decisions.
- [x] Update README roadmap labels/navigation to match the reconciled statuses.
Keep genuine future-work navigation discoverable without duplicating contracts.
**Completion:** Routed current work to canonical contracts and mechanics,
labeled completed planning records, and exposed genuine deferrals separately.
## D-11: remove temporary references from durable ADRs
Owners:
[ADR 0004](../adr/0004-standard-inspection-surface.md),
[ADR 0006](../adr/0006-command-grammar.md),
[ADR 0007](../adr/0007-native-yaml-reports.md),
[ADR 0008](../adr/0008-semantic-configuration-diff.md), and
[ADR 0009](../adr/0009-configuration-scopes.md).
- [x] Remove references to documents under `docs/roadmap` from these permanent
records, using durable references where appropriate.
- [x] Preserve accepted decision content and historical context. Link maintenance
must not change architectural decisions or manufacture new requirements.
- [x] Confirm that no ADR retains a temporary-roadmap reference after the edits.
**Completion:** Removed all temporary-roadmap links from ADRs through editorial
reference updates; accepted statuses, dates, and architectural choices remain
unchanged.
## D-12: review the reconciled documentation
- [x] Review every changed document against its canonical owner and current code.
Verify command spellings, defaults, outcomes, ownership, and report descriptions
affected by the corrections.
- [x] Check local links and heading targets, including links affected by retiring
sections. The audit found no unresolved local prose links or heading targets;
preserve that result.
- [x] Check diffs for whitespace, stale references, and claims that delivered
components are absent or superseded choices remain active requirements.
Historical baselines and explicitly labeled rejected alternatives remain valid.
- [x] Confirm that deferred features are still identified accurately and that
reconciliation introduces no new APIs, commands, guarantees, or consumer policy.
- [x] Record completion here and commit completed documentation units under the
local commit policy. Use document review for this prose work; do not add tests
or validation machinery solely to reconcile documentation.
**Completion:** Reviewed all changed documentation against current code and
owners; local links, headings, whitespace, deferrals, and preserved ADR/policy
scope checked.
## Final reconciliation evidence
All D-01 through D-12 items are complete. The completed records distinguish
historical planning from implemented contracts and genuine future work. Review
confirmed that only Markdown documents changed, accepted ADR metadata and
architectural choices were preserved, and policy source/version provenance was
retained. Local prose links and heading targets resolve; diff whitespace checks
passed. No Go tests were added or run for this documentation-only work.
Leave source publication, hosted delivery, binary assets, and other explicitly
deferred capabilities outside this remediation work. Update item status only
after the relevant correction and evidence are complete.