From 3b9332b814b64a0842d09d01cecb669114b12ffa Mon Sep 17 00:00:00 2001 From: Yeachan-Heo Date: Thu, 21 May 2026 11:30:52 +0000 Subject: [PATCH] docs(roadmap): add slash json error contract gap --- ROADMAP.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ROADMAP.md b/ROADMAP.md index eb01b917..8fd3a462 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -6631,3 +6631,5 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed) 537. **`pr` and `issue` malformed arguments zero-byte hang, so GitHub artifact helpers fall through to runtime instead of validating their context/output grammar** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 10:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@87fa106` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw pr bogus`, `claw pr bogus --output-format json`, `claw pr --output-format json bogus`, and `claw issue bogus` each timed out after 6s with `stdout=0`/`stderr=0`; `claw issue bogus --output-format json` then entered the same zero-output wait before the run was killed. `pr [context]` and `issue [context]` may intentionally accept freeform context, but then they must either treat trailing text as context and fail with a bounded missing-auth/no-session/model-preflight diagnostic, or document that direct non-REPL invocation is unsupported and reject it. They should not silently wait before any event/log signal. **Required fix shape:** (a) define the direct CLI contract for `pr`/`issue`: supported one-shot artifact generation vs REPL-only helper; (b) if REPL-only, return `kind:"slash_command_repl_only"` with usage for bare/context/JSON forms; (c) if one-shot is supported, parse context and JSON/output flags strictly, then preflight auth/session requirements with bounded typed errors; (d) add elapsed-time regressions for `pr bogus`, `pr bogus --output-format json`, `pr --output-format json bogus`, `issue bogus`, and `issue bogus --output-format json`; (e) align with #536's `commit` handling so all GitHub/artifact helpers share one no-fallthrough parser. **Why this matters:** PR/issue generation is a high-value automation surface. A malformed or unsupported direct invocation should not look like prompt delivery, GitHub auth, or artifact generation has deadlocked; users need an immediate contract/error before trusting the helper in scripts. Source: gaebal-gajae dogfood response to Clawhip message `1506967318054436914` on 2026-05-21. 538. **Direct slash-command invocations return bounded interactive-only errors but use `kind:"unknown"`, so automation cannot distinguish expected REPL-only usage from unclassified failures** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 11:00 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@236d345` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw /status`, `claw /diff`, `claw /version`, and `claw /session list` all returned bounded nonzero errors explaining the slash command is interactive-only and suggesting `claw --resume ... /` where applicable, but every envelope used `[error-kind: unknown]`. `claw /status --output-format json` also returned a bounded usage error for unexpected args, again with `kind:"unknown"`. Positive control `claw /help` exited 0 with usage. This is better than the zero-byte fallthrough family, but still a machine-contract gap: direct slash command misuse is a deterministic, expected CLI condition, not an unknown internal failure. **Required fix shape:** (a) add typed error kinds for direct slash command routing: `slash_command_repl_only`, `slash_command_unexpected_args`, and/or `slash_command_resume_required`; (b) include fields such as `slash`, `resume_supported`, `usage`, `suggested_invocations`, and `unexpected_args`; (c) make JSON mode return the same typed envelope without prose scraping; (d) add regressions for `/status`, `/diff`, `/version`, `/session list`, `/status --output-format json`, and `/help`; (e) reserve `kind:"unknown"` for genuine unclassified failures only. **Why this matters:** slash commands are a major entrypoint for users migrating from REPL to scripts. Wrappers need to distinguish “this command is REPL-only; use --resume or top-level equivalent” from actual CLI/runtime failure without parsing English help text. Source: gaebal-gajae dogfood response to Clawhip message `1506974870372745368` on 2026-05-21. + +539. **Direct slash commands reject `--output-format json` as unexpected args and still print prose `kind:"unknown"` errors to stderr, so JSON-mode callers cannot get machine-readable slash diagnostics** — dogfooded 2026-05-21 from the `#clawcode-building-in-public` 11:30 UTC nudge on `/home/bellman/Workspace/claw-code-pr2967` with branch/origin `docs/roadmap-workdir-provenance@ad6b573` and binary `./rust/target/debug/claw` built from source SHA `25d663d`. Clean-home probes from a minimal temp workspace: `claw /diff --output-format json`, `claw /version --output-format json`, `claw /session list --output-format json`, `claw /config env --output-format json`, and `claw /agents list --output-format json` all exited nonzero with `stdout=0` and stderr-only prose usage/error output. Every case used `[error-kind: unknown]`; none emitted a JSON error envelope despite an explicit `--output-format json` token. This is distinct from #538's generic slash `unknown` kind drift: JSON-mode slash invocations are both rejected as unexpected args and denied machine-readable error output. **Required fix shape:** (a) decide whether direct slash commands support `--output-format json`; if yes, parse it before slash-arg validation and return structured errors; if no, reject with a typed JSON-capable `unsupported_flag_for_slash_command` envelope; (b) include `slash`, `unexpected_args`, `usage`, `resume_supported`, and `suggested_top_level_command` fields; (c) return JSON on stdout or stderr consistently with other JSON error contracts; (d) add regressions for the five probes above plus valid `/help --output-format json` behavior (support or typed reject); (e) replace `kind:"unknown"` with slash-specific kinds from #538. **Why this matters:** wrappers often add `--output-format json` globally to every probe. Slash-command errors currently force prose scraping and make expected REPL-only or unsupported-format cases indistinguishable from unknown failures. Source: gaebal-gajae dogfood response to Clawhip message `1506982418014277683` on 2026-05-21.