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](../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 [implementation.md](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).

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

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