From 3871d837489b9955998b362587a52b47282dc021 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 7 Oct 2026 18:32:44 +0000 Subject: [PATCH] Complete documentation reconciliation and final review --- docs/cli.md | 19 ++++++----- docs/internal/overview.md | 13 ++++--- docs/roadmap/implementation.md | 10 +++--- docs/roadmap/initial.md | 12 ++++--- docs/roadmap/remediation.md | 62 ++++++++++++++++++++++++---------- 5 files changed, 73 insertions(+), 43 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 34c57e2..1a44482 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -149,9 +149,10 @@ order, with a `# scope: NAME` comment at each document boundary. For ordinary block documents the comment follows the marker. When a native opening marker contains inline content, the comment precedes that marker so it does not interrupt the native value. Existing native markers and leading comments are -retained; documents without a marker receive one. Scope labels containing line control characters are quoted to keep them on -one comment line. A provider failure leaves the output stream empty. A rendering -or output failure may leave an aggregate prefix, and the outcome reports +retained; documents without a marker receive one. Scope labels containing line +control characters are quoted to keep them on one comment line. A provider +failure leaves the output stream empty. A rendering or output failure may leave +an aggregate prefix, and the outcome reports incomplete report delivery. ### List configuration sources @@ -230,12 +231,12 @@ serialized as `[]`. ## PromptKit definition inspection Applications can install prompt and profile inspection independently with -`RegisterPromptKit`. Each installed handler invokes its registered inspection -callback once with the caller's selection and context. The bundled -`NewPromptKitSuite` helper acquires an engine through the application loader and -asks PromptKit to inspect its captured named definition. The loader can construct -or reuse an engine; direct suite callbacks retain their own implementation and -lifecycle. +`RegisterPromptKit`. When acquisition is reached, the handler invokes its +registered inspection callback once with the caller's selection and context. +The bundled `NewPromptKitSuite` helper acquires an engine through the application +loader and asks PromptKit to inspect its captured named definition. The loader +can construct or reuse an engine; direct suite callbacks retain their own +implementation and lifecycle. CommandKit's inspection path does not execute prompts, contact model providers, or resolve provider credential values. Application acquisition and direct diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 0073154..e682120 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -17,17 +17,16 @@ The root lowers registered command metadata into the internal adapter's neutral bridge. The adapter returns raw parsed values and neutral syntax-failure data; the root prepares typed input, invokes application/standard handlers, and coordinates outcomes and diagnostic delivery. Application callbacks and their -supported error identity remain in the root's typed contracts rather than -crossing the backend bridge. Context and streams are passed to the adapter for -its parsing and help operations. +supported error identity are handled in the root through its typed contracts. +Context and streams are passed to the adapter for its parsing and help operations. ## `internal/cobra` This package owns the Cobra-specific command tree, argument/flag parsing, -and help rendering. It translates neutral command metadata and parsed values into a bridge -result consumed by the root package. It does not import `commandkit` and does not -own registry policy, public command declarations, provider loading, or standard -inspection report rendering. +and help rendering. It translates neutral command metadata and parsed values +into a bridge result consumed by the root package. It does not import `commandkit` +and does not own registry policy, public command declarations, provider loading, +or standard inspection report rendering. ## External implementation boundaries diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 6e12d36..56b5523 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -797,11 +797,11 @@ func RegisterPromptKit[C any](app *App, suite PromptKitSuite[C]) error bookkeeping. Configuration scope installation remains independent. 3. Accept ID as one required operand. Prompt alone has singleton `--version` (default empty). Both accept standard Config/Overlay selection, context-selector - bindings, and `--format text|yaml` (text default), plus help. No built-in configuration-scope selector is - installed for definition commands; a custom context selector can use the name - `scope` when it does not collide with an installed flag. Selector target is - `promptkit`; empty Scopes - or a list containing promptkit applies, independent of a config scope registry. + bindings, and `--format text|yaml` (text default), plus help. No built-in + configuration-scope selector is installed for definition commands; a custom + context selector can use the name `scope` when it does not collide with an + installed flag. Selector target is `promptkit`; empty Scopes or a list containing + promptkit applies, independent of a config scope registry. Other explicit targets are miswired metadata at registration. 4. Reuse Stage 7's input/context creation and input-check rules. Missing ID is usage; a supplied blank/unknown/ambiguous selection reaching the owning API is diff --git a/docs/roadmap/initial.md b/docs/roadmap/initial.md index 21c707a..03946ac 100644 --- a/docs/roadmap/initial.md +++ b/docs/roadmap/initial.md @@ -46,9 +46,9 @@ owns current package inventory and mechanics. | Compare safe semantic snapshots with sensitivity union and explicit coverage gaps when comparison is enabled. | [ADR 0008](../adr/0008-semantic-configuration-diff.md) | deferred DIFF-01 | | Declare scope capabilities; default to `app`; preserve the meaning and coverage of `all`; order scopes consistently. | [ADR 0009](../adr/0009-configuration-scopes.md) | CFG-01–05, INT-01 | -The [four earlier roadmaps](01-cli-plan.md), [dispatcher proposal](02-dispatch.md), -[backend proposal](03-backend.md), and [facade proposal](04-facade.md) supply design -evidence. Carry these controlling corrections into implementation: +The [CLI planning record](01-cli-plan.md), [dispatcher record](02-dispatch.md), +[backend record](03-backend.md), and [facade record](04-facade.md) preserve the +review history. These corrections were selected for the initial target: - Singleton flags use the last supplied occurrence, including mixed `--name value` and `--name=value` spellings. Repeatable flags accumulate in order. @@ -58,8 +58,10 @@ evidence. Carry these controlling corrections into implementation: - Partial capabilities remain useful; neither scopes nor families need every verb. - Preparing every selected view before report output is a `config show` requirement. Other operations have their own output timing. -- The older acquisition graph, shared-load mandates, selector inheritance rules, - illustrative Go declarations, and exact report layouts remain proposals. +- The older acquisition graph and shared-load mandates were superseded by + application-composed callbacks. Exact declarations, selector behavior, and + report layouts are owned by GoDoc and the CLI reference. Old illustrations + remain historical evidence. ## Initial delivery scope diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 76c7e74..c32821b 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -1,6 +1,6 @@ # Documentation reconciliation work -Status: reconciliation in progress. +Status: all twelve documentation remediation units complete. Date: 2026-10-07. @@ -68,7 +68,8 @@ Owner: [01-cli-plan.md](01-cli-plan.md). - [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. +**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 @@ -84,7 +85,8 @@ Owner: [02-dispatch.md](02-dispatch.md). [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. +**Completion:** Replaced pending dispatcher work with a completed planning +record and links to implemented API, consumer, and internal owners. ## D-03: reconcile backend planning @@ -99,7 +101,8 @@ Owner: [03-backend.md](03-backend.md). 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. +**Completion:** Recorded the implemented backend, retired completed adaptation +tasks, and replaced singleton-rejection proposals with canonical references. ## D-04: reconcile facade planning @@ -115,7 +118,9 @@ Owner: [04-facade.md](04-facade.md). - [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. +**Completion:** Recorded facade completion, retired illustrative extra +packages, and preserved backend replacement and proportionate-check +considerations. ## D-05: close the preparation checklist @@ -128,7 +133,8 @@ Owner: [initial-plan.md](initial-plan.md). - [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. +**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 @@ -146,7 +152,9 @@ Owners: [initial.md](initial.md) and [implementation.md](implementation.md). 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. +**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 @@ -166,7 +174,8 @@ Owner: [cli.md](../cli.md). 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. +**Completion:** Corrected native marker/comment placement, qualified callback +and engine lifecycle claims, and reconciled cancellation attribution. ## D-08: remove stale policy status statements @@ -180,7 +189,8 @@ Owners: [testing.md](../policy/testing.md) and [oss.md](../policy/oss.md). - [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. +**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 @@ -192,7 +202,9 @@ Owner: [internal/overview.md](../internal/overview.md). - [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. +**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 @@ -205,7 +217,8 @@ Owners: [development.md](../development.md) and [README.md](../../README.md). - [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. +**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 @@ -222,21 +235,36 @@ Owners: 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. +**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. +- [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. -- [ ] Check local links and heading targets, including links affected by retiring +- [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. -- [ ] Check diffs for whitespace, stale references, and claims that delivered +- [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. -- [ ] Confirm that deferred features are still identified accurately and that +- [x] 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 +- [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.