docs(roadmap): add #388 diff help json rejected

ROADMAP.md

@@ -6300,3 +6300,4 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 358. **Top-level `cost --help --output-format json` hangs with zero stdout/stderr instead of returning bounded command help JSON** — dogfooded 2026-04-30 for the 02:00 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `d95b230c`. After rebuilding and verifying the binary provenance, repeated bounded runs of `timeout 8 ./rust/target/debug/claw cost --help --output-format json` exited `124` with `stdout=0` and `stderr=0`. In the same rebuilt binary, `version --output-format json` returned promptly with version/build metadata, proving the binary itself and the JSON output path are reachable; the hang is specific to the cost help path, though other help surfaces have separate known JSON contract issues (#356/#357). **Required fix shape:** (a) make `cost --help --output-format json` return static/bounded stdout JSON with `kind:"help"` or `kind:"cost"`, `action:"help"`, usage, options, examples, supported output formats, and related slash/direct commands; (b) ensure help rendering does not initialize slow cost/session/accounting providers; (c) if any dynamic provider is accidentally consulted, return a typed JSON timeout/unavailable error instead of hanging; (d) add regression coverage proving cost help in JSON mode returns within a deterministic budget. **Why this matters:** cost/tokens surfaces are commonly consumed by automation for budgeting. If even cost help can hang silently, claws cannot discover cost command semantics or present safe budget diagnostics before running potentially slow accounting paths. Source: gaebal-gajae dogfood follow-up for the 02:00 nudge on rebuilt `./rust/target/debug/claw` `d95b230c`.
 380. **Top-level `tokens --help --output-format json` hangs with zero stdout/stderr instead of returning bounded command help JSON** — dogfooded 2026-04-30 for the 02:30 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `d95b230c`. After verifying #358 covered `cost --help`, a fresh adjacent probe on the token-budget surface showed the same silent failure class: repeated bounded runs of `timeout 8 ./rust/target/debug/claw tokens --help --output-format json` exited `124` with `stdout=0` and `stderr=0`. In the same rebuilt binary, `version --output-format json` returned promptly with version/build metadata, proving the binary itself and JSON output path are reachable. This is distinct from #358's cost help hang: the affected surface is the sibling `tokens` command help, which agents use before estimating prompt/session token budgets. **Required fix shape:** (a) make `tokens --help --output-format json` return static/bounded stdout JSON with `kind:"help"` or `kind:"tokens"`, `action:"help"`, usage, options, examples, supported output formats, and related slash/direct commands; (b) ensure help rendering does not initialize slow token accounting, session, or provider state; (c) if any dynamic provider is consulted, return a typed JSON timeout/unavailable error instead of hanging; (d) add regression coverage proving tokens help in JSON mode returns within a deterministic budget. **Why this matters:** token budgeting is a preflight clawability surface. If help hangs silently, automation cannot safely discover how to inspect or constrain token usage before running expensive prompts, and budget-aware wrappers stall at the discovery step. Source: gaebal-gajae dogfood follow-up for the 02:30 nudge on rebuilt `./rust/target/debug/claw` `d95b230c`.
 381. **Top-level `cache --help --output-format json` hangs with zero stdout/stderr instead of returning bounded command help JSON** — dogfooded 2026-04-30 for the 03:00 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `d95b230c`. After #358 and #380 landed for the cost/tokens preflight help hangs, a fresh adjacent probe on the cache-control surface showed the same silent failure class: repeated bounded runs of `timeout --kill-after=1s 8s ./rust/target/debug/claw cache --help --output-format json` exited `124` with `stdout=0` and `stderr=0`. In the same rebuilt binary, `version --output-format json` returned promptly with version/build metadata, proving the binary itself and JSON output path are reachable. This is distinct from the separate `/cache` slash-command envelope mismatch class: the affected surface here is top-level `cache` command help, where agents need bounded local discovery before deciding whether to inspect, clear, or summarize cache state. **Required fix shape:** (a) make `cache --help --output-format json` return static/bounded stdout JSON with `kind:"help"` or `kind:"cache"`, `action:"help"`, usage, options, examples, supported output formats, and related slash/direct commands; (b) ensure help rendering does not initialize slow cache/session/provider state; (c) if any dynamic provider is consulted, return a typed JSON timeout/unavailable error instead of hanging; (d) add regression coverage proving cache help in JSON mode returns within a deterministic budget. **Why this matters:** cache inspection and cleanup are recovery/control-plane operations. If cache help hangs silently, claws cannot safely discover cache semantics before attempting cleanup, and automation stalls before it can choose a non-destructive cache action. Source: gaebal-gajae dogfood follow-up for the 03:00 nudge on rebuilt `./rust/target/debug/claw` `d95b230c`.
+388. **Top-level `diff --help --output-format json` is rejected as an unexpected argument instead of returning help or a structured slash-command handoff** — dogfooded 2026-04-30 for the 06:30 nudge on current `origin/main` / local workspace while the checked-out `./rust/target/debug/claw` binary still reported embedded `git_sha` `d95b230c`. A fresh probe on the diff/preflight surface showed that `./rust/target/debug/claw diff --help --output-format json` exits `1` with `stdout=0` and `stderr=109`; stderr contains JSON `{"error":"unexpected extra arguments after `claw diff`: --help","hint":null,"kind":"unknown","type":"error"}`. The wrapper then emits additional non-JSON prose guidance (`claw diff is a slash command...`) outside the captured JSON in the outer command output. In the same workspace, `version --output-format json` returned promptly with version/build metadata, proving the binary itself and JSON output path are reachable. This is distinct from help hangs (#358/#380/#381/#382/#383/#387), plaintext help fallbacks (#384/#385/#386), and `/diff` raw patch structure issues: the affected surface is top-level diff help/discovery, where claws need a machine-readable way to learn that diff is slash/resume-only and how to invoke it safely. **Required fix shape:** (a) make `diff --help --output-format json` return a valid stdout JSON help/handoff envelope with `kind:"help"` or `kind:"diff"`, `action:"help"`, `supported_invocations`, `resume_required:true`, examples such as `claw --resume latest /diff`, and related commands; (b) if top-level `diff` remains unsupported, classify the response as `code:"slash_command_only"` or equivalent instead of generic `kind:"unknown"`/`type:"error"`; (c) keep all primary JSON-mode payloads on the documented stream and avoid mixing additional prose with JSON-mode errors; (d) add regression coverage proving `diff --help --output-format json` is machine-readable and does not report `--help` as an unexpected extra argument. **Why this matters:** diff inspection is a core preflight/review surface. If help discovery itself is treated as an invalid diff argument, automation cannot learn the resume-only contract without scraping error prose, and safe review flows break before they can inspect changes. Source: gaebal-gajae dogfood follow-up for the 06:30 nudge on rebuilt/local `./rust/target/debug/claw` `d95b230c`.