base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Retire completed roadmaps and preserve deferred work

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-09 04:04:24 +00:00
parent 6bc37e7ba6
commit 54750dd957
15 changed files with 117 additions and 2841 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

@@ -22,20 +22,13 @@ The [consumer guide](docs/consumers/guide.md) links to two maintained examples:
- [Consumer guide](docs/consumers/guide.md)
- [Internal package overview](docs/internal/overview.md)
- [Maintainer release procedure](docs/release.md)
- [Computational efficiency roadmap](docs/roadmap/performance.md)
- [Performance implementation record](docs/roadmap/implementation.md)
- [Architecture policy](docs/policy/architecture.md)
- [Policy provenance](docs/policy/meta.md)
## Planning history and future work
## Future work and history
- [Initial delivery and deferred capabilities](docs/roadmap/initial.md)
- [Completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md)
- [Completed ReleaseKit implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/implementation.md)
- [Historical CLI planning](docs/roadmap/01-cli-plan.md)
- [Completed dispatcher planning](docs/roadmap/02-dispatch.md)
- [Completed backend planning](docs/roadmap/03-backend.md)
- [Completed facade planning](docs/roadmap/04-facade.md)
- [Deferred capabilities and proposals](docs/roadmap/deferred.md)
- [Completed planning and implementation records in Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap)
CommandKit is licensed under the [LGPL v3.0 or later](COPYRIGHT).

25
docs/development.md
View File

@@ -1,7 +1,7 @@
# Developing CommandKit
CommandKit currently contains adopted repository policies, accepted architectural
decisions, implementation plans, identity and outcome primitives, typed command
decisions, identity and outcome primitives, typed command
declarations, an instance-owned registry, a Cobra-backed routing and parsing
adapter, public `App.Execute` coordination, and generated help/version commands.
Configuration suite registration, scope discovery, ConfigKit validation and
@@ -52,23 +52,20 @@ canonical documentation owners.
| Dispatcher, registration, or typed inputs | [Command declarations](../command.go), [bindings](../binding.go), [invocation](../execute.go), and [ADR 0001](adr/0001-command-dispatch-and-inputs.md) |
| Backend integration | [Internal overview](internal/overview.md), [adapter implementation](../internal/cobra/parse.go), and [ADR 0002](adr/0002-cobra-backend.md) |
| Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0003](adr/0003-public-facade.md), and the architecture policy |
| Deferred capabilities and delivery scope | [Initial feature target](roadmap/initial.md#deferred-capability-targets) and [explicit deferrals](roadmap/initial.md#explicit-deferrals) |
| Initial planning history | [CLI](roadmap/01-cli-plan.md), [dispatcher](roadmap/02-dispatch.md), [backend](roadmap/03-backend.md), [facade](roadmap/04-facade.md), and [completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md) |
| Release tooling | [Maintainer release procedure](release.md) and [ReleaseKit upgrade roadmap](roadmap/releasekit.md) |
| Performance work | [Computational efficiency roadmap](roadmap/performance.md) and [performance implementation record](roadmap/implementation.md) |
| Deferred capabilities and proposals | [Deferred work](roadmap/deferred.md) |
| Completed planning and implementation history | [Retired records in Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap) |
| Release tooling | [Maintainer release procedure](release.md) |
| Performance maintenance | [Internal overview](internal/overview.md), existing benchmarks, and [deferred efficiency work](roadmap/deferred.md#possible-further-efficiency-work) |
| Licensing or incorporated material | [Project grant](../COPYRIGHT), [license texts](../LICENSE), and [attribution](oss/attribution.md) |
| Policy provenance | [Policy provenance](policy/meta.md) |
Read all applicable rows for cross-cutting work. Go declarations and GoDoc own
current exported contracts; the CLI reference owns operator behavior. The
initial numbered roadmaps are completed planning records. The
[maintainer release procedure](release.md) owns current release operations.
The completed ReleaseKit adoption records remain available in Git history. The
[performance roadmap](roadmap/performance.md) and its implementation record
own the efficiency target and evidence. Retained illustrations and historical
staged instructions are not current API references or assignments to restart
implementation. Future capabilities remain explicitly identified in their
feature roadmaps.
Completed roadmaps and implementation evidence remain available in Git history;
they are not assignments to restart completed work. The
[deferred-work record](roadmap/deferred.md) preserves future capability targets
and unselected proposals separately from current contracts.
## Documentation validation
@@ -87,8 +84,8 @@ git diff --cached --check -- '*.md' COPYRIGHT
These commands do not cover untracked files. Review their contents and whitespace
before staging, or use the staged check after staging only the intended files.
Sibling-checkout evidence links in the CLI planning record are historical review
references, not build dependencies. Implemented contracts belong in CommandKit
Sibling-checkout references in retired planning records are historical review
evidence, not build dependencies. Implemented contracts belong in CommandKit
under their canonical owners.
Run `go test ./...` from the repository root to compile the module and run its

7
docs/policy/agents.md
View File

@@ -2,7 +2,7 @@
**Base Policy Version:** 1.3
**Last Updated**: 2026-10-06
**Last Updated**: 2026-10-08
**Upstream Source:** [agents.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md)
@@ -56,8 +56,9 @@ invariant, not from the convenience of the selected implementation. Explain the
specific failure it prevents and why a less restrictive implementation cannot
satisfy the contract.
The CLI roadmap distinguishes accepted choices from remaining proposals. Do not
approve proposed commands, grammar, statuses, or illustrative API declarations
The [deferred-work record](../roadmap/deferred.md) distinguishes future proposals
from accepted contracts. Do not approve proposed commands, grammar, statuses, or
illustrative API declarations
merely by repeating them in implementation or tests. Cobra/pflag defaults do not
independently establish CommandKit contracts.

10
docs/policy/architecture.md
View File

@@ -2,7 +2,7 @@
**Base Policy Version:** 1.3
**Last Updated**: 2026-10-07
**Last Updated**: 2026-10-08
**Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
@@ -181,10 +181,10 @@ logging system, hosted service, or standalone application. Shared vocabulary is
recommended for application-owned commands; their names and domain behavior
remain application choices.
The [CLI roadmap](../roadmap/01-cli-plan.md) distinguishes accepted operator
choices from remaining command and grammar proposals. Backend defaults and
incidental consumer behavior do not establish new contracts. A replacement
backend must preserve published CLI behavior or follow deliberate compatibility
Accepted ADRs and current CLI/API owners define selected contracts; the
[deferred-work record](../roadmap/deferred.md) preserves remaining proposals.
Backend defaults and incidental consumer behavior do not establish new contracts.
A replacement backend must preserve published CLI behavior or follow deliberate compatibility
changes under the release policy.
Base restrictions and guarantees on selected requirements. Configuration and

133
docs/roadmap/01-cli-plan.md
View File

@@ -1,133 +0,0 @@
# CommandKit CLI planning record
Status: initial CLI planning complete; remaining proposals deferred.
Original review: 2026-10-06. Reconciled: 2026-10-07.
## Purpose and current owners
This document preserves the initial command-suite review and identifies remaining
future work. Its completed implementation tasks and obsolete contract drafts
have been retired. The [initial feature target](initial.md) and
[completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md)
record delivery scope and execution history.
The [CLI reference](../cli.md) owns implemented commands, syntax, formats, and
outcomes. Go declarations and GoDoc own exact exported APIs; the
[consumer guide](../consumers/guide.md) explains integration. Accepted ADRs own
architectural rationale, and the [architecture policy](../policy/architecture.md)
owns responsibility boundaries. This planning record does not define a second
current command contract.
## Completed initial scope
| Planning area | Delivered boundary and current reference |
| --- | --- |
| Discovery and identity | Generated [help](../cli.md#help) and [version reporting](../cli.md#version). |
| Configuration inspection | [Scope discovery](../cli.md#configuration-scopes), validation, native display including aggregate display, sources, and path explanation. |
| PromptKit integration | Engine configuration scope and optional [named prompt/profile inspection](../cli.md#promptkit-definition-inspection), registered independently. |
| Common command infrastructure | Instance registry, typed inputs, presence, routing, and outcomes; see the [consumer guide](../consumers/guide.md) and [internal overview](../internal/overview.md). |
CommandKit owns its standard families. Applications retain custom commands,
source selection, schema/domain work, acquisition callbacks, and executable
lifecycle. Migration of existing applications remains separate work; the
maintained [simple](../../examples/simple/README.md) and
[composed](../../examples/composed/README.md) consumers demonstrate library usage.
## Superseded proposal choices
The following entries are historical reconciliation notes. They summarize why
older drafts no longer describe the selected implementation; use the linked
owner for the complete current contract.
| Earlier proposal, now superseded | Selected result and owner |
| --- | --- |
| Bare validation defaults to every scope | Configuration operations default to `app`; aggregate validation/display is explicit. See [configuration scopes](../cli.md#configuration-scopes). |
| Reject repeated singleton flags | Last occurrence supplies the value; every supplied occurrence is converted. See [registered syntax](../cli.md#registered-command-syntax). |
| Prompt inspection uses `--prompt-version` | It uses `--version`. See [definition inspection](../cli.md#promptkit-definition-inspection). |
| Rich profile reports await an upstream provider-parameter redaction API | Current public inspection supplies effective `ExtraParams`, included without additional redaction requirements. See [profile reports](../cli.md#promptkit-definition-inspection). |
| Fix application root/overlay interpretation in CommandKit, reject empty config values, and derive PromptKit selection from one prescribed root | Values and presence are passed to application callbacks, which interpret them. See [scope integration](../consumers/guide.md#a-configuration-scope) and [selection declarations](../../config.go). |
| Validation failure always emits no success report | Completed scope records can precede a later failure. See [validation](../cli.md#validate-configuration). |
| Native display has no format flag | `config show --format yaml` is accepted. See [effective display](../cli.md#show-effective-configuration) for syntax and framing. |
| Scope inventory includes description/default fields; sources use a prescribed table | The selected report shapes are defined in [scope discovery](../cli.md#configuration-scopes) and [source inventory](../cli.md#list-configuration-sources). |
| Root `app --version` is a standard entry point | The delivered entry point is `app version`; text can include revision and YAML has explicit identity fields. See [version reporting](../cli.md#version). |
| Blank definition IDs are usage failures | Missing operands are usage failures; explicitly blank values reach owning inspection and produce operational results. See [definition inspection](../cli.md#promptkit-definition-inspection). |
| CommandKit automatically coordinates shared loads and dependencies | Applications compose acquisition and may use invocation-local caches. See [consumer integration](../consumers/guide.md) and the composed example. |
The selected namespace/resource-first grammar, capability-based family assembly,
application-focused default version, native aggregate YAML, and initial JSON
deferral remain reflected in the accepted ADRs and delivered target. The earlier
alternatives are review history, not unresolved implementation choices.
## Deferred work and remaining proposals
### `config diff`
Semantic comparison is deferred pending supported upstream safe snapshot APIs.
[ADR 0008](../adr/0008-semantic-configuration-diff.md) owns its accepted comparison
and sensitivity-gap decisions. The [deferred capability target](initial.md#deferred-capability-targets)
records dependencies.
Exact comparison selection syntax and report layout remain future design work.
The original proposal considered separate right-side root/overlay selection,
shared versus independent domain context, and an optional assertion mode. None
of those flags or modes is installed or promised by the initial implementation.
CommandKit should use owning public APIs rather than compare rendered YAML or
implement another configuration engine.
### PromptKit catalogs
Prompt/profile listing is deferred pending public catalog APIs. Catalog resource
names and enumeration/report details can be specified when supported APIs exist;
CommandKit does not enumerate by reparsing PromptKit configuration YAML. See the
[deferred capability target](initial.md#deferred-capability-targets).
### Other proposals outside the initial delivery
Configuration mutation, reloadable export, credential diagnostics, live provider
probes, shell completion, exhaustive field-origin inventories, generic value
assignment, additional component identity registration, and domain artifact
catalogs remain outside the initial scope. Their inclusion requires a concrete
operator purpose and an appropriate ownership/behavior decision. JSON remains
deferred without a commitment to add it.
Execution, rendering, serving, and session operations remain application-owned.
Shared vocabulary is guidance under [ADR 0006](../adr/0006-command-grammar.md),
not a reserved implementation contract for every consumer.
Application migrations should replace divergent standard paths and update
subprocess consumers and documentation for intentional breaking changes. The
original review considered Scriptorium/Notarius followed by Audita/Narratio;
that ordering is historical evidence, not a completed migration or mandatory
adoption sequence. Future capabilities can be adopted independently.
## Historical review evidence
The initial review on 2026-10-06 compared Audita's `print-effective`, Notarius's
`effective`, and Narratio/Scriptorium's `show`; inconsistent scope/source reports;
repeated dispatch/loading/report plumbing; and differing help, syntax, and status
conventions. Those differences informed the shared standard, rather than imposing
compatibility requirements. Narratio's subprocess interpretation of application
statuses also demonstrated the need to coordinate consumer adoption.
Evidence sources, relative to this roadmap in the sibling workspace checkouts:
- [Audita CLI contract](../../../audita/docs/cli.md) and
[configuration parsing](../../../audita/internal/cli/config_input.go).
- [Narratio CLI contract](../../../narratio/docs/cli.md),
[configuration inspection](../../../narratio/internal/app/config_commands.go),
and [comparison](../../../narratio/internal/app/config_diff.go).
- [Notarius CLI contract](../../../notarius/docs/cli.md) and
[configuration commands](../../../notarius/internal/cli/configkit_commands.go).
- [Scriptorium CLI contract](../../../scriptorium/docs/cli.md),
[application inspection](../../../scriptorium/internal/adapter/cli/config.go),
and [framework inspection](../../../scriptorium/internal/adapter/cli/framework_config.go).
- [ConfigKit inspection API](../../../ConfigKit/inspection.go),
[source records](../../../ConfigKit/records.go), and
[configuration contract](../../../ConfigKit/docs/config.md).
- [PromptKit configuration inspection](../../../promptkit/configuration_inspection.go)
and [consumer guide](../../../promptkit/docs/consumers/pkg-promptkit.md).
These links identify sibling-checkout evidence from that review. They are not
build dependencies, permanent implementation references, or claims about the
applications' present adoption status. Current contracts are owned in CommandKit.

57
docs/roadmap/02-dispatch.md
View File

@@ -1,57 +0,0 @@
# CommandKit dispatcher planning record
Status: initial dispatcher implementation complete.
Original planning: 2026-10-06. Reconciled: 2026-10-07.
## Authority and current owners
[ADR 0001](../adr/0001-command-dispatch-and-inputs.md) owns the dispatcher,
registry, and typed-input decisions and rationale. The
[architecture policy](../policy/architecture.md) owns responsibility boundaries.
This document records completion of the initial dispatcher design; the
[completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md)
preserves its execution history.
The registry, typed inputs, command/group APIs, invocation coordination, and
outcomes are implemented. Their exact contracts are owned by Go declarations
and GoDoc, rather than the early illustrations formerly maintained here.
| API area | Current owner |
| --- | --- |
| Application construction and registration | [App/New](../../app.go) and [App.Register](../../registry.go) |
| Typed command declarations, groups, and presence | [CommandSpec, NewCommand, Group, WithChildren, Supplied](../../command.go) |
| Typed flag and operand bindings | [Binding helpers](../../binding.go) |
| Invocation and result delivery | [App.Execute](../../execute.go), [Invocation/Streams](../../identity.go), and [Outcome](../../outcome.go) |
| Standard integration registration | [Configuration suite](../../config.go) and [PromptKit suite](../../promptkit.go) |
The [consumer guide](../consumers/guide.md) explains assembly and callback usage.
The [CLI reference](../cli.md) owns syntax and operator behavior; the
[internal overview](../internal/overview.md) owns implemented package mechanics.
## Completed design and evidence
The initial work delivered instance registration, composable nested groups,
typed handlers and bindings, presence-aware input, capability-based installation,
lazy acquisition, and distinct shared/domain outcomes. The original `Supplied`
illustration is now a public declaration; application-specific restore inputs
remain consumer examples rather than proposed CommandKit types.
The [simple](../../examples/simple/README.md) and
[composed](../../examples/composed/README.md) consumers demonstrate the API with
configuration inspection and a custom session command. The completed plan
records behavioral evidence for routing, ownership conflicts, help, invocation
state, cancellation, output failures, and domain outcome preservation.
Completed constructor/binding/outcome design tasks and implementation assignments
have been retired from this roadmap. Concurrent dispatch remains outside the
initial target under the [feature roadmap](initial.md#explicit-deferrals).
## Remaining adoption work
Applications can migrate their routers and repeated standard handlers to the
implemented API, update documentation and subprocess consumers for breaking
changes, and retain their domain command behavior. Migration is separate from
library completion; this record does not claim that the sibling applications
have adopted CommandKit. Deferred standard capabilities are tracked in the
[feature roadmap](initial.md#deferred-capability-targets).

54
docs/roadmap/03-backend.md
View File

@@ -1,54 +0,0 @@
# CommandKit backend planning record
Status: initial Cobra/pflag backend implemented.
Original planning: 2026-10-06. Reconciled: 2026-10-07.
## Authority and current owners
[ADR 0002](../adr/0002-cobra-backend.md) records the backend selection and rationale;
[ADR 0003](../adr/0003-public-facade.md) records its isolation behind the public
facade. The [architecture policy](../policy/architecture.md) owns boundaries.
Cobra/pflag dependencies, the internal adapter, routing/parsing, generated help,
and invocation integration are implemented. Selected dependency versions belong
in [go.mod](../../go.mod); license and notice entries belong in
[attribution](../oss/attribution.md). The former dependency-selection and
adapter-construction tasks are complete.
Current mechanics belong in the [internal overview](../internal/overview.md),
with adapter contracts and implementation in
[internal/cobra](../../internal/cobra/parse.go). The root owns registration,
typed input preparation, invocation coordination, standard handlers, and reports.
The [CLI reference](../cli.md) owns observable syntax and presentation.
## Completed adaptation and evidence
The initial implementation translated registered metadata through a neutral
bridge, rebuilt backend state for each invocation, and adapted backend routing,
local flags, operands, presence, help, and syntax failures to selected semantics.
The [completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md)
records these stages and their checks.
The earlier discussion of rejecting repeated singletons was superseded by the
accepted last-occurrence rule in [ADR 0006](../adr/0006-command-grammar.md).
Detailed conversion, repetition, and terminator behavior belongs in
[registered command syntax](../cli.md#registered-command-syntax).
The delivered integrations expose native ConfigKit/PromptKit reports through the
root, as recorded in the [feature target](initial.md). Backend selection creates
no parallel configuration engine or public backend-specific provider contract.
Completed parsing/help, provider integration, attribution, and evidence tasks
have been retired from this roadmap.
## Future maintenance and adoption
A later backend replacement remains a maintenance possibility governed by the
accepted public/CLI boundary and [release policy](../policy/release.md). A second
backend or generalized selection framework is outside the initial delivery.
Application migrations and updates to their documentation/subprocess consumers
remain separate work. They can use the [consumer guide](../consumers/guide.md)
and maintained examples; this record does not claim migration completion.
Other deferred capabilities remain in the
[feature roadmap](initial.md#explicit-deferrals).

56
docs/roadmap/04-facade.md
View File

@@ -1,56 +0,0 @@
# CommandKit facade planning record
Status: initial public facade and internal adapter implemented.
Original planning: 2026-10-06. Reconciled: 2026-10-07.
## Authority and current owners
[ADR 0003](../adr/0003-public-facade.md) owns the facade/adapter decision and its
rationale. The [architecture policy](../policy/architecture.md) owns normative
dependency and public-surface boundaries.
Root public declarations, private implementation state, and the internal
Cobra/pflag adapter exist. Exact contracts belong in Go declarations and GoDoc;
the [consumer guide](../consumers/guide.md) explains their use. The
[internal overview](../internal/overview.md) owns the actual package inventory,
and [go.mod](../../go.mod) owns dependency versions.
The [initial target](initial.md) and [completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md)
record the chosen layout and delivered API work. The initial implementation
requires no further facade package construction.
## Retired package exploration
Early illustrations considered an `internal/engine` for registration and
coordination and an `internal/command` for shared declarations, with a root
limited mainly to forwarding. Those were possible layouts, not required
packages, and are superseded as active implementation targets.
The selected root contains straightforward private implementation alongside its
public contracts; the internal adapter isolates backend machinery. Consult the
internal overview for current responsibilities instead of treating the early
package table as an inventory or expansion checklist.
## Completed boundary work
The initial work established root-owned public named types and handles, selected
integration dependencies, typed callback/value semantics, backend-neutral bridge
metadata/results, and adaptation of backend-owned failures. API design,
package-selection, and initial documentation tasks are complete.
The completed plan records review of public declarations and dependency direction,
plus consumer behavior through the real adapter. Earlier suggestions to adopt
ConfigKit/ReleaseKit-style automated export scanners were validation possibilities,
not a requirement to add a checker. Future automation remains a maintenance
choice under the [testing policy](../policy/testing.md) when its protection
justifies its cost.
## Future backend replacement
A later replacement remains possible behind the accepted boundary. It must
preserve the public API and selected CLI behavior or follow the
[release policy](../policy/release.md) for deliberate incompatible changes.
Signature isolation alone does not prove behavioral compatibility; parsing,
help, diagnostic delivery, reports, and outcomes remain relevant to that review.
Replacement and public backend selection are outside the initial delivered scope.

94
docs/roadmap/deferred.md Normal file
View File

@@ -0,0 +1,94 @@
# Deferred work
Status: retained future work and unselected proposals; no implementation schedule.
## Purpose and authority
Completed initial delivery, performance, ReleaseKit upgrade, and remediation
records have been retired. This document preserves their unfinished capability
targets and deferred ideas under the
[release policy](../policy/release.md#release-documentation-and-preparation).
The original records remain available in
[Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap).
Accepted [ADRs](../adr/) and the [architecture policy](../policy/architecture.md)
govern any future implementation. The [CLI reference](../cli.md), public GoDoc,
and [consumer guide](../consumers/guide.md) own implemented behavior. Retaining
an idea here does not select its syntax, API, priority, or delivery date.
## Deferred capability targets
### DIFF-01: semantic configuration comparison
Expose comparison of two independently resolved selections of one scope using
owning-library safe snapshots. [ADR 0008](../adr/0008-semantic-configuration-diff.md)
owns the accepted comparison semantics, sensitivity union, and coverage-gap
handling. The target includes text/YAML reports of differences and gaps;
completed comparisons can succeed even when they find either.
The initial review of ConfigKit v0.5.0 and PromptKit v0.12.0 did not find the
complete public snapshot/sensitivity contract needed for that target. Reassess
released upstream APIs when planning it; do not treat that historical review as
a claim about newer versions. Hidden-path metadata and supported gap reasons
must be available without fetching secrets. Rendered YAML and sibling internals
are not substitutes for an agreed public comparison representation.
Comparison selection syntax, context inheritance, and report layout remain
future design work. Earlier possibilities included right-side root/overlay
selection, shared versus independent domain context, and an optional assertion
mode. Those choices are unselected. Add public types and handlers when the
capability is supported, rather than exposing placeholders.
### CAT-01: PromptKit catalogs
List captured prompt/version entries and named profiles through owning public
catalog APIs, with deterministic reports of loaded definitions. Resource names,
enumeration details, and report shapes remain future design work.
The initial PromptKit v0.12.0 review did not find public enumeration APIs.
Reassess current released capabilities before planning delivery. Do not infer
catalogs by reparsing configuration YAML or inspecting sibling internals.
## Other deferred proposals
These capabilities remain outside the delivered scope and require a concrete
operator or consumer need and an appropriate ownership/behavior decision:
- JSON reports, shell completion, and output-file management or reloadable export.
- Configuration mutation, generic value assignment, and exhaustive field-origin
inventories.
- Credential diagnostics and live provider probes.
- Additional component identity registration and domain artifact catalogs.
- Additional library families, including possible FeedKit integration; families
can define suitable verbs without requiring comparison or configuration scopes.
- Backend selection or replacement, a plugin framework, general dependency
injection, and concurrent-dispatch guarantees.
Execution, rendering, serving, and session operations remain application-owned.
Shared vocabulary is guidance under [ADR 0006](../adr/0006-command-grammar.md).
Backend replacement remains possible behind the accepted facade, subject to the
published API/CLI contracts and deliberate compatibility decisions.
## Possible further efficiency work
Selected-scope memoization and selector-membership indexes were deferred pending
measurements that justify their bookkeeping. Mutable backend reuse across
invocations, segmented aggregate YAML delivery, provider caching, consumer-loader
redesign, and a replacement backend were outside the completed performance
target. Reconsider them only with concrete motivation and review of ownership,
invocation state, native reports, and the affected contracts. Retained measurement
records are historical evidence, not performance guarantees or release gates.
## Consumer adoption and release preparation
Consumer migrations remain separate from library delivery. Applications can
replace duplicated standard handlers and routing, then update their CLI docs
and subprocess consumers for intentional changes while retaining domain commands.
No migration order or claim about individual applications' adoption is recorded
here; the [consumer guide](../consumers/guide.md) and maintained examples provide
integration guidance.
The next CommandKit release note must explain the Go 1.26.0 minimum and the
consumer action required by the ReleaseKit v0.3.0 upgrade. Version selection,
matching notes, and publication follow the [maintainer procedure](../release.md).
This cleanup does not select a release version or publish a release.

1027
docs/roadmap/implementation.md
View File

File diff suppressed because it is too large Load Diff

202
docs/roadmap/initial-plan.md
View File

@@ -1,202 +0,0 @@
# Preparing the initial CommandKit feature roadmap
Status: roadmap preparation and implementation-plan handoff complete.
Date: 2026-10-07.
The [feature roadmap](initial.md) records the selected initial target and its
completion. The [completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md)
was prepared from that review and has been executed. Checked entries below
record the completed preparation process; they are not assignments to restart
planning.
## Historical preparation process
The checklist below was used to select the initial feature target and prepare an
ordered Luna implementation plan. Its instructions and suggested outline are
retained as planning history. Current public contracts belong in Go declarations
and GoDoc, operator behavior in the [CLI reference](../cli.md), and usage guidance
in the [consumer guide](../consumers/guide.md).
The [architecture policy](../policy/architecture.md) and accepted ADRs control
architectural choices. This document owns the preparation process; `initial.md`
owns the initial feature targets. Exact implemented contracts belong in
Go declarations, GoDoc, and the CLI reference under the
[documentation policy](../policy/documentation.md).
## 1. Establish authoritative requirements
- [x] Review all nine accepted ADRs and the architecture policy.
- [x] Build a requirements checklist linking each requirement to its authority.
- [x] Review the four numbered roadmaps as evidence and design proposals:
[CLI plan](01-cli-plan.md), [dispatcher](02-dispatch.md),
[backend](03-backend.md), and [facade](04-facade.md).
- [x] Identify conflicts with accepted decisions and carry the controlling choice
into the new roadmap.
- [x] Distinguish accepted requirements, remaining design choices, and proposed
delivery scope. Approval of this drafting process leaves those design choices
to be resolved during roadmap preparation.
Use these ADR owners for traceability:
| Topic | Authority |
| --- | --- |
| Dispatch, registration, typed inputs, and consumer boundaries | [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) |
| Initial backend and invocation state | [ADR 0002](../adr/0002-cobra-backend.md) |
| Public facade and internal adapter | [ADR 0003](../adr/0003-public-facade.md) |
| Standard operations and capability-based availability | [ADR 0004](../adr/0004-standard-inspection-surface.md) |
| Outcomes, streams, and diagnostic delivery | [ADR 0005](../adr/0005-invocation-outcomes.md) |
| Grammar and vocabulary guidance | [ADR 0006](../adr/0006-command-grammar.md) |
| Native YAML and combined display | [ADR 0007](../adr/0007-native-yaml-reports.md) |
| Semantic comparison and sensitivity gaps | [ADR 0008](../adr/0008-semantic-configuration-diff.md) |
| Scopes, supported operations, and selection defaults | [ADR 0009](../adr/0009-configuration-scopes.md) |
Confirm these known differences from older planning material:
- Singleton flags use the last occurrence; repeatable flags accumulate in order.
- Configuration operations, including validation, default to `app`.
- Straightforward implementation may live in the root package.
- Providers can expose subsets of inspection capabilities.
- Loading all selected views before output is specifically a `config show`
requirement; other operations define their own output timing.
**Result:** a traceable requirements checklist and a reconciliation of older
planning assumptions.
## 2. Select a concrete package layout
Evaluate this starting recommendation:
| Package | Target responsibilities |
| --- | --- |
| Root `commandkit` | Public API; instance registry; command groups; typed bindings and presence; invocation coordination; outcomes; standard handlers; scope metadata; ConfigKit/PromptKit integration contracts; report composition. Straightforward unexported implementation can live here. |
| `internal/cobra` | Translate backend-neutral declarations into Cobra/pflag machinery; implement parsing and help mechanics; maintain independent invocation state; translate backend-owned failures. |
- [x] Define each package's purpose, owned features, inputs, outputs, dependencies,
and extension points.
- [x] Describe the boundary between the root and adapter, including how declarations
and callbacks cross it while retaining supported value and error semantics.
- [x] Keep Cobra/pflag types and operations confined to the internal adapter and
retain root-owned public named types.
- [x] Evaluate whether comparison or inspection code warrants another cohesive
internal package, using concrete implementation and integration needs.
- [x] Settle package placement during roadmap preparation so the later plan gives
Luna a defined target layout.
- [x] Keep package structure proportionate to the actual responsibilities under
the architecture and agent policies.
**Result:** a target package inventory and dependency/ownership map.
## 3. Define the initial feature inventory
Organize the inventory around these feature groups:
| Group | Features to evaluate |
| --- | --- |
| Command infrastructure | Construction, registration, groups, ownership checks, typed inputs, presence, repetition, operands, help, and invocation. |
| Identity and outcomes | Application/component version reporting, classifications, supported error identity, streams, and delivery failures. |
| Configuration inspection | Scopes, validation, native display, combined display, sources, explanation, and semantic comparison. |
| PromptKit inspection | Configuration scope, prompt/profile catalogs, and definition inspection. |
| Consumer integration | Lazy acquisition, selector applicability, upstream public types, and application-owned callbacks. |
- [x] Assign stable feature identifiers for later implementation-plan traceability.
- [x] For each feature, specify its observable result, package owner, provider
requirements, dependencies, and completion evidence.
- [x] Describe CommandKit behavior and provider result contracts separately from
recommended consumer practices.
- [x] Build an upstream capability matrix from current supported ConfigKit and
PromptKit public APIs, recording the inspected revisions or versions.
- [x] Identify which capabilities are available now and which need upstream work.
- [x] For each missing capability, recommend including the upstream work or
explicitly deferring that feature, with the reason and affected targets.
- [x] Settle initial delivery scope before preparing the ordered implementation
plan. Missing capabilities leave independently supported operations available.
**Result:** feature specifications and an explicit initial delivery scope with its
upstream dependencies and deferrals.
## 4. Evaluate existing code for reuse
Begin with these review candidates:
- [Notarius configuration commands](../../../notarius/internal/cli/configkit_commands.go):
native effective configuration and explanation integration.
- [Scriptorium inspection commands](../../../scriptorium/internal/adapter/cli/inspect.go):
PromptKit inspection acquisition and report preparation.
Expand to other consumers where their implementations provide useful evidence.
Use the repository's code-discovery workflow when locating and tracing code.
- [x] Identify reusable logic and the behavior it supplies.
- [x] Separate it from application-specific acquisition, schemas, domain resolution,
parsers, names, statuses, and formats.
- [x] Evaluate the candidate against the accepted CommandKit contracts and the
selected feature target.
- [x] For each proposed port, record the source revision, relevant symbols/files,
adaptation work, and dependencies.
- [x] Verify applicable licensing and attribution treatment under the
[OSS policy](../policy/oss.md) before copying material.
- [x] Identify reusable examples or fixtures that demonstrate meaningful behavior.
- [x] Use representative simple and complex consumer examples to evaluate whether
the proposed API removes repeated infrastructure and remains practical to wire.
Sibling checkout links are review references. CommandKit implementation and
consumer examples use supported published APIs and module dependencies.
**Result:** a reuse assessment and representative integration examples, with
provenance and adaptation requirements for proposed ports.
## 5. Resolve implementation choices explicitly
- [x] Recommend construction, registration, command-group, and typed-binding API
shapes, including presence-aware inputs.
- [x] Select narrow provider representations against concrete integration needs,
reusing upstream public types where useful.
- [x] Define acquisition lifetime and any justified dependency coordination or
result reuse, with callback ownership clear.
- [x] Specify configuration and context selectors and their applicability.
- [x] Define diagnostic presentation responsibility and delivery-failure handling.
- [x] Select report formats, framing, and schemas for the included operations.
- [x] Define comparison selection inputs for included diff capabilities.
- [x] Select the module baseline and supported dependency versions using the
applicable policies and current dependency requirements.
- [x] For viable alternatives, record a recommendation and a short analysis of
each alternative.
- [x] Resolve choices that would otherwise require Luna to invent public behavior
or package boundaries while following the implementation plan.
API shapes in planning remain design targets until implemented. Go declarations
and GoDoc will own the exact exported contracts. Significant changes to accepted
architecture follow the ADR process in the documentation policy.
**Result:** a coherent design with remaining decisions explicitly tracked and
resolved to the depth needed by the later implementation plan.
## 6. Define completion and prepare the handoff
- [x] Define observable completion criteria for each included feature.
- [x] Cover supported commands, capability discovery, native YAML preservation,
outcomes, backend isolation, and representative public API usage.
- [x] Identify proportionate evidence under the [testing policy](../policy/testing.md),
prioritizing real adapter behavior and the supported public consumer boundary.
- [x] Identify documentation and attribution deliverables as their corresponding
implementation lands.
- [x] Review the complete draft against its requirements checklist and package map.
- [x] Make upstream work, deferrals, and unresolved decisions visible in the draft.
- [x] Review the targeted end state before translating it into implementation tasks.
- [x] Prepare the subsequent staged plan with ordered tasks, prerequisites, precise
deliverables, and completion checks mapped to the roadmap's feature identifiers.
**Result:** a reviewed feature roadmap and the completed staged implementation
plan suitable for Luna.
## Historical outline for `initial.md`
1. Authority and initial scope.
2. Target package layout and dependencies.
3. Public API and integration model.
4. Feature specifications by package.
5. Ownership boundaries.
6. Upstream dependencies and reuse candidates.
7. Explicit deferrals.
8. Completion criteria.

627
docs/roadmap/initial.md
View File

@@ -1,627 +0,0 @@
# Initial CommandKit feature roadmap
Status: selected initial target implemented; completed design baseline.
Date: 2026-10-07.
## Purpose and authority
This document defines the selected initial target for the library: packages,
features, integration contracts, dependencies, and completion evidence. It was
prepared using [the agreed checklist](initial-plan.md). Implementation steps and
stage evidence belong in the [completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md).
Detailed specifications below preserve the selected design baseline; they are
planning history, not a parallel current API or operator reference. The included
target is implemented; the table below records feature status.
| Included feature IDs | Status | Evidence |
| --- | --- | --- |
| API-01, REG-01, INPUT-01, BACK-01, INV-01, OUT-01 | complete | Root API and dispatcher tests; `go test ./...`. |
| HELP-01, VER-01 | complete | Help/version behavior tests; `go test ./...`. |
| INT-01, CFG-01–05 | complete | Configuration scope, validation, show, sources, and explain tests; `go test ./...`. |
| PK-01 | complete | PromptKit scope adapter tests; `go test ./...`. |
| PK-02, PK-03 | complete | Prompt/profile inspection tests; `go test ./...`. |
| DIFF-01, CAT-01 | deferred | Require upstream safe snapshot and catalog APIs; see [deferred capability targets](#deferred-capability-targets). |
The [architecture policy](../policy/architecture.md) and nine accepted ADRs control
this roadmap. The delivery scope, typed API model, selector/report behavior, and
full profile inspection described here were selected during roadmap review.
These implementation choices operate within the accepted architecture. Exact
exported contracts belong in Go declarations and GoDoc, navigated through the
[consumer guide](../consumers/guide.md); implemented operator contracts belong in
the [CLI reference](../cli.md). The [internal overview](../internal/overview.md)
owns current package inventory and mechanics.
### Requirements and traceability
| Requirement | Authority | Feature targets |
| --- | --- | --- |
| Own dispatch; use explicit instance registries, composable groups, typed inputs, and capability-based standard families. Keep application domain behavior with applications. | [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) | REG-01, INPUT-01, INV-01, INT-01 |
| Use Cobra/pflag internally; initially rebuild backend state for each invocation. | [ADR 0002](../adr/0002-cobra-backend.md) | BACK-01, INPUT-01 |
| Expose one root facade with root-owned public named types and no backend leakage. | [ADR 0003](../adr/0003-public-facade.md) | API-01, BACK-01 |
| Supply standard help/version and available configuration/PromptKit inspection operations; families may support different subsets. | [ADR 0004](../adr/0004-standard-inspection-surface.md) | HELP-01, VER-01, CFG-01–05, PK-01–03; deferred DIFF-01, CAT-01 |
| Return explicit classifications and recommended statuses; preserve supported cause identity and report delivery failures. | [ADR 0005](../adr/0005-invocation-outcomes.md) | OUT-01 |
| Apply namespace/resource-first grammar, options after the complete command path, interspersed operands, presence, and selected repetition rules. | [ADR 0006](../adr/0006-command-grammar.md) | INPUT-01, HELP-01 |
| Preserve native effective YAML; prepare all selected show views before writing; frame aggregate display as separate documents. | [ADR 0007](../adr/0007-native-yaml-reports.md) | CFG-03 |
| 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 [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.
- Every configuration operation, including `validate`, defaults to `app`.
- Straightforward private implementation may live in the root package. A
forwarding-only facade and a separate internal engine are unnecessary targets.
- 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 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
Deliver the dispatcher, public registration/binding API, identity/outcomes, and
inspection operations supported by ConfigKit v0.5.0 and PromptKit v0.12.0.
Applications can use CommandKit without registering either integration; the Go
module still declares the dependencies used by its bundled helpers.
| Family | Initial target |
| --- | --- |
| Identity and discovery | `help`, command/group help, `version`, explicit CommandKit version selection |
| Configuration | `config scopes`, `validate`, `show`, `sources`, `explain`, including explicit aggregate validation/display |
| PromptKit configuration | The `promptkit` configuration scope, independently of definition inspection |
| PromptKit definitions | `promptkit show prompt` and `promptkit show profile`, including effective `ExtraParams` |
| Application commands | Typed custom leaf commands, nested groups, and groups with their own runnable handler |
Catalog listing and semantic comparison remain deferred until the owning
libraries expose the required public contracts. Their absence appears accurately
in help and capabilities. The implemented target uses the released inspection
APIs; upstream snapshot/catalog enhancements are separate follow-up work.
This scope provides meaningful configuration inspection immediately and avoids
requiring an initial consumer migration to wait for every future capability.
## Target packages and dependencies
Create two production packages. Keep comparison and inspection helpers as private
root implementation when needed; the current target does not justify another
production package or a public integration subpackage.
| Package | Purpose and owned features | Inputs and outputs | Dependencies and extension points |
| --- | --- | --- | --- |
| Root `commandkit` | Sole public facade; registry, typed bindings, standard handlers, provider integration, reports, identity, and outcomes | Accepts metadata, typed command declarations, acquisition callbacks, context, arguments, and caller streams; returns registration errors and invocation outcomes | Standard library, public ConfigKit/PromptKit APIs, YAML encoder, and the internal adapter. Consumers extend through commands, groups, parsers, scopes, and supported provider callbacks. |
| `internal/cobra` | Routing/parsing/help adapter; fresh backend state; conversion of backend-owned failures | Accepts neutral command/flag/operand metadata, binding callbacks, and invocation callbacks; returns neutral parse/help results and classified syntax failures | Cobra/pflag and standard library. Its bridge is internal and carries no Cobra/pflag objects back to the root. |
Dependency direction is root → adapter → Cobra/pflag. The adapter does not import
the root. Root command declarations are lowered into the adapter's small neutral
bridge; closures bind freshly allocated typed inputs and invoke root/application
handlers. The root translates bridge failures into its public outcomes. Reuse
standard `context.Context`, `io.Writer`, and ordinary Go values at this boundary.
Keep registry policy, capability checks, standard handlers, and reports in the
root. Cobra supplies routing and parsing machinery; its defaults must be adapted
where they differ from the accepted grammar. Do not copy its entire API into
CommandKit or introduce a selectable backend abstraction.
### Module baseline
Use the following reproducible starting baseline:
| Item | Initial baseline | Reason |
| --- | --- | --- |
| Module | `gitea.maximumdirect.net/eric/CommandKit` | Matches project identity and the existing library suite's module convention. |
| Go | `1.25.5` | Matches PromptKit v0.12.0's declared minimum; ConfigKit v0.5.0 declares 1.25.0. |
| ConfigKit | `v0.5.0` | Reviewed released inspection API. |
| PromptKit | `v0.12.0` | Reviewed released configuration and named-definition inspection API. |
| Cobra | `v1.10.1` | Concrete initial pin implementing the accepted backend decision. Its [module declaration](https://github.com/spf13/cobra/blob/v1.10.1/go.mod) requires pflag v1.0.9. |
| pflag | `v1.0.9` | Match that Cobra baseline; its [module declaration](https://github.com/spf13/pflag/blob/v1.0.9/go.mod) fits the selected Go baseline. |
| YAML encoder | `go.yaml.in/yaml/v4 v4.0.0-rc.6` | Match ConfigKit's existing dependency for CommandKit-owned YAML reports. Native configuration writers remain authoritative. |
These pins identify the initial baseline without claiming they are the newest
releases. Resolve and review the actual module graph and license notices when
adding dependencies.
Deferred snapshot/catalog capabilities will require released upstream versions
containing the new public APIs and a revised capability assessment.
## Public API and integration model
### API-01: public facade
**Owner:** root. **Prerequisites:** registry and invocation contracts below.
Expose an application handle with private state and a small deliberate method
set. Use construction from application identity and explicit initial command
registrations, registration methods for groups/standard suites, and invocation
with context, arguments, and caller streams. Keep runtime dependencies in handler
closures or a separate typed execution dependency parameter; they are not parsed
CLI fields.
Construction automatically installs help and version from identity/build metadata.
Provider registration assembles the other standard families' supported operations.
The target concepts are identity, application/registry handle, command/group
declarations, typed bindings, presence, invocation environment, outcome, and scope
registration. Public named CommandKit types live in the root. Public ConfigKit
and PromptKit types are deliberate integration dependencies where useful.
Use generic package functions/factories with explicit typed binding setters and
composable groups. Go methods cannot declare their own type parameters, so generic
entry points belong in package functions/factories. Typed declarations and captured
views retain their selected ownership and supported public value/error semantics.
**Completion evidence:** an external consumer uses only the root facade to
register and execute commands; public signatures, callbacks, fields, constraints,
and method sets contain no backend/internal types. No public aliases, anonymous
embedding, loosely typed bridge values, or returned backend errors defeat this
boundary. Caller-supplied values/errors retain their documented treatment.
### REG-01: instance registry and command groups
**Owner:** root. **Provider requirements:** none. **Depends on:** API-01.
Use one metadata declaration for each command's path, description, operands,
flags, bindings, and handler. Compose groups explicitly per application instance.
Support nested custom commands and a group that has both children and a runnable
handler. Groups without handlers show help when invoked bare.
Reject duplicate command paths and replacement of standard handlers. Own the
`config` namespace when installed and `promptkit` when installed: applications
cannot insert private children underneath them. Additional application families
remain registerable without needing the standard families' verb subsets.
Build standard command availability from declared capabilities. Validate missing
wiring at registration; never load files to discover operations. Return errors
from registration rather than allowing registration order to choose a winner.
**Completion evidence:** two separate instances have independent registries;
collisions and reserved-family violations return clear errors; nested custom
groups work; partial standard suites expose only their available operations.
### INPUT-01 and BACK-01: typed inputs and adapter behavior
**Owners:** root for bindings/presence; adapter for backend mechanics.
**Provider requirements:** none. **Depends on:** REG-01.
Use generic command factories with explicit typed flag/operand setters and
a typed handler. Allocate the input struct for each invocation. A presence wrapper
such as `Supplied[T]` carries a value and whether it was supplied; omission differs
from an explicitly supplied empty string, false, or zero. A repeatable binding
collects ordered values. Support ordinary scalar conversions and caller-provided
typed domain parsers without handler lookups by flag name.
Metadata expresses required operands/flags, counts, and declared incompatible
combinations. Parsing and declared input-shape failures are usage outcomes;
application domain validation stays with the application handler. Do not infer
additional incompatibilities from parser convenience.
Apply ADR 0006's grammar through the adapter: standard long lowercase hyphenated
flags, separated/equal string values, boolean presence or explicit boolean value,
`--` termination, options after the full command path, and interspersed options
and operands within that command. Help bypasses missing execution requirements;
unknown help paths/flags still fail as usage errors.
Initially rebuild the Cobra tree and binding state for each invocation. Repeated
calls retain no prior values, slices, or presence bits. Caller closures keep their
own lifecycle; this design does not establish concurrent dispatch support.
**Completion evidence:** public invocations exercise the real adapter, explicit
zero/false/empty values, omission, singleton last-wins, ordered repetition,
interspersed operands, termination, and repeated executions with fresh inputs.
Help routing must follow CommandKit's grammar even where Cobra differs.
### INV-01 and OUT-01: invocation, outcomes, and diagnostics
**Owner:** root, with syntax adaptation in the adapter.
**Provider requirements:** handlers/acquisition callbacks. **Depends on:** INPUT-01.
Pass caller context to handlers and acquisition callbacks. CommandKit does not
create the executable entry point, install signal handlers, or call `os.Exit`.
Return explicit success, usage, operational, or application-domain classification,
recommended status, and supported cause identity. Standard statuses are 0, 2, and
1 respectively for success, usage, and operational failure. Preserve an
application handler's explicit domain classification and suggested status.
Make root invocation the single presenter of CommandKit diagnostics.
Standard handlers return report/delivery information and safe diagnostic data;
the adapter suppresses its own automatic error printing. Use public
`configkit.WriteDiagnostics` for ConfigKit diagnostics and neutral presentation
for syntax errors. Pair diagnostics with supplied source records where useful.
Do not print an owning-library diagnostic twice through nested CommandKit paths.
Return one root-owned outcome containing classification, suggested status,
operation cause, delivery failure, and a clear diagnostic-delivery indication.
This indication distinguishes a diagnostic already presented from one whose write
failed. Preserve both the operation cause and a delivery error when both occur;
do not replace either with a backend error. Invocation returns this outcome
without a separate error result. Warnings alone allow success. Report or diagnostic
writer errors are operational failures and can leave partial output.
Callbacks control their own output. Consumer guidance should recommend returning
diagnostics to the standard path and avoiding repeated presentation, without
prescribing all downstream error handling. Upstream APIs determine how much
underlying error identity survives; CommandKit cannot recover causes an upstream
library deliberately withholds.
**Completion evidence:** usage guidance appears on the diagnostic stream;
reports appear on the report stream; warnings permit success; callback,
cancellation, report-write, and diagnostic-write failures are classified correctly;
public causes remain usable with `errors.Is`/`errors.As` where supported.
### INT-01: acquisition and provider contracts
**Owner:** root. **Depends on:** registry, typed inputs, outcomes.
Use a typed configuration-suite factory parameterized by an
application-owned inspection-context input. It installs the standard input
bindings once, plus explicit typed application selector bindings, and scope
registrations with acquisition callbacks. A simple consumer uses an empty context
type. A complex consumer supplies campaign or other domain selection as typed
fields. Generic suite helpers and small capabilities provide this assembly without
a universal untyped service container or handler access to parser objects.
Each scope declares supported operations and obtains a captured view only on an
invocation that needs it. Use small operation-specific interfaces/callbacks:
native effective writer; source reader; safe explanation reader/writer; and
validation callback. Reuse `configkit.SourceInfo`, `Diagnostic`, `Path`, and
`Explanation` rather than creating parallel provenance types. A bundled generic
ConfigKit helper connects a loader returning `*configkit.Result[T]`; a PromptKit
helper connects engine acquisition and `ConfigurationInspection`. Missing an
operation must not require dummy implementations of other interfaces.
For a selected operation, acquire its scope once and retain that view through
reporting. A bundled helper can reuse the same loaded result for diagnostics and
the report. Aggregate show retains all selected views before writing. Other
operations need no application-wide cache or dependency graph.
When an engine depends on application configuration, the application acquisition
callback composes that dependency. It may share results in an invocation-local
closure. Document that pattern, without requiring one universal loading method,
forbidding consumer effects, or promising that arbitrary callbacks never reload.
Recommend sharing inspection and execution loading/resolution where practical.
**Completion evidence:** metadata-only commands do not invoke acquisition;
single-scope operations acquire only their target; aggregate show observes its
preparation rule; simple and complex consumer examples require no parallel
dispatcher, manual standard-command parser, or duplicated standard report logic.
## Standard command features
All features below belong to the root; routing, flag conversion, and help
mechanics use the adapter. Their common prerequisites are REG-01, INPUT-01,
INV-01, and OUT-01. Provider requirements and additional dependencies are stated
per feature. The following flags/report shapes are selected implementation
targets for the initial standard suite.
### HELP-01 and VER-01: help and identity
- Help describes installed standard and custom commands using registry metadata.
Root bare invocation, `help [COMMAND…]`, `--help`, and `-h` follow ADR 0006.
- Use `version` and `version --scope commandkit`; default output is only
application identity. Version subjects are separate from configuration scopes.
- Application identity is supplied at construction. Recommend obtaining embedded
CommandKit identity from Go build information, respecting module replacement
metadata; use an explicit development/unknown label when a tag is unavailable.
Do not invent a separate integer CLI version. Use a text default and
optional `--format yaml` for version records.
**Provider requirements:** identity metadata only. **Completion evidence:** help,
version, and discovery work with missing/invalid configuration and never invoke
acquisition callbacks. Default version excludes dependency inventory; explicit
CommandKit selection identifies the embedded component accurately.
### CFG-01: scope metadata and selection
`config scopes` lists identifiers and supported operations in order: `app`,
`promptkit`, then additional identifiers alphabetically. Use text by default
and `--format yaml` producing `scopes: [{name, operations}]`.
All installed configuration operations use `--scope NAME`, defaulting to `app`.
`validate` and `show` additionally accept `all`. Check requested coverage before
acquisition. An unsupported scope/operation is usage failure with available
choices; `all` never silently skips a scope. If `app` is absent, its default
selection fails with useful choices rather than silently selecting another scope.
**Provider requirements:** registration metadata only. **Completion evidence:**
discovery matches installed handlers and partial capabilities; aggregate coverage
errors occur before any acquisition; ordering and defaults match ADR 0009.
### CFG-02: validation
`config validate` invokes the selected provider's configuration load/validation
boundary. ConfigKit's bundled helper regards successful load and required owning
validation as success. PromptKit's helper constructs/obtains a valid engine;
it does not run a prompt or probe model availability. Application domain context
validation, when needed for its inspection view, belongs in its callback.
Use text by default and `--format yaml` with a `scopes` sequence of completed
validation records (`name`, `valid`). For `all`, preflight capability coverage,
then validate in scope order and report successful scopes as they complete;
stop on the first operational failure. Diagnostics explain the failure and the
outcome indicates incomplete completion. This selected validation timing preserves
show's separate preparation rule.
**Provider requirements:** validation/acquisition callback and safe diagnostics.
**Depends on:** INT-01, CFG-01. **Completion evidence:** default validates `app`;
explicit `all` validates requested coverage; invalid configuration yields status 1;
warnings alone do not fail; no model execution is triggered by bundled handlers.
### CFG-03: native effective display
`config show` writes the selected scope's owning-library effective YAML. It must
not marshal `Result.Config`, reinterpret defaults, remove nulls, or rebuild the
native document from runtime structs. Use YAML as its sole initial format;
accept `--format yaml` for explicitness.
For `--scope all`, acquire and complete required owning validation of every view
before writing any report bytes. Compose separate native documents in scope order,
with YAML separators and scope-label comments. Use `---` followed by
`# scope: NAME` before each document. Single-scope show writes native output
without an added scope envelope. Preserve native content; framing must account
for any native document marker without creating accidental empty documents.
**Provider requirements:** native writer plus successful acquisition/validation.
**Depends on:** INT-01, CFG-01. **Completion evidence:** single native output is
preserved; aggregate YAML has one labeled document per selected scope in order;
a later acquisition failure leaves no successful prefix; writer failure returns
operational failure and may leave partial output.
### CFG-04: source inventory
`config sources` exposes the selected captured view's public source records.
Retain the owning source IDs, labels, paths, kinds, layers, underlay indices, and
import locations where available; missing fields do not acquire invented values.
Keep owning-library record order. Use readable text by default and
`--format yaml` with `{scope, sources}` and explicit snake-case source fields.
**Provider requirements:** public source reader and acquisition.
**Depends on:** INT-01, CFG-01. **Completion evidence:** acquired and synthetic
records remain identifiable; import references correlate with owning IDs;
reporting does not reload files or confuse provenance with effective values.
### CFG-05: path explanation
Use `config explain --path POINTER`, including an explicitly supplied empty
pointer for the root. Use public `configkit.ParsePath`; malformed pointers are
usage errors and unknown effective/historical paths are operational lookup
failures. Do not treat a native writer's empty output as successful lookup.
Text defaults to the owning `WriteExplanation` rendering. Use
`--format yaml` with `{scope, path, effective, origin, history, secret_reference}`.
Preserve `present`, `redacted`, and the owner's YAML fragment in each value
snapshot; represent fragments as strings so absence/null/masked values remain
unambiguous. Canonicalize paths through public `Path.String()`. Preserve owning
provenance, reasons, dependencies, and reference names, not credential values.
**Provider requirements:** safe public explanation and native text writer.
**Depends on:** INT-01, CFG-01. **Completion evidence:** known current and removed
historical paths work, root-pointer presence works, invalid/missing paths have
distinct outcomes, and safe snapshots survive YAML report conversion.
### PK-01: PromptKit configuration integration
The bundled helper acquires an engine through the application callback, then
uses `Engine.InspectConfiguration()` and its public native writers, sources,
diagnostics, and explanation methods. Register these capabilities under the
`promptkit` scope. Registration of this scope neither requires nor implicitly
installs definition inspection.
**Provider requirements:** engine/configuration-inspection acquisition.
**Depends on:** INT-01, CFG-01–05. **Completion evidence:** native PromptKit YAML
and ConfigKit-compatible provenance are exposed through the standard family;
aggregate show can combine it with `app` without translating either document.
### PK-02 and PK-03: named definition inspection
Use these command inputs:
```text
app promptkit show prompt ID [--version VERSION] [--format text|yaml]
app promptkit show profile ID [--format text|yaml]
```
Both acquire the engine lazily and pass the invocation context to the public
inspection method. Prompt-version omission follows PromptKit's own selection
semantics. Missing named definitions are operational lookup failures. These
operations do not render/execute prompts, resolve credential values, or generate
model output through CommandKit's handlers; application acquisition retains its
own behavior.
Prompt reports include ID, selected version, opaque hash, declared default profile,
input definitions in declaration order, and declared output contract. Use explicit
YAML fields rather than depending on incidental Go struct serialization. An
output-contract value of `json` is domain metadata, not a JSON report format.
Profile reports include the named ID, backend-completed effective target fields,
`ExtraParams`, credential environment-variable name, and direct-credential
requirement from the existing public `ProfileInspection` result. `ExtraParams`
contains provider settings and is included in both text and YAML reports. It
requires no additional redaction or upstream inspection API for this feature.
Preserve nested parameter values when projecting the public result into the
CommandKit report schema. Credential values remain separate from these settings.
**Provider requirements:** public `InspectPrompt`/`InspectProfile` respectively;
each capability can be registered independently. **Depends on:** INT-01 and the
public report projection. **Completion evidence:** text and YAML preserve public
metadata and effective provider parameters; profile credentials are reported as
requirements/references; unknown IDs and cancellation retain supported public
error identity; help never constructs an engine.
## Selectors, reports, and ownership
Use a shared standard selection input for acquisition-bearing inspection
commands, carrying presence-aware `--config` and singleton `--overlay`.
Application callbacks interpret their values using the owning loader. Omission
delegates discovery/default selection; an explicitly empty overlay can represent
the loader's no-overlay selection. The application
supplies schema, filesystem/source construction, imports, and domain resolution.
PromptKit integration does not assume its configuration is at the application
root path; its callback maps selectors to its acquisition path.
Register application context flags through typed bindings with declared scope
applicability. For example, a Narratio campaign selection can matter to `app`
inspection and to engine acquisition derived from that application view. Reject
explicit selectors that do not apply to any selected scope with a usage diagnostic;
for `all`, route each selector to the scopes that declare it. Metadata/help should
state applicability. Validate declared selector combinations before acquisition;
domain lookup/validation remains operational. Do not infer application-specific
campaign or session policy.
Use text defaults for CommandKit-owned summaries and YAML alternatives;
`config show` is native YAML. CommandKit owns report schemas for summaries,
source/explanation projections, and definition reports. Owning libraries own the
native documents and safe values. Select schema fields deliberately and document
them with implementation; no separate schema-version integer is proposed.
| Responsibility | Owner |
| --- | --- |
| Command paths, shared grammar, standard handlers, metadata/help, selection preflight, report framing, outcomes | CommandKit |
| Typed custom input mechanics and routing | CommandKit; custom domain meaning remains with the application |
| Configuration composition, recorded resolution, provenance, sensitivity, native effective/explanation rendering | ConfigKit/PromptKit through supported public APIs |
| Source discovery, application schema and domain validation/resolution, engine construction, runtime dependencies | Application callbacks |
| Custom session/execution commands, effects, outputs, and domain results | Application |
| Process context/signals, streams, final status mapping, process exit | Application entry point |
Safe owning-library inspection is required for enabled standard operations. This
does not promise that arbitrary configuration or prompt content is suitable for
public disclosure, and CommandKit does not inspect arbitrary consumer error
objects to enforce a broader confidentiality policy.
## Upstream capability evidence
The following clean sibling revisions were reviewed on 2026-10-07. They are
evidence snapshots, not build dependencies.
| Repository | Reviewed revision | Released API baseline |
| --- | --- | --- |
| ConfigKit | `dc09959cca4e105f49ec316c6d4ba585bd2340bd` | v0.5.0 |
| PromptKit | `4b8169da286917fde7875425bb32b799b12c6af3` | v0.12.0 |
| Scriptorium | `723fee9c466789fd3b6cca5492bf2edf99f4136c` | Consumer evidence |
| Notarius | `66fa5585c1190581e96ec42102ce745c3869ba6d` | Consumer evidence |
| Narratio | `8afb49c01808c04bc73f782d1619e87c8c2cd312` | Consumer evidence |
| Audita | `3b4933256eff84327b812e7ae12babf743bc04a6` | Consumer evidence |
| Capability | ConfigKit v0.5.0 | PromptKit v0.12.0 | Delivery consequence |
| --- | --- | --- | --- |
| Validated acquisition | `Load`/recorded resolution with application definition | `NewEngine` and application acquisition | Include CFG-02; do not add a parallel validator. |
| Native effective YAML | `Result[T].WriteEffective` | `ConfigurationInspection.WriteEffective` | Include CFG-03 and PK-01. |
| Sources/diagnostics | Public result/load-error source and diagnostic records | Configuration-inspection sources/diagnostics | Include CFG-04 and OUT-01. |
| Safe path explanation | `Explain`, `WriteExplanation`, public `Path` | Equivalent configuration-inspection methods | Include CFG-05. |
| Named prompt metadata | Outside its resource domain | `Engine.InspectPrompt` and `PromptInspection` | Include PK-02. |
| Named effective profile target | Outside its resource domain | `Engine.InspectProfile` exposes the effective target including copied `ExtraParams`, plus credential requirements/reference names | Include PK-03 using the existing public result, including provider parameters. |
| Catalog enumeration | Outside its resource domain | No public prompt/profile enumeration API found | Defer CAT-01; recommend upstream captured catalog inspection. |
| Safe full semantic comparison snapshot | No dedicated public structured tree plus full sensitivity/coverage contract found | No corresponding configuration snapshot API found | Defer DIFF-01; recommend upstream safe snapshot support. |
Relevant public declarations are [ConfigKit inspection](../../../ConfigKit/inspection.go),
[metadata](../../../ConfigKit/metadata.go), [PromptKit configuration inspection](../../../promptkit/configuration_inspection.go),
[engine methods](../../../promptkit/engine.go), and [inspection types](../../../promptkit/types.go).
ConfigKit's `HistoricalPaths`, `Explain`, and redacted YAML provide useful pieces;
they do not expressly define the full comparison representation required by ADR
0008. Deriving a comparison contract from these pieces would require an explicit
owning-library agreement and design, rather than assuming masks imply equality.
### Deferred capability targets
- **DIFF-01:** acquire two independently resolved selections of one scope through
public safe snapshots. Preserve absent/null/empty distinctions and scalar
semantics, recursively compare mappings, compare ordered sequences atomically,
apply sensitivity union, and report differences plus gaps in text/YAML. Completed
comparisons succeed even with differences/gaps. Snapshot data must describe
hidden paths and supported reasons without fetching secrets. Comparison selector
syntax/inheritance must be decided when bringing this feature into delivery.
- **CAT-01:** list captured prompt/version entries and named profiles through public
owning catalog APIs; deterministic reports describe actual loaded definitions.
Do not infer catalogs from configuration YAML or inspect sibling internals.
Do not create empty handlers, pretend capabilities, or unused public snapshot
types for these deferred targets. Future upstream contracts should inform their
representations. Future FeedKit-like families can supply appropriate operations
without supporting comparison or configuration scopes.
## Reuse assessment and consumer fit
Use the reviewed revisions above to evaluate extraction; no source is copied by
this roadmap. Prefer existing public owning writers over porting their renderers.
| Candidate | Useful behavior | Adaptation and boundary |
| --- | --- | --- |
| [Notarius configuration handlers](../../../notarius/internal/cli/configkit_commands.go): `runConfigEffective`, `runConfigExplain` | Load an application result and call native ConfigKit writers; canonical path parsing and lookup handling | Retain the acquisition-to-writer pattern. Replace application scopes, manual flag sets, output/status handling, and loader coupling with INT-01/CFG-03/05. The application keeps its loader and domain selection. |
| Same file: `runConfigProfile`, `runConfigValidate` | Named profile inspection and application-specific validation examples | Evaluate inputs and callback needs. Their JSON report, private wrappers, and runtime/domain validation are not standard contracts. |
| [Scriptorium inspection dispatch](../../../scriptorium/internal/adapter/cli/inspect.go): `inspectCommand` | Lazy engine acquisition and named inspection followed by formatting | Keep upstream method use. Replace private dispatch, `context.Background`, output-file behavior, old command paths, and integer-status plumbing with caller context, streams, and outcomes. |
| [Scriptorium report projections](../../../scriptorium/internal/format/inspection.go): `FormatPromptInspection`, `FormatProfileInspection` | Explicit prompt/profile field projection and readable presentation | Prompt/profile DTO fields are useful starting inventories. Replace JSON output with YAML and include the public effective `ExtraParams` values in profile reports. |
| [Narratio comparison](../../../narratio/internal/app/config_diff.go): `ConfigDiff`, `configDiffWithDependencies` and comparison helpers | Independent resolved selections, deterministic path records, and add/remove/change presentation | Evidence for future DIFF-01. Its application projection/digests, overlay-only operands, shared campaign policy, and absence of ADR 0008 sensitivity-gap semantics require redesign; no initial direct port is proposed. |
Recommend implementing the small integration glue from these public contracts,
using consumer code as behavioral evidence. If a substantive helper or fixture is
actually copied/adapted, record its source commit, affected symbols/files,
modifications, and required notices when it lands. Scriptorium and Notarius grants
are GPL-3.0-or-later; CommandKit is LGPL-3.0-or-later. Common ownership does not by
itself change those grants. Resolve applicable reuse rights or an author's
deliberate licensing choice before any such copy under the
[OSS policy](../policy/oss.md). No blanket source-port permission is inferred.
Use secret-free synthetic fixtures reflecting existing consumer scenarios:
defaults plus overlays and historical deletion, inherited profiles, explicit
zero/false selectors, missing definitions, and a second scope that fails during
aggregate show. Existing consumer cases can inform these fixtures; entire
application schemas/workspaces need not be imported.
Two maintained public examples should substantiate infrastructure reduction:
1. **Simple ConfigKit consumer:** register one application loader and its schema,
use bundled scope wiring, then register a typed custom command. Standard help,
parsing, validation, native show, sources, and explanation need no private CLI
handlers or formatters.
2. **Complex consumer modeled on Narratio/Scriptorium:** register app and PromptKit
scopes plus named definition inspection, with typed campaign/context selection;
compose app → engine acquisition in consumer code; retain a custom
`session restore` group/handler. Standard paths and report composition remain
CommandKit-owned while campaign/session meaning stays with the application.
The declaration and callback burden should demonstrate infrastructure reduction
against the existing handlers. Consumers should be able to use these examples
without recreating dispatch, standard input parsing, or standard report projection.
## Explicit deferrals
In addition to DIFF-01 and CAT-01, defer JSON report
output, shell completion, output-file management, backend selection, a plugin
framework, general dependency injection, concurrent-dispatch guarantees, and
implementation of additional library families. None is needed to prove the
initial selected feature target. Application-owned commands remain extensible.
Consumer migrations and source publication were kept outside the initial
library target. ReleaseKit adoption is complete; current release operations
are in the [maintainer procedure](../release.md). The completed adoption record is
available at the [historical adoption revision](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/implementation.md).
The initial implementation targeted a usable module with maintained examples;
it did not create placeholder publisher commands or a binary build matrix.
## Completion criteria
The initial target is complete when the included feature IDs have their stated
observable behavior and evidence, and the selected roadmap choices are reflected
consistently in the API and CLI contracts.
Use proportionate deterministic, offline behavioral evidence under the
[testing policy](../policy/testing.md): public consumer tests with the real adapter
for grammar/presence/state, real local ConfigKit/PromptKit fixtures for inspection,
and controlled acquisition/writer failures at those boundaries. Review the public
type/dependency boundary directly; choose automation only where its distinct
protection justifies maintenance. Do not retest complete upstream libraries or
add blanket coverage, race, scanner, or platform gates.
Maintain these substantive documents/artifacts as implementation lands:
- GoDoc for exact exported contracts, ownership, errors, and lifecycle.
- `docs/cli.md` for installed standard syntax, formats, scope coverage, and outcomes.
- Consumer guidance and complete simple/complex examples; link to owning upstream
configuration contracts instead of duplicating schemas.
- `docs/internal/overview.md` describing the two implemented packages and their
actual boundary. Add focused internal/integration documents only where useful.
- Dependency/source attribution and applicable license/notice material in the
change that incorporates it, under the OSS policy.
- Contributor commands and orientation updates once the Go module and validation
commands actually exist; preserve existing policy ownership.

268
docs/roadmap/performance.md
View File

@@ -1,268 +0,0 @@
# Computational efficiency roadmap
Status: implemented; PF-01–PF-06 and selected approaches OD-1/OD-2 are complete.
Date: 2026-10-09.
## Purpose and authority
Reduce repeated work and avoidable allocations in CommandKit's command dispatch,
registration, and inspection reports. Favor straightforward changes with clear
benefits, and use measurements to decide whether more complex optimizations are
worth maintaining.
This document owns the target state, priorities, and selected implementation
scope. The completed [implementation record](implementation.md) owns ordered
stages, measurement fixtures, validation, and execution evidence. The
[architecture policy](../policy/architecture.md), accepted
[ADRs](../adr/), [Go declarations](../../app.go), and
[CLI reference](../cli.md) continue to govern behavior. Follow the
[agent policy](../policy/agents.md) for proportionate implementation and the
[testing policy](../policy/testing.md) for validation. These proposals do not
establish new public performance or concurrency guarantees.
## Reviewed baseline
The efficiency review examined commit `54cfbd8` with a clean worktree. Its
findings come from source inspection; no benchmarks or allocation profiles were
run. Complexity observations identify scaling costs, not measured bottlenecks
or promised speedups. Recheck the affected implementation before starting work.
| ID | Observed work | Target result | Primary benefit |
| --- | --- | --- | --- |
| PF-01 | PromptKit text reports are built even for YAML requests. | Render only the requested format and avoid redundant report buffers. | Inspection CPU and allocation reduction |
| PF-02 | Selected-command lookup scans a map; each ancestor is rediscovered from the root. | Direct declaration lookup and ancestry traversal proportional to path depth. | Wide or deeply nested command trees |
| PF-03 | Every invocation translates and sorts metadata; help and usage construct another backend tree. | Reuse immutable metadata and the invocation's prepared tree. | Repeated execution and help/usage paths |
| PF-04 | Aggregate YAML framing splits every line and copies the complete native document. | Inspect only the opening lines and retain a complete framed buffer for delivery. | Large or newline-dense reports |
| PF-05 | Each registration copies the existing top-level registry. | Prepare new entries separately and install a validated batch atomically. | App construction with many registrations |
| PF-06 | Scope ordering, lookup, and selection repeat; selector duplicate checks scan previous entries. | Prepare stable scope metadata once and use direct duplicate checks. | Growing scope and selector sets |
The implemented package inventory remains owned by the
[internal overview](../internal/overview.md). The target is internal improvement
within the existing root facade and Cobra adapter; no additional public package
or consumer registration API is proposed.
## Target behavior and ownership
Optimizations preserve the existing contracts rather than changing operator or
consumer workflows:
- Keep Cobra/pflag objects and operations inside the internal adapter, following
[ADR 0003](../adr/0003-public-facade.md).
- Keep parsed values, collections, and presence independent between invocations.
[ADR 0002](../adr/0002-cobra-backend.md) permits safe reuse; rebuilding backend
storage is an implementation choice. Caller-owned state retains its lifecycle.
- Preserve registration validation, reserved command ownership, and complete
batch validation before changing the registry, as documented in
[command declarations](../../command.go) and [registration](../../registry.go).
- Keep metadata construction, help, and version independent of provider
acquisition under the architecture policy.
- Preserve owning-library rendering and confidentiality semantics, aggregate
document order, and acquisition of all selected views before `config show`
output under [ADR 0007](../adr/0007-native-yaml-reports.md).
- Preserve cancellation, diagnostic delivery, outcome classification, and
reporting of partial output and write failures under
[ADR 0005](../adr/0005-invocation-outcomes.md).
Registration and command metadata belong to the root implementation. Backend
indexes and invocation machinery belong to `internal/cobra`. Report formatting
and scope preparation remain with the corresponding root handlers. Acquisition,
configuration resolution, and provider lifetime remain with the existing
integration contracts and consuming applications.
## Target improvements
### PF-01: Render only the requested PromptKit format
In [PromptKit handlers](../../promptkit.go), `runPromptKitPrompt` calls
`formatPromptText` before `writePromptKitReport` chooses a format.
`runPromptKitProfile` similarly calls `formatProfileText` unconditionally. The
profile text formatter serializes `ExtraParams` as nested YAML; a YAML request
then serializes those parameters again as part of the structured report. Text
delivery also copies an already completed report into another builder.
The target selects the requested formatter before rendering and delivers the
completed report without a redundant intermediate text buffer. It retains the
existing structured report representation and YAML encoder, including
`ExtraParams`, diagnostics, and delivery-failure semantics. YAML requests produce
only the structured report; text requests produce only the text report.
### PF-02: Index command declarations and ancestry
In the [Cobra adapter](../../internal/cobra/parse.go), `declarationFor` scans the
declaration-to-backend map to find a selected backend command. `pathFor` calls
`parentOf` from the root for every ancestor. For N command nodes and selected
depth D, repeated parent searches can take O(N × D) work; a chain can produce
quadratic work.
The target provides direct backend-to-declaration lookup and reconstructs only
the selected path from parent relationships inside the adapter. Declaration
lookup is constant time, with path construction proportional to D after tree
preparation. Exact registered-path matching and error classification are retained.
This improvement removes redundant searches; constructing the complete backend
tree still has a separate cost addressed by PF-03.
### PF-03: Reduce command-tree reconstruction
[Metadata translation](../../parser.go) copies and sorts the registered tree on
every invocation, including flag and operand declarations. The adapter then
builds backend commands and flag sets for all nodes. Help and usage rendering
build another complete backend tree after parsing has already built one.
The target retains the invocation's prepared backend tree inside the adapter for
parsing, help, and usage. The root coordinates these operations through a narrow
internal handle without receiving Cobra/pflag objects. Immutable bridge metadata
and sorted child order are cached per `App` and refreshed when registration
changes the declared tree. Failed registration leaves existing commands usable,
including their help and dispatch behavior.
Metadata caching principally benefits repeated `Execute` calls. Avoiding a
second backend construction also benefits a single CLI help or usage request.
Efficiency evidence distinguishes both cases, including app construction and
registration for consumers that execute only once.
Under the selected OD-1 approach, construct fresh mutable backend parse state for
each invocation, reuse that state within the invocation, and cache immutable
metadata between invocations. Reusing mutable backend trees across invocations
is deferred beyond this target. Measurements may motivate reconsidering it in
future work. No public freeze step, backend selector, or concurrent-dispatch
guarantee is needed for these improvements.
### PF-04: Reduce aggregate YAML preamble scanning
In [configuration display](../../show.go), `hasYAMLDirective` and
`frameEffectiveYAML` split the complete document into lines before examining its
opening content. These splits scan all bytes and allocate a slice entry for each
line, even when the framing decision can be made immediately. Framing then
allocates a complete copy alongside the native buffer.
The target analyzes the preamble with byte offsets and stops when the directive
or marker decision is complete. Directive detection and scope-label placement
share that analysis. Framing needs no document-wide line index or unnecessary
string conversions.
Under the selected OD-2 approach, retain the native render buffer and assemble a
complete framed buffer for each document before delivery. This keeps delivery
and write-failure handling straightforward. The full document copy remains an
accepted cost of this target; the optimization removes the document-wide line
index and redundant preamble scanning.
Preserve native bytes, directive placement, inline document content and block
scalars, scope-label escaping, and boundary newlines according to the CLI
contract. Keep single-scope native delivery direct. Aggregate acquisition remains
complete before output; the current code buffers one rendered document at a time,
not every scope's rendered bytes simultaneously.
This target removes avoidable scans and allocations; complete rendering and
delivery still require work proportional to output size.
### PF-05: Avoid repeated registry copying
[Registration](../../registry.go) copies all existing top-level entries for each
`Register` call. Registering R top-level commands individually therefore produces
O(R²) cumulative map-copy work, apart from validation and declaration cloning.
This is a construction cost, not work performed by a registered handler.
The target prepares owned pending declarations and checks collisions against
existing and pending entries before changing the registry. Successful batch
validation installs the pending entries without copying existing map entries,
while preserving declaration ownership and atomic validation. Its completion
point also invalidates derived metadata for PF-03 when the tree changes.
Batch registration remains an optional consumer optimization. Both individual
and batch registration are supported by this target.
### PF-06: Prepare stable configuration scope metadata
[Scope selection](../../selectors.go) sorts scope declarations and repeatedly
searches the scope slice. Aggregate selection and handler acquisition each look
up every scope by name, producing quadratic scope-search work. Selection also
occurs during preflight and again in the handler. In
[suite normalization](../../config.go), selector duplicate checking compares each
selector with all previous selectors; PromptKit already uses name and short-name
maps for the equivalent check.
The target retains normalized declarations, stable scope order, direct name
lookup, and discovery inventory as private registered-suite metadata. Selector
duplicate validation uses direct name and short-name checks. Context projection
and selection validation remain fresh for each invocation; both preflight and
handlers can consult the same prepared metadata without repeated sorting or
quadratic scope searches.
Scope order, declared operation availability, and scope-aware selector validation
remain governed by [ADR 0009](../adr/0009-configuration-scopes.md). Metadata
preparation leaves acquisition and runtime context callbacks uninvoked.
## Delivery scope and evidence
PF-01 through PF-06 are included in the implementation target. Conditional
formatting, indexed ancestry, and YAML preamble analysis address the clearest
redundant work. Registry and scope preparation are lower-priority, bounded
changes that remove observed scaling costs without adding consumer requirements.
The [implementation plan](implementation.md) specifies the concrete mechanisms
and divisions of work.
Efficiency evidence compares elapsed cost, bytes allocated, and allocations per
operation for representative dispatch, reports, registration, and scope sizes.
It distinguishes cold and repeated execution, isolated and complete command
costs, provider work, and memory retained by caches. Source analysis alone does
not establish a measured speedup. Measurements establish no fixed timing
threshold, public allocation budget, or additional release gate.
Implementation preserves existing public API and CLI contracts. Internal
documentation describes the changed mechanics when they land; detailed
validation and before/after evidence belong in the implementation plan.
Selected-scope memoization and additional selector-membership indexes are
deferred pending evidence that their bookkeeping is worthwhile. Mutable backend
reuse across invocations and segmented YAML delivery are outside the selected
target; future reconsideration needs a deliberate change to OD-1 or OD-2.
Provider caching, consumer loader redesign, removing copies required for value
ownership, and replacing Cobra are outside this target. They require their own
concrete motivation and review rather than following automatically from a
performance optimization.
## Resolved Decisions
The following approaches were selected on 2026-10-09. Both are implementation
choices within the existing public contracts. No significant open decisions
remain for this roadmap's scope.
### OD-1: How far should backend reuse extend?
**Selected approach:** Adopt the recommended approach: reuse the prepared backend
within one invocation and cache immutable metadata between invocations, while
constructing fresh mutable backend state for each `Execute`.
**Reasoning:** This removes repeated help/usage work and metadata translation
while keeping invocation isolation straightforward. Measure the remaining
backend construction cost to inform future work. The selection defines the
PF-03 target without establishing a permanent architectural restriction.
**Alternative considered:** Retain a mutable backend tree per `App` and reset it
before each invocation. This can remove more command and flag-set construction
work for consumers that execute repeatedly. It also retains more memory and requires
careful reset of parsed values, presence, operands, contexts, streams, and other
backend state, plus refresh after registration. The added lifecycle complexity
is deferred until measurements justify reconsideration and behavioral evidence
establishes independent invocations. A CLI that executes only once receives
little benefit from this additional reuse.
### OD-2: How much buffering should aggregate YAML retain?
**Selected approach:** Adopt the previously listed alternative: retain the
complete framed buffer after replacing the line splits with prefix scanning.
**Reasoning:** This keeps delivery simple and avoids additional writes for each
document. It accepts the second document allocation and copy while removing the
line index and unnecessary scanning. Measure the resulting allocation cost,
particularly for large reports, without making segmented delivery part of this
implementation target.
**Alternative considered:** Retain only the native render buffer and deliver
framing and native slices as separate segments. This can reduce peak allocation
and copying while keeping native rendering complete before delivery. It requires
accounting for cancellation and partial output across segment writes and may
increase writer-call overhead. It remains a viable future optimization if the
selected approach's measured memory cost warrants the additional delivery logic.

247
docs/roadmap/releasekit.md
View File

@@ -1,247 +0,0 @@
# ReleaseKit v0.3.0 upgrade roadmap
Status: implemented; ReleaseKit v0.3.0, Go 1.26.0 minimum, and Go 1.26.8
release toolchain are in place.
Date: 2026-10-08.
## Purpose and authority
Upgrade CommandKit's maintainer publication tool from ReleaseKit v0.2.0 to
v0.3.0 and simultaneously raise CommandKit's declared Go consumer minimum to
1.26.0. The user has accepted both changes. Retain the existing root-module Go
tool dependency and source-only publication workflow.
This document records the target state, completed upgrade work, and evidence
from the reviewed baseline. The
[release policy](../policy/release.md),
[architecture policy](../policy/architecture.md),
[agent policy](../policy/agents.md),
[testing policy](../policy/testing.md), and
[documentation policy](../policy/documentation.md) govern the work. Apply the
[OSS policy](../policy/oss.md) to any changed attribution or incorporated material.
The [maintainer procedure](../release.md) owns current release operations.
This is a new upgrade roadmap. The completed initial ReleaseKit adoption is
available in Git history; its retired assignments are not part of this work.
Implementation completion is distinct from publishing a CommandKit release.
## Reviewed baseline
CommandKit was reviewed at `7eebe877cf9a21fb4f886f89bbc2089661237fc1` with a clean
worktree. ReleaseKit v0.3.0 identifies commit
`e43df4416e0ed987349b2ea04a2c68c25e552772`; the local checkout and published tag
matched that revision during review. Its [release notes](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e43df4416e0ed987349b2ea04a2c68c25e552772/docs/releases/v0.3.0.md)
record the compatibility and upgrade guidance.
| Area | Reviewed baseline | Target |
| --- | --- | --- |
| Module | `go 1.25.5`; ReleaseKit v0.2.0 selected through a `tool` directive and module requirement. | `go 1.26.0`; the same CLI tool dependency selects ReleaseKit v0.3.0. |
| Release toolchain | Go 1.25.5 selected in the runbook. The review environment has Go 1.26.8. | Go 1.26.8, documented separately from the Go 1.26.0 consumer minimum. |
| Launcher | `scripts/release` builds the module-selected native CLI in readonly mode and delegates publication with argument, status, and stream preservation. | The same bootstrap and delegation use v0.3.0 under the selected compatible toolchain. |
| Profile | `releasekit.json` specifies product, remote, and expected push endpoint; validation uses the default suite. | The same minimal source-only profile. |
| Evidence | Deterministic launcher tests and an opt-in publication exercise against disposable local Git repositories exist. | Those boundaries work with the upgraded module selection and toolchain. |
| Documentation | Policy, runbook, and consumer guide describe v0.2.0 and/or the Go 1.25.5 selection. | Canonical owners describe the implemented upgrade and its consumer impact. |
The upstream CLI, profile schema, and public signatures are unchanged. ReleaseKit
itself raises its minimum from Go 1.25.0 to 1.26.0; its dependency versions are
unchanged from v0.2.0. The original planning review did not run a test suite or
publication exercise; completed upgrade validation is recorded below.
## Target end state
### Module selection and Go compatibility
The root [go.mod](../../go.mod) declares **Go 1.26.0** and selects
**ReleaseKit v0.3.0** for `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit`.
The corresponding [go.sum](../../go.sum) records the resolved checksums. The
existing tool declaration retains the executable through ordinary module tidy.
The tool shares CommandKit's module graph, so the new minimum applies to library
consumers as well as maintainers even though production packages do not import
ReleaseKit. This is an intentional compatibility change. Go 1.25 consumers need
to upgrade before adopting the CommandKit revision containing it.
The consumer minimum remains the initial stable release of the Go 1.26 series.
A newer release-validation patch does not raise that floor by itself. The
[release policy's toolchain rules](../policy/release.md#consumer-minimum-and-release-toolchain)
define the support presumption and compatibility treatment. No additional
minimum-version test matrix or promise of identical results across toolchains
is introduced.
### Ownership and publication behavior
ReleaseKit remains maintainer tooling. The root `commandkit` facade and internal
Cobra adapter keep their existing responsibilities; this upgrade adds no runtime
ReleaseKit import, public wrapper, or operator-facing command family.
The existing launcher remains the publication entry point. It builds the native
CLI from the committed module selection with readonly metadata and automatic
workspace/toolchain switching disabled. The maintainer's selected `go` on `PATH`
is used for bootstrap and candidate validation. A `toolchain` directive is not
needed to make this launcher select that executable; setup belongs in the runbook.
CommandKit continues to publish an annotated source tag after its candidate is
available on the authoritative branch. ReleaseKit owns validation, publication
guards, tag creation, and publication outcome reporting. CommandKit owns the
candidate, version, note, profile, and runbook. Successful publication remains
separate from optional delivery investigations under the existing release policy.
### Benefits within the selected scope
ReleaseKit v0.3.0 reduces output-copying and retention during Go command
execution, preserving full failure diagnostics and underlying causes. That
improvement benefits CommandKit's default candidate suite.
The upstream Git reader, file-check caches, cancellation cleanup, asset hashing,
and runtime-version improvements remain upstream responsibilities. Our current
profile does not enable optional committed-file checks or hosted artifact
delivery. Their improvements are available if those capabilities are deliberately
selected later; this upgrade does not enable them. No CommandKit latency or
allocation target is part of adoption.
## Completed upgrade work
### Module and toolchain alignment
- [x] Select Go 1.26.8 under OD-1 and document its installation
and `PATH` setup in the runbook. Use that toolchain for upgrade validation and
subsequent release tasks governed by the procedure.
- [x] Upgrade the existing CLI tool dependency to v0.3.0 and set the Go directive to
exactly 1.26.0 using ordinary Go module tooling. Review the resulting module
and checksum changes, including any automatically generated toolchain metadata.
Keep the consumer floor separate from the maintainer patch selection.
- [x] Prepare dependencies before offline validation. The local sibling checkout is
review evidence, not a replacement module or build prerequisite. Diagnose any
checksum failure using upstream guidance and retain checksum verification.
- [x] Review incidental module changes. ConfigKit, PromptKit, and backend upgrades
are separate work; v0.3.0 does not require new versions of its own dependencies.
### Launcher and profile verification
- [x] Confirm the existing launcher builds the upgraded native executable from the
module-selected package and preserves publication arguments, streams, and
statuses. Confirm that the executable identifies ReleaseKit v0.3.0.
- [x] Retain the current profile and launcher design. Change implementation only if
a demonstrated compatibility issue requires it; no migration is indicated by
the reviewed upstream CLI or schema.
- [x] Reuse existing launcher tests. Adjust fixtures only where the selected version
or Go requirement actually affects their behavior. An older version string
used to test rejection of an independent package pin need not be replaced just
because the adopted version changes.
### Canonical documentation and provenance
- [x] Update [docs/policy/release.md](../policy/release.md) to identify the selected
ReleaseKit version while retaining its v1.6 upstream provenance and local
source-only rules. This tooling upgrade is not another policy-template adoption.
- [x] Update [docs/release.md](../release.md) with the selected Go 1.26 patch,
executable setup commands, and v0.3.0 source-pinned upstream references. Keep
versioning rules in the policy and operations in the runbook.
- [x] Update the [consumer guide](../consumers/guide.md#go-compatibility) to explain
the Go 1.26.0 minimum and shared tool-module reason. The current attribution
of the floor to PromptKit's Go 1.25.5 requirement becomes obsolete.
- [x] Check contributor navigation and current references affected by the upgrade.
Historical planning records and immutable release notes retain their original
facts; avoid replacing every historical version string.
- [x] Apply the [OSS policy](../policy/oss.md) to the actual material scope. Tool use
alone does not require a new attribution entry. Update entries or license links
if incorporated material or dependency selection changes require it.
### Validation and completion evidence
Use the existing validation boundaries rather than adding recurring release gates:
- [x] Run the deterministic offline default suite under the selected toolchain,
covering the public library and native launcher behavior.
- [x] Exercise the existing opt-in local publication test with the upgraded module
selection after cache preparation. It covers a real native bootstrap, exact
candidate tag publication to a disposable bare repository, one candidate suite,
clean fixture state, and endpoint-mismatch preflight. Keep it opt-in in normal
development and publication; this is upgrade evidence, not a new release gate.
- [x] Inspect production package dependencies to confirm ReleaseKit remains outside
the root library and internal adapter import closures. Review module selection
and CLI version evidence separately from that runtime boundary.
- [x] Review canonical-document changes, local links/fragments, provenance, and
whitespace. Record the actual toolchain, resolved module revision, checks run,
outcomes, and any qualifications when marking this roadmap implemented.
The [developer guide](../development.md#release-tooling-development) owns the
existing local exercise commands. Reuse successful evidence for unchanged
content; adding a benchmark requirement, platform matrix, or upstream suite
rerun is not necessary to establish this upgrade's selected behavior.
## Completion criteria
The upgrade is implemented when the root module selects v0.3.0 with Go 1.26.0,
the documented release toolchain can bootstrap and validate it, existing
launcher/publication behavior has the stated evidence, and current documentation
accurately describes the minimum and ownership boundaries. Release notes carry
the compatibility explanation when a release containing the change is prepared.
This work does not publish CommandKit, add hosted delivery, split tooling into a
second module, or change standard CLI/API semantics. Actual publication and its
fresh version-matched note remain a separate release-preparation task.
## Completion evidence
Implemented from `efc5065` using Go 1.26.8 on Linux/amd64. The module now
contains `go 1.26.0`, the retained CLI tool declaration, and the ReleaseKit
v0.3.0 requirement/checksums. Module tidy retained that selection. No other
dependency versions changed and no toolchain directive was added. The downloaded
module's origin identifies the reviewed `e43df4416e0ed987349b2ea04a2c68c25e552772`
tag revision; dependency preparation required no checksum repair.
Validation completed:
- Default suite: `go test -mod=readonly -count=1 ./...` passed with `GOWORK=off`,
`GOTOOLCHAIN=local`, `GOPROXY=off`, `GONOPROXY=none`, and `GOSUMDB=off`.
This includes public library and deterministic launcher tests; existing test
sources were sufficient and unchanged.
- The existing local publication exercise passed with
`COMMANDKIT_RELEASE_INTEGRATION=1` and the same offline settings:
`go test -mod=readonly -count=1 ./scripts -run '^TestReleaseIntegration$' -v`.
It published only within disposable repositories and proved the candidate,
single suite execution, clean fixture, and endpoint-mismatch behaviors above.
- A native CLI was built in ignored `.releasekit/bin/` storage with the launcher's
host-target and readonly settings. Its `version` output was `releasekit v0.3.0`;
`go version -m` identified Go 1.26.8 and the module-selected v0.3.0 build.
- `go list -mod=readonly -deps` for the root package and `internal/cobra` found no
ReleaseKit, Goldmark, or `golang.org/x/mod` runtime imports. The launcher and
profile were unchanged. ReleaseKit remains tool-only material; no attribution
entry or copied source was added under the existing OSS policy.
- The runbook, release policy's local tool selection, consumer compatibility
explanation, and contributor navigation now describe the upgrade. The
release policy remains based on v1.6 at its existing upstream revision.
Local documentation destinations/fragments, shell snippet syntax, and
whitespace checks passed.
This verifies the upgrade without publishing CommandKit or establishing an
additional recurring release check. No upstream benchmark or test suite was
rerun; the evidence concerns CommandKit's selected integration.
## Release preparation follow-up
The next CommandKit release note must explain the Go minimum increase and
required consumer action. Its CommandKit version is selected during release
preparation under policy, with the matching note and footer. That separate
publication task was not performed or authorized by this upgrade; the current
consumer guide already explains the compatibility change.
## Selected decisions
### OD-1: release-validation patch version
**Resolved: Go 1.26.8, accepted by the user and implemented.** It is the
toolchain available in the review environment and used by ReleaseKit v0.3.0's maintainers. Using it avoids
an additional installation in that environment and benefits from later patch
updates within the selected Go series. Declare `go 1.26.0` for consumers and
document 1.26.8 as the runbook's release-toolchain selection. The adopted
policy permits same-series support to be presumed from this validation; a
second mandatory run on 1.26.0 is unnecessary absent a concrete concern.
**Alternative considered: Go 1.26.0.** It validates directly at the consumer floor
and makes the minimum and release toolchain identical initially. It requires
installing that patch in the reviewed environment and forgoes subsequent patch
updates. It is viable if direct minimum-toolchain validation is preferred, but
the current policy does not require that extra alignment.

138
docs/roadmap/remediation.md
View File

@@ -1,138 +0,0 @@
# Performance implementation review findings
Status: R-01 complete; all recorded remediation work is addressed.
Date: 2026-10-09.
## Review scope and authority
Reviewed the performance implementation at `18ff0d6`, covering the changes after
`1274ae7` against the [efficiency target](performance.md), selected OD-1/OD-2
approaches, [implementation record](implementation.md), accepted
[ADRs](../adr/), and applicable architecture, agent, and testing policies.
The completed ReleaseKit review findings remain available in
[Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/18ff0d6/docs/roadmap/remediation.md).
Release tooling is outside this implementation review.
## Architecture assessment
The selected structure is present:
- The root facade owns declarations, registration, typed inputs, standard
handlers, and invocation outcomes. Cobra and pflag remain inside the internal
adapter; the changes add no exported API declarations.
- Each `App` lazily retains immutable neutral command metadata. Successful
nonempty registration invalidates it; failed and empty registrations leave
it intact. Pending declarations are validated and cloned before installation
without copying the previously installed registry.
- Each invocation prepares a fresh mutable adapter session, reusing it for
parsing, help, and usage. Presentation can refresh metadata after callback
registration without rerunning input callbacks. Backend commands map directly
to declarations; parent links reconstruct the selected path.
- Configuration registration prepares ordered scopes, name lookup, installed
operations, and discovery metadata. Invocation contexts and acquisition remain
live callbacks. PromptKit builds the requested report format, and aggregate
configuration framing scans only the YAML preamble while retaining the
selected full native and framed buffers.
These changes implement PF-01–PF-06. The review identified an ownership
regression in the session integration, corrected under R-01 below. The
[internal overview](../internal/overview.md) owns the maintained package inventory.
## R-01: restrict built-in help interception to the root command
**Priority:** high. **Category:** dispatch correctness, application ownership,
and unintended restriction.
**Location:** [execute.go](../../execute.go), `App.Execute`, line 45 at the
reviewed revision. Introduced by `a7960e5`.
The dispatcher selects a leaf declaration and then checks `command.name ==
"help"` to identify the built-in help operation. That matches an application
command named `help` at any depth. Its ordinary typed input is then asserted to
be CommandKit's private `*helpInput`, producing an operational failure instead
of invoking the registered application handler.
A public API reproduction created a runnable `help` command with `struct{}`
input, composed it beneath the application-owned `session` group, and passed the
group to `New`. Construction and registration succeeded. Execution produced:
```text
args=[session help] kind=operational status=1 cause=built-in help input has an unexpected type handlerCalls=0
args=[help session] kind=success status=0 cause=<nil> handlerCalls=0
args=[session help --help] kind=success status=0 cause=<nil> handlerCalls=0
```
The first invocation must reach the application handler. The remaining two are
metadata help requests and appropriately leave that handler uninvoked.
[ADR 0001](../adr/0001-command-dispatch-and-inputs.md#ownership-and-namespace-structure)
and the [architecture policy](../policy/architecture.md#command-and-application-ownership)
leave custom names and semantics with applications outside standard families.
[ADR 0006](../adr/0006-command-grammar.md) also encourages consistent verbs,
including `help`. The selected session integration specifically concerns the
reserved **top-level** help command. Matching only the leaf name effectively
introduces a global reservation of that name, although registration still
accepts it. No such additional restriction was selected.
Required work:
- [x] Identify the root built-in help command by its complete selected path
or an equivalent explicit reserved-command identity. A root-path check such
as `len(parsed.Path) == 1 && parsed.Path[0] == "help"` is sufficient for the
current registry. Other runnable declarations must continue to their handler.
- [x] Add a public behavior regression for an application-owned nested `help`
command. Verify it receives its typed input and that its handler outcome is
preserved. Keep local `--help` and `help session help` as metadata operations.
- [x] Retain existing root help, invalid-target, usage, fresh-invocation,
registration-refresh, and diagnostic behavior. Use existing coverage where
sufficient; verify the relevant regression and default suite after the fix.
Do not remediate this by rejecting nested `help` names or imposing new command
naming rules. Keep the session optimization and established ownership boundary.
Mark this item complete only after the correction and its evidence are recorded.
### Completion evidence
**Completed:** `App.Execute` now recognizes the built-in help command only when
its selected path is the root `help` command. Nested application commands keep
their existing handler path and naming freedom; session reuse is retained.
The public regression `TestExecuteRunsApplicationOwnedNestedHelp` verifies a
required typed operand reaches the nested handler and preserves its domain,
status, and cause. Local `session help --help` and explicit `help session help`
render the command's metadata without invoking that handler or requiring its
execution operand.
The regression first failed against the original dispatcher with the reported
unexpected-input-type failure and passed after the correction. Focused validation
and the full default suite passed with readonly, offline module access:
```sh
GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off go test -mod=readonly -count=1 . -run '^TestExecuteRunsApplicationOwnedNestedHelp$'
GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off go test -mod=readonly -count=1 ./...
```
Existing root help, invalid-target, usage, fresh-invocation, registration-refresh,
and diagnostic tests passed. Changed Go files were formatted; document links
and whitespace checks passed. No new public contract or command-name restriction
was introduced.
## Original review evidence and limits
- Reviewed the production diffs, changed behavioral tests, benchmark fixtures,
architecture documentation, and completion/measurement records. Traced cache
invalidation, session refresh, input preparation, scope lookup, acquisition,
YAML framing, and requested-format delivery.
- Executed the public consumer reproduction above from a temporary file outside
the repository with readonly, offline module access. No repository test or
production code was added or changed during this review.
- The implementation record reports a successful default suite at `62b4a48`,
the last production-code revision. This review did not rerun that suite or the
benchmarks. Allocation improvements and registration tradeoffs are documented
there; its final cross-run timing comparison is explicitly inconclusive under
differing host load. This review does not establish a latency guarantee.
- No other issue requiring remediation was identified in the reviewed scope.
The changes do not establish concurrent dispatch, application startup rules,
provider-result caching, new release gates, or additional public API promises.