docs(roadmap): add #418 — system-prompt json sections[] exposes __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ sentinel

ROADMAP.md

@@ -6301,16 +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`.
 
-359. **`init --output-format json` artifact entries only have `name` and `status` fields; `status: "skipped"` artifacts include no `reason` explaining why they were skipped, preventing automation from distinguishing "file already exists" from "no write permission" from "explicitly excluded"** — dogfooded 2026-04-30 by Jobdori on `74338dc6`. Running `./claw --output-format json init` in an already-initialised workspace returns artifacts with only `{name, status}` and no `reason`, `skip_reason`, or `existing_path` field. `created`/`skipped`/`updated` arrays duplicate artifact data but also provide no reasons. **Required fix:** add `reason: "already_exists"|"permission_denied"|"dry_run"|"excluded_by_config"` to each artifact; add `existing_path` for `already_exists`; add regression coverage. Source: Jobdori live dogfood, `74338dc6`, 2026-04-30.
-360. **`help --output-format json` and `--help --output-format json` return `{"kind":"help","message":"..."}` while `/help --output-format json` returns `{"kind":"help","text":"..."}` — the prose content field is named `message` in CLI subcommand form and `text` in slash-command form for the same `kind:"help"` response** — dogfooded 2026-04-30 by Jobdori on `52a909ce`. Three invocations: (1) `claw help` → `message` field; (2) `claw --help` → `message` field; (3) `claw --resume latest /help` → `text` field. Automation must check `d.message || d.text`. **Required fix:** standardise on one field name; update SCHEMAS.md; add regression coverage. Source: Jobdori live dogfood, `52a909ce`, 2026-04-30.
-361. **`skills --output-format json` skill entries include no `path` field; automation cannot determine the SKILL.md file location from the JSON output; `origin.detail_label` is `null` for all 147 skills; two skills have `description: ">"` — a single-character parsing artifact** — dogfooded 2026-04-30 by Jobdori on `52a909ce`. Skill entry has keys `['active','description','name','origin','shadowed_by','source']` — no `path` anywhere. **Required fix:** add `path` to each entry; populate `origin.detail_label`; sanitize stub descriptions; add regression coverage. Source: Jobdori live dogfood, `52a909ce`, 2026-04-30.
-362. **`version/doctor/sandbox/status --help` with `--output-format json` return plain-text output instead of JSON; `agents/mcp --help` correctly return JSON — inconsistent `--help` JSON contract across subcommands** — dogfooded 2026-04-30 by Jobdori on `d95b230c`. Broader instance of #356. **Required fix:** all subcommands must honour `--output-format json` for `--help`; add regression coverage. Source: Jobdori live dogfood, `d95b230c`, 2026-04-30.
-363. **`sandbox --output-format json` response omits `action` field; `agents/mcp` include `action:"list"` — inconsistent structural envelope across inspect-style commands** — dogfooded 2026-04-30 by Jobdori on `d95b230c`. `sandbox` → no `action`; `agents/mcp` → `action:"list"`. Also: `requested_namespace:true` + `supported:false` mismatch exposed only as `fallback_reason` string, not typed `degraded` field. **Required fix:** add `action:"status"` to inspect-style commands; add `degraded: bool` + `degraded_reasons[]` to sandbox JSON. Source: Jobdori live dogfood, `d95b230c`, 2026-04-30.
-364. **`mcp --output-format json` response has `summary: null` and no `count` field; `agents --output-format json` has `summary: {active, shadowed, total}` and `count` — inconsistent list-command envelope between `mcp` and `agents`; also `claw --output-format json mcp` emits unstructured `enabledPlugins is deprecated` warning to stderr with no typed JSON warning object** — dogfooded 2026-04-30 by Jobdori on `44cca205`. **Required fix:** add `count` + `summary` to `mcp` JSON; emit deprecation warnings as structured JSON to stderr when `--output-format json`; add regression coverage. Source: Jobdori live dogfood, `44cca205`, 2026-04-30.
-
-359. **`init --output-format json` artifact entries only have `name` and `status` fields; `status: "skipped"` artifacts include no `reason` explaining why they were skipped, preventing automation from distinguishing "file already exists" from "no write permission" from "explicitly excluded"** — dogfooded 2026-04-30 by Jobdori on `74338dc6`. Running `./claw --output-format json init` in an already-initialised workspace returns artifacts with only `{name, status}` and no `reason`, `skip_reason`, or `existing_path` field. `created`/`skipped`/`updated` arrays duplicate artifact data but also provide no reasons. **Required fix:** add `reason: "already_exists"|"permission_denied"|"dry_run"|"excluded_by_config"` to each artifact; add `existing_path` for `already_exists`; add regression coverage. Source: Jobdori live dogfood, `74338dc6`, 2026-04-30.
-360. **`help --output-format json` and `--help --output-format json` return `{"kind":"help","message":"..."}` while `/help --output-format json` returns `{"kind":"help","text":"..."}` — the prose content field is named `message` in CLI subcommand form and `text` in slash-command form for the same `kind:"help"` response** — dogfooded 2026-04-30 by Jobdori on `52a909ce`. Three invocations: (1) `claw help` → `message` field; (2) `claw --help` → `message` field; (3) `claw --resume latest /help` → `text` field. Automation must check `d.message || d.text`. **Required fix:** standardise on one field name; update SCHEMAS.md; add regression coverage. Source: Jobdori live dogfood, `52a909ce`, 2026-04-30.
-361. **`skills --output-format json` skill entries include no `path` field; automation cannot determine the SKILL.md file location from the JSON output; `origin.detail_label` is `null` for all 147 skills; two skills have `description: ">"` — a single-character parsing artifact** — dogfooded 2026-04-30 by Jobdori on `52a909ce`. Skill entry has keys `['active','description','name','origin','shadowed_by','source']` — no `path` anywhere. **Required fix:** add `path` to each entry; populate `origin.detail_label`; sanitize stub descriptions; add regression coverage. Source: Jobdori live dogfood, `52a909ce`, 2026-04-30.
-362. **`version/doctor/sandbox/status --help` with `--output-format json` return plain-text output instead of JSON; `agents/mcp --help` correctly return JSON — inconsistent `--help` JSON contract across subcommands** — dogfooded 2026-04-30 by Jobdori on `d95b230c`. Broader instance of #356. **Required fix:** all subcommands must honour `--output-format json` for `--help`; add regression coverage. Source: Jobdori live dogfood, `d95b230c`, 2026-04-30.
-363. **`sandbox --output-format json` response omits `action` field; `agents/mcp` include `action:"list"` — inconsistent structural envelope across inspect-style commands** — dogfooded 2026-04-30 by Jobdori on `d95b230c`. `sandbox` → no `action`; `agents/mcp` → `action:"list"`. Also: `requested_namespace:true` + `supported:false` mismatch exposed only as `fallback_reason` string, not typed `degraded` field. **Required fix:** add `action:"status"` to inspect-style commands; add `degraded: bool` + `degraded_reasons[]` to sandbox JSON. Source: Jobdori live dogfood, `d95b230c`, 2026-04-30.
-364. **`mcp --output-format json` response has `summary: null` and no `count` field; `agents --output-format json` has `summary: {active, shadowed, total}` and `count` — inconsistent list-command envelope between `mcp` and `agents`; also `claw --output-format json mcp` emits unstructured `enabledPlugins is deprecated` warning to stderr with no typed JSON warning object** — dogfooded 2026-04-30 by Jobdori on `44cca205`. **Required fix:** add `count` + `summary` to `mcp` JSON; emit deprecation warnings as structured JSON to stderr when `--output-format json`; add regression coverage. Source: Jobdori live dogfood, `44cca205`, 2026-04-30.
+418. **`system-prompt --output-format json` exposes `"__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__"` as a literal element in the `sections` array — an internal split delimiter leaked into the public structured output** — dogfooded 2026-04-30 by Jobdori on `e939777f`. Running `claw system-prompt --output-format json` returns `{"kind":"system-prompt","message":"<full prose>","sections":["You are an interactive agent...", "# System\n...", "# Doing tasks\n...", "# Executing actions with care\n...", "__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__", "# Environment context\n...", "# Project context\n...", "# Claude instructions\n...", "# Runtime config\n..."]}`. The `sections` array has 9 elements; element index 4 is the raw string `"__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__"`. This internal sentinel marks the boundary between the static and dynamic sections of the compiled system prompt, used during assembly to split the prompt at injection time. It appears in the public JSON output verbatim as a first-class section, indistinguishable from real sections by type alone. Automation that iterates `sections[]` must special-case this sentinel or it will process an internal implementation string as if it were a real system prompt section. **Required fix shape:** (a) strip `"__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__"` and any similar internal delimiters from the `sections` array before serializing to JSON; (b) if the static/dynamic boundary is semantically meaningful for callers, expose it as a structured metadata field such as `boundary_index:4` or as a `section_type:"static"|"dynamic"` field on each section entry, not as a raw sentinel string in the array; (c) rename the `sections` type from `string[]` to `[{id, type, content}]` to enable this without breaking the boundary signal; (d) add regression coverage proving the `system-prompt --output-format json` output's `sections` array contains no elements whose value equals `"__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__"` or matches `/__[A-Z_]+__/`. **Why this matters:** internal sentinel strings in public JSON are a contract liability — they couple the wire format to internal implementation details. Any refactor that renames or removes the sentinel breaks callers that don't special-case it, and automation that doesn't know to filter it will miscount, misparse, or misrender the system prompt. Source: Jobdori live dogfood, `e939777f`, 2026-04-30.