docs(roadmap): add #458 — no portable success-detection field across --output-format json envelopes; only kind is universal

[Yeachan-Heo]

ROADMAP pinpoint #458 — cross-subcommand JSON envelope catalog: only kind is universal

Dogfooded for the 2026-05-24 09:00 Clawhip pinpoint nudge (message 1508031832669814834).

Catalog of top-level fields across success envelopes

Clean isolated env, no .claw.json, fresh git-init workspace:

Subcommand	kind	status	action	summary	message	report
status	✅ "status"	✅ "ok"	–	–	–	–
mcp	✅ "mcp"	✅ "ok"	✅ "list"	–	–	–
skills	✅ "skills"	–	✅ "list"	✅	–	–
agents	✅ "agents"	–	✅ "list"	✅	–	–
doctor	✅ "doctor"	–	–	✅	✅	✅
sandbox	✅ "sandbox"	–	–	–	–	–
init	✅ "init"	–	–	–	✅	–
system-prompt	✅ "system-prompt"	–	–	–	✅	–
version	✅ "version"	–	–	–	✅	–

Only kind is universal. Every other top-level discriminator is present on some envelopes and missing on others.

Why it matters

• A claw that does if response["status"] == "ok" works for exactly 2 of 9 subcommands (status, mcp) and silently returns false/None for the other 7 because the field doesn't exist.
• if response["action"] == "list" works for 3 of 9 and breaks for the rest.
• There is no single field a claw can read to determine "did this subcommand succeed?" other than parsing stdout-vs-stderr routing (broken by 我也来合影，比心 #447/合影 #450/来过，留影 #340/MEDIUM POST - Claude Code’s Entire Source Code Was Just Leaked via npm Source Maps — Here’s What’s Inside #341) or checking process exit code (broken by 到此一游 #435/一曲vibecoding ，天涯何处觅知音 #444).

Why distinct from existing items

Existing	Surface
#90 / #91 / #92 / #110 / #115 / #116 / #130	Error envelope shape asymmetry ({error, type} vs {kind, error})
#340 / #341 / #347 / #349 / #350	Specific subcommand envelopes where not-found/unsupported is shaped wrong
#121	doctor message/report byte-duplication (one symptom)
#458	Cross-subcommand catalog of success envelopes — the meta-pattern that the above are individual instances of

This is the structural fact that no single top-level field is present on every success envelope, so no portable success detection is possible across the catalog without per-subcommand special-casing.

Trace

Every envelope is emitted from a separate code path with no shared envelope constructor:

• status JSON at main.rs:5738 emits "status": "ok" directly
• mcp JSON emits both status:"ok" and action:"list"
• skills / agents emit action:"list" and summary but no status
• doctor JSON at main.rs:1905-1923 emits kind/message/report/has_failures/summary{ok,warn,fail,total}/checks[] — no status field at all, while every checks[i] has its own status
• sandbox / init / system-prompt / version each emit different ad-hoc shapes

There is no EnvelopeBuilder / BaseEnvelope shared struct that guarantees a uniform success/error discriminator.

Required fix shape (full detail in ROADMAP entry)

(a) Define a single shared BaseEnvelope: {kind, status: "ok"|"warn"|"error", action: …|null, summary: "<one-line>", details: <command-specific>}. Two universal fields: kind + status. (b) Drop ad-hoc message/report in favor of summary (one line) + optional text_render. (c) doctor rollup: top-level status derived from has_failures and summary.warnings. (d) Contract test that parses every subcommand's JSON, asserts kind matches subcommand name and status ∈ {ok,warn,error}. (e) Doc the envelope in docs/json-envelope-contract.md.

Acceptance check (one-liner)

for c in status mcp skills agents doctor sandbox init system-prompt version; do
  claw $c --output-format json 2>&1 | jq -e '.kind and (.status | IN("ok","warn","error"))' || echo "FAIL: $c"
done

Should print no FAILs.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]