Describe exact leaf command paths

Traceability

• Spec ID: issue-33-describe-leaf-command-paths
• Story: #33
• Status: Implemented

Intent

Make better-harness command describe resolve the complete registered command path so contributors and automation can inspect a leaf command without executing its capability. A two-segment request must not silently fall back to metadata for the parent command.

Acceptance Scenarios

• AC-1: command describe <parent> <leaf> --json returns parser-safe metadata for the exact registered leaf, including its canonical path, audience, and script, without dispatching the leaf.
• AC-2: The human form identifies the canonical two-segment path and reports the leaf audience, script, and summary or description when present.
• AC-3: One-segment parent descriptions and parent-alias canonicalization remain unchanged.
• AC-4: An unknown leaf fails with the existing unknown-subcommand diagnostic in human and JSON modes instead of returning parent metadata.
• AC-5: A third command-path segment fails with a bounded invalid-path diagnostic in human and JSON modes instead of being ignored.

Non-goals

• Do not execute a described command or inspect capability-private runtime state.
• Do not add leaf aliases, change command registration, or change dispatch.
• Do not redesign command inventory, OpenCLI schema, global option parsing, or command output contracts outside command describe.

Plan and Tasks

1. Add a registry-owned lookup for an exact canonical command path while preserving the existing parent metadata lookup.
2. Parse the describe path after removing the recognized --json bootstrap flag, reject paths longer than two command segments, and distinguish unknown parents from unknown leaves.
3. Render leaf descriptions through the existing human and JSON output paths.
4. Add focused regression coverage for group and direct-command leaves, human and JSON output, parent compatibility, unknown leaves, extra path segments, and non-dispatch behavior.
5. Record the user-visible correction in CHANGELOG.md and run focused, full, documentation, package, and diff validation.

Test and Review Evidence

• Before implementation, the five focused #33 regression cases failed against origin/main: 0 passed, 5 failed.
• AC-1 through AC-5 and frozen root CLI contracts: node --test --test-concurrency=1 test/better-harness-cli.test.mjs test/scripts-refactor-contract.test.mjs completed with 39 passed, 0 failed, and 1 Windows symlink-permission skip.
• The additional sparse leaf human-output check passed: 1 passed, 0 failed.
• Documentation integrity: node scripts/doc-link-graph/cli.mjs skills/better-harness reported 34 files and 50 links; node --test test/doc-link-graph.test.mjs passed 6 of 6.
• Package boundary: npm run pack:verify passed with 359 npm entries and 382 runtime-zip entries.
• Final full regression: node --test completed with 1015 passed, 10 failed, and 3 skipped. Every failure was a Windows host error before or after the assertion body: directory cleanup returned EBUSY, or symlink creation returned EPERM. The changed CLI test file passed 32 tests with one symlink skip and no failure.
• A same-name selected run on untouched origin/main reproduced 6 of the 10 failures with the same EBUSY/EPERM classes. Four cleanup-sensitive cases passed in that attempt; the baseline also produced nondeterministic EBUSY failures in the same unchanged test areas.
• git diff --check passed.

Risk is limited to root CLI introspection. Dispatch, registry contents, parent metadata, schemas, and capability-owned scripts remain unchanged.