docs(roadmap): add #402 — doctor config resolved_model:null status:ok; loaded_config_files int vs array

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`.
 
-406. **`diff --output-format json` returns `staged` and `unstaged` as empty strings `""` instead of `null` or structured objects when the diff is clean — `result:"clean"` + `staged:""` is ambiguous between "diff ran and produced no output" and "diff was not run" — automation must check `result` to know whether `staged:""` means empty diff or unevaluated field** — dogfooded 2026-04-30 by Jobdori on `e939777f`. Running `./claw --output-format json diff` on a clean workspace returns `{"kind":"diff","result":"clean","staged":"","unstaged":""}`. The `staged` and `unstaged` fields are raw diff text strings — empty string `""` on clean, presumably a patch string when dirty. Two issues: (1) `""` (empty string) and `null` cannot be distinguished as a diff field value — `staged:""` could mean "staged diff is empty" (intentional null-patch) or "diff evaluation was skipped/errored"; (2) a structured consumer expecting `staged_files:[]` / `unstaged_files:[]` with per-file metadata cannot use a raw patch string for anything except display; (3) `result` is a string enum `"clean"|?` with no documented other values, so automation must special-case `result:"clean"` before trusting `staged`/`unstaged`. **Required fix shape:** (a) use `null` (not `""`) for `staged`/`unstaged` when no diff exists; (b) add `staged_file_count: u32` and `unstaged_file_count: u32`; (c) document the `result` enum values and add `changed_files: u32` as a machine-countable summary; (d) add regression coverage proving `staged:null` on clean vs `staged:"<patch>"` on dirty and that `result` takes only documented enum values. Source: Jobdori live dogfood, `e939777f`, 2026-04-30.
+402. **`doctor --output-format json` `config` check has `resolved_model: null` and `status:"ok"` simultaneously — a null/unresolved model is not flagged as a warning or misconfiguration, and `loaded_config_files` is an integer count while `discovered_files` is an array, making the two fields inconsistently typed for the same domain** — dogfooded 2026-04-30 by Jobdori on `e939777f`. Running `./claw --output-format json doctor` returns `{"name":"config","status":"ok","resolved_model":null,"loaded_config_files":2,"discovered_files":[...2 paths...]}`. Two issues: (1) `resolved_model: null` with `status:"ok"` — automation that reads doctor JSON to validate pre-flight state cannot tell from the config check alone that no model is configured; only the `system` check's `default_model: null` exposes the same gap, but from a different check with no cross-reference; (2) `loaded_config_files: 2` is an int count while `discovered_files: [...]` is an array — the two fields describe the same set of files but one is a scalar and the other a collection, preventing automation from correlating which loaded files map to which count. **Required fix shape:** (a) add `model_configured: bool` and `model_source: "config"|"default"|"env"|null` to the `config` check; (b) when `resolved_model: null`, set `status:"warn"` or add a structured `issues[]` entry rather than `status:"ok"`; (c) rename `loaded_config_files` to `loaded_config_file_count` or change it to a `loaded_config_files[]` array matching `discovered_files[]`; (d) add regression coverage. Source: Jobdori live dogfood, `e939777f`, 2026-04-30.