docs(roadmap): add #336 — session subcommand resume inconsistency and type/kind error mismatch

ROADMAP.md

@@ -6265,3 +6265,5 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 324. **Stale local debug binaries can impersonate the current workspace because version/status/doctor do not compare embedded build provenance to repo HEAD** — dogfooded 2026-04-29 on current `origin/main` / workspace HEAD `e7074f47` after PR #2838. The working tree was at `e7074f47`, but running `./rust/target/debug/claw version --output-format json` reported embedded `git_sha` `1f901988`. `status` and `doctor` remained green and exposed no warning that the executable under test was stale relative to the workspace HEAD, nor any structured build-provenance freshness signal that downstream claws could use to decide whether the observed behavior came from the checked-out code or an older debug artifact. This is a repo-identity opacity gap: the JSON truth surfaces can look authoritative while actually describing a different binary lineage than the source tree being dogfooded. **Required fix shape:** (a) compare the embedded build `git_sha` / build date with the current workspace git HEAD and dirty state when the binary can discover a containing worktree; (b) expose redaction-safe structured fields in `version --output-format json`, `status --output-format json`, and `doctor --output-format json`, including `binary_provenance`, `workspace_head`, and `stale_binary` (with enough reason/detail to distinguish clean match, dirty workspace, unknown workspace, and definite stale SHA mismatch); (c) warn in human/text mode when executing a stale local debug binary such as `./rust/target/debug/claw` so dogfooders do not trust old behavior as current-main evidence; (d) avoid leaking secrets or absolute sensitive paths beyond the existing workspace-identification policy; (e) add regression/fixture coverage for matching HEAD, dirty workspace, no-worktree/unknown provenance, and stale embedded SHA cases. **Why this matters:** status/doctor/version are supposed to be the machine-readable basis for dogfood truth. If a stale binary can report a different `git_sha` than the checked-out repo without any freshness warning, claws can file or verify bugs against the wrong code and waste cycles chasing already-fixed or not-yet-built behavior. Source: gaebal-gajae dogfood follow-up from current main `e7074f47` after PR #2838; observed `./rust/target/debug/claw version --output-format json` reporting `git_sha` `1f901988` with no stale-binary-vs-workspace-HEAD warning.
 
 325. **`help --output-format json` returns valid JSON but hides the actual help schema inside one prose `message` string** — dogfooded 2026-04-29 on current `origin/main` / workspace HEAD `d607ff36`. Running `./rust/target/debug/claw help --output-format json` produces parseable JSON, but the object only exposes top-level keys like `kind` and `message`; all command names, global flags, slash-command metadata, aliases, resume-safety, output-format support, auth/preflight notes, and descriptions are flattened into one human-oriented prose blob. That technically satisfies “valid JSON” while still forcing automation to scrape the same help text humans read, making `/issue`, `/help`, and resume-safety contracts opaque to claws. **Required fix shape:** (a) keep `message` as the compact human-rendered help summary, but add a documented structured schema with `schema` / `schema_version` fields; (b) expose first-class arrays/objects such as `commands[]`, `options[]`, and `slash_commands[]` with stable fields including `name`, `aliases`, `description`, `args`, `output_formats_supported`, `resume_safe`, `interactive_only`, and `creates_external_side_effects`; (c) include auth and creation preflight metadata where relevant, especially for GitHub/issue flows (`auth_preflight`, `creation_unavailable`, `gh_cli_authenticated`, `github_token_present`, or equivalent non-secret state); (d) make `/issue`, `/help`, aliases, and resume-dispatch safety machine-readable from the JSON payload instead of recoverable only by parsing prose markers; (e) add regression coverage proving `help --output-format json` is valid JSON and that `/issue`, `/help`, resume-safe vs interactive-only slash commands, aliases, descriptions, supported output formats, and side-effect/auth-preflight fields are present and internally consistent. **Why this matters:** help JSON is the discoverability surface automation uses before invoking commands. If it is just prose wrapped in JSON, claws cannot safely decide whether a command can run non-interactively, resume from a saved session, create external GitHub side effects, or requires auth/preflight without brittle text scraping. Source: gaebal-gajae dogfood follow-up from current main `d607ff36`; observed `./rust/target/debug/claw help --output-format json` returning valid JSON with only `{kind,message}` at the top level while the actionable command schema remained buried in `message`.
+
+336. **`/session` and `/session list` have inconsistent resume-mode support: bare `/session` returns `"unsupported resumed slash command"` while `/session list` works in `--resume` — yet `/help` JSON exposes no per-subcommand resume flag** — dogfooded 2026-04-29 by Jobdori on current main (`b90875f`). Running `claw --output-format json --resume latest /session` returns `{"command":"/session","error":"unsupported resumed slash command","type":"error"}`. Running `claw --output-format json --resume latest /session list` returns a valid session list JSON. The two forms share the same slash command name but have divergent resume-mode contracts with no documentation path to learn which subcommands are resume-safe. Additionally, the error JSON uses `"type"` instead of `"kind"` — violating the vocabulary used by all other JSON outputs (`kind=status`, `kind=version`, `kind=doctor`, etc.), making error responses structurally inconsistent with success responses. **Required fix shape:** (a) document per-subcommand resume support in `/help` JSON output — each command entry should carry `"resume_subcommands": ["list"]` or similar so callers know which subcommands work in `--resume` mode; (b) align the error JSON vocabulary: replace `"type"` with `"kind"` and use `kind=error` consistently; (c) either mark `/session` bare as `[resume]`-safe (showing the list by default) or emit a typed error that names the resume-safe subcommands; (d) add regression coverage proving that all error JSON responses use `"kind"` not `"type"`, and that `/session list` resume-mode support is stable. **Why this matters:** callers using `/session` in automation cannot discover from `/help` or error text which subcommands work in resume-mode; the `type` vs `kind` vocabulary mismatch in errors also breaks generic JSON-kind dispatchers that expect a stable `kind` field. Source: Jobdori live dogfood on mengmotaHost, claw-code `b90875f`, 2026-04-29.