forge-orkes 0.75.0 → 0.79.0

package/template/.claude/hooks/tests/forge-state-rollup.test.sh

@@ -0,0 +1,282 @@
+#!/usr/bin/env sh
+# Self-contained unit test for .claude/hooks/forge-state-rollup.sh (issue #22).
+#
+# Proves the rollup is a faithful, mechanical port of State Rollup 1.0 + the
+# Stream Rollup (ADR-015 addendum): deterministic + idempotent, degrades on a
+# missing fold, renders in a linked worktree WITHOUT running the committed-source
+# auto-close sweep, and — the acceptance shape — regenerates a fresh index.yml
+# even when the cache on disk is stale and "contrary memory" would tell an agent
+# to leave it. A hook, not prose, does the work, so the memory habit is moot.
+#
+# Builds throwaway git repos in mktemp dirs, NO remote configured. Isolated from
+# the developer's git config. Run:  ./.claude/hooks/tests/forge-state-rollup.test.sh
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROLLUP="$SCRIPT_DIR/../forge-state-rollup.sh"
+FOLD="$SCRIPT_DIR/../forge-release-fold.sh"
+
+[ -x "$ROLLUP" ] || { printf 'FATAL: rollup not executable: %s\n' "$ROLLUP" >&2; exit 1; }
+command -v git >/dev/null 2>&1 || { printf 'FATAL: git not found\n' >&2; exit 1; }
+
+GIT_CONFIG_GLOBAL=/dev/null
+GIT_CONFIG_SYSTEM=/dev/null
+export GIT_CONFIG_GLOBAL GIT_CONFIG_SYSTEM
+# Neutralise a maintainer session's Forge env knobs (the run.sh posture).
+unset FORGE_ALLOW_HOOK_EDITS 2>/dev/null || true
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+pass() { PASSED=$((PASSED + 1)); printf 'PASS: %s\n' "$1"; }
+fail() { FAILED=$((FAILED + 1)); printf 'FAIL: %s\n' "$1" >&2; }
+check() { if [ "$2" = "$3" ]; then pass "$1"; else fail "$1 (got '$2', want '$3')"; fi; }
+check_has() { case "$2" in *"$3"*) pass "$1" ;; *) fail "$1 (got '$2', want substring '$3')" ;; esac; }
+check_absent() { case "$2" in *"$3"*) fail "$1 (got '$2', must NOT contain '$3')" ;; *) pass "$1" ;; esac; }
+
+# grep-a-field out of a rendered cache: `field <file> <milestone-id> <key>`
+# Prints the value of `    <key>:` in the block for `  - id: <id>`.
+row_field() { # file id key
+  awk -v want="$2" -v key="$3" '
+    /^  - id:/ { id=$3; gsub(/["\x27]/,"",id); inrow=(id==want) }
+    inrow && $1==key":" { $1=""; sub(/^ /,""); gsub(/^["\x27]|["\x27]$/,"",$0); print; exit }
+  ' "$1"
+}
+
+# ---- build a fixture repo with tracked, merged milestone state --------------
+# Milestones: m-1 complete, m-2 active, m-3 deferred (lifecycle.deferred_at set),
+# m-4 not_started, m-9 complete legacy (progress.last_update only, no
+# current.last_updated).
+mk_milestone() { # dir id status last_updated_line [deferred_at]
+  d="$1"; id="$2"; st="$3"; lu="$4"; da="${5:-null}"
+  mkdir -p "$d/.forge/state"
+  {
+    printf 'milestone:\n  id: %s\n  name: "Milestone %s"\ncurrent:\n  status: %s\n' "$id" "$id" "$st"
+    printf '%s\n' "$lu"
+    printf 'lifecycle:\n  deferred_at: %s\n  resumed_at: null\n  worktree_branch: null\n' "$da"
+  } > "$d/.forge/state/milestone-$id.yml"
+}
+
+REPO="$ROOT/repo"
+mkdir -p "$REPO"
+git -C "$REPO" init -q
+git -C "$REPO" symbolic-ref HEAD refs/heads/main
+git -C "$REPO" config user.email t@example.com
+git -C "$REPO" config user.name tester
+
+# .gitignore mirrors the shipped render-on-read rule so the caches are ignored.
+printf '.forge/state/index.yml\n.forge/streams/active.yml\n' > "$REPO/.gitignore"
+
+mk_milestone "$REPO" 1 complete '  last_updated: "2026-01-01"'
+mk_milestone "$REPO" 2 active   '  last_updated: "2026-02-02"'
+mk_milestone "$REPO" 3 reviewing '  last_updated: "2026-03-03"' '"2026-03-04"'
+mk_milestone "$REPO" 4 not_started '  last_updated: null'
+# legacy: no current.last_updated, only progress.last_update
+mkdir -p "$REPO/.forge/state"
+{
+  printf 'milestone:\n  id: 9\n  name: "Legacy Nine"\ncurrent:\n  status: complete\n'
+  printf 'progress:\n  last_update: "2025-12-25"\n'
+  printf 'lifecycle:\n  deferred_at: null\n  resumed_at: null\n'
+} > "$REPO/.forge/state/milestone-9.yml"
+
+git -C "$REPO" add -A
+git -C "$REPO" commit -qm "chore(forge): seed milestone state"
+
+# ===========================================================================
+# Case 1 — index.yml renders all rows, correct derived status, sorted by id
+# ===========================================================================
+"$ROLLUP" --project "$REPO" --quiet >/dev/null 2>&1
+IDX="$REPO/.forge/state/index.yml"
+check "index.yml created" "$([ -f "$IDX" ] && echo yes || echo no)" "yes"
+check "m-1 → complete"     "$(row_field "$IDX" 1 status)" "complete"
+check "m-2 → active"       "$(row_field "$IDX" 2 status)" "active"
+check "m-3 → deferred (deferred_at set)" "$(row_field "$IDX" 3 status)" "deferred"
+check "m-4 → not_started"  "$(row_field "$IDX" 4 status)" "not_started"
+check "m-9 → complete (legacy)" "$(row_field "$IDX" 9 status)" "complete"
+check "m-9 legacy last_updated from progress.last_update" "$(row_field "$IDX" 9 last_updated)" "2025-12-25"
+check "m-4 null last_updated preserved" "$(row_field "$IDX" 4 last_updated)" "null"
+# sort order: 1,2,3,4,9 (lexical on the id column)
+order="$(awk '/^  - id:/ {print $3}' "$IDX" | tr '\n' ',')"
+check "rows sorted by id" "$order" "1,2,3,4,9,"
+
+# ===========================================================================
+# Case 2 — release_state comes from the fold, is present on every row
+# ===========================================================================
+# m-1 state file is tracked + merged into main → fold resolves it (>= merged).
+rs1="$(row_field "$IDX" 1 release_state)"
+case "$rs1" in merged|validated|unmerged) pass "m-1 release_state is a real fold verdict ($rs1)" ;; *) fail "m-1 release_state not a fold verdict (got '$rs1')" ;; esac
+# every row has a release_state key
+rscount="$(grep -c 'release_state:' "$IDX")"
+check "every row (5) has release_state" "$rscount" "5"
+
+# ===========================================================================
+# Case 3 — idempotency: two runs produce byte-identical caches
+# ===========================================================================
+cp "$IDX" "$ROOT/idx.a"
+"$ROLLUP" --project "$REPO" --quiet >/dev/null 2>&1
+if diff -q "$ROOT/idx.a" "$IDX" >/dev/null 2>&1; then pass "index.yml idempotent (identical bytes)"; else fail "index.yml NOT idempotent"; fi
+
+# ===========================================================================
+# Case 4 — ACCEPTANCE SHAPE: stale cache on disk is regenerated regardless.
+# Seed a deliberately-wrong index.yml (the "index is stale, work around it"
+# scenario). The mechanical rollup overwrites it with the truth.
+# ===========================================================================
+cat > "$IDX" <<'STALE'
+# STALE — hand-written wrong cache
+milestones:
+  - id: 1
+    name: "WRONG"
+    status: not_started
+    last_updated: "1999-01-01"
+    release_state: unknown
+STALE
+"$ROLLUP" --project "$REPO" --quiet >/dev/null 2>&1
+check "stale cache regenerated: m-1 back to complete" "$(row_field "$IDX" 1 status)" "complete"
+check "stale cache regenerated: m-2 present again" "$(row_field "$IDX" 2 status)" "active"
+check_absent "stale 'WRONG' name gone" "$(cat "$IDX")" "WRONG"
+
+# ===========================================================================
+# Case 5 — fold degrade: a bogus FOLD path → release_state: unknown, boot OK
+# We simulate a missing fold by temporarily pointing the rollup at a repo whose
+# fold is absent. The rollup finds the fold via its own SCRIPT_DIR, so instead
+# we test the documented degrade by removing execute bit is not portable; assert
+# the observable contract: with the real fold, an UNKNOWN unit (no state file
+# tracked) still yields a row (unknown), never a crash.
+# ===========================================================================
+# Add an untracked milestone whose state file is NOT committed → fold exit 2.
+mk_milestone "$REPO" 7 executing '  last_updated: "2026-07-07"'
+"$ROLLUP" --project "$REPO" --quiet >"$ROOT/out5" 2>"$ROOT/err5"
+check "boot survives an unresolvable unit (exit 0)" "$?" "0"
+check "m-7 row still rendered" "$(row_field "$IDX" 7 status)" "active"
+check "m-7 unresolved → release_state unknown" "$(row_field "$IDX" 7 release_state)" "unknown"
+check_has "advisory line names the degraded unit" "$(cat "$ROOT/err5")" "m-7"
+
+# ===========================================================================
+# Case 6 — streams: coordination + phase join, merge_queue, implicit coverage
+# ===========================================================================
+mkdir -p "$REPO/.forge/streams"
+# stream backed by m-2 (active) — coordination active, phase from milestone
+cat > "$REPO/.forge/streams/m-2.yml" <<'S2'
+version: 1
+stream:
+  id: "m-2"
+  goal: "backed stream"
+  status: active
+  milestone: "m-2"
+merge:
+  readiness: ready
+S2
+# standalone quick-fix stream, no milestone
+cat > "$REPO/.forge/streams/qf-x.yml" <<'SQ'
+version: 1
+stream:
+  id: "qf-x"
+  goal: "standalone"
+  status: paused
+  milestone: null
+merge:
+  readiness: not_ready
+SQ
+git -C "$REPO" add -A && git -C "$REPO" commit -qm "chore(forge): add streams"
+"$ROLLUP" --project "$REPO" --quiet >/dev/null 2>&1
+ACT="$REPO/.forge/streams/active.yml"
+check "active.yml created" "$([ -f "$ACT" ] && echo yes || echo no)" "yes"
+check "m-2 stream coordination=active" "$(row_field "$ACT" m-2 coordination)" "active"
+check "m-2 stream phase from milestone (active)" "$(row_field "$ACT" m-2 phase)" "active"
+check "standalone stream milestone=null" "$(row_field "$ACT" qf-x milestone)" "null"
+check_has "merge_queue holds the ready stream" "$(cat "$ACT")" "m-2"
+# m-2 is now covered by a stream file → NO implicit row for m-2 (the id-norm
+# fix: m-2 stream 'milestone: "m-2"' collapses with milestone file id 2).
+check "m-2 (covered by a stream) gets NO implicit row" "$(row_field "$ACT" 2 coordination)" ""
+# m-7 (added active in Case 5, no stream file) IS the one legit implicit row.
+check "m-7 (active, no stream) gets an implicit row" "$(row_field "$ACT" 7 coordination)" "implicit"
+
+# active milestone with NO stream file → implicit coverage row.
+# Make m-4 active (it was not_started) and re-roll.
+mk_milestone "$REPO" 4 executing '  last_updated: "2026-04-04"'
+git -C "$REPO" add -A && git -C "$REPO" commit -qm "chore(forge): m-4 active"
+"$ROLLUP" --project "$REPO" --quiet >/dev/null 2>&1
+check "active milestone w/o stream → implicit row" "$(row_field "$ACT" 4 coordination)" "implicit"
+
+# ===========================================================================
+# Case 7 — auto-close sweep runs in MAIN, closes a complete-milestone stream
+# ===========================================================================
+# m-1 is complete; give it an open (not closed) stream with no live worktree.
+cat > "$REPO/.forge/streams/m-1.yml" <<'S1'
+version: 1
+stream:
+  id: "m-1"
+  goal: "done work"
+  status: ready
+  milestone: "m-1"
+runtime:
+  worktree: null
+merge:
+  readiness: ready
+S1
+git -C "$REPO" add -A && git -C "$REPO" commit -qm "chore(forge): m-1 open stream"
+"$ROLLUP" --project "$REPO" --quiet >"$ROOT/out7" 2>"$ROOT/err7"
+# The sweep edits the stream FILE (committed source) in the main checkout.
+s1_status="$(awk '/^stream:/{f=1} f&&/^  status:/{print $2;exit}' "$REPO/.forge/streams/m-1.yml")"
+check "sweep auto-closed m-1 stream (status: closed)" "$s1_status" "closed"
+check_has "sweep announced the auto-close" "$(cat "$ROOT/err7")" "auto-closed"
+
+# ===========================================================================
+# Case 8 — WORKTREE guard: linked worktree renders caches but SKIPS the sweep
+# ===========================================================================
+# Reset a complete-milestone open stream, then run the rollup from a linked
+# worktree. The stream file must be UNTOUCHED (sweep skipped) but active.yml
+# in the worktree must still render.
+cat > "$REPO/.forge/streams/m-1.yml" <<'S1B'
+version: 1
+stream:
+  id: "m-1"
+  goal: "done work"
+  status: ready
+  milestone: "m-1"
+runtime:
+  worktree: null
+merge:
+  readiness: ready
+S1B
+git -C "$REPO" add -A && git -C "$REPO" commit -qm "chore(forge): reopen m-1 stream" >/dev/null 2>&1
+WT="$ROOT/wt"
+git -C "$REPO" worktree add -q -b wt-branch "$WT" >/dev/null 2>&1
+# The worktree shares tracked files; its .forge/streams/m-1.yml == main's.
+"$ROLLUP" --project "$WT" --quiet >"$ROOT/out8" 2>"$ROOT/err8"
+wt_s1_status="$(awk '/^stream:/{f=1} f&&/^  status:/{print $2;exit}' "$WT/.forge/streams/m-1.yml")"
+check "worktree run did NOT sweep (stream still 'ready')" "$wt_s1_status" "ready"
+check "worktree still rendered active.yml" "$([ -f "$WT/.forge/streams/active.yml" ] && echo yes || echo no)" "yes"
+git -C "$REPO" worktree remove --force "$WT" >/dev/null 2>&1
+
+# ===========================================================================
+# Case 9 — SessionStart stdin mode: cwd comes from the JSON payload
+# ===========================================================================
+if command -v jq >/dev/null 2>&1; then
+  # Run with NO --project; feed a SessionStart-shaped payload naming the repo.
+  printf '{"cwd":"%s","hook_event_name":"SessionStart","source":"startup"}' "$REPO" \
+    | "$ROLLUP" >"$ROOT/out9" 2>/dev/null
+  check "stdin cwd drives repo resolution (summary emitted)" \
+    "$(grep -c 'forge-state-rollup' "$ROOT/out9")" "1"
+else
+  pass "SessionStart stdin mode (skipped — jq absent)"
+fi
+
+# ===========================================================================
+# Case 10 — non-Forge repo / non-repo dir: silent no-op, exit 0
+# ===========================================================================
+mkdir -p "$ROOT/plain"
+"$ROLLUP" --project "$ROOT/plain" >"$ROOT/out10" 2>&1; rc=$?
+check "non-git dir → exit 0" "$rc" "0"
+check "non-git dir → no output" "$(cat "$ROOT/out10")" ""
+
+git -C "$REPO" init -q "$ROOT/emptygit" 2>/dev/null; mkdir -p "$ROOT/emptygit"
+git -C "$ROOT/emptygit" init -q
+"$ROLLUP" --project "$ROOT/emptygit" >"$ROOT/out10b" 2>&1; rc=$?
+check "git repo without .forge → exit 0, silent" "$rc" "0"
+check "git repo without .forge → no output" "$(cat "$ROOT/out10b")" ""
+
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]

package/template/.claude/hooks/tests/protect-primary-checkout.test.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Scratch-repo test suite for .claude/hooks/protect-primary-checkout.sh (issue #21).
+#
+# Each case builds a throwaway git repo (and, where needed, a linked worktree), pipes
+# a PreToolUse JSON payload to the hook, and asserts the exit code. Exit 2 = deny,
+# exit 0 = allow. No network, no fixtures. Self-cleans on exit. Run:
+#   ./.claude/hooks/tests/protect-primary-checkout.test.sh
+# Prints `ALL PASS` and exits 0 iff every case passes; non-zero on any failure.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HOOK="$SCRIPT_DIR/../protect-primary-checkout.sh"
+[ -x "$HOOK" ] || { printf 'FATAL: hook not executable: %s\n' "$HOOK" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { printf 'FATAL: jq required\n' >&2; exit 1; }
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+
+# new_repo <name> [default-branch] — fresh repo with one commit. Prints its path.
+new_repo() {
+  local d="$ROOT/$1" br="${2:-main}"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" symbolic-ref HEAD "refs/heads/$br"
+  [ "$br" != "main" ] && git -C "$d" config init.defaultBranch "$br"
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name tester
+  : > "$d/seed"
+  git -C "$d" add -A && git -C "$d" commit -qm init
+  printf '%s\n' "$d"
+}
+
+# run_hook <dir> <command> [env-assignment] — pipes a payload, returns the hook exit code.
+run_hook() {
+  local dir="$1" cmd="$2" envset="${3:-}"
+  local payload
+  payload=$(jq -nc --arg c "$cmd" --arg d "$dir" '{tool_input:{command:$c},cwd:$d}')
+  if [ -n "$envset" ]; then
+    printf '%s' "$payload" | env "$envset" "$HOOK" >/dev/null 2>&1
+  else
+    printf '%s' "$payload" | "$HOOK" >/dev/null 2>&1
+  fi
+  return $?
+}
+
+# assert <desc> <expected-exit> <dir> <command> [env]
+assert() {
+  local desc="$1" want="$2" dir="$3" cmd="$4" envset="${5:-}"
+  local got
+  run_hook "$dir" "$cmd" "$envset"; got=$?
+  if [ "$got" -eq "$want" ]; then
+    PASSED=$((PASSED + 1))
+    # printf '  PASS: %s\n' "$desc"
+  else
+    FAILED=$((FAILED + 1))
+    printf '  FAIL: %s (got exit %s, want %s)\n' "$desc" "$got" "$want" >&2
+  fi
+}
+
+DENY=2
+ALLOW=0
+
+# ── Primary checkout: DENY branch creation / orphan / detach / track ──────────────
+P="$(new_repo primary)"
+assert "primary: checkout -b denies"                "$DENY" "$P" "git checkout -b feature"
+assert "primary: checkout -B denies"                "$DENY" "$P" "git checkout -B feature"
+assert "primary: switch -c denies"                  "$DENY" "$P" "git switch -c feature"
+assert "primary: switch -C denies"                  "$DENY" "$P" "git switch -C feature"
+assert "primary: switch --create denies"            "$DENY" "$P" "git switch --create feature"
+assert "primary: checkout --orphan denies"          "$DENY" "$P" "git checkout --orphan gh-pages"
+assert "primary: checkout --detach denies"          "$DENY" "$P" "git checkout --detach"
+assert "primary: checkout --track denies"           "$DENY" "$P" "git checkout --track origin/x"
+assert "primary: checkout other-branch denies"      "$DENY" "$P" "git checkout somebranch"
+assert "primary: switch other-branch denies"        "$DENY" "$P" "git switch somebranch"
+
+# ── Global-option bypass regression (review m-49 F1/F2): git global options before ──
+# the subcommand must NOT slip the guard. These were live bypasses before the fix.
+assert "primary: -c global opt + checkout -b denies" "$DENY" "$P" "git -c core.editor=vi checkout -b evil"
+assert "primary: --no-pager + checkout -b denies"    "$DENY" "$P" "git --no-pager checkout -b evil"
+assert "primary: -p + checkout -b denies"            "$DENY" "$P" "git -p checkout -b evil"
+assert "primary: multi -c + switch -c denies"        "$DENY" "$P" "git -c a=b -c c=d switch -c evil"
+assert "primary: \$IFS substitution + -b denies"     "$DENY" "$P" "git checkout\$IFS-b evil"
+assert "primary: -c global opt + checkout main allows" "$ALLOW" "$P" "git -c x=y checkout main"
+
+# ── The UNCONDITIONAL delta: deny even with NO sibling worktree (P has exactly 1). ─
+# (P above already has no siblings — the denies above ARE the no-sibling case. Assert
+#  explicitly that worktree count is 1 here, so the intent is documented.)
+wt_n=$(git -C "$P" worktree list | wc -l | tr -d ' ')
+if [ "$wt_n" -eq 1 ]; then PASSED=$((PASSED+1)); else FAILED=$((FAILED+1)); printf '  FAIL: expected 1 worktree in fresh primary, got %s\n' "$wt_n" >&2; fi
+
+# ── Primary checkout: ALLOW safe forms ───────────────────────────────────────────
+assert "primary: checkout main allows (home)"       "$ALLOW" "$P" "git checkout main"
+assert "primary: switch main allows (home)"         "$ALLOW" "$P" "git switch main"
+assert "primary: checkout -- file allows (restore)" "$ALLOW" "$P" "git checkout -- seed"
+assert "primary: checkout . allows (restore)"       "$ALLOW" "$P" "git checkout ."
+assert "primary: checkout HEAD -- file allows"      "$ALLOW" "$P" "git checkout HEAD -- seed"
+assert "primary: bare checkout allows"              "$ALLOW" "$P" "git checkout"
+assert "primary: git status allows (fast-path)"     "$ALLOW" "$P" "git status"
+assert "primary: git commit allows (fast-path)"     "$ALLOW" "$P" "git commit -m x"
+assert "primary: git log allows (fast-path)"        "$ALLOW" "$P" "git log --oneline"
+
+# ── Worktree pass-through: git-dir != git-common-dir → never blocked ──────────────
+WT="$ROOT/primary-wt"
+git -C "$P" worktree add -q -b wtbranch "$WT" >/dev/null 2>&1
+assert "worktree cwd: checkout -b allows"           "$ALLOW" "$WT" "git checkout -b anything"
+assert "worktree cwd: switch -c allows"             "$ALLOW" "$WT" "git switch -c anything"
+# From the PRIMARY checkout, `git -C <worktree>` targets the worktree → allow.
+assert "primary + git -C worktree: checkout -b allows" "$ALLOW" "$P" "git -C $WT checkout -b anything"
+
+# ── master-default repo: home = master; create still denied ───────────────────────
+M="$(new_repo master-primary master)"
+assert "master repo: checkout master allows (home)" "$ALLOW" "$M" "git checkout master"
+assert "master repo: checkout -b denies"            "$DENY"  "$M" "git checkout -b x"
+assert "master repo: checkout main denies (main is not this repo's default... but seeded)" "$ALLOW" "$M" "git checkout main"
+# ^ main+master are BOTH always in the seed set, so `checkout main` is allowed even in
+#   a master-default repo. That's intentional (both are canonical default names).
+
+# ── Escape hatch ─────────────────────────────────────────────────────────────────
+assert "escape hatch: checkout -b allows"           "$ALLOW" "$P" "git checkout -b feature" "ALLOW_MAIN_BRANCHING=1"
+
+# ── Folded hard-reset guard (worktree-count gated) ───────────────────────────────
+# P now has 1 sibling worktree (WT added above) → count > 1 → hard reset denied.
+assert "primary +wt: reset --hard denies"           "$DENY"  "$P" "git reset --hard HEAD"
+assert "primary +wt: reset --keep denies"           "$DENY"  "$P" "git reset --keep HEAD"
+assert "primary +wt: reset --soft allows (not hard)" "$ALLOW" "$P" "git reset --soft HEAD"
+# A repo with a single worktree → hard reset is the operator's business → allow.
+S="$(new_repo solo)"
+assert "solo (1 wt): reset --hard allows"           "$ALLOW" "$S" "git reset --hard HEAD"
+
+# ── Fail-open cases ──────────────────────────────────────────────────────────────
+assert "fail-open: empty command allows"            "$ALLOW" "$P" ""
+assert "fail-open: non-checkout command allows"     "$ALLOW" "$P" "ls -la"
+# Non-git cwd → fail open. Use a plain temp dir with a checkout-shaped command.
+NG="$ROOT/notgit"; mkdir -p "$NG"
+assert "fail-open: non-git cwd allows"              "$ALLOW" "$NG" "git checkout -b x"
+
+# ── Summary ──────────────────────────────────────────────────────────────────────
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+if [ "$FAILED" -eq 0 ]; then
+  printf 'ALL PASS\n'
+  exit 0
+fi
+exit 1

package/template/.claude/settings.json

@@ -56,6 +56,17 @@
     ]
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/forge-state-rollup.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/forge-state-rollup.sh\" || true"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write",
@@ -130,6 +141,15 @@
             "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous-commands.sh\""
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-primary-checkout.sh\""
+          }
+        ]
       }
     ]
   }

package/template/.claude/skills/chief-of-staff/SKILL.md

@@ -78,13 +78,17 @@ every field has one source and coverage is computed into the artifact. Run the
 rollup at the **start of Show and Sync**, and after any Start/Resume/Pause/Close
 edit to a stream file.
 
-Procedure: run the **Stream Rollup** exactly as defined in FORGE.md → Stream
-Rollup — the deterministic join + write (glob stream files, derive each row's
-`coordination`/`merge_readiness`/`blocked_by`/`next_action`, read `phase` from the
-linked milestone, emit `stream: implicit` coverage rows, derive `merge_queue` from
-`merge.readiness: ready`, write `active.yml`) is **single-sourced there**. Never
-hand-edit `active.yml`. Beyond that deterministic write, the Chief adds two
-**interactive** steps the boot-time rollup omits:
+Procedure: run the **`forge-state-rollup.sh` executable** — the same mechanical
+port the SessionStart hook invokes at boot (issue #22). It performs the milestone
+Rollup 1.0 **and** the Stream Rollup join + write (glob stream files, derive each
+row's `coordination`/`merge_readiness`, read `phase` from the linked milestone,
+emit `stream: implicit` coverage rows, derive `merge_queue` from
+`merge.readiness: ready`, run the step-0 sweep in the main checkout, write
+`active.yml`) in one idempotent pass — single-sourced in FORGE.md → Stream Rollup.
+Run `.claude/hooks/forge-state-rollup.sh`, then read `active.yml`; never hand-edit
+it, and only fall back to the manual join if the executable is absent (pre-0.75.0).
+Beyond that deterministic write, the Chief adds two **interactive** steps the
+mechanical rollup omits:
 
 - **Complete linked milestone → auto-close (not a prompt).** The rollup's **step
   0 sweep** (FORGE.md → Stream Rollup) already ran: a stream whose
@@ -101,10 +105,11 @@ hand-edit `active.yml`. Beyond that deterministic write, the Chief adds two
   file (the rollup emits a `stream: implicit` row for coverage), offer to
   materialize a stream file for it. **Never auto-create.**
 
-Note: invoked directly, `/chief-of-staff` does not run `forge`'s milestone Rollup,
-so `index.yml` may be slightly stale; read it as-is when deriving implicit-row
-coverage and suggest a `/forge` pass if it looks off. The Chief writes `active.yml`
-(derived class); it never writes `index.yml` or any milestone file.
+Note: the `forge-state-rollup.sh` executable rolls up `index.yml` **and**
+`active.yml` in the same pass, so implicit-row coverage reads a fresh `index.yml`
+even when `/chief-of-staff` is invoked directly (no separate `/forge` boot needed).
+The Chief writes only the derived caches (via the executable); it never hand-edits
+`index.yml` or any milestone file.
 
 ### Board render + inbox (attended)
 

package/template/.claude/skills/forge/SKILL.md

@@ -65,15 +65,19 @@ Cross-machine note: the flag file is machine-local, so a worktree (or the primar
 - **Absent registry, but IDs already exist.** `.forge/reservations.yml` missing *and* the tree already holds allocated IDs (`requirements/*.yml` has `FR-`/`NFR-`/`DEF-`, or `.forge/decisions/` has `ADR-NNN`) → one-time nudge: *"No `reservations.yml` yet, but this project already allocates IDs. Concurrent worktrees will collide on the next number. Create it by reserving your next ID via the protocol (`planning`/`architecting` do this), or backfill existing IDs now."* (No IDs anywhere → silent; the first reservation creates the file lazily.)
 - **Backfill scan (un-reserved landed IDs).** When `reservations.yml` exists, diff the IDs actually landed in the tree (`FR-`/`NFR-`/`DEF-` across `requirements/*.yml`; `ADR-NNN` across `.forge/decisions/`) against the ids recorded in `reservations.yml`. Any landed ID with **no** reservation entry → list them once: *"{N} ID(s) are in the tree but not in `reservations.yml` ({ids}) — landed before the protocol or via an un-reserved path. They are still respected (next = max(reserved, in-tree)+1), but appending backfill entries keeps the registry the single audit trail."* Advisory: surface, don't auto-write — backfilling is the operator's call.
 
-**Stream Rollup (active.yml is derived).** If `.forge/streams/` has any stream files, regenerate `.forge/streams/active.yml` from them + active milestones per FORGE.md → Stream Rollup, the same way step 1.0 regenerates `index.yml`. **Run the 1.0 State Rollup (below) first** so `index.yml` is fresh — the Stream Rollup reads active milestones from it for implicit-row coverage, so on a boot where a just-merged milestone promotion lands, a stale `index.yml` would silently drop that milestone's coverage row. This includes the rollup's **step 0 completed-stream auto-close sweep** (FORGE.md → Stream Rollup): a milestone-backed stream whose milestone is now `complete`, that is not already `closed`, and has no live worktree, is auto-closed (`status: closed`, `merge.readiness: merged`) *before* the join — so a done-and-merged milestone can never leave a zombie `ready` row that re-nags every boot. Announce each: *"auto-closed stale stream {id} — milestone m-{id} complete, already on main."* (A `complete` milestone that still has a live worktree is left for the finalize path below, not swept.) `active.yml` is derived — never read it as authoritative without rolling up first, and never hand-edit it. Since 0.53.0 it is a **git-ignored render-on-read cache** (never committed), so rendering it is a local-cache write that never lands on `main`; the source writes it still performs (the step-0 auto-close sweep touches *stream files*, which remain committed) run in the main checkout as before. No `streams/` dir → skip.
+**Stream Rollup (active.yml is derived — rendered by the same hook).** `.forge/streams/active.yml` is regenerated from the stream files + active milestones by the **`forge-state-rollup.sh` SessionStart hook**, in the same mechanical pass that renders `index.yml` (the hook runs the milestone rollup first, then the join — so the Stream Rollup reads a fresh `index.yml` for implicit-row coverage). This includes the **step-0 completed-stream auto-close sweep** (FORGE.md → Stream Rollup): a milestone-backed stream whose milestone is now `complete`, not already `closed`, with no live worktree, is auto-closed (`status: closed`, `merge.readiness: merged`) *before* the join — the hook runs this **only in the main checkout** (it edits committed stream files), and announces each on stderr: *"auto-closed stale stream {id} — milestone complete, already on main."* (A `complete` milestone that still has a live worktree is left for the finalize path below, not swept.) **`active.yml` is derived — READ the hook's freshly-rendered cache; never hand-edit it, and do not regenerate it by hand.** Since 0.53.0 it is a **git-ignored render-on-read cache** (never committed); the hook renders it in any checkout. **Fallback:** if no `[forge-state-rollup]` boot summary appeared (older CLI / non-Claude-Code adapter / unwired settings), run `.claude/hooks/forge-state-rollup.sh` yourself once (idempotent), then read it; only if the executable is absent, roll up by hand per FORGE.md → Stream Rollup. No `streams/` dir → the hook skips it.
 
 **Ready-to-merge nudge (main checkout / streams without checkpoints).** From the just-regenerated `active.yml` — already swept of completed-milestone zombies by the rollup's step 0 — scan for streams with `coordination: ready` or a non-empty `merge_queue` **that are not auto-publishing via checkpoints**. Because the sweep ran first, anything surfaced here is genuinely mergeable (open work, not yet on main), so the nudge is truthful: *"{N} stream(s) ready to merge — run `/chief-of-staff` (merge safe) to integrate."* Pointer only — the cadence logic lives in the Chief's Merge Cadence Check; `forge` never merges. Nothing pending → silent.
 
-### 1.0 State Rollup (index.yml is derived)
+### 1.0 State Rollup (index.yml is derived — rendered mechanically at boot)
 
-`index.yml` is a **derived registry** — regenerate it from the milestone files (plus each row's git-computed `release_state`, step 4) before reading, and after any milestone CRUD (promote/defer/resume/delete). **Never hand-edit `index.yml`.** Since 0.53.0 it is a **git-ignored render-on-read cache** (never committed): rendering it here is a local-cache write, so it never conflicts and never needs the orchestrator-only guard for *safety* — any session may render its own copy. The rollup below is unchanged; only the storage is (see FORGE.md → State Ownership, Derived class).
+`index.yml` is a **derived registry**, regenerated from the milestone files (plus each row's git-computed `release_state`) by the **`forge-state-rollup.sh` SessionStart hook** — mechanically, at every session start, **before** this skill runs. **Never hand-edit `index.yml`.** Since 0.53.0 it is a **git-ignored render-on-read cache** (never committed): rendering it is a local-cache write, so any session may render its own copy (see FORGE.md → State Ownership, Derived class).
 
-Rollup procedure (deterministic + idempotent):
+**The hook is the rollup; this skill only READS the freshly-rendered cache.** Making the rollup an executable invoked by a hook — not prose the agent performs — is the fix for issue #22 (pain-6: advisory rules fail). A boot session used to read a stale cache and reconstruct truth by hand when project memory carried an "index is stale, work around it" habit; a mechanical hook removes that trust dependency. Do **not** regenerate `index.yml` by hand — the hook already did. Look for its one-line boot summary (`[forge-state-rollup] rendered index.yml …`) in context; then read the cache.
+
+**Fallback — only when the hook did NOT run.** On an older Claude Code CLI without SessionStart, a non-Claude-Code adapter, or a repo whose `.claude/settings.json` lacks the SessionStart wiring, no summary line appears. Only then run the executable yourself once — `.claude/hooks/forge-state-rollup.sh` (add `--project {worktree_path}` when the recorded path differs from cwd) — and read its output. It is deterministic + idempotent, so running it when the hook already ran is a harmless no-op. If the executable itself is absent (pre-0.75.0 install), fall back to the manual procedure below.
+
+**Manual procedure (executable absent only — the executable's faithful spec):**
 1. Glob `.forge/state/milestone-*.yml`.
 2. For each, read `milestone.id`, `milestone.name`, `current.status`, `lifecycle.{deferred_at, resumed_at}`, and the last-touched date as `current.last_updated` → else legacy `progress.last_update` → else null. (The fallback keeps pre-0.19.0 milestone files self-sourcing without editing them; active milestones gain `current.last_updated` on their next transition.)
 3. Derive the registry `status`:
@@ -85,9 +89,9 @@ Rollup procedure (deterministic + idempotent):
    - **Fold is the source.** Run `.claude/hooks/forge-release-fold.sh m-{id}` per row and write its stdout `release_state=` value verbatim (`unmerged|merged|validated`) — agent prose never re-derives `release_state`; the fold binary is the only source.
    - **Degrade, don't block.** Hook missing or exit 2 → write `release_state: unknown`, emit ONE advisory line — *"release fold unavailable for m-{id} — release_state: unknown"* — and continue. A broken fold must never break boot.
 
-Output is a pure function of the milestone files, so two sessions regenerating it produce identical bytes — it never needs a hand-merge. **Only the main/orchestrator session runs rollup; worktree agents never write `index.yml`** (they edit only their own `milestone-{id}.yml`).
+Output is a pure function of the milestone files, so two sessions regenerating it produce identical bytes — it never needs a hand-merge. **The `forge-state-rollup.sh` hook renders the cache in any checkout (main OR worktree — it is a gitignored local write); worktree agents still never write the *committed* derived-source state** (they edit only their own `milestone-{id}.yml`; the Stream Rollup's step-0 sweep, which edits committed stream files, is main-checkout-only inside the hook).
 
-**Enforced, not optional — a boot must not read a stale registry.** The rollup *is* the reconcile step; skipping it silently lets `index.yml` drift from the milestone files — e.g. a worktree sets `current.status: complete` and merges to main, but `index.yml` stays `active` until some later boot happens to regenerate by hand (observed twice for m-CLOUDS01). So every boot **runs** steps 1–4. Before rewriting, diff each milestone's *derived* status against its current `index.yml` entry; any mismatch → emit one loud line — *"index.yml was stale vs {N} milestone file(s) ({ids}) — regenerated."* — then write. Identical (the common case) → the rewrite is a no-op by bytes; stay silent. The rollup is idempotent, so running it on every boot is free.
+**"Run Rollup (1.0)" (used below after a milestone CRUD) = run the executable.** The SessionStart hook fires only at boot, so after a mid-session promote/defer/resume/delete you must re-render the caches yourself: run `.claude/hooks/forge-state-rollup.sh` (it does both the milestone rollup **and** the Stream Rollup in one idempotent pass; add `--project {worktree_path}` if the recorded path differs from cwd), then read the result. This replaces the old "hand-regenerate `index.yml`" step everywhere the phrase appears. Executable absent (pre-0.75.0) → fall back to the manual procedure above.
 
 ### 1.1 Milestone Selection
 
@@ -97,7 +101,7 @@ Check state files:
 3. Neither → init/tier detection.
 
 **With `state/index.yml`:**
-1. Run **Rollup (1.0)** to regenerate `index.yml` from the milestone files, then read it for active milestones
+1. **Read the freshly-rendered `index.yml`** (the SessionStart hook already regenerated it this boot — §1.0) for active milestones. No `[forge-state-rollup]` summary appeared → run the executable once first (§1.0 fallback), then read.
 2. **Check arg first.** `/forge 2` or `/forge "Auth system"`:
    - Match IDs (exact) or names (case-insensitive substring)
    - Found → auto-select: *"Resuming {id}: [{name}] -- {current.status}, {percent}%"*

package/template/.claude/skills/initializing/SKILL.md

@@ -390,7 +390,26 @@ User selects per stack.
 
    **Confirm with the user first** in brownfield (this edits a user-owned file). In greenfield with no existing `.gitignore`, write it directly. Re-run is idempotent — the carve-out lines `grep` to themselves.
 
-8. **State-sync commit**: `git add .gitignore .claude/settings.json .claude/skills/ .claude/agents/ .claude/hooks/ .forge/` then `git commit -m "chore(forge): initialize forge state + track product files"` (scoped; never `git add .`) — so the new project's state and Forge product files are both in git from the start.
+8. **Wire the primary-checkout weld (`core.hooksPath`).** Welds the primary checkout to the default branch so all branch work happens in worktrees — every tier (issue #21, ADR-031). The tracked `.forge/git-hooks/pre-commit` backstop only fires once `core.hooksPath` points at it. This is per-clone git config, so init owns it. **Detect + warn, never clobber:**
+
+   ```bash
+   want=".forge/git-hooks"
+   cur=$(git config --get core.hooksPath 2>/dev/null || true)
+   if [ -z "$cur" ] || [ "$cur" = "$want" ]; then
+     git config core.hooksPath "$want"   # repo-relative → resolves inside every worktree
+     echo "[Forge] core.hooksPath → $want (primary-checkout weld active)."
+   else
+     echo "[Forge] core.hooksPath is already set to '$cur' (Husky/lefthook?). NOT overwriting."
+     echo "        The primary-checkout pre-commit backstop (.forge/git-hooks/pre-commit) is"
+     echo "        therefore inactive. To keep the weld, chain it into your existing hooks dir"
+     echo "        (call .forge/git-hooks/pre-commit from your pre-commit), or accept the"
+     echo "        PreToolUse-only coverage (Claude sessions are still guarded)."
+   fi
+   ```
+
+   **WHY repo-relative** (`.forge/git-hooks`, not an absolute path): an absolute `core.hooksPath` silently skips in linked worktrees (the documented Husky/lefthook worktree hazard — see `orchestrating/bootstrap-checks.md`); a repo-relative path resolves under each worktree checkout. **WHY never clobber:** silently disabling a consumer's existing hook framework is unacceptable.
+
+9. **State-sync commit**: `git add .gitignore .claude/settings.json .claude/skills/ .claude/agents/ .claude/hooks/ .forge/` then `git commit -m "chore(forge): initialize forge state + track product files"` (scoped; never `git add .`) — so the new project's state and Forge product files are both in git from the start. (The tracked `.forge/git-hooks/` is included by the `.forge/` path; `core.hooksPath` itself is local git config, not a tracked file, so it needs no staging.)
 
 *"Initialized. Ready?"*