From 2af1355b78d7e2b2f15b889ed1be474609ff6863 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 7 Oct 2026 17:06:10 +0000 Subject: [PATCH] Record required documentation reconciliation work --- docs/roadmap/remediation.md | 550 ++++++++++++++---------------------- 1 file changed, 216 insertions(+), 334 deletions(-) diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 20271eb..ae16b4f 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -1,338 +1,220 @@ -# Initial implementation review and remediation +# Documentation reconciliation work -Status: all ten findings addressed. +Status: required updates recorded; reconciliation pending. Date: 2026-10-07. -## Review baseline and scope - -Reviewed committed implementation at `85f44cd`, including the changes since -planning baseline `e5c361d`. The review covered production code, public contracts, -the internal adapter, integration helpers, maintained examples, and existing -behavioral tests against the accepted ADRs, architecture policy, and selected -[initial target](initial.md) and [implementation plan](implementation.md). - -These are static review findings. No tests were added or executed during this -review; prior completion notes are historical evidence, not a new validation -result. The triggering cases below describe those baseline code paths. The remediation -progress and validation evidence record the subsequent fixes. - -The findings below describe the review baseline. Completion is tracked here as -implementation fixes land. - -## Remediation progress - -- R-01 complete: required selectors are checked after scope selection; unrelated - scopes remain usable, and help describes conditional requiredness. - -- R-02 complete: inline document starts are recognized and native content is - retained, including block scalars. - -- R-03 complete: standard inspection handlers check cancellation before runtime - construction/acquisition, after acquisition, and before prepared report delivery. - -- R-04 complete: every help entry form finalizes report failures through the - common diagnostic presentation path once. - -- R-05 complete: validation header/record write failures retain `DeliveryError` - separately from acquisition failures and combined diagnostic-stream failures. - -- R-06 complete: zero outcomes normalize to success/0 and empty delivery state - normalizes to none without altering explicit domain outcomes. - -- R-07 complete: nil diagnostic writers are no-output entries, do not count as - delivery attempts, and cannot suppress cause presentation. - -- R-08 complete: unknown scopes and absent default app scopes report available - choices in standard scope order without runtime acquisition. - -- R-09 complete: PromptKit selector collisions are checked against installed - standard flags; profile-only `version` and custom `scope` selectors are usable. - -- R-10 complete: help inventories and usage discover all registered children, - including non-runnable metadata-only group chains. - -### Validation evidence - -Each fix includes a focused regression check and passed `go test ./...` before -its commit. The final combined suite also passed with caching disabled using -`go test -count=1 ./...`. Go formatting, diff whitespace, and affected local -Markdown links were checked. No live services or credentials were used. - -| Findings | Regression evidence | -| --- | --- | -| R-01, R-08 | [Configuration selection tests](../../config_test.go): scope-specific requiredness, help, unknown/default absent scopes, and callback avoidance. | -| R-02 | [Native framing tests](../../show_test.go) and existing aggregate show tests in [configkit_test.go](../../configkit_test.go). | -| R-03 | [Cancellation tests](../../cancellation_test.go): all four configuration operations, both definition operations, pre-acquisition cancellation, cancellation during successful acquisition, and completed aggregate validation prefix/diagnostics. | -| R-04, R-06, R-07, R-10 | [Public invocation tests](../../execute_external_test.go): every help entry form, independent writer errors, outcome defaults/domain preservation, no-output diagnostics, and metadata-only group discovery. | -| R-05 | [Validation tests](../../configkit_test.go): header/record failures, short writes, completed prefixes, independent acquisition errors, and combined stream failures. | -| R-09 | [PromptKit tests](../../promptkit_test.go): profile-only version selector, custom scope selector, typed delivery, and rejection of actual installed flag collisions. | - -## Architecture assessment - -The main architecture is implemented: - -- The root `commandkit` package owns public named types, opaque handles, - per-instance registration, typed bindings, outcomes, standard handlers, scope - assembly, and ConfigKit/PromptKit integration. -- `internal/cobra` owns Cobra/pflag operations behind a neutral internal bridge. - Public signatures do not expose the backend. Each invocation rebuilds backend - state; configuration and engine acquisition remain lazy. -- Standard families own their namespaces. Applications retain custom commands, - loaders, domain behavior, executable entry points, streams, and process exit. -- Scope capabilities and prompt/profile callbacks can be supplied independently. - Native YAML writers and public upstream inspection APIs are used. Profile - reports include `ExtraParams` without additional redaction. -- The module uses published dependencies rather than sibling internal packages - or local replacement directives. Simple and composed consumer examples exist. - -No package restructuring or additional implementation framework is recommended. -Diff, catalogs, JSON output, consumer migrations, publication tooling, and -concurrent-dispatch guarantees are deliberate deferrals, not missing initial -architecture. The issues below affect behavior within the implemented structure. - -## Findings and priority - -P1 means a supported invocation is blocked or its report content is corrupted. -P2 means a selected behavior or public contract is incomplete or unnecessarily -restricted. The historical findings below have been resolved as recorded above. - -| ID | Priority | Finding | Review category | -| --- | --- | --- | --- | -| R-01 | P1 | Required selectors block scopes to which they do not apply | Strengthened requirement; behavior defect | -| R-02 | P1 | Aggregate YAML framing inserts empty documents for inline start markers | Report correctness | -| R-03 | P2 | Standard inspection handlers omit cancellation boundary checks | Target gap | -| R-04 | P2 | Help shortcuts bypass diagnostic presentation | Target gap; inconsistent delivery | -| R-05 | P2 | Validation report failures omit `DeliveryError` | Public outcome contract gap | -| R-06 | P2 | Zero outcomes and empty delivery state are not normalized | Target gap | -| R-07 | P2 | Nil diagnostic writers are rejected despite the documented no-output behavior | Strengthened prohibition; contract inconsistency | -| R-08 | P2 | Unknown/default absent scopes omit available choices | Operator contract gap | -| R-09 | P2 | PromptKit selectors reserve flag names absent from installed commands | Strengthened prohibition | -| R-10 | P2 | Parent help omits registered groups containing only help metadata | Discovery gap | - -### R-01: enforce selector requiredness only where applicable - -**Evidence:** [selectors.go](../../selectors.go), `adaptContextSelector` and -`configInputFlags`; [binding.go](../../binding.go), `prepareInput`. - -All configuration operation commands receive every suite selector. Adaptation -copies `FlagMeta.Required` unchanged, and generic input preparation checks it -before scope selection or applicability checks. - -With an app-only required `--campaign` selector and app/PromptKit validation -scopes, `config validate --scope promptkit` fails because campaign is missing. -Supplying campaign instead fails because it does not apply to PromptKit. There -is no successful invocation for that independently supported scope. - -**Authority:** selected scope-specific routing in INT-01 and the initial -roadmap's selector section. A required selector for one scope does not authorize -requiring it for every other scope. - -**Remediation:** apply selector requiredness after selecting applicable scopes. -Keep ordinary custom-command required flags unchanged. Preserve requiredness -and applicability in help metadata without an unconditional preparation check. - -**Completion evidence:** an unrelated scope succeeds without the selector; an -applicable scope fails before acquisition when it is missing; `all` enforces -the requirements of its selected scopes; help remains available. - -### R-02: recognize inline YAML document-start markers - -**Evidence:** [show.go](../../show.go), `frameEffectiveYAML`. - -The framer recognizes only a line equal to `---` or starting with `--- #`. -A native document such as `--- {setting: value}\n` already has a valid document -start, but receives another opening marker and scope comment. The result starts -with an empty document followed by the actual value, so document count and scope -association are wrong even though execution returns success. - -**Authority:** [ADR 0007](../adr/0007-native-yaml-reports.md) and CFG-03 require -native YAML preservation and one framed document per selected scope. - -**Remediation:** recognize the document-start token with supported whitespace and -inline content. Preserve native bytes; a parallel decode/remarshal pipeline or -a new prohibition on valid native YAML is unnecessary. - -**Completion evidence:** aggregate decoding yields exactly one value per scope -for inline mapping/scalar starts, ordinary marked documents, unmarked documents, -and directive-bearing documents, while preserving native content. - -### R-03: check cancellation at standard inspection boundaries - -**Evidence:** `runConfigValidation`, `runConfigShow`, `runConfigSources`, and -`runConfigExplanation` in [validate.go](../../validate.go), -[show.go](../../show.go), [sources.go](../../sources.go), and -[explain.go](../../explain.go); definition handlers and engine loading in -[promptkit.go](../../promptkit.go). - -The handlers pass context to callbacks but do not check `Context.Err()` at their -own boundaries. With an already canceled context and a successful loader that -does not itself inspect context, configuration inspection can acquire and emit a -successful report. Direct PromptKit suite callbacks have the same exposure; -the engine helper also loads before delegating to context-aware named inspection. - -**Authority:** INV-01/OUT-01 and implementation Stage 5 explicitly select standard -handler checks at operation/acquisition boundaries, with supported cancellation -identity preserved. ADR 0005 classifies cancellation as operational failure. - -**Remediation:** check context at standard acquisition/report boundaries and -between aggregate acquisitions. Retain `context.Canceled`/deadline identity and -existing diagnostics/partial-report information. This does not require a -goroutine cancellation runner, interruption of callbacks, or new restrictions on -application-owned custom command semantics. - -**Completion evidence:** cancellation before acquisition and during acquisition -returns operational failure with the context cause, and prevents subsequent -standard work at the next boundary. Include an acquisition callback that ignores -context so the test protects CommandKit's responsibility. - -### R-04: finalize help outcomes through the presentation path - -**Evidence:** [execute.go](../../execute.go), `Execute`; [builtins.go](../../builtins.go), -`renderHelpOutcome`. - -Root help, non-runnable group help, and `--help`/`-h` return directly from -`renderHelpOutcome`. A failed help report write returns an operational outcome -but bypasses `present`, so it produces no operational diagnostic and cannot -record a simultaneous diagnostic-stream failure. Explicit `help PATH` goes -through the normal handler finalization and behaves differently. - -**Authority:** ADR 0005's diagnostic channels and INV-01's single presentation path. - -**Remediation:** route these outcomes through the same finalization path exactly -once, preserving existing report failure fields and lazy metadata behavior. - -**Completion evidence:** all help entry forms have consistent failure delivery; -broken report and diagnostic streams retain both errors without double delivery. - -### R-05: retain validation report errors in `DeliveryError` - -**Evidence:** [validate.go](../../validate.go), `runConfigValidation` and -`validationFailure`; [outcome.go](../../outcome.go), `Outcome`. - -Both validation header and record write failures call `validationFailure`, which -sets cause and incomplete-report state but never sets `DeliveryError`. With a -working diagnostic stream, the returned delivery error remains nil despite a -failed report write. Other standard report paths record this field. - -**Remediation:** distinguish report-writing failures from acquisition failures -and retain the former in `DeliveryError`, alongside the operational cause. -Do not misclassify every validation acquisition error as a delivery error. - -**Completion evidence:** header/record errors and short writes populate both -relevant error fields and retain incomplete-report state. Combined stdout/stderr -failures preserve both errors. Existing validation short-write checks inspect -the report cause but do not check its `DeliveryError`. - -### R-06: implement the selected outcome normalization - -**Evidence:** [execute.go](../../execute.go), `present`; [outcome.go](../../outcome.go). - -A handler returning `Outcome{}` retains an empty kind and delivery state because -`present` returns it unchanged when there are no diagnostics. An explicit domain -outcome with an omitted diagnostic state likewise retains an empty state. - -**Authority:** the selected outcome model, specified in implementation Stage 1, -normalizes a zero outcome to success/0 and an empty delivery state to -`DeliveryNone`. The latter is also stated in public GoDoc. - -**Remediation:** normalize these selected defaults during invocation coordination. -Preserve explicit domain classification, status, cause, and delivery information; -do not introduce inference of domain meaning from numeric status. - -**Completion evidence:** a zero handler outcome returns success/0/none; explicit -domain outcomes retain their values with an omitted delivery state normalized. - -### R-07: honor nil diagnostic writers as no-output diagnostics - -**Evidence:** [outcome.go](../../outcome.go), `Diagnostic` GoDoc; -[execute.go](../../execute.go), `present` and `hasErrorDiagnostic`. - -GoDoc says a nil `Write` function has no output. Coordination instead turns it -into an operational delivery failure with `diagnostic has no writer`. Thus an -otherwise successful result containing a zero diagnostic becomes a failure. -An error-severity diagnostic with a nil writer also suppresses automatic cause -presentation because deduplication checks severity alone. - -**Remediation:** treat nil writers as no-output entries, consistent with the -documented behavior, and exclude them from cause-presentation deduplication and -delivery-attempt bookkeeping. Requiring every entry to have a writer would be a -new API restriction requiring a deliberate decision. - -**Completion evidence:** nil writers do not change success/domain classifications -or suppress a real cause; active diagnostic writer failures remain observable. - -### R-08: include available scope choices in selection failures - -**Evidence:** [selectors.go](../../selectors.go), `selectConfigScopes`. - -Unknown selection returns only `unknown configuration scope NAME`. This also -occurs when only a PromptKit scope exists and the default `app` scope is absent. -The operator receives no available choices. - -**Authority:** CFG-01 expressly requires useful choices for unsupported scopes -and absent `app`; ADR 0009 requires available choices for unsupported selections. - -**Remediation:** include registered scope choices in stable scope order. Retain -the usage classification, default selection, strict aggregate coverage, and -pre-acquisition failure; do not silently select an alternative. - -**Completion evidence:** explicit unknown scope and omitted selection with absent -`app` identify available choices without invoking runtime callbacks. - -### R-09: reserve selector names for actual command collisions - -**Evidence:** [promptkit.go](../../promptkit.go), `normalizePromptKitSuite` and -`promptKitInputFlags`. - -Normalization unconditionally rejects a selector called `version`, even when -only profile inspection is supplied. `--version` is installed only on prompt -inspection, so there is no flag collision in a profile-only suite. It also -reserves `scope` despite not installing a scope-selection flag on definitions. - -**Authority:** capability-based family assembly and the agent policy's prohibition -on inventing restrictions. The selector rules in Stage 7, reused by Stage 12, -call for detecting collisions with standard local flags, not a reservation of -absent flags for hypothetical future use. - -**Remediation:** detect collisions against flags actually installed on commands -receiving the selector. Keep genuine collisions rejected. If a broader vocabulary -reservation is desired, record it as a new decision rather than a parser necessity. - -**Completion evidence:** a profile-only selector named `version` can register; -the same selector is rejected when it collides with installed prompt inspection. -Review the absent `scope` reservation against the same rule. - -### R-10: expose registered metadata groups in parent help - -**Evidence:** [command.go](../../command.go), `Group`; -[internal/cobra/parse.go](../../internal/cobra/parse.go), `buildTree` and -`usageTemplate`; pinned Cobra v1.10.1 `Command.IsAvailableCommand`. - -CommandKit accepts a non-runnable group with no children, and direct invocation -renders its help. However, parent help filters commands with Cobra's -`IsAvailableCommand`, which requires a runnable command or an available -descendant. A metadata-only group, or a chain containing only such groups, -disappears from the parent's command inventory despite being registered and -addressable. The custom template provides no additional help-topic inventory. - -**Authority:** HELP-01 and the architecture policy select discovery from registered -metadata; Cobra's availability defaults do not independently select a CommandKit -visibility restriction. - -**Remediation:** derive help inventory from CommandKit's declared commands, -including groups that expose help. Do not prohibit empty groups or add fake -application handlers solely to satisfy a backend visibility rule. - -**Completion evidence:** parent/root help discovers metadata-only groups and -their nesting; direct help works and leaves acquisition callbacks uninvoked. - -## Follow-up boundaries - -Address the behavioral findings with focused fixes and regression evidence at -the public invocation boundary or the narrow framing boundary as appropriate. -Update GoDoc/CLI references where needed to match the selected contracts. -Do not expand this work into upstream redaction changes, general framework -construction, new consumer mandates, blanket validation gates, or new concurrency -guarantees. Recheck the completed target after remediation; this review does not -claim that the existing tests establish these missing cases. +## 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). + +- [ ] 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. + +## D-02: reconcile dispatcher planning + +Owner: [02-dispatch.md](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](../consumers/guide.md), and current mechanics to the internal + overview. Preserve application migration work as separate future work. + +## D-03: reconcile backend planning + +Owner: [03-backend.md](03-backend.md). + +- [ ] 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). +- [ ] 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. + +## D-04: reconcile facade planning + +Owner: [04-facade.md](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. + +## D-05: close the preparation checklist + +Owner: [initial-plan.md](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. + +## D-06: clarify completed feature and implementation records + +Owners: [initial.md](initial.md) and [implementation.md](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. + +## D-07: correct the current CLI reference + +Owner: [cli.md](../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. + +## D-08: remove stale policy status statements + +Owners: [testing.md](../policy/testing.md) and [oss.md](../policy/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. + +## D-09: correct the internal bridge description + +Owner: [internal/overview.md](../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. + +## D-10: reconcile navigation and reading guidance + +Owners: [development.md](../development.md) and [README.md](../../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. + +## 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.