Add the missing explicit-path regression so operators keep the current fail-fast contract covered, and record the completed ROADMAP follow-up.
Constraint: scope limited to ROADMAP helper regression coverage plus the DONE roadmap entry; tests/__init__.py is included so the requested python -m unittest tests.test_roadmap_helpers invocation resolves locally instead of an external tests package.
Rejected: changing roadmap-next-id.sh behavior | dogfood showed the script already returns the desired nonzero empty-stdout error.
Confidence: high
Scope-risk: narrow
Directive: Keep stdout reserved for the single next id on successful roadmap-next-id.sh runs.
Tested: python -m unittest tests.test_roadmap_helpers -q; scripts/roadmap-check-ids.sh ROADMAP.md; scripts/roadmap-next-id.sh ROADMAP.md; git diff --check -- ROADMAP.md tests/test_roadmap_helpers.py tests/__init__.py
Constraint: roadmap-next-id.sh must preserve single-id stdout on success while failing closed if duplicate validation cannot run.
Rejected: Relying only on CI/pre-push duplicate checks | the helper is used immediately before appending and must not certify an already-poisoned file.
Confidence: high
Scope-risk: narrow
Directive: Keep roadmap-next-id.sh stdout machine-clean; route validation failures and checker availability errors to stderr, and keep focused helper behavior coverage in the docs/ROADMAP CI path.
Tested: scripts/roadmap-next-id.sh ROADMAP.md printed 725 before appending #725 and 726 after; temp ROADMAP with duplicate 999 exited nonzero and listed duplicate id; scripts/roadmap-check-ids.sh ROADMAP.md; bash -n scripts/roadmap-next-id.sh scripts/roadmap-check-ids.sh; python -m unittest discover -s tests -p test_roadmap_helpers.py; python -m pytest tests/test_roadmap_helpers.py -q; SKIP_CLAW_PRE_PUSH_BUILD=1 bash .github/hooks/pre-push
Not-tested: full cargo workspace build, unchanged docs/script-only path
Add a lightweight ROADMAP duplicate-id guard and wire it into the low-risk docs/pre-push paths so optimistic append collisions introduced after the next-id helper are caught before merge.
Constraint: Current ROADMAP contains legacy numbered lists and pre-helper duplicate low ids, so the default guard checks helper-era ids >=723 while preserving --min-id 1 for a future strict audit.
Rejected: Fail CI on every numeric duplicate in the whole historical ROADMAP | current main would fail before this PR because old prose/list numbering is already duplicated.
Confidence: high
Scope-risk: narrow
Directive: Keep roadmap-next-id.sh paired with roadmap-check-ids.sh when changing ROADMAP append workflows.
Tested: bash -n scripts/roadmap-check-ids.sh scripts/roadmap-next-id.sh .github/hooks/pre-push; scripts/roadmap-check-ids.sh; temp ROADMAP copy with duplicate 723 failed nonzero and listed id 723; SKIP_CLAW_PRE_PUSH_BUILD=1 .github/hooks/pre-push; git diff --check; python3 .github/scripts/check_doc_source_of_truth.py; python3 .github/scripts/check_release_readiness.py
Not-tested: full cargo workspace build/test because this is docs/scripts-only and the local pre-push cargo build was smoke-tested with its documented skip path.
Constraint: Docs-only ROADMAP pinpoint requested; existing #324/#695 cover adjacent stale-binary and stale-worktree cases but not stale local cargo-run current-main misclassification.
Rejected: Implementing provenance warnings now | scope was to keep implementation out unless trivially obvious and safe.
Confidence: high
Scope-risk: narrow
Directive: Preserve #719 as the cargo-run/local-checkout sibling of #324/#695 when implementing provenance freshness.
Tested: python3 .github/scripts/check_doc_source_of_truth.py; python3 scripts/validate_cc2_board.py --board .omx/cc2/board.json; git diff --check
Not-tested: Runtime provenance warning implementation not changed.
Pinpoint: 'enabled:true, supported:false' is semantic nonsense.
'filesystem_active:true allowed_mounts:[]' contradicts 'workspace-only'.
'active:false filesystem_active:true' has no documented aggregation rule.
Renaming 'enabled' to 'requested' and exposing 'active_components:[]'
would surface real isolation state to automation.
Pinpoint: claw --no-such-flag --output-format json writes the JSON
envelope to stderr (115 bytes) while stdout is 0 bytes. Same for
missing_credentials, session_load_failed, invalid_model_syntax —
all 4 error kinds tested put JSON on stderr. Breaks the standard
'output=$(cmd --output-format json)' pattern. Every major CLI
(kubectl/gh/aws/jq/terraform -json) puts JSON on stdout regardless
of success/failure. Sibling: deprecation warnings precede the JSON
envelope on stderr, breaking 'tail -1 | jq' parsing.
Pinpoint: status emits 3x deprecation warnings, doctor 2x, mcp 2x,
version 0x. Each duplicate is byte-identical (same file/line/field).
Config-load pipeline is fanned out across commands without a cache.
15 redundant disk reads in worst case. Real warnings drowned out by
copies. Count fluctuates between HEADs (3 at 6c0c305a, 4 at d7dbe951,
3 at 5a4cc506) — no architectural fix landed.
Pinpoint: .claw/skills/wrong-name/SKILL.md with frontmatter name:
actually-different-name silently loads as the frontmatter name. Users
referencing by dir name get skill_not_found while skills list shows
the frontmatter name. Siblings: subdir without SKILL.md silently
skipped; loose .md at skills root dropped; no --scope filter for
workspace vs user merge.
Pinpoint: claw --resume latest from / hits 'Read-only file system'
(OS error 30) — only saved by root being read-only. From /tmp or
$HOME, silently creates .claw/sessions/<fingerprint>/ droppings.
Exit code 0 on the read-only-FS error. Stale /tmp/.claw from 13:31
dogfood still present at 21:30 (10 hours, 6+ HEADs later) — #435's
deferred-creation fix hasn't landed. The broad-cwd guard only covers
shorthand prompt path, not resume/status/doctor.
Pinpoint: claw-code only loads .toml files from .claw/agents/. Claude
Code uses .md with YAML frontmatter — schema divergence. Source code
at commands/src/lib.rs:3378 silently skips non-.toml extensions with
no warning. Help text omits the format requirement. Same silent-drop
pattern as #440 (MCP) and #441 (hooks). Also: .claude/agents/ never
discovered; required fields undocumented; no scaffolding command.
Pinpoint: claw-code expects {hooks:{PreToolUse:['cmd-string']}} while
Claude Code docs specify {hooks:{PreToolUse:[{matcher,hooks:[{type,command}]}]}}.
Users copy-pasting from Claude Code docs get the cryptic 'must be an
array of strings, got an array' error. PR #3000 already addresses
this but is conflicting and unmerged. Siblings: unknown hook event
rejects entire hooks config (#440 pattern); first-error-only halting;
kind:unknown catch-all (13th occurrence).
Pinpoint: .claw.json with one valid mcpServers entry + one missing-command
entry → mcp list returns configured_servers:0, servers:[]. The valid
server is silently dropped because parser halts on first error.
Five invalid entries in the same file produce only ONE error message
(first one); user must iterate N times to discover all problems.
Violates ROADMAP product principle #5 (partial success first-class).
