Keep nested help commands with application handlers

This commit is contained in:
2026-10-09 03:03:10 +00:00
parent c3a5cae012
commit dacc743551
3 changed files with 89 additions and 8 deletions

View File

@@ -1,6 +1,6 @@
# Performance implementation review findings
Status: R-01 requires remediation.
Status: R-01 complete; all recorded remediation work is addressed.
Date: 2026-10-09.
@@ -36,8 +36,8 @@ The selected structure is present:
configuration framing scans only the YAML preamble while retaining the
selected full native and framed buffers.
These changes implement PF-01–PF-06. The dispatch defect below is an ownership
regression in the session integration, rather than a missing subsystem. The
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
@@ -78,14 +78,14 @@ accepts it. No such additional restriction was selected.
Required work:
- [ ] Identify the root built-in help command by its complete selected path
- [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.
- [ ] Add a public behavior regression for an application-owned nested `help`
- [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.
- [ ] Retain existing root help, invalid-target, usage, fresh-invocation,
- [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.
@@ -93,7 +93,33 @@ 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.
## Evidence and limits
### 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