docs(roadmap): add #462 — version --output-format json envelope missing build_date structured field; ROADMAP #79 line 1380 cites it as exemplary while the field has never existed (40-day drift)

ROADMAP.md

@@ -6429,47 +6429,40 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 
 450. **`prompt` emits `kind:"missing_credentials"` JSON on STDERR (not stdout), leaving stdout at 0 bytes — automation pattern `output=$(claw prompt hello --output-format json)` captures nothing on auth-absent failure; `doctor` correctly surfaces `auth.status:"warn"` with `api_key_present:false` but exposes no `prompt_ready:false` field that automation can check before invoking `prompt`** — dogfooded 2026-05-16 by Jobdori on `a35ee9a0` in response to Clawhip pinpoint nudge at `1505208225321062521`. Exact reproduction (isolated env, no creds, fresh git repo, HEAD `a35ee9a0`): `timeout 5 env -i HOME=$ISOLATED_HOME PATH=$PATH CLAW_CONFIG_HOME=$PROBE/.claw-cfg claw prompt hello --output-format json > stdout.txt 2> stderr.txt` → stdout = **0 bytes**, stderr = 195 bytes containing `{"error":"missing Anthropic credentials…","exit_code":1,"hint":null,"kind":"missing_credentials","type":"error"}`, exit code 1. Confirms Gaebal's `1505208553793781792` pinpoint that `prompt` timeout + zero bytes was the prior state — HEAD `a35ee9a0` now correctly exits 1 with `kind:"missing_credentials"` **but the envelope is still routed to stderr** (issue #447 class, same class as prior entries #422, #435). **Contrast with `doctor`:** `claw doctor --output-format json 2>/dev/null` succeeds to stdout with `checks[auth].status:"warn"`, `api_key_present:false`, `auth_token_present:false` — but the auth check has no `prompt_ready:false` field. Automation that gates on `doctor` before invoking `prompt` must re-derive readiness from `api_key_present && auth_token_present` — there is no single canonical boolean. **Three compound problems:** (a) **stdout-empty on `--output-format json` failure**: same class as #447; `prompt`'s error envelope goes to stderr, not stdout. The canonical automation idiom `if ! result=$(claw prompt "q" --output-format json); then echo "$result" | jq .kind; fi` sees `$result=""` on failure — the jq call gets nothing. All `--output-format json` error paths must route JSON to stdout per #447 contract; (b) **`doctor` missing `prompt_ready` field**: `doctor --output-format json` already knows auth is absent (`api_key_present:false`) but surfaces no derived `prompt_ready:bool` or `prompt_blocked_reason:string` field. Automation must infer readiness from `api_key_present || auth_token_present || legacy_*_present` — a 5-field OR across legacy fields that is fragile as auth mechanisms evolve. A single `prompt_ready:false` (with `prompt_blocked_reason:"auth_missing"`) inside the `auth` check would give downstream a stable contract; (c) **`claw prompt` with no auth does no preflight and fires straight at the API**: the preflight check that `doctor` runs (auth discovery) is not reused by `prompt` to emit a fast typed error before attempting the network call. Both Gaebal's pinpoint (prompt hanging silently on older HEAD) and the current behavior (prompt hitting auth gate after a brief API attempt) stem from the same root: prompt does not short-circuit at the point where `doctor` already knows auth is absent. If `doctor` can emit `kind:"doctor"` with `auth.status:"warn"` in ~20ms without a network call, `prompt` should emit `kind:"missing_credentials"` in the same window and output it to stdout. **Required fix shape:** (a) `prompt --output-format json` must write the `kind:"missing_credentials"` JSON envelope to **stdout**, not stderr — same fix as #447 for all error envelopes; (b) add `prompt_ready:bool` and `prompt_blocked_reason:string|null` to the `auth` check in `doctor --output-format json`; derive it as `api_key_present || auth_token_present || legacy_saved_oauth_present`; (c) `prompt` must run the credential preflight check (same codepath as doctor's auth check) before attempting any API call and emit `{"kind":"missing_credentials","prompt_blocked_reason":"auth_missing"}` on **stdout** with exit 1 if the check fails; (d) `--output-format json` stdout routing fix must cover: `prompt`, `session list` (cross-ref #449), `skills uninstall` (cross-ref #431), `resume` (cross-ref #435), `acp serve` (cross-ref #443) — the full `kind:"missing_credentials"` class; (e) regression test: `claw prompt hello --output-format json` with no creds writes JSON to stdout (0 bytes stderr), exits 1, `kind:"missing_credentials"`, in under 200ms (no network attempt). **Why this matters:** `prompt` is the primary consumer entry point. Auth-absent failure routing to stderr breaks every automation wrapper that captures `$(claw prompt ... --output-format json)`. The `doctor` preflight metadata gap means auth-readiness checks require parsing 5 legacy fields instead of reading one boolean. Cross-references #447 (all JSON error envelopes on stderr), #449 (session list hits auth gate), #431 (skills uninstall hits auth gate), #357 (auth gate on local ops cluster), #422 (exit-code parity). Source: Jobdori live dogfood, `a35ee9a0`, 2026-05-16.
 
-684. **`init --help --output-format json` returns parseable JSON but keeps the init contract inside a prose `message`, unlike `export` help which exposes structured defaults/options; automation cannot discover which artifacts `init` creates, idempotency semantics, or next-step/recovery fields without scraping aligned text** — dogfooded 2026-05-24 for the 21:30 Clawhip nudge at message `1508220580053389436`, reproduced on a freshly rebuilt current `origin/main` binary (`git_sha f8e1bb726`) from `/tmp/cc-probe-main-2130`, after discarding stale-debug-binary observations from `003b739d`/`e939777f`.
-
-    Reproduction:
+462. **`claw version --output-format json` envelope is missing the `build_date` structured field even though all four other fields the human prose displays ARE structured (`version`, `git_sha`, `target`, `kind`) AND ROADMAP #79's "contrast" claim at line 1380 explicitly cites version as exemplary by listing `{kind, message, version, git_sha, target, build_date}` — the documentation says "structured", the code emits four fields out of five, and the string `"build_date"` literally does not appear anywhere in `rust/crates/rusty-claude-cli/` (zero hits across src/ and tests/). This is both a missing-field bug AND a 40-day-old ROADMAP self-contradiction: the entry filed 2026-04-17 to argue init should match version's structure cited a field that was never there** — dogfooded 2026-05-24 for the 13:00 Clawhip pinpoint nudge at message `1508092230261539039`, reproduced on local `./rust/target/debug/claw` `git_sha 003b739d` (origin/main `f8e1bb72`). Live envelope from clean isolated env (`HOME=/tmp/iso16/home`, fresh `/tmp/iso16/proj`):
 
     ```bash
-    $ env -i HOME=/tmp/iso38/home PATH=/usr/bin:/bin TERM=dumb \
-        claw init --help --output-format json
+    $ env -i HOME=/tmp/iso16/home PATH=/usr/bin:/bin TERM=dumb claw version --output-format json
     {
-      "command": "init",
-      "kind": "help",
-      "message": "Init\n  Usage            claw init [--output-format <format>]\n  Purpose          create .claw/, .claw.json, .gitignore, and CLAUDE.md in the current project\n  Output           list of created vs. skipped files (idempotent: safe to re-run)\n  Formats          text (default), json\n  Related          claw status · claw doctor",
-      "topic": "init"
+      "git_sha": "003b739d",
+      "kind": "version",
+      "message": "Claw Code\n  Version          0.1.0\n  Git SHA          003b739d\n  Target           x86_64-unknown-linux-gnu\n  Build date       2026-05-04",
+      "target": "x86_64-unknown-linux-gnu",
+      "version": "0.1.0"
     }
     ```
 
-    The command returns valid JSON, but every init-specific contract is embedded in the human `message` string. There are no structured fields for `usage`, `purpose`, `creates`, `idempotent`, `output_shape`, `formats`, `related`, `side_effects`, `requires_confirmation`, or `next_step`.
+    Field parity audit:
 
-    Contrast with the same current-main binary's actual init output:
+    | Field shown in `message` prose | Structured envelope field | Source constant |
+    |---|---|---|
+    | `Version 0.1.0` | ✅ `version` | `VERSION = env!("CARGO_PKG_VERSION")` |
+    | `Git SHA 003b739d` | ✅ `git_sha` | `GIT_SHA = option_env!("GIT_SHA")` |
+    | `Target x86_64-unknown-linux-gnu` | ✅ `target` | `BUILD_TARGET = option_env!("TARGET")` |
+    | `Build date 2026-05-04` | ❌ **MISSING** | `DEFAULT_DATE = option_env!("BUILD_DATE")` exists |
 
-    ```bash
-    $ claw init --output-format json
-    {
-      "kind": "init",
-      "artifacts": [
-        {"name":".claw/", "status":"created"},
-        {"name":".claw.json", "status":"created"},
-        {"name":".gitignore", "status":"created"},
-        {"name":"CLAUDE.md", "status":"created"}
-      ],
-      "created": [".claw/", ".claw.json", ".gitignore", "CLAUDE.md"],
-      "skipped": [],
-      "updated": [],
-      "next_step": "Review and tailor the generated guidance",
-      ...
+    **Root cause (traced):** `rust/crates/rusty-claude-cli/src/main.rs:2629-2637`:
+
+    ```rust
+    fn version_json_value() -> serde_json::Value {
+        json!({
+            "kind": "version",
+            "message": render_version_report(),
+            "version": VERSION,
+            "git_sha": GIT_SHA,
+            "target": BUILD_TARGET,
+        })
     }
     ```
 
-    And contrast with `export --help --output-format json` on the same binary, which already exposes structured fields beyond `message` such as `defaults`, `formats`, `kind`, and `options[]` with `name`, `value`, `description`, aliases, and defaults. The init help surface is therefore a schema-quality outlier among local command help surfaces: parseable JSON exists, but not the machine-readable contract that a claw needs before running a side-effectful initializer.
-
-    **Why distinct from existing items:** #325 covers top-level `help --output-format json` being prose wrapped in JSON. #356/#357/#683 cover status/doctor/sandbox help returning plain text or command-specific help-format gaps. #358/#380/#381 cover hanging help surfaces. #420 covers `plugins help` mutation-envelope drift. #684 is narrower: current-main `init` help is valid JSON but under-structured for a side-effectful project initializer, while sibling `export` help already demonstrates the richer command-help schema pattern. This is not a stale-binary finding; the binary under test reports `git_sha f8e1bb726` matching `origin/main`.
-
-    **Why this matters:** `init` is side-effectful: it creates `.claw/`, `.claw.json`, `.gitignore`, and `CLAUDE.md`. A wrapper or onboarding claw should be able to discover these writes, idempotency guarantees, and follow-up expectations before executing the command. Today it must scrape the aligned prose in `message`, then separately infer the actual artifact list from a dry-run-less real invocation. That is backwards for safe automation: help should expose side effects before mutation.
-
-    **Required fix shape:** (a) Extend `init --help --output-format json` with structured fields mirroring its real output and side-effect contract: `usage`, `purpose`, `formats:["text","json"]`, `creates:[{"name":".claw/","kind":"directory"}, ...]`, `idempotent:true`, `mutates_workspace:true`, `requires_confirmation:false`, `output_fields:["artifacts","created","skipped","updated","next_step","project_path"]`, `related:["claw status","claw doctor"]`, and optional `dry_run_available:false` until such a flag exists. (b) Keep `message` as human summary only. (c) Align command-help JSON schemas so side-effectful commands expose side-effect metadata consistently; `export` already proves richer help JSON is acceptable. (d) Add regression coverage proving `claw init --help --output-format json | jq '.creates[]?.name'` contains `.claw/`, `.claw.json`, `.gitignore`, and `CLAUDE.md`, and that it declares `idempotent:true` / `mutates_workspace:true`. **Acceptance check:** `claw init --help --output-format json | jq -e '.command=="init" and .mutates_workspace==true and .idempotent==true and ([.creates[].name] | index(".claw.json")) and ([.output_fields[]] | index("artifacts"))'` should pass; currently `.creates`, `.idempotent`, `.mutates_workspace`, and `.output_fields` are absent. Source: gaebal-gajae dogfood for the 2026-05-24 21:30 Clawhip nudge. Coordination note: avoided #420 after pre-grep showed Jobdori already tracked `plugins help`; avoided stale-binary candidates by rebuilding current `origin/main` before filing.
+    The function consumes the prose via `render_version_report()` for `message`, then re-extracts three of the four structured values from compile-time constants — but skips `DEFAULT_DATE` (the BUILD_DATE constant defined at `main.rs:159-162`). The fourth structured field is just missing from the json! macro. One-line fix: add `"build_date": DEFAULT_DATE,`. Verification: `grep -rnE '"build_date"|build_date' rust/crates/rusty-claude-cli/{src,tests}/ --include='*.rs'` returns **zero hits** — the field name has never appeared in either source or test code. **ROADMAP self-contradiction:** ROADMAP entry #79 at line 1380 contrasts `init`'s prose-only envelope against `version` as exemplary: `"claw --output-format json version → {kind, message, version, git_sha, target, build_date} — structured."` This claim was filed 2026-04-17 and has been wrong ever since — the actual envelope is `{kind, message, version, git_sha, target}` (5 fields, not 6). The contrast argument for #79 stands because version IS more structured than init, but the specific field list is incorrect. The pre-grep gate caught this near-miss: I almost wrote up "version envelope missing build_date" as a brand-new pinpoint, then grepped ROADMAP for `build_date.*version`, found line 1380, realized it was a documentation-vs-implementation drift instead of a brand-new symptom. **Why distinct from existing items:** ROADMAP #324 covers the broader binary-provenance freshness problem (compare embedded git_sha vs workspace HEAD, emit `stale_binary` boolean) across `version`/`status`/`doctor`. #324 mentions `binary_provenance`/`workspace_head`/`stale_binary` as proposed structured fields but does NOT itemize the existing-field gap on `build_date`. #79 cites version as exemplary structured (the contrast direction) but never re-verified the cited field set. #83 covers BUILD_DATE leaking into the system prompt as "today's date" (the wrong-place-for-build-date problem). **None** document the simple fact that `version`'s ONE legitimate place to display build_date (the `version` JSON envelope) just doesn't expose it as a structured field. **Why this matters:** (1) **Bug reports and CI fingerprinting need machine-readable build_date.** A claw producing a bug report wants `{"version": "0.1.0", "git_sha": "003b739d", "build_date": "2026-05-04"}` as a self-describing provenance triple. Today it must regex `/Build date\s+(\S+)/` against the `message` prose — the same anti-pattern ROADMAP #79 was filed against for `init`. (2) **The fix is one line.** `"build_date": DEFAULT_DATE,` in `version_json_value()`. There is no architectural cost, no breakage risk, no behavior change beyond adding the field. (3) **Self-fulfilling documentation drift:** future ROADMAP entries (#324 already does this) cite the `version` envelope as the reference shape for binary-provenance JSON. Each new entry that propagates the wrong field list makes the drift harder to detect because the documented shape now disagrees with itself across multiple ROADMAP entries. Catching this at #462 prevents further drift accumulation. (4) **Cross-envelope inconsistency:** if `version` had `build_date` as a structured field, `status`/`doctor` could legitimately reference it as a precedent for #324's `binary_provenance` work. Without it, every related entry must re-justify the structured-field principle. (5) **Aligns with #459 (memory_files[] absent), #455 (missing_credentials hint shape), #79 (init artifacts[]), #326 (status panes[])** — the pattern is: a prose surface emits a value derived from an in-process structured source, but the JSON envelope discards the structure. Per-entry one-line fixes accumulate; together they define a "structured-envelope completeness" doctrine. **Required fix shape:** (a) **At `main.rs:2636`**, add `"build_date": DEFAULT_DATE,` to the `version_json_value()` json! macro. (b) **Fix ROADMAP #79 line 1380** in the same commit: keep the contrast point (version is more structured than init) but make the field-list accurate. (c) **Regression coverage:** add an `output_format_contract.rs` assertion that `claw version --output-format json | jq -e '.build_date'` returns a non-null string matching `/^\d{4}-\d{2}-\d{2}$|^unknown$/`. (d) **Optional, related to #324:** while in this file, consider adding `build_date` to `doctor` and `status` envelopes so binary-provenance fields cluster naturally for the #324 work. (e) **Optional, related to #83:** add a `today_date` field that uses `chrono::Utc::today()` so the difference between BUILD_DATE and runtime today is observable from one envelope alone. **Acceptance check (one-liner):** `claw version --output-format json | jq -e '.build_date | type == "string"'` should print `true` (currently returns `null` → exit 1). Source: gaebal-gajae dogfood follow-up for the 2026-05-24 13:00 Clawhip pinpoint nudge at message `1508092230261539039`. Triple-grep gate caught one near-miss on ROADMAP #83 (BUILD_DATE in system prompt — same root coLine truncated