forge-orkes 0.70.0 → 0.72.2

package/template/.forge/checks/tests/forge-jarvis-dispatch.test.sh

@@ -192,6 +192,217 @@ else
   bad "numeric-id branch pick" "rc=$rc err=$err14"
 fi
 
+# --- 15-18. --plan WORK-ORDER SCOPING (FR-234; canvaz desire path 2026-07-22 defect 2:
+#     materialization bundled ALL phase dirs + ALL plan-NN.md, so a mid-milestone re-dispatch
+#     re-bundled landed work). --plan <phase> takes a whole phase, <phase>/plan-NN one plan
+#     file; unknown specs and hand-authored slice.yml refuse loudly. mktemp fixtures — a
+#     single milestone dir exercises the (branch-free) fallback pick.
+
+# 15. single-plan spec: only the named plan file lands in the phase's plan.md
+PSLICE="$ROOT/plan-one-wt"
+mkdir -p "$PSLICE/.forge/phases/milestone-77/1-aaa"
+printf 'LANDED plan one\n' > "$PSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+printf 'NEXT plan two\n'   > "$PSLICE/.forge/phases/milestone-77/1-aaa/plan-02.md"
+err15="$(sh "$DISPATCH" --slice "$PSLICE" --materialize-only --plan 1-aaa/plan-02 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && grep -q '^  - 1-aaa$' "$PSLICE/slice.yml" 2>/dev/null \
+   && grep -q 'NEXT plan two' "$PSLICE/phases/1-aaa/plan.md" 2>/dev/null \
+   && ! grep -q 'LANDED plan one' "$PSLICE/phases/1-aaa/plan.md" 2>/dev/null; then
+  ok "--plan <phase>/plan-NN scopes to exactly that plan (landed sibling NOT re-bundled)"
+else
+  bad "--plan single-plan scoping" "rc=$rc err=$err15 plan.md=$(cat "$PSLICE/phases/1-aaa/plan.md" 2>/dev/null)"
+fi
+
+# 16. whole-phase specs + ordering: numeric slice order regardless of flag order; unselected
+#     phases do NOT materialize
+OSLICE="$ROOT/plan-order-wt"
+mkdir -p "$OSLICE/.forge/phases/milestone-77/71-aaa" "$OSLICE/.forge/phases/milestone-77/72-bbb" "$OSLICE/.forge/phases/milestone-77/73-ccc"
+printf 'plan A\n' > "$OSLICE/.forge/phases/milestone-77/71-aaa/plan-01.md"
+printf 'plan B\n' > "$OSLICE/.forge/phases/milestone-77/72-bbb/plan-01.md"
+printf 'decoy\n'  > "$OSLICE/.forge/phases/milestone-77/73-ccc/plan-01.md"
+err16="$(sh "$DISPATCH" --slice "$OSLICE" --materialize-only --plan 72-bbb --plan 71-aaa 2>&1)"; rc=$?
+if [ "$rc" = 0 ] \
+   && [ "$(grep -E '^  - ' "$OSLICE/slice.yml" 2>/dev/null | tr -d ' -')" = "71aaa
+72bbb" ] \
+   && grep -q 'plan A' "$OSLICE/phases/71-aaa/plan.md" 2>/dev/null \
+   && grep -q 'plan B' "$OSLICE/phases/72-bbb/plan.md" 2>/dev/null \
+   && [ ! -d "$OSLICE/phases/73-ccc" ]; then
+  ok "--plan whole-phase specs keep numeric order (flag order ignored); unselected phase skipped"
+else
+  bad "--plan ordering" "rc=$rc err=$err16 slice.yml=$(cat "$OSLICE/slice.yml" 2>/dev/null)"
+fi
+
+# 17. NEG: unknown spec → loud refusal, no slice.yml (a typo must not dispatch the wrong order)
+USLICE="$ROOT/plan-unknown-wt"
+mkdir -p "$USLICE/.forge/phases/milestone-77/1-aaa"
+printf 'x\n' > "$USLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+err17="$(sh "$DISPATCH" --slice "$USLICE" --materialize-only --plan 2-nope 2>&1)"; rc=$?
+if [ "$rc" != 0 ] && [ ! -f "$USLICE/slice.yml" ] && printf '%s' "$err17" | grep -q 'REFUSED'; then
+  ok "neg-control: unknown --plan spec → loud refusal, no slice.yml"
+else
+  bad "unknown --plan spec" "rc=$rc err=$err17"
+fi
+
+# 18. NEG: --plan vs a HAND-AUTHORED slice.yml (no materializer header) → refusal; slice.yml
+#     byte-unchanged, seeded runner-work untouched (hand-authored work orders win, always)
+HPSLICE="$ROOT/plan-hand-wt"
+mkdir -p "$HPSLICE/.forge/phases/milestone-77/1-aaa" "$HPSLICE/.forge/runner-work/pings"
+printf 'x\n' > "$HPSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+printf 'phases:\n  - hand-rolled\n' > "$HPSLICE/slice.yml"
+touch "$HPSLICE/.forge/runner-work/pings/k-done.marker"
+before18="$(cat "$HPSLICE/slice.yml")"
+err18="$(sh "$DISPATCH" --slice "$HPSLICE" --materialize-only --plan 1-aaa 2>&1)"; rc=$?
+if [ "$rc" != 0 ] && printf '%s' "$err18" | grep -q 'REFUSED' \
+   && [ "$(cat "$HPSLICE/slice.yml")" = "$before18" ] \
+   && [ -f "$HPSLICE/.forge/runner-work/pings/k-done.marker" ]; then
+  ok "neg-control: --plan refuses a hand-authored slice.yml; nothing touched"
+else
+  bad "--plan vs hand-authored" "rc=$rc err=$err18"
+fi
+
+# 18b. NEG (path hygiene): a plan part carrying a separator (traversal shape) refuses —
+#      sh case patterns let * match /, so plan-../x.md would pass the plan-*.md form check
+#      and reach outside the milestone dir without this guard.
+TSLICE="$ROOT/plan-traverse-wt"
+mkdir -p "$TSLICE/.forge/phases/milestone-77/1-aaa"
+printf 'x\n' > "$TSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+err18b="$(sh "$DISPATCH" --slice "$TSLICE" --materialize-only --plan '1-aaa/plan-../x' 2>&1)"; rc=$?
+if [ "$rc" != 0 ] && [ ! -f "$TSLICE/slice.yml" ] && printf '%s' "$err18b" | grep -q 'REFUSED'; then
+  ok "neg-control: --plan file part with a path separator → loud refusal (no traversal)"
+else
+  bad "--plan traversal guard" "rc=$rc err=$err18b"
+fi
+
+# --- 19-21. RUNNER-WORK ROTATION (FR-235; canvaz desire path 2026-07-22 defect 3: stale
+#     pings/{key}-{kind}.marker silenced the new run's done ping and index-keyed
+#     phase-{idx}/phase-report.yml verdict:done short-circuited the new phase). A NEW work
+#     order rotates runner-work WHOLE (relay-markers are line-number-keyed siblings of
+#     notify.log — a partial reset would misalign offsets); resume paths keep slice.yml and
+#     are never rotated; archive, never delete.
+
+# 19. materializing a NEW order rotates seeded state into runner-work-archive; a replaced
+#     helper-materialized slice.yml is archived alongside
+RSLICE="$ROOT/rotate-wt"
+mkdir -p "$RSLICE/.forge/phases/milestone-77/1-aaa"
+printf 'LANDED\n' > "$RSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+printf 'NEXT\n'   > "$RSLICE/.forge/phases/milestone-77/1-aaa/plan-02.md"
+sh "$DISPATCH" --slice "$RSLICE" --materialize-only >/dev/null 2>&1   # first order (all plans) — seeds a materialized slice.yml
+# Seed the "run happened" state AFTER the first materialization (a dispatch with stale
+# runner-work already present would rotate it — exactly the behavior under test in 19).
+mkdir -p "$RSLICE/.forge/runner-work/pings" "$RSLICE/.forge/runner-work/phase-1" "$RSLICE/.forge/runner-work/relay-markers"
+touch "$RSLICE/.forge/runner-work/pings/k-done.marker"
+printf 'verdict: done\n' > "$RSLICE/.forge/runner-work/phase-1/phase-report.yml"
+touch "$RSLICE/.forge/runner-work/relay-markers/1.relayed"
+err19="$(sh "$DISPATCH" --slice "$RSLICE" --materialize-only --plan 1-aaa/plan-02 2>&1)"; rc=$?
+if [ "$rc" = 0 ] \
+   && [ ! -e "$RSLICE/.forge/runner-work/pings/k-done.marker" ] \
+   && [ ! -e "$RSLICE/.forge/runner-work/phase-1/phase-report.yml" ] \
+   && ls "$RSLICE/.forge/runner-work-archive/"*/pings/k-done.marker >/dev/null 2>&1 \
+   && ls "$RSLICE/.forge/runner-work-archive/"*/phase-1/phase-report.yml >/dev/null 2>&1 \
+   && ls "$RSLICE/.forge/runner-work-archive/"*/relay-markers/1.relayed >/dev/null 2>&1 \
+   && ls "$RSLICE/.forge/runner-work-archive/"*/slice.yml >/dev/null 2>&1 \
+   && grep -q 'NEXT' "$RSLICE/phases/1-aaa/plan.md" 2>/dev/null \
+   && ! grep -q 'LANDED' "$RSLICE/phases/1-aaa/plan.md" 2>/dev/null; then
+  ok "new work order rotates runner-work WHOLE (pings+report+relay-markers) + archives replaced slice.yml"
+else
+  bad "rotation on new order" "rc=$rc err=$err19"
+fi
+
+# 20. NEG (resume preserved): existing materialized slice.yml, NO --plan → honored as-is,
+#     runner-work untouched, no archive (crash-resume / park→answer→resume path)
+KSLICE="$ROOT/keep-wt"
+mkdir -p "$KSLICE/.forge/phases/milestone-77/1-aaa"
+printf 'x\n' > "$KSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+sh "$DISPATCH" --slice "$KSLICE" --materialize-only >/dev/null 2>&1   # materialized header slice.yml
+mkdir -p "$KSLICE/.forge/runner-work/pings"                            # seed AFTER — see case 19 note
+touch "$KSLICE/.forge/runner-work/pings/k-done.marker"
+before20="$(cat "$KSLICE/slice.yml")"
+err20="$(sh "$DISPATCH" --slice "$KSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && [ "$(cat "$KSLICE/slice.yml")" = "$before20" ] \
+   && [ -f "$KSLICE/.forge/runner-work/pings/k-done.marker" ] \
+   && [ ! -d "$KSLICE/.forge/runner-work-archive" ]; then
+  ok "neg-control: existing slice.yml honored → NO rotation (resume state survives)"
+else
+  bad "resume preserved" "rc=$rc err=$err20"
+fi
+
+# 21. NEG: --dry-run stays fully side-effect-free — no slice.yml, no rotation, even with
+#     stale runner-work present (extends case 12)
+YSLICE="$ROOT/dry-rotate-wt"
+mkdir -p "$YSLICE/.forge/phases/milestone-77/1-aaa" "$YSLICE/.forge/runner-work/pings"
+printf 'x\n' > "$YSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+touch "$YSLICE/.forge/runner-work/pings/k-done.marker"
+sh "$DISPATCH" --slice "$YSLICE" --dry-run >/dev/null 2>&1
+if [ ! -f "$YSLICE/slice.yml" ] && [ ! -d "$YSLICE/.forge/runner-work-archive" ] \
+   && [ -f "$YSLICE/.forge/runner-work/pings/k-done.marker" ]; then
+  ok "neg-control: --dry-run rotates nothing, writes nothing"
+else
+  bad "dry-run rotation" "dry-run had side effects"
+fi
+
+# 22. NEG: --work-dir refused loudly BEFORE the detach (R092) — a forwarded work dir
+#     would split-brain against the pinned notify.log/dispatch.out/rotation paths.
+#     Both arg forms; no slice.yml materialized, nothing dispatched.
+WSLICE="$ROOT/workdir-wt"
+mkdir -p "$WSLICE/.forge/phases/milestone-78/1-bbb"
+printf 'x\n' > "$WSLICE/.forge/phases/milestone-78/1-bbb/plan-01.md"
+err22="$(sh "$DISPATCH" --slice "$WSLICE" --work-dir "$ROOT/elsewhere" 2>&1 >/dev/null)"; rc=$?
+err22b="$(sh "$DISPATCH" --slice "$WSLICE" --work-dir="$ROOT/elsewhere" 2>&1 >/dev/null)"; rc2=$?
+if [ "$rc" = 2 ] && [ "$rc2" = 2 ] && [ ! -f "$WSLICE/slice.yml" ] \
+   && printf '%s' "$err22" | grep -q 'REFUSED' && printf '%s' "$err22b" | grep -q 'REFUSED'; then
+  ok "neg-control: --work-dir refused (both forms), nothing materialized"
+else
+  bad "work-dir refusal" "rc=$rc rc2=$rc2 err=$err22"
+fi
+
+# --- 23-24. STALENESS GUARD (live 2026-07-23: an amended source plan never reached the
+#     materialized work order — plain re-dispatch silently rebuilt the OLD spec). The
+#     materializer fingerprints each bundled plan-NN.md (`# source: ... cksum=N`); a plain
+#     re-dispatch re-checks them and refuses loudly on divergence. Refuse, never auto-rebuild
+#     (the honored-as-is branch serves resume paths whose runner-work must survive).
+
+# 23. NEG: amend a source plan after materialization → plain re-dispatch REFUSES loudly;
+#     slice.yml + runner-work untouched (no rotation — the operator decides)
+ZSLICE="$ROOT/stale-wt"
+mkdir -p "$ZSLICE/.forge/phases/milestone-77/1-aaa"
+printf 'original spec\n' > "$ZSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+sh "$DISPATCH" --slice "$ZSLICE" --materialize-only >/dev/null 2>&1
+mkdir -p "$ZSLICE/.forge/runner-work/pings"                           # seed AFTER — see case 19 note
+touch "$ZSLICE/.forge/runner-work/pings/k-done.marker"
+printf 'AMENDED spec\n' > "$ZSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+before23="$(cat "$ZSLICE/slice.yml")"
+err23="$(sh "$DISPATCH" --slice "$ZSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" != 0 ] && printf '%s' "$err23" | grep -q 'REFUSED' && printf '%s' "$err23" | grep -q 'STALE' \
+   && printf '%s' "$err23" | grep -q '1-aaa/plan-01.md' \
+   && [ "$(cat "$ZSLICE/slice.yml")" = "$before23" ] \
+   && [ -f "$ZSLICE/.forge/runner-work/pings/k-done.marker" ] \
+   && grep -q 'original spec' "$ZSLICE/phases/1-aaa/plan.md" 2>/dev/null; then
+  ok "staleness guard: amended source plan → plain re-dispatch refuses loudly, nothing touched"
+else
+  bad "staleness guard" "rc=$rc err=$err23"
+fi
+
+# 23b. the remedy the refusal names: --plan re-materializes the amended spec (and case 20's
+#      unchanged-source plain re-dispatch already proves the guard stays quiet when fresh)
+err23b="$(sh "$DISPATCH" --slice "$ZSLICE" --materialize-only --plan 1-aaa 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && grep -q 'AMENDED spec' "$ZSLICE/phases/1-aaa/plan.md" 2>/dev/null; then
+  ok "staleness remedy: --plan rebuilds the work order to the amended spec"
+else
+  bad "staleness remedy" "rc=$rc err=$err23b"
+fi
+
+# 24. NEG (lazy migration): a pre-guard materialized slice.yml (helper header, NO
+#     fingerprint lines) is still honored as-is — the guard never bricks an in-flight order
+GSLICE="$ROOT/legacy-wt"
+mkdir -p "$GSLICE/.forge/phases/milestone-77/1-aaa" "$GSLICE/phases/1-aaa"
+printf 'x\n' > "$GSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+printf 'x\n' > "$GSLICE/phases/1-aaa/plan.md"
+printf '# Materialized by forge-jarvis-dispatch from .forge/phases/milestone-77 (delete to re-materialize)\nphases:\n  - 1-aaa\n' > "$GSLICE/slice.yml"
+err24="$(sh "$DISPATCH" --slice "$GSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && printf '%s' "$err24" | grep -q 'using it as-is'; then
+  ok "lazy migration: pre-guard materialized slice.yml (no fingerprints) honored as-is"
+else
+  bad "legacy materialized order" "rc=$rc err=$err24"
+fi
 # --- summary -----------------------------------------------------------------
 printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
 [ "$FAILED" = 0 ]

package/template/.forge/checks/tests/forge-jarvis.test.sh

@@ -13,11 +13,17 @@
 #   mode (post-UAT 2026-07-22): jarvis.spawn_permission_mode appends --permission-mode,
 #   env FORGE_JARVIS_SPAWN_PERMISSION_MODE beats config, unset = no flag. Refusals:
 #   jarvis.enabled: false, unknown spawn_permission_mode, or not a git repo →
-#   non-zero exit, NO command on stdout.
+#   non-zero exit, NO command on stdout. Double-start guard (firstmate-review
+#   adoption 2026-07-22): on REAL launch a live `claude remote-control` already
+#   holding the resolved sticky name → refusal naming the live pid; exact --name
+#   token match (a live prefix-sibling never blocks); unreadable ps → warn +
+#   proceed. --dry-run never runs the guard.
 #
-# Builds throwaway git repos in a mktemp dir, offline by construction; only ever
-# invokes --dry-run, so `claude`/`caffeinate` need not exist (dry-run is pure
-# resolution — that determinism is itself part of the contract).
+# Builds throwaway git repos in a mktemp dir, offline by construction; dry-run
+# cases need no `claude`/`caffeinate` (dry-run is pure resolution — that
+# determinism is itself part of the contract), and the real-launch guard cases
+# stub the ps read via FORGE_JARVIS_PS and put a fake `claude` first on PATH so
+# fall-through provably reaches the launch without ever starting a real server.
 #
 # Usage: ./.forge/checks/tests/forge-jarvis.test.sh
 # RED-phase friendly: a missing/non-executable script fails every case, exits non-zero.
@@ -176,6 +182,74 @@ else
   bad "neg-control non-repo" "rc=$rc out=$out"
 fi
 
+# --- double-start guard (real launch; firstmate-review adoption 2026-07-22) ---
+# Reset the fixture to a clean enabled config (sticky base is jarvis-proj again).
+cat > "$REPO/.forge/project.yml" <<'EOF'
+jarvis:
+  enabled: true
+EOF
+# Fake `claude` first on PATH: fall-through cases provably REACH the launch
+# (marker file written) without ever starting a real server. caffeinate, when
+# present, resolves `claude` through the same inherited PATH → still the fake.
+FAKEBIN="$ROOT/fakebin"
+mkdir -p "$FAKEBIN"
+cat > "$FAKEBIN/claude" <<EOF
+#!/bin/sh
+printf '%s\n' "\$*" > "$ROOT/launch.args"
+exit 0
+EOF
+chmod +x "$FAKEBIN/claude"
+
+# 13. a live same-name server → refusal naming the live pid, nothing launched
+STUB_DUP="$ROOT/stub-ps-dup"
+cat > "$STUB_DUP" <<'EOF'
+#!/bin/sh
+printf '  4242 caffeinate -s claude remote-control --name jarvis-proj --spawn worktree --capacity 4\n'
+printf '  4243 claude remote-control --name jarvis-proj --spawn worktree --capacity 4\n'
+EOF
+chmod +x "$STUB_DUP"
+rm -f "$ROOT/launch.args"
+out="$(cd "$REPO" && FORGE_JARVIS_PS="$STUB_DUP" PATH="$FAKEBIN:$PATH" sh "$JARVIS" 2>/dev/null)"; rc=$?
+err="$(cd "$REPO" && FORGE_JARVIS_PS="$STUB_DUP" PATH="$FAKEBIN:$PATH" sh "$JARVIS" 2>&1 >/dev/null)"
+if [ "$rc" != 0 ] && [ -z "$out" ] && [ ! -f "$ROOT/launch.args" ]; then
+  case "$err" in
+    *jarvis-proj*4242*) ok "double-start guard: live same-name server → refusal naming the live pid" ;;
+    *) bad "double-start refusal message" "err=$err" ;;
+  esac
+else
+  bad "double-start guard" "rc=$rc out=$out launched=$([ -f "$ROOT/launch.args" ] && echo yes || echo no)"
+fi
+
+# 14. NEG: prefix near-miss (jarvis-proj-personal live) must NOT trip the guard —
+#     exact --name token match; fall-through provably reaches the launch
+STUB_NEAR="$ROOT/stub-ps-nearmiss"
+cat > "$STUB_NEAR" <<'EOF'
+#!/bin/sh
+printf '  5151 caffeinate -s claude remote-control --name jarvis-proj-personal --spawn worktree --capacity 4\n'
+printf '  5152 vim notes-on-remote-control.md\n'
+EOF
+chmod +x "$STUB_NEAR"
+rm -f "$ROOT/launch.args"
+out="$(cd "$REPO" && FORGE_JARVIS_PS="$STUB_NEAR" PATH="$FAKEBIN:$PATH" sh "$JARVIS" 2>/dev/null)"; rc=$?
+if [ "$rc" = 0 ] && [ -f "$ROOT/launch.args" ] && grep -q -- "--name jarvis-proj --spawn" "$ROOT/launch.args"; then
+  ok "neg-control: live prefix-sibling name does not block — exact token match, launch reached"
+else
+  bad "neg-control prefix near-miss" "rc=$rc launched=$([ -f "$ROOT/launch.args" ] && cat "$ROOT/launch.args" || echo no)"
+fi
+
+# 15. unreadable ps → warn + proceed (advisory hygiene, never a hard fail)
+rm -f "$ROOT/launch.args"
+out="$(cd "$REPO" && FORGE_JARVIS_PS="$ROOT/no-such-stub" PATH="$FAKEBIN:$PATH" sh "$JARVIS" 2>/dev/null)"; rc=$?
+err="$(cd "$REPO" && FORGE_JARVIS_PS="$ROOT/no-such-stub" PATH="$FAKEBIN:$PATH" sh "$JARVIS" 2>&1 >/dev/null)"
+if [ "$rc" = 0 ] && [ -f "$ROOT/launch.args" ]; then
+  case "$err" in
+    *"duplicate-door check unavailable"*) ok "unreadable ps → stated warning + launch proceeds (fail-open, explicit)" ;;
+    *) bad "ps-failure warning wording" "err=$err" ;;
+  esac
+else
+  bad "ps-failure fail-open" "rc=$rc launched=$([ -f "$ROOT/launch.args" ] && echo yes || echo no)"
+fi
+
 # --- summary -----------------------------------------------------------------
 printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
 [ "$FAILED" = 0 ]

package/template/.forge/checks/tests/forge-reserve.test.sh

@@ -0,0 +1,235 @@
+#!/usr/bin/env sh
+# Fixture-repo test suite for .claude/hooks/forge-reserve.sh (m-41, plan 81-01).
+#
+# Contract under test (ADR-021/023/029 + FR-236/237/238, NFR-045):
+#   phase  — computed P-0NN; in-tree scan = live roadmap `- id: N` ints ∪ archived
+#            phase dirs .forge/archive/milestone-*/phases/<N>-* (burned ids never
+#            reallocated); ledger + main:reservations.yml floors as for all kinds.
+#   wave   — computed W-0NN; in-tree scan = live waves-map KEYS only (never the
+#            phase ids inside the brackets).
+#   version — RECORD-ONLY (--value): clean claim dual-writes ledger +
+#            reservations.yml and echoes the value; the SAME value claimed by a
+#            DIFFERENT milestone → exit 1, stderr names the holder, nothing
+#            written; re-claim by the SAME milestone → exit 0, idempotent, no
+#            duplicate line; missing --value → usage exit 2, nothing written.
+#   regression (NFR-045) — the pre-existing kinds' ids and file shapes are
+#            unchanged; the lock releases so back-to-back calls never time out.
+#
+# Every case builds its own mktemp fixture repo (real `git init`) — the suite
+# never touches the enclosing dev repo's state. Output: one line per case,
+# `case N <tag> PASS` or `case N <tag> FAIL: <why>`; non-zero exit if any FAIL.
+#
+# Usage: sh .forge/checks/tests/forge-reserve.test.sh
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RESERVE="$SCRIPT_DIR/../../../.claude/hooks/forge-reserve.sh"
+[ -f "$RESERVE" ] || { printf 'FATAL: %s missing\n' "$RESERVE" >&2; exit 1; }
+
+GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null
+export GIT_CONFIG_GLOBAL GIT_CONFIG_SYSTEM
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+fails=0
+n=0
+
+# new_fixture <name> → prints the fixture repo path
+new_fixture() {
+  fx="$ROOT/$1"
+  mkdir -p "$fx"
+  git -C "$fx" init -q
+  printf '%s' "$fx"
+}
+
+report() { # report <tag> <pass|fail> [why]
+  n=$((n + 1))
+  if [ "$2" = pass ]; then
+    printf 'case %d %s PASS\n' "$n" "$1"
+  else
+    printf 'case %d %s FAIL: %s\n' "$n" "$1" "${3:-unspecified}"
+    fails=$((fails + 1))
+  fi
+}
+
+# ── FR-236: phase kind ────────────────────────────────────────────────────────
+
+# case 1 phase-archive-aware — roadmap max 12, archived phase dir 14 → P-015
+fx=$(new_fixture c1)
+mkdir -p "$fx/.forge/archive/milestone-9/phases/14-old"
+printf 'roadmap:\n  phases:\n    - id: 11\n    - id: 12\n' > "$fx/.forge/roadmap.yml"
+out=$(cd "$fx" && "$RESERVE" phase --milestone m-t 2>/dev/null)
+if [ "$out" = "P-015" ]; then report phase-archive-aware pass
+else report phase-archive-aware fail "expected P-015 (archived 14 must stay burned), got: $out"; fi
+
+# case 2 phase-dual-write — case 1's claim landed in BOTH registries
+if grep -q "phase	P-015	m-t" "$fx/.git/forge/id-reservations" 2>/dev/null \
+   && grep -q "id: P-015" "$fx/.forge/reservations.yml" 2>/dev/null; then
+  report phase-dual-write pass
+else report phase-dual-write fail "P-015 missing from ledger or reservations.yml"; fi
+
+# case 3 phase-sibling-ledger — uncommitted sibling ledger claim is visible
+fx=$(new_fixture c3)
+mkdir -p "$fx/.forge" "$fx/.git/forge"
+printf 'roadmap:\n  phases:\n    - id: 12\n' > "$fx/.forge/roadmap.yml"
+printf 'phase\tP-015\tm-sib\t2026-07-23T00:00:00Z\n' >> "$fx/.git/forge/id-reservations"
+out=$(cd "$fx" && "$RESERVE" phase --milestone m-t 2>/dev/null)
+if [ "$out" = "P-016" ]; then report phase-sibling-ledger pass
+else report phase-sibling-ledger fail "sibling claim P-015 ignored — expected P-016, got: $out"; fi
+
+# case 4 phase-fresh — no roadmap, no archive → P-001
+fx=$(new_fixture c4)
+out=$(cd "$fx" && "$RESERVE" phase --milestone m-t 2>/dev/null)
+if [ "$out" = "P-001" ]; then report phase-fresh pass
+else report phase-fresh fail "fresh repo expected P-001, got: $out"; fi
+
+# case 5 phase-wave-keys-not-counted — waves KEYS and bracket ids must not leak
+# into the phase max: roadmap phase max 3, waves key 9 pointing at [3] → P-004.
+fx=$(new_fixture c5)
+mkdir -p "$fx/.forge"
+printf 'roadmap:\n  phases:\n    - id: 3\n  waves:\n    9: [3]\n' > "$fx/.forge/roadmap.yml"
+out=$(cd "$fx" && "$RESERVE" phase --milestone m-t 2>/dev/null)
+if [ "$out" = "P-004" ]; then report phase-wave-keys-not-counted pass
+else report phase-wave-keys-not-counted fail "expected P-004 (wave key 9 is not a phase id), got: $out"; fi
+
+# ── FR-237: wave kind ────────────────────────────────────────────────────────
+
+# case 6 wave-max-key — waves keys 1,7 (bracket ids larger) → W-008
+fx=$(new_fixture c6)
+mkdir -p "$fx/.forge"
+printf 'roadmap:\n  phases:\n    - id: 1\n  waves:\n    1: [40]\n    7: [41]\n' > "$fx/.forge/roadmap.yml"
+out=$(cd "$fx" && "$RESERVE" wave --milestone m-t 2>/dev/null)
+if [ "$out" = "W-008" ]; then report wave-max-key pass
+else report wave-max-key fail "expected W-008 (max KEY 7, ids in brackets ignored), got: $out"; fi
+
+# case 7 wave-fresh — no waves block anywhere → W-001
+fx=$(new_fixture c7)
+out=$(cd "$fx" && "$RESERVE" wave --milestone m-t 2>/dev/null)
+if [ "$out" = "W-001" ]; then report wave-fresh pass
+else report wave-fresh fail "expected W-001, got: $out"; fi
+
+# ── FR-238: version kind (record-only) ───────────────────────────────────────
+
+# case 8 version-clean-claim — records in BOTH registries, echoes the value
+fx=$(new_fixture c8)
+out=$(cd "$fx" && "$RESERVE" version --value 0.9.0 --milestone m-a 2>/dev/null)
+if [ "$out" = "0.9.0" ] \
+   && grep -q "version	0.9.0	m-a" "$fx/.git/forge/id-reservations" 2>/dev/null \
+   && grep -q 'id: 0.9.0' "$fx/.forge/reservations.yml" 2>/dev/null; then
+  report version-clean-claim pass
+else report version-clean-claim fail "claim not recorded in both registries (stdout: $out)"; fi
+
+# case 9 version-conflict-refused — different milestone, same value → exit 1,
+# stderr names the holder, NOTHING written
+err=$(cd "$fx" && "$RESERVE" version --value 0.9.0 --milestone m-b 2>&1 >/dev/null)
+rc=$?
+lines=$(grep -c '^version' "$fx/.git/forge/id-reservations" 2>/dev/null)
+case "$err" in
+  *m-a*) named=yes ;;
+  *) named=no ;;
+esac
+if [ "$rc" -ne 0 ] && [ "$named" = yes ] && [ "$lines" = "1" ]; then
+  report version-conflict-refused pass
+else report version-conflict-refused fail "rc=$rc named-holder=$named ledger-version-lines=$lines (want rc!=0, holder m-a named, 1 line)"; fi
+
+# case 10 version-idempotent-reclaim — same milestone re-claims → exit 0, no dup
+out=$(cd "$fx" && "$RESERVE" version --value 0.9.0 --milestone m-a 2>/dev/null)
+rc=$?
+lines=$(grep -c '^version' "$fx/.git/forge/id-reservations" 2>/dev/null)
+if [ "$rc" -eq 0 ] && [ "$out" = "0.9.0" ] && [ "$lines" = "1" ]; then
+  report version-idempotent-reclaim pass
+else report version-idempotent-reclaim fail "rc=$rc stdout=$out ledger-version-lines=$lines (want 0 / 0.9.0 / 1)"; fi
+
+# case 11 version-missing-value — usage exit 2, nothing written
+fx=$(new_fixture c11)
+err=$(cd "$fx" && "$RESERVE" version --milestone m-a 2>&1 >/dev/null)
+rc=$?
+if [ "$rc" -eq 2 ] && [ ! -f "$fx/.git/forge/id-reservations" ] && [ ! -f "$fx/.forge/reservations.yml" ]; then
+  report version-missing-value pass
+else report version-missing-value fail "rc=$rc (want 2) or files written on usage error"; fi
+
+# ── NFR-045: existing kinds regression + lock release ────────────────────────
+
+# case 12 regression-existing-kinds — fr x2 / milestone / refactor sequence and
+# reservations.yml shape identical to pre-m-41 behavior
+fx=$(new_fixture c12)
+a=$(cd "$fx" && "$RESERVE" fr --milestone m-t 2>/dev/null)
+b=$(cd "$fx" && "$RESERVE" fr --milestone m-t 2>/dev/null)
+m=$(cd "$fx" && "$RESERVE" milestone --milestone m-new 2>/dev/null)
+r=$(cd "$fx" && "$RESERVE" refactor --milestone m-t 2>/dev/null)
+if [ "$a $b $m $r" = "FR-001 FR-002 M-1 R001" ] \
+   && grep -q '^reservations:' "$fx/.forge/reservations.yml" 2>/dev/null \
+   && grep -q 'kind: refactor' "$fx/.forge/reservations.yml" 2>/dev/null; then
+  report regression-existing-kinds pass
+else report regression-existing-kinds fail "expected FR-001 FR-002 M-1 R001 + seeded header, got: $a $b $m $r"; fi
+
+# case 13 regression-lock-release — back-to-back calls in one fixture must not
+# time out (a leaked lock would make the second call exit 3)
+fx=$(new_fixture c13)
+(cd "$fx" && "$RESERVE" adr --milestone m-t >/dev/null 2>&1)
+out=$(cd "$fx" && FORGE_RESERVE_WAIT=2 "$RESERVE" adr --milestone m-t 2>/dev/null)
+rc=$?
+if [ "$rc" -eq 0 ] && [ "$out" = "ADR-002" ]; then
+  report regression-lock-release pass
+else report regression-lock-release fail "second call rc=$rc out=$out (leaked lock?)"; fi
+
+# ── input hardening (review, m-41): validation before the lock, nothing written ─
+
+# case 14 version-value-rejects-non-semver — --value must be X.Y.Z; a non-semver
+# (here a YAML-injection payload) → exit 2, NOTHING written
+fx=$(new_fixture c14)
+err=$(cd "$fx" && "$RESERVE" version --value '9.9.9
+injected: pwned' --milestone m-a 2>&1 >/dev/null)
+rc=$?
+if [ "$rc" -eq 2 ] && [ ! -f "$fx/.git/forge/id-reservations" ] && [ ! -f "$fx/.forge/reservations.yml" ]; then
+  report version-value-rejects-non-semver pass
+else report version-value-rejects-non-semver fail "rc=$rc (want 2) or files written on bad --value"; fi
+
+# case 15 version-value-accepts-prerelease — X.Y.Z-pre is valid semver → recorded
+fx=$(new_fixture c15)
+out=$(cd "$fx" && "$RESERVE" version --value 1.2.0-rc.1 --milestone m-a 2>/dev/null)
+if [ "$out" = "1.2.0-rc.1" ]; then report version-value-accepts-prerelease pass
+else report version-value-accepts-prerelease fail "expected 1.2.0-rc.1 recorded, got: $out"; fi
+
+# case 16 milestone-rejects-control-char — a newline in --milestone would split
+# the ledger row / inject a sibling YAML key → exit 2, NOTHING written
+fx=$(new_fixture c16)
+err=$(cd "$fx" && "$RESERVE" fr --milestone 'm-1
+    injected: pwned' 2>&1 >/dev/null)
+rc=$?
+if [ "$rc" -eq 2 ] && [ ! -f "$fx/.git/forge/id-reservations" ] && [ ! -f "$fx/.forge/reservations.yml" ]; then
+  report milestone-rejects-control-char pass
+else report milestone-rejects-control-char fail "rc=$rc (want 2) or files written on control-char milestone"; fi
+
+# case 17 symlink-target-refused — reservations.yml is a symlink → refuse to
+# write through it, exit 2, and the symlink target stays untouched
+fx=$(new_fixture c17)
+mkdir -p "$fx/.forge"
+: > "$ROOT/c17-victim.txt"
+ln -s "$ROOT/c17-victim.txt" "$fx/.forge/reservations.yml"
+err=$(cd "$fx" && "$RESERVE" fr --milestone m-t 2>&1 >/dev/null)
+rc=$?
+if [ "$rc" -eq 2 ] && [ ! -s "$ROOT/c17-victim.txt" ]; then
+  report symlink-target-refused pass
+else report symlink-target-refused fail "rc=$rc (want 2) or victim written through symlink"; fi
+
+# case 18 main-floor — cross-machine/cold-start floor: main:reservations.yml
+# carries a merged P-020, empty ledger + roadmap → next phase is P-021
+fx=$(new_fixture c18)
+mkdir -p "$fx/.forge"
+printf 'reservations:\n  - kind: phase\n    id: P-020\n    milestone: m-old\n' > "$fx/.forge/reservations.yml"
+git -C "$fx" add .forge/reservations.yml >/dev/null 2>&1
+git -C "$fx" -c user.email=t@t -c user.name=t commit -qm seed >/dev/null 2>&1
+git -C "$fx" branch -M main >/dev/null 2>&1
+out=$(cd "$fx" && "$RESERVE" phase --milestone m-t 2>/dev/null)
+if [ "$out" = "P-021" ]; then report main-floor pass
+else report main-floor fail "main floor P-020 ignored — expected P-021, got: $out"; fi
+
+# ── summary ──────────────────────────────────────────────────────────────────
+if [ "$fails" -eq 0 ]; then
+  printf 'forge-reserve.test.sh: all %d cases PASS\n' "$n"
+  exit 0
+fi
+printf 'forge-reserve.test.sh: %d of %d cases FAILED\n' "$fails" "$n" >&2
+exit 1