diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index d861578..047748b 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -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.