docs(roadmap): add #423 — diff json staged/unstaged are raw strings; no structured file-change objects

ROADMAP.md

@@ -6303,4 +6303,4 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 
 422. **`export --output-format json` and `--resume latest` report the same "no managed sessions" scenario using two different `kind` codes — `no_managed_sessions` vs `session_load_failed` — making "no session found" undetectable by a single kind-code check** — dogfooded 2026-04-30 KST (UTC+9) by Jobdori on `e939777f`. Running `claw export --output-format json` with no session present returns (on stderr, exit 1): `{"error":"no managed sessions found in .claw/sessions/<fingerprint>/","hint":"Start \`claw\` to create a session, then rerun with \`--resume latest\`.\nNote: claw partitions sessions per workspace fingerprint; sessions from other CWDs are invisible.","kind":"no_managed_sessions","type":"error"}`. Running `claw --resume latest /status --output-format json` with no session present returns (on stderr, exit 1): `{"error":"failed to restore session: no managed sessions found in .claw/sessions/<fingerprint>/","hint":"Start \`claw\` to create a session, then rerun with \`--resume latest\`.\nNote: claw partitions sessions per workspace fingerprint; sessions from other CWDs are invisible.","kind":"session_load_failed","type":"error"}`. Both describe the same root condition — there are no sessions to operate on — but they expose it via different `kind` discriminants. Automation that checks `kind == "no_managed_sessions"` to detect a cold workspace will miss the `--resume` path's `session_load_failed`, and vice versa. A wrapper that guards "run with --resume only if a session exists" must special-case both codes. The hint text is identical between them, suggesting the messages are logically equivalent. Additionally neither code matches the proposed canonical names `session_not_found` / `session_load_failed` as stable `ErrorKind` discriminants described in ROADMAP #77's fix shape, which explicitly proposes typed error-kind codes for session lifecycle failures. **Required fix shape:** (a) unify "no sessions found for this workspace fingerprint" under a single canonical `kind` code — either `no_managed_sessions` or `session_not_found` — used consistently by every command path that encounters an empty session registry; (b) if `session_load_failed` is a more general category (covering e.g. corrupt session files, IO errors, schema version mismatches), it should nest a concrete `reason:"no_managed_sessions"` or `reason:"session_not_found"` sub-field so callers can distinguish "empty registry" from "found but unreadable"; (c) align with the canonical error-kind contract proposed in #77; (d) add regression coverage proving `export` and `--resume latest` in an empty workspace both return an error with the same top-level `kind` code. **Why this matters:** session guard-rails in orchestration need a single stable `kind` to detect cold workspaces without enumerating all possible no-session synonyms. Two divergent codes for the same condition make defensive automation brittle and contradict the promise of machine-readable error envelopes. Source: Jobdori live dogfood, `e939777f`, 2026-04-30 KST (UTC+9).
 
-425. **`status --output-format json` workspace.`changed_files` silently includes untracked files in its count alongside staged and unstaged tracked files — a claw checking `changed_files > 0` to detect "uncommitted changes" will false-positive when only untracked files exist** — dogfooded 2026-04-30 KST (UTC+9) by Jobdori on `e939777f`, traced to source. In a workspace with only one untracked file and no staged/unstaged tracked changes: `claw status --output-format json` returns `{"workspace":{"changed_files":1,"staged_files":0,"unstaged_files":0,"untracked_files":1,"git_state":"dirty · 1 files · 1 untracked",...}}`. `changed_files` is 1 even though `staged_files` and `unstaged_files` are both 0. Source trace: `rust/crates/rusty-claude-cli/src/main.rs:3230-3255` — `parse_git_workspace_summary` increments `changed_files` for every non-header, non-blank line in `git status --short --branch` output before branching on `??` (untracked). The `??` branch increments `untracked_files` then calls `continue`, but `changed_files` was already incremented — so `changed_files = staged_files + unstaged_files + untracked_files` (plus conflicted). Meanwhile `git_state` is computed from `is_clean() = changed_files == 0`, so a repo with only untracked files produces `git_state:"dirty"` and `changed_files:N` while `staged_files == 0 && unstaged_files == 0`. A claw using the idiomatic guard `if workspace.changed_files > 0 { block_commit_or_rebase }` will block even when there are only new untracked files that will not be part of any commit. A claw using `changed_files == 0` as a "clean for commit" signal must additionally check `staged_files == 0 && unstaged_files == 0` — but the field name `changed_files` does not signal this requirement. This is distinct from #125 (git_state:"clean" in non-git dirs): #125 covers a false "clean" in non-git dirs; this covers a false "dirty" in git repos with only untracked files. **Required fix shape:** (a) rename `changed_files` to `total_git_status_entries` or similar to accurately reflect it counts all `git status --short` entries including untracked, OR exclude untracked from `changed_files` and rename the field to `tracked_changed_files`; (b) OR keep `changed_files` but document it explicitly as "includes untracked" in the schema and add a separate `tracked_changed_files = staged_files + unstaged_files` computed field; (c) fix `is_clean()` to also require `untracked_files == 0` if untracked files are meant to be included in the "dirty" signal, or to only use `staged_files + unstaged_files` if they are not; (d) add regression coverage proving that a workspace with only untracked files returns `changed_files > 0` and the documentation makes the semantic explicit. **Why this matters:** `changed_files` is the primary integer gate for "is this workspace clean enough to proceed?" in CI/automation flows. A silent untracked-file false positive causes automation to block valid operations (commits, rebases, PR creation) or fail health checks unnecessarily. Source: Jobdori live dogfood + source trace, `e939777f`, 2026-04-30 KST (UTC+9). Cross-reference: #125 (git_state clean in non-git dir), #400 (status workspace session/session_id mismatch).
+423. **`diff --output-format json` returns `staged` and `unstaged` as raw `git diff` prose strings, not structured file-change objects — automation must parse the diff text to identify which files changed** — dogfooded 2026-04-30 KST (UTC+9) by Jobdori on `e939777f`. Running `claw diff --output-format json` in a repo with unstaged changes returns `{"kind":"diff","result":"changes","staged":"","unstaged":"diff --git a/ROADMAP.md b/ROADMAP.md\nindex ca63e33..2e4b74e 100644\n--- a/ROADMAP.md\n+++ b/ROADMAP.md\n@@ -1,3 +1,4 @@\n+// test change\n ..."}`. The `staged` and `unstaged` fields are raw multi-line `git diff` output strings. A claw that wants to know which files changed, how many lines were added/removed, or whether a specific path is in the diff must parse the raw unified diff format — there are no structured `files:[{path, additions, deletions, status}]` fields, no `changed_files_count`, no per-file change summary. The `result` field (`"changes"`, `"clean"`, `"no_git_repo"`) is machine-readable, but everything else is raw prose. Automation that relies on `diff --output-format json` to make decisions (e.g. "did the test files change?", "are there staged changes before a commit?") must implement a full unified diff parser. **Required fix shape:** (a) add a `files` field containing structured per-file change metadata: `{path, status:"added"|"modified"|"deleted"|"renamed", additions:int, deletions:int, old_path:null|string}`; (b) add top-level `total_additions:int` and `total_deletions:int` summary fields; (c) keep `staged` and `unstaged` raw strings as optional verbatim fields (e.g. under `raw_staged`, `raw_unstaged`) for callers that need the full text; (d) add regression coverage proving `diff --output-format json` in a workspace with changes includes a `files[]` array with at least one entry containing `path` and `status` fields. **Why this matters:** diff inspection is a key control-plane signal for claws deciding whether to commit, what to commit, or whether user-edited files need re-analysis. If the only machine-readable diff signal is a raw unified diff string, every orchestration layer must bundle a full diff parser, re-deriving what `git diff --stat` would have given for free. Source: Jobdori live dogfood, `e939777f`, 2026-04-30 KST (UTC+9).