commandkit/docs/roadmap/remediation.md

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, selected OD-1/OD-2 approaches, implementation record, accepted ADRs, and applicable architecture, agent, and testing policies.

The completed ReleaseKit review findings remain available in Git history. 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 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, 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:

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 and the architecture policy leave custom names and semantics with applications outside standard families. ADR 0006 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:

• 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.
• 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.
• 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:

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.