commandkit/docs/roadmap/remediation.md

Documentation reconciliation work

Status: reconciliation in progress.

Date: 2026-10-07.

Purpose 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 to reconcile stale status statements and superseded plans. The documentation policy assigns canonical owners.

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; package inventory belongs in the internal overview. Roadmaps retain planning history, implementation status, and future work. Historical proposals must not read as current requirements.

Check each item when its documentation changes and review are complete.

D-01: reconcile the CLI proposal

Owner: 01-cli-plan.md.

• Replace the status claiming that no commands are implemented. Identify implemented operations, superseded proposals, and deferred features.
• 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.
• 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.
• Replace obsolete --prompt-version examples and descriptions with the implemented --version spelling.
• 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.
• 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.
• 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.
• Reconcile native display syntax: config show --format yaml is accepted. Link to the current framing contract rather than maintaining another report reference.
• 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.
• Remove the claim that root app --version is supported. Reconcile identity presentation with the implemented version command, optional text revision, and explicit YAML fields.
• 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.
• Remove promises of automatic shared dependency reuse or mandatory acquisition coordination. Describe application-composed loading and optional invocation-local caching as consumer integration patterns.
• 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.
• Label superseded alternatives and dated sibling-checkout evidence clearly. Replace duplicated current contracts with concise summaries and canonical links.

Completion: Retired completed CLI work and reconciled obsolete choices; current contracts link to their owners and future work remains explicit.

D-02: reconcile dispatcher planning

Owner: 02-dispatch.md.

• Remove the pending status and claims that the registry, typed inputs, constructors, binding/group APIs, handler signatures, and outcomes are absent or unresolved.
• Retire completed API design, implementation sequence, and evidence tasks. Clearly label retained illustrations as historical; the public Supplied type is now implemented.
• Link current API usage to Go declarations/GoDoc and the consumer guide, and current mechanics to the internal overview. Preserve application migration work as separate future work.

Completion: Replaced pending dispatcher work with a completed planning record and links to implemented API, consumer, and internal owners.

D-03: reconcile backend planning

Owner: 03-backend.md.

• Remove claims that the module dependencies, adapter, and invocation behavior are unimplemented. Link dependency facts to go.mod and notices to attribution.
• Remove the unresolved singleton-rejection discussion and reconcile it with accepted repetition semantics.
• 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.

Completion: Recorded the implemented backend, retired completed adaptation tasks, and replaced singleton-rejection proposals with canonical references.

D-04: reconcile facade planning

Owner: 04-facade.md.

• Remove the pending status and claims that public declarations, implementation packages, the adapter, and dependency versions do not exist.
• 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.
• Retire completed API/boundary design and documentation tasks. Preserve legitimate future backend replacement considerations.
• Keep old automated boundary-checker suggestions clearly historical or optional; do not turn them into a new implementation requirement.

Completion: Recorded facade completion, retired illustrative extra packages, and preserved backend replacement and proportionate-check considerations.

D-05: close the preparation checklist

Owner: initial-plan.md.

• Mark roadmap preparation and implementation-plan handoff complete.
• 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.
• Check the completed final handoff item and label the preparation process and recommended outline as historical planning material.

Completion: Closed the planning handoff, checked its final item, and labeled the retained process and outline as historical.

D-06: clarify completed feature and implementation records

Owners: initial.md and implementation.md.

• 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.
• Label the implementation plan as a completed execution record and explain that subsequent fixes were committed after its original completion.
• 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.
• 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.

• 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.
• 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.
• Describe the absence of execution/provider/credential operations as the behavior of CommandKit's inspection path, preserving application callback ownership of its effects.
• 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 and oss.md.

• Remove the testing policy's claim that there is currently no Go suite. Keep concrete validation commands in the developer guide.
• 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.
• 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.

• 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.
• 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 and README.md.

• Route current implementation work to GoDoc, consumer guidance, CLI reference, internal overview, and applicable ADRs/policies.
• Label the older numbered roadmaps as completed/historical planning rather than the active source of unresolved implementation decisions.
• 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 0006, ADR 0007, ADR 0008, and ADR 0009.

• Remove references to documents under docs/roadmap from these permanent records, using durable references where appropriate.
• Preserve accepted decision content and historical context. Link maintenance must not change architectural decisions or manufacture new requirements.
• 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

• Review every changed document against its canonical owner and current code. Verify command spellings, defaults, outcomes, ownership, and report descriptions affected by the corrections.
• 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.
• 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.
• Confirm that deferred features are still identified accurately and that reconciliation introduces no new APIs, commands, guarantees, or consumer policy.
• 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.