commandkit/docs/roadmap/remediation.md

# Documentation reconciliation work

Status: all twelve documentation remediation units complete.

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](../policy/architecture.md)
to reconcile stale status statements and superseded plans. The
[documentation policy](../policy/documentation.md) 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](../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.

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

## D-01: reconcile the CLI proposal

Owner: [01-cli-plan.md](01-cli-plan.md).

- [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.

**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](02-dispatch.md).

- [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.

**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](03-backend.md).

- [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.

**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](04-facade.md).

- [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.

**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](initial-plan.md).

- [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.

**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](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.