docs(roadmap): add #403 — agents/mcp/skills list-envelope schema drift (count/working_directory/summary)

ROADMAP.md

@@ -6301,4 +6301,4 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 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`.
 
-391. **`version --output-format json` includes a `message` field containing human-readable prose (`"Claw Code\n  Version  0.1.0\n  Git SHA  ..."`) in addition to the structured fields `version`, `git_sha`, `target`; no `action` field; no `build_date`, `platform`, or `rustc_version` structured fields — the prose is embedded inside the JSON envelope instead of being derivable from the structured fields** — dogfooded 2026-04-30 by Jobdori on `e939777f`. Running `./claw --output-format json version` returns `{"git_sha":"5eb1d7d8","kind":"version","message":"Claw Code\n  Version  0.1.0\n  Git SHA  5eb1d7d8\n  Target  aarch64-apple-darwin\n  Build date  2026-04-30","target":"aarch64-apple-darwin","version":"0.1.0"}`. The `message` field duplicates structured data as prose, preventing automation from using the JSON without also parsing the prose for any field not promoted to a top-level key (e.g., `build_date`). No `action` field present (compare `agents/mcp` which include `action:"list"`). No `platform`, `rustc_version`, or `build_timestamp_ms` structured fields. **Required fix shape:** (a) remove or deprecate `message` prose field from `--output-format json` output; (b) add structured `build_date` (ISO-8601), `platform`, and `rustc_version` fields; (c) add `action:"version"` for envelope consistency; (d) add regression coverage proving the JSON response contains no prose-only fields. Source: Jobdori live dogfood, `e939777f`, 2026-04-30.
+403. **`agents`, `mcp`, and `skills` list-subcommands emit JSON envelopes with three different top-level schemas for the same list/inventory concept: `agents` has `count`, `working_directory`, `agents[]`, and `summary{}`; `mcp` has `configured_servers` (int, no `count`), `working_directory`, `servers[]`, and `status` but no `summary`; `skills` has `summary{}` and `skills[]` but no `count`, no `working_directory` — automation must hard-code three separate parsers for structurally equivalent list operations** — dogfooded 2026-04-30 by Jobdori on `e939777f`. Running all three: `agents` → `{action,agents[],count,kind,summary{active,shadowed,total},working_directory}`; `mcp` → `{action,config_load_error,configured_servers,kind,servers[],status,working_directory}`; `skills` → `{action,kind,skills[],summary{active,shadowed,total}}`. The fields that vary: (a) `count` present in `agents`, absent in `mcp` and `skills`; (b) `working_directory` present in `agents` and `mcp`, absent in `skills`; (c) `summary{}` present in `agents` and `skills`, absent in `mcp`; (d) `configured_servers` is an integer count unique to `mcp` that doesn't appear in any other list surface; (e) `status:"ok"` appears in `mcp` only; (f) `config_load_error` appears in `mcp` only. **Required fix shape:** (a) define a canonical list-response envelope shared by `agents`, `mcp`, `skills`, and any future resource-list subcommands: `{kind, action:"list", count, items[], working_directory, summary{}, schema_version}`; (b) retire or alias surface-specific count fields (`configured_servers`) behind the canonical `count`; (c) add `config_load_error` and `status` as optional fields available on any list surface; (d) add regression coverage proving all three commands share the same top-level key set. Source: Jobdori live dogfood, `e939777f`, 2026-04-30.