From f42aefe02d84e154855ac922173e6f367180929f Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 20 Oct 2026 00:30:53 +0000 Subject: [PATCH] Reconcile alias documentation with the completed implementation --- docs/consumers/guide.md | 4 +-- docs/roadmap/aliases.md | 67 ++++++++++++++++++++----------------- docs/roadmap/remediation.md | 14 ++++++-- 3 files changed, 50 insertions(+), 35 deletions(-) diff --git a/docs/consumers/guide.md b/docs/consumers/guide.md index 29ddc60..c0eaf13 100644 --- a/docs/consumers/guide.md +++ b/docs/consumers/guide.md @@ -120,8 +120,8 @@ conflicting rules are reported at installation. Identical rules are safe to contribute from reusable helpers. The [core example](../../examples/core) and [composed consumer](../../integrations/ckprompt/examples/composed) show complete maintained wiring with ordinary command behavior alongside aliases. The -[application-owned aliases roadmap](../roadmap/aliases.md) records the routing -contract; the [CLI reference](../cli.md#application-owned-aliases) describes +[Go declarations and GoDoc](../../command.go) own the public API contracts; +the [CLI reference](../cli.md#application-owned-aliases) owns routing and operator-visible behavior. ## ConfigKit scopes diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index 32100ea..dcf3b73 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -1,10 +1,12 @@ # Application-owned aliases -Status: implementation complete; core v0.3.0 release note prepared and -publication pending. OD-1 through OD-6 are resolved. This roadmap records the -target and selected behavior. The -[staged implementation plan](implementation.md) owns delivery sequencing and -stage-specific validation. +Status: implementation and [review remediation](remediation.md) complete; +core v0.3.0 release note prepared and publication pending. OD-1 through OD-6 +are resolved. This roadmap records the target and selected behavior. The +[completed implementation plan](implementation.md) preserves delivery sequencing +and stage-specific validation. Current contracts belong to the +[Go declarations and GoDoc](../../command.go) and +[CLI reference](../cli.md#application-owned-aliases). [ADR 0013](../adr/0013-application-alias-routing.md) records the accepted architectural ownership and shared installation decisions. @@ -38,19 +40,19 @@ Flag aliases likewise leave canonical flag definitions and typed bindings unchanged. This is one conceptual routing layer; its internal implementation cooperates with the existing parser to preserve token interpretation. -## Current baseline +## Preimplementation baseline -Core captures reusable `Command` declarations and installs them through `New` -and `App.Register`. Installation validates a batch before registry mutation. -Optional standard families own their installed root namespaces. Core routing -and the internal backend coordinate parsing, help, and execution through one -invocation lifecycle. +At the planning baseline, core captured reusable `Command` declarations and +installed them through `New` and `App.Register`. Installation validated a batch +before registry mutation. Optional standard families owned their installed root +namespaces. Core routing and the internal backend coordinated parsing, help, +and execution through one invocation lifecycle. -The current public model has no application alias layer. PromptKit already -exposes the collection catalog and smoke-test command used in the examples -below. `promptkit test` takes a `KIND` operand, including `all`; those values -are not registered child commands. These examples illustrate alternate routes -to existing capabilities; they do not introduce new PromptKit operations. +That public model had no application alias layer. PromptKit already exposed +the collection catalog and smoke-test command used in the examples below. +`promptkit test` took a `KIND` operand, including `all`; those values were not +registered child commands. The examples illustrate alternate routes to existing +capabilities; they do not introduce new PromptKit operations. The [CLI reference](../cli.md) owns current grammar. Options follow the complete command path, can be interspersed with operands, and use `--` to terminate @@ -66,8 +68,8 @@ API is needed. ### Installation types and composition -Introduce a common `Declaration` interface with an unexported marker method. -CommandKit supplies its implementations through public factories. `Command` +The delivered API has a common `Declaration` interface with an unexported marker +method. CommandKit supplies its implementations through public factories. `Command` represents canonical commands; a separate opaque `RoutingRule` represents aliases. Both satisfy `Declaration`: @@ -120,7 +122,7 @@ app, err := commandkit.New( ) ``` -These are planned APIs. Later registration uses the same model and validation. +These APIs are implemented. Later registration uses the same model and validation. Accept identical duplicate alias mappings as harmless, including when reusable helpers contribute them. Identity includes the alias kind, source, target, and @@ -513,11 +515,11 @@ A spelling such as `-color` follows short-option parsing; long aliases use the `--` prefix. Options still follow the complete command path, and `--` ends option parsing. -Correct explicit empty-value handling for both canonical short spellings and -aliases: `-c=` supplies an empty string, consistently with `--color=` and -`-c ""`. The current backend instead passes the literal string `"="` for `-c=`; -this delivery corrects that behavior. Likewise, `-v=` supplies an empty value -to boolean conversion and fails conversion. This correction preserves the +Explicit empty-value handling was corrected for both canonical short spellings +and aliases: `-c=` supplies an empty string, consistently with `--color=` and +`-c ""`. The preimplementation backend passed the literal string `"="` for `-c=`; +the delivered implementation corrects that behavior. Likewise, `-v=` supplies an +empty value to boolean conversion and fails conversion. This correction preserves the distinction between an omitted value and an explicitly supplied empty value. ### Flag help and diagnostics @@ -574,8 +576,10 @@ dynamic value completion remain future design work. ## Delivery and compatibility -The [implementation plan](implementation.md) defines the ordered work from the -current baseline, implementation choices, and evidence for the selected behavior. +The [completed implementation plan](implementation.md) records the ordered work +from the planning baseline, implementation choices, and stage evidence for the +selected behavior. The [review remediation](remediation.md) records subsequent +findings, corrections, and validation without restarting those stages. The delivered feature includes maintained consumer examples, GoDoc, CLI and consumer guidance, and internal documentation matching the implemented owners. @@ -583,11 +587,12 @@ Consumer guidance and release notes explain migration from `...Command` to `...Declaration`, including slice conversion, and the explicit short-option empty-value correction under the [release policy](../policy/release.md#versioning-and-compatibility). Nil and zero -declaration handling is specified by the implementation plan alongside the -existing invalid-zero and explicit-absence command contracts. +declaration handling is documented in the +[Go declarations and GoDoc](../../command.go) alongside the invalid-zero and +explicit-absence command contracts. -This delivery is complete when consumers can declare alternate command paths -and flag spellings with minimal wiring and invoke canonical behavior and help through -them while canonical ownership and binding semantics stay intact. Installation +The delivery goal was to let consumers declare alternate command paths +and flag spellings with minimal wiring and invoke canonical behavior and help +through them while canonical ownership and binding semantics stay intact. Installation rejects conflicts with canonical commands and applicable flags in either registration order. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 5837883..0f3e159 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -1,6 +1,6 @@ # Alias implementation review remediation -Status: in progress; completed issues are marked individually below. +Status: complete; R-1 through R-8 are addressed and marked individually below. ## Review scope and evidence @@ -289,7 +289,7 @@ Go 1.26.8. ## R-8: Reconcile the completed feature roadmap's historical descriptions -Status: open. Priority: P3. Category: documentation drift. +Status: complete. Priority: P3. Category: documentation drift. **Evidence:** [aliases.md](aliases.md) now declares implementation complete but still has a `Current baseline` section saying the public model has no alias @@ -308,3 +308,13 @@ restart completed implementation stages or rewrite published release notes. **Completion evidence:** Roadmap status, baseline, and API wording agree; consumer navigation identifies the canonical owners and the open remediation work is discoverable without claiming that these findings are already fixed. + +**Completed:** The feature roadmap now labels its preimplementation baseline +and former short-option behavior as historical, identifies the APIs as +implemented, and links this completed review separately from the completed +implementation stages. Consumer navigation points to GoDoc and the maintained +CLI contract. Published release records and completed stage evidence were left +unchanged. Local links and fragment destinations in all three affected documents +resolve, and whitespace checks pass. Final uncached offline suites passed on +Go 1.26.8: root with the workspace disabled, plus both integration modules and +their maintained examples in the existing workspace against the local core.