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`.
 
-413. **`acp --output-format json` leaks internal ROADMAP tracking numbers and implementation notes as top-level JSON fields — `discoverability_tracking:"ROADMAP #64a"` and `tracking:"ROADMAP #76"` are internal backlog references that should not appear in the public machine-readable contract** — dogfooded 2026-04-30 by Jobdori on `e939777f`. Running `claw acp --output-format json` returns a ten-key envelope: `aliases`, `discoverability_tracking`, `kind`, `launch_command`, `message`, `recommended_workflows`, `serve_alias_only`, `status`, `supported`, `tracking`. Two fields are verbatim internal backlog cross-references: `"discoverability_tracking":"ROADMAP #64a"` and `"tracking":"ROADMAP #76"`. These were presumably used during initial scaffolding to track which backlog items the stub relates to, but they are now part of the public JSON contract that automation consumes. The `message` field also contains implementation-note prose (`"ACP/Zed editor integration is not implemented in claw-code yet. \`claw acp serve\`..."`) that describes the build state rather than the command's machine-readable status. **Required fix shape:** (a) remove `discoverability_tracking` and `tracking` from the public JSON envelope or move them to an optional `_debug` or `_meta` sub-object gated on a debug flag; (b) replace `message` prose with a structured `reason` enum (`"not_implemented"`, `"discoverability_only"`, `"serve_only"`) plus optional `detail` string; (c) rename `supported:false` + `status:"discoverability_only"` to a single typed `availability` object with `status`, `reason`, and `target_command` fields; (d) add regression coverage proving the public `acp --output-format json` envelope contains no internal tracking/backlog fields and that `message` is not the sole machine-classifiable signal. **Why this matters:** public JSON APIs should not leak internal ticket references. Automation that snapshots or validates the ACP JSON schema will embed these internal identifiers into external contracts and need to change every time backlog numbering shifts. 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.