Prevent helper-era ROADMAP id collisions before review (#3115)

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.

scripts/roadmap-check-ids.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# roadmap-check-ids.sh — fail when helper-era ROADMAP item ids are duplicated.
+# Usage: scripts/roadmap-check-ids.sh [--min-id N] [path/to/ROADMAP.md]
+#
+# By default this validates ids >= 723, the point where ROADMAP appends started
+# using scripts/roadmap-next-id.sh. Earlier ROADMAP content contains historical
+# numbered lists and already-landed duplicate low ids, so the default guard is
+# intentionally scoped to new helper-era append collisions. Use --min-id 1 for a
+# strict whole-file audit after legacy numbering is cleaned up.
+set -euo pipefail
+
+MIN_ID=723
+ROADMAP="ROADMAP.md"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --min-id)
+      if [[ $# -lt 2 || ! "$2" =~ ^[0-9]+$ ]]; then
+        echo "error: --min-id requires a non-negative integer" >&2
+        exit 2
+      fi
+      MIN_ID="$2"
+      shift 2
+      ;;
+    --help|-h)
+      sed -n '2,9p' "$0" | sed 's/^# //; s/^#//'
+      exit 0
+      ;;
+    --*)
+      echo "error: unknown option: $1" >&2
+      exit 2
+      ;;
+    *)
+      ROADMAP="$1"
+      shift
+      ;;
+  esac
+done
+
+if [[ ! -f "$ROADMAP" ]]; then
+  echo "error: ROADMAP not found at $ROADMAP" >&2
+  exit 1
+fi
+
+awk -v min_id="$MIN_ID" -v path="$ROADMAP" '
+  /^[0-9]+\./ {
+    id = $0
+    sub(/\..*/, "", id)
+    id += 0
+    if (id >= min_id) {
+      count[id]++
+      lines[id] = lines[id] (lines[id] ? ", " : "") FNR
+    }
+  }
+  END {
+    for (id in count) {
+      if (count[id] > 1) {
+        duplicate_count++
+        duplicate_ids[duplicate_count] = id
+      }
+    }
+    if (duplicate_count) {
+      print "error: duplicate ROADMAP numeric id(s) in " path " (min id " min_id "):" > "/dev/stderr"
+      for (i = 1; i <= duplicate_count; i++) {
+        id = duplicate_ids[i]
+        print "  - " id " at line(s) " lines[id] > "/dev/stderr"
+      }
+      exit 1
+    }
+    print "roadmap id check passed: no duplicate ids >= " min_id " in " path
+  }
+' "$ROADMAP"

scripts/roadmap-next-id.sh

@@ -12,8 +12,9 @@
 #
 # The script reads the highest numeric id prefix from ROADMAP.md and
 # prints highest+1.  It does not lock the file; callers working in
-# parallel should git-pull immediately before appending and resolve
-# any append collision at git-push time.
+# parallel should git-pull immediately before appending, run
+# scripts/roadmap-check-ids.sh before push, and resolve any append
+# collision at git-push time.
 set -euo pipefail
 
 ROADMAP="${1:-ROADMAP.md}"