forge-orkes 0.75.0 → 0.79.0

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

@@ -0,0 +1,431 @@
+#!/usr/bin/env sh
+# forge-state-rollup — the boot rollup made mechanical (issue #22). Ports
+# State Rollup 1.0 (index.yml ← state/milestone-*.yml) and the Stream Rollup
+# (active.yml ← streams/*.yml ⋈ active milestones, ADR-015 addendum) from
+# advisory skill prose into an executable, so a boot regenerates the derived
+# registries deterministically instead of trusting an agent to run the prose
+# (which a "the index is stale, work around it" project-memory habit can
+# out-compete — the exact ptnrkit failure #22 was filed against).
+#
+#   forge-state-rollup.sh [--project <path>] [--quiet]
+#   (SessionStart hook)  reads {cwd, hook_event_name, source} from stdin JSON.
+#
+#     --project <path>   operate on the repo containing <path>. Default: the
+#                        SessionStart payload's `cwd`, else the CWD. NEVER
+#                        $CLAUDE_PROJECT_DIR — that resolves to the repo ROOT
+#                        (main checkout) even in a worktree, which would
+#                        render this worktree's caches into the wrong tree.
+#     --quiet            suppress the stdout summary line (still writes caches).
+#
+# What it writes (both are git-ignored render-on-read caches since 0.53.0):
+#     .forge/state/index.yml       — derived milestone registry
+#     .forge/streams/active.yml    — derived stream registry (if streams/ exists)
+# It NEVER commits them and NEVER runs git add/commit. Rendering a gitignored
+# cache is a local write that never lands on main, so any checkout (main OR
+# worktree) may render its own copy (FORGE.md → State Ownership, Derived class).
+#
+# The ONE write that is committed-source and therefore main-checkout-only is
+# the Stream Rollup's step-0 completed-stream auto-close sweep (it edits
+# streams/{stream}.yml). In a linked worktree that step is skipped; the caches
+# still render. Detection: `git rev-parse --git-dir` == `--git-common-dir`.
+#
+# release_state is NOT re-derived here — the fold binary
+# (forge-release-fold.sh) is its only source (FORGE.md → derived release_state).
+# Fold missing / exit 2 for a unit → that row gets release_state: unknown and
+# one advisory stderr line; a broken fold must never break boot.
+#
+# Contract (SessionStart, verified against Claude Code hooks docs):
+#   - Exit 0 ALWAYS. SessionStart is non-blocking; this hook must never abort
+#     a session. Every failure degrades to a no-op + an advisory stderr line.
+#   - stdout is injected into the model's context. We emit ONE terse summary
+#     line (unless --quiet) so the boot session sees the caches were freshly
+#     rendered by machinery — it then READS them, never regenerates by hand.
+#   - stderr carries advisories/diagnostics (shown in transcript, not context).
+#
+# Portable: POSIX sh + git + awk/sed (mirrors forge-release-fold.sh). jq is
+# used only to parse the SessionStart stdin JSON and degrades to a no-stdin
+# path when absent. No network calls (NFR-030).
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+FOLD="$SCRIPT_DIR/forge-release-fold.sh"
+
+# --- argument / stdin parsing ------------------------------------------------
+
+project=""
+quiet=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --project) shift; project="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+    --project=*) project="${1#*=}"; shift ;;
+    --quiet) quiet=1; shift ;;
+    -*) shift ;;                 # unknown flag — ignore, never fail a boot hook
+    *) shift ;;
+  esac
+done
+
+# SessionStart delivers {cwd, source, hook_event_name, ...} on stdin. When no
+# --project was given, prefer the payload's cwd (the actual worktree the
+# session started in) over the process CWD. Read stdin only if it is not a tty
+# and jq is present; never block waiting for input that will not arrive.
+stdin_cwd=""
+if [ -z "$project" ] && [ ! -t 0 ] && command -v jq >/dev/null 2>&1; then
+  payload="$(cat 2>/dev/null || true)"
+  if [ -n "$payload" ]; then
+    stdin_cwd="$(printf '%s' "$payload" | jq -r '.cwd // empty' 2>/dev/null || true)"
+  fi
+fi
+[ -z "$project" ] && project="${stdin_cwd:-$PWD}"
+
+# --- repo resolution ---------------------------------------------------------
+# Resolve from `project` (cwd), NOT $CLAUDE_PROJECT_DIR. Silent no-op when not
+# in a git repo or the repo has no .forge/ — the common case for a non-Forge
+# session, and the hook must be invisible there.
+
+root="$(git -C "$project" rev-parse --show-toplevel 2>/dev/null)" || exit 0
+[ -d "$root/.forge" ] || exit 0
+[ -d "$root/.forge/state" ] || exit 0
+
+# Main checkout vs linked worktree: --git-dir == --git-common-dir → main.
+this_gitdir="$(git -C "$root" rev-parse --git-dir 2>/dev/null || true)"
+common_gitdir="$(git -C "$root" rev-parse --git-common-dir 2>/dev/null || true)"
+in_main_checkout=0
+[ -n "$this_gitdir" ] && [ "$this_gitdir" = "$common_gitdir" ] && in_main_checkout=1
+
+# --- YAML helpers (ported from forge-release-fold.sh, identical contract) -----
+
+# yaml_get <content> <block> <key> — scalar value of a 2-space-indented key
+# inside a top-level block. Strips trailing `# comments`. Prints raw value.
+yaml_get() {
+  printf '%s\n' "$1" | awk -v blk="$2" -v key="$3" '
+    /^[^ \t]/ { inblk = (index($0, blk ":") == 1) }
+    inblk && index($0, "  " key ":") == 1 {
+      val = substr($0, length(key) + 4)
+      sub(/[ \t]#.*$/, "", val)
+      if (val ~ /^[ \t]*#/) val = ""
+      gsub(/^[ \t]+/, "", val); gsub(/[ \t]+$/, "", val)
+      print val
+      exit
+    }
+  '
+}
+
+unquote() {
+  uq="$1"
+  uq="${uq#\"}"; uq="${uq%\"}"
+  uq="${uq#"'"}"; uq="${uq%"'"}"
+  printf '%s\n' "$uq"
+}
+
+yaml_scalar() { unquote "$(yaml_get "$1" "$2" "$3")"; }
+
+# is_nullish <val> — true when empty, "null", or "~".
+is_nullish() {
+  case "$1" in ''|null|'~') return 0 ;; *) return 1 ;; esac
+}
+
+# --- milestone Rollup 1.0 ----------------------------------------------------
+# Deterministic + idempotent: output is a pure function of the milestone files,
+# so two sessions rendering it produce identical bytes.
+
+fold_unavailable=0    # count of rows that fell back to release_state: unknown
+
+render_index() {
+  index_path="$root/.forge/state/index.yml"
+  rows=""              # accumulated "id\tname\tstatus\tlast_updated\trelease_state" lines
+  n=0
+
+  for mfile in "$root"/.forge/state/milestone-*.yml; do
+    [ -f "$mfile" ] || continue
+    content="$(cat "$mfile")"
+
+    m_id="$(yaml_scalar "$content" milestone id)"
+    [ -z "$m_id" ] && continue      # a file with no milestone.id is not a registry row
+    m_name="$(yaml_scalar "$content" milestone name)"
+    c_status="$(yaml_scalar "$content" current status)"
+
+    # last_updated: current.last_updated → legacy progress.last_update → null.
+    last_updated="$(yaml_scalar "$content" current last_updated)"
+    if is_nullish "$last_updated"; then
+      last_updated="$(yaml_scalar "$content" progress last_update)"
+    fi
+    is_nullish "$last_updated" && last_updated="null"
+
+    deferred_at="$(yaml_scalar "$content" lifecycle deferred_at)"
+    resumed_at="$(yaml_scalar "$content" lifecycle resumed_at)"
+
+    # Derive registry status (order matters — deferred wins unless resumed later).
+    reg_status="active"
+    if [ "$c_status" = "complete" ]; then
+      reg_status="complete"
+    elif [ "$c_status" = "not_started" ]; then
+      reg_status="not_started"
+    fi
+    if ! is_nullish "$deferred_at"; then
+      # deferred unless a later resumed_at supersedes it (string compare works
+      # for ISO 8601 / date strings; a resumed_at >= deferred_at un-defers).
+      if is_nullish "$resumed_at" || [ "$resumed_at" \< "$deferred_at" ]; then
+        reg_status="deferred"
+      fi
+    fi
+
+    # release_state — the fold is the ONLY source. Degrade to unknown, never
+    # re-derive. Fold unit id is the milestone id normalized to m-{N}.
+    fold_unit="$m_id"
+    case "$fold_unit" in m-*) ;; *) fold_unit="m-$m_id" ;; esac
+    rel="unknown"
+    if [ -x "$FOLD" ]; then
+      fold_out="$("$FOLD" "$fold_unit" --project "$root" 2>/dev/null)"; fold_rc=$?
+      if [ "$fold_rc" -eq 0 ]; then
+        rel="$(printf '%s\n' "$fold_out" | sed -n 's/^release_state=\([a-z]*\).*/\1/p' | head -1)"
+        [ -z "$rel" ] && rel="unknown"
+      fi
+    fi
+    if [ "$rel" = "unknown" ]; then
+      fold_unavailable=$((fold_unavailable + 1))
+      printf 'forge-state-rollup: release fold unavailable for %s — release_state: unknown\n' "$fold_unit" >&2
+    fi
+
+    rows="$rows$m_id	$m_name	$reg_status	$last_updated	$rel
+"
+    n=$((n + 1))
+  done
+
+  # Sort rows by id (stable, deterministic). Then emit YAML.
+  sorted="$(printf '%s' "$rows" | LC_ALL=C sort -t'	' -k1,1)"
+
+  {
+    printf '# Forge Global State — Cross-Milestone Index (DERIVED — do not hand-edit)\n'
+    printf '# Regenerated at boot by .claude/hooks/forge-state-rollup.sh from\n'
+    printf '# state/milestone-*.yml (+ per-row release_state from forge-release-fold.sh).\n'
+    printf '# Git-ignored render-on-read cache (0.53.0) — never committed.\n'
+    printf 'milestones:\n'
+    if [ "$n" -eq 0 ]; then
+      printf '  []\n'
+    else
+      printf '%s\n' "$sorted" | while IFS='	' read -r r_id r_name r_status r_lu r_rel; do
+        [ -z "$r_id" ] && continue
+        printf '  - id: %s\n' "$r_id"
+        printf '    name: %s\n' "$(yaml_quote "$r_name")"
+        printf '    status: %s\n' "$r_status"
+        if [ "$r_lu" = "null" ]; then
+          printf '    last_updated: null\n'
+        else
+          printf '    last_updated: %s\n' "$(yaml_quote "$r_lu")"
+        fi
+        printf '    release_state: %s\n' "$r_rel"
+      done
+    fi
+  } > "$index_path.tmp.$$" && mv -f "$index_path.tmp.$$" "$index_path"
+
+  INDEX_ROW_COUNT="$n"
+}
+
+# yaml_quote <val> — always double-quote a scalar for the rendered cache,
+# escaping embedded backslashes and double quotes. Keeps names with `:`/`#`/
+# unicode safe. Empty → "".
+yaml_quote() {
+  qq="$1"
+  qq="$(printf '%s' "$qq" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+  printf '"%s"' "$qq"
+}
+
+# --- Stream Rollup (ADR-015 addendum) ----------------------------------------
+
+# norm_id <id> — canonical unit key: strip a single leading `m-` so a stream's
+# `milestone: "m-27"` and a numeric milestone file id `27` compare equal (a
+# real repo mixes both spellings). A labeled id (m-AUTO01) has no numeric twin,
+# so stripping is harmless there — the key is just used for equality.
+norm_id() { printf '%s' "${1#m-}"; }
+
+# derived_milestone_status <id> — read the just-rendered index.yml row's status
+# for a milestone id, matched on the normalized key. Empty when no index row.
+derived_milestone_status() {
+  awk -v want="$(norm_id "$1")" '
+    /^  - id:/ { id=$3; gsub(/["\x27]/,"",id); sub(/^m-/,"",id) }
+    /^    status:/ { if (id==want) { print $2; exit } }
+  ' "$root/.forge/state/index.yml" 2>/dev/null
+}
+
+# stream_field <file> <block> <key> — thin wrapper over yaml_scalar on a file.
+stream_field() { yaml_scalar "$(cat "$1")" "$2" "$3"; }
+
+# worktree_is_live <path> — true when <path> resolves to a registered live
+# git worktree of this repo. Empty/nullish path → not live.
+worktree_is_live() {
+  wt="$1"
+  is_nullish "$wt" && return 1
+  git -C "$root" worktree list --porcelain 2>/dev/null \
+    | awk -v p="$wt" '/^worktree / { if ($2 == p) { found=1 } } END { exit found?0:1 }'
+}
+
+SWEEP_CLOSED=""       # ids auto-closed this run (for the summary)
+
+# step 0 — completed-stream auto-close sweep. Writes stream files (committed
+# source) → MAIN CHECKOUT ONLY. A milestone-backed stream whose milestone is
+# `complete`, that is not already `closed`, with no live worktree → auto-close.
+stream_autoclose_sweep() {
+  [ "$in_main_checkout" -eq 1 ] || return 0
+  for sfile in "$root"/.forge/streams/*.yml; do
+    [ -f "$sfile" ] || continue
+    case "$(basename "$sfile")" in active.yml) continue ;; esac
+    s_status="$(stream_field "$sfile" stream status)"
+    [ "$s_status" = "closed" ] && continue
+    s_ms="$(stream_field "$sfile" stream milestone)"
+    is_nullish "$s_ms" && continue
+    m_status="$(derived_milestone_status "$s_ms")"
+    [ "$m_status" = "complete" ] || continue
+    # Guard: a deferred milestone is never swept (handled above by status
+    # check). A complete milestone WITH a live worktree is left for the
+    # forge-boot finalize path — do not sweep it here.
+    s_wt="$(stream_field "$sfile" runtime worktree)"
+    if worktree_is_live "$s_wt"; then continue; fi
+
+    # Auto-close: status → closed, merge.readiness → merged, append a note.
+    # Edit in place with awk (2-space-indented keys under their blocks).
+    awk '
+      /^[^ \t]/ { blk=$0; sub(/:.*/,"",blk) }
+      blk=="stream" && /^  status:/ { print "  status: closed                   # auto-closed: milestone complete + on main (rollup sweep)"; next }
+      blk=="merge"  && /^  readiness:/ { print "  readiness: merged                # auto-closed by rollup sweep"; next }
+      { print }
+    ' "$sfile" > "$sfile.tmp.$$" && mv -f "$sfile.tmp.$$" "$sfile"
+    SWEEP_CLOSED="$SWEEP_CLOSED $s_ms"
+    printf 'forge-state-rollup: auto-closed stale stream %s — milestone complete, already on main\n' "$s_ms" >&2
+  done
+}
+
+STREAM_ROW_COUNT=0
+
+render_active() {
+  [ -d "$root/.forge/streams" ] || return 0
+  active_path="$root/.forge/streams/active.yml"
+
+  stream_rows=""      # "id\tcoordination\tphase\tmilestone\tmerge_readiness"
+  merge_rows=""       # stream ids with merge.readiness: ready
+  seen_ms=" "         # milestones covered by a stream file (for implicit rows)
+  sn=0
+
+  for sfile in "$root"/.forge/streams/*.yml; do
+    [ -f "$sfile" ] || continue
+    case "$(basename "$sfile")" in active.yml) continue ;; esac
+    s_id="$(stream_field "$sfile" stream id)"
+    [ -z "$s_id" ] && s_id="$(basename "$sfile" .yml)"
+    s_coord="$(stream_field "$sfile" stream status)"
+    [ -z "$s_coord" ] && s_coord="unknown"
+    s_ms="$(stream_field "$sfile" stream milestone)"
+    s_merge="$(stream_field "$sfile" merge readiness)"
+    [ -z "$s_merge" ] && s_merge="not_ready"
+
+    # phase from the milestone (backed streams only) — never stored in stream.
+    s_phase="-"
+    if ! is_nullish "$s_ms"; then
+      seen_ms="$seen_ms$(norm_id "$s_ms") "   # normalized key: m-27 and 27 collapse
+      mp="$root/.forge/state/milestone-${s_ms#m-}.yml"
+      [ -f "$mp" ] || mp="$root/.forge/state/milestone-${s_ms}.yml"
+      if [ -f "$mp" ]; then
+        s_phase="$(yaml_scalar "$(cat "$mp")" current status)"
+        [ -z "$s_phase" ] && s_phase="-"
+      fi
+    else
+      s_ms="null"
+    fi
+
+    stream_rows="$stream_rows$s_id	$s_coord	$s_phase	$s_ms	$s_merge
+"
+    [ "$s_merge" = "ready" ] && merge_rows="$merge_rows$s_id
+"
+    sn=$((sn + 1))
+  done
+
+  # implicit rows: every ACTIVE milestone (from the fresh index.yml) with no
+  # stream file → a coverage row so it can never be silently missing.
+  if [ -f "$root/.forge/state/index.yml" ]; then
+    active_ms="$(awk '
+      /^  - id:/ { id=$3; gsub(/["\x27]/,"",id) }
+      /^    status:/ { if ($2=="active") print id }
+    ' "$root/.forge/state/index.yml" 2>/dev/null)"
+    for am in $active_ms; do
+      case "$seen_ms" in *" $(norm_id "$am") "*) continue ;; esac
+      mp="$root/.forge/state/milestone-${am#m-}.yml"
+      [ -f "$mp" ] || mp="$root/.forge/state/milestone-${am}.yml"
+      ph="-"
+      [ -f "$mp" ] && ph="$(yaml_scalar "$(cat "$mp")" current status)"
+      [ -z "$ph" ] && ph="-"
+      stream_rows="$stream_rows$am	implicit	$ph	$am	not_ready
+"
+      sn=$((sn + 1))
+    done
+  fi
+
+  sorted="$(printf '%s' "$stream_rows" | LC_ALL=C sort -t'	' -k1,1)"
+  msorted="$(printf '%s' "$merge_rows" | LC_ALL=C sort)"
+
+  {
+    printf '# Forge Stream Registry — active work (DERIVED — do not hand-edit)\n'
+    printf '# Regenerated at boot by .claude/hooks/forge-state-rollup.sh: streams/*.yml\n'
+    printf '# joined with active milestones (ADR-015). Git-ignored cache — never committed.\n'
+    printf 'version: 1\n'
+    printf 'streams:\n'
+    if [ "$sn" -eq 0 ]; then
+      printf '  []\n'
+    else
+      printf '%s\n' "$sorted" | while IFS='	' read -r r_id r_coord r_phase r_ms r_merge; do
+        [ -z "$r_id" ] && continue
+        printf '  - id: %s\n' "$(yaml_quote "$r_id")"
+        printf '    coordination: %s\n' "$r_coord"
+        printf '    phase: %s\n' "$r_phase"
+        if [ "$r_ms" = "null" ]; then
+          printf '    milestone: null\n'
+        else
+          printf '    milestone: %s\n' "$(yaml_quote "$r_ms")"
+        fi
+        printf '    merge_readiness: %s\n' "$r_merge"
+      done
+    fi
+    printf 'merge_queue:\n'
+    if [ -z "$msorted" ]; then
+      printf '  []\n'
+    else
+      printf '%s\n' "$msorted" | while IFS= read -r mq; do
+        [ -z "$mq" ] && continue
+        printf '  - %s\n' "$(yaml_quote "$mq")"
+      done
+    fi
+  } > "$active_path.tmp.$$" && mv -f "$active_path.tmp.$$" "$active_path"
+
+  STREAM_ROW_COUNT="$sn"
+}
+
+# --- run ---------------------------------------------------------------------
+
+render_index                 # index.yml first — stream rollup reads it
+
+if [ -d "$root/.forge/streams" ]; then
+  stream_autoclose_sweep     # step 0 (main checkout only)
+  render_active              # then the join
+fi
+
+# --- summary (stdout → injected into boot context) ---------------------------
+
+if [ "$quiet" -eq 0 ]; then
+  summary="[forge-state-rollup] rendered index.yml (${INDEX_ROW_COUNT:-0} milestone"
+  [ "${INDEX_ROW_COUNT:-0}" = "1" ] || summary="${summary}s"
+  summary="$summary)"
+  if [ -d "$root/.forge/streams" ]; then
+    summary="$summary + active.yml (${STREAM_ROW_COUNT:-0} stream row"
+    [ "${STREAM_ROW_COUNT:-0}" = "1" ] || summary="${summary}s"
+    summary="$summary)"
+  fi
+  [ -n "$SWEEP_CLOSED" ] && summary="$summary; auto-closed:${SWEEP_CLOSED}"
+  [ "${fold_unavailable:-0}" -gt 0 ] && summary="$summary; ${fold_unavailable} release_state unknown (fold unavailable)"
+  if [ "$in_main_checkout" -eq 1 ]; then
+    summary="$summary. Registries are fresh — READ them, do not regenerate by hand."
+  else
+    summary="$summary (worktree: caches rendered locally; auto-close sweep skipped). READ the caches, do not regenerate by hand."
+  fi
+  printf '%s\n' "$summary"
+fi
+
+exit 0

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

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Weld the primary checkout to the default branch — deny branch create/switch there.
+#
+# PreToolUse(Bash) hook. Exit 2 (+ JSON permissionDecision:deny) = block. Exit 0 = allow.
+#
+# WHY: the primary checkout's HEAD is shared mutable state across every concurrent
+# Claude session running in that directory. One session running `git checkout -b`
+# silently redirects every OTHER session's subsequent commits onto its branch — an
+# invisible clobber that surfaces later as wrong-branch commits, contaminated PRs,
+# stranded milestone state, or dropped history (issue #21: 3 confirmed incidents —
+# m85's 12-commit drop, m62's stranded phase commits, a Quick-tier checkout -b that
+# contaminated a concurrent PR). Branch work belongs in worktrees, which each own
+# their own HEAD.
+#
+# Scope: fires ONLY in the primary checkout (git-dir == git-common-dir). Linked
+# worktrees are unaffected (their git-dir differs). Unlike the dormant
+# forge-branch-guard.sh this supersedes, the branch weld is UNCONDITIONAL — it fires
+# even when no sibling worktree exists yet, because the second session's worktree is
+# typically created AFTER the offending `checkout -b`. This hook also folds in the
+# one distinct protection the old guard provided: denying a hard-reset in the primary
+# checkout while sibling worktrees are branched off it (the history-rewrite class).
+#
+# Default branch is resolved dynamically (main/master + init.defaultBranch), never
+# hardcoded — Forge ships to repos on any default branch.
+#
+# Fails OPEN (exit 0 / allow) on any malfunction (no jq, empty command, non-git cwd,
+# git probe error) — a guard must never wedge the agent on its own failure.
+#
+# Escape hatch (deliberate, human use): ALLOW_MAIN_BRANCHING=1
+
+set -uo pipefail
+
+emit_deny() {
+  local reason="${1//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
+  exit 2
+}
+
+[ "${ALLOW_MAIN_BRANCHING:-0}" = "1" ] && exit 0
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+[ -z "$COMMAND" ] && exit 0
+
+# Normalize the cheapest whitespace-substitution evasion (`git checkout$IFS-b`) to a
+# real space before matching. A string matcher on an un-expanded shell command can
+# never be complete against expansion — the pre-commit backstop is the sound layer —
+# but closing the trivial $IFS trick keeps the PreToolUse layer honest.
+COMMAND=$(printf '%s' "$COMMAND" | sed -E 's/\$\{?IFS\}?/ /g')
+
+# Git allows global options BEFORE the subcommand: `git -c k=v checkout`,
+# `git --no-pager switch`, `git -C <path> -p checkout`, etc. The guard must tolerate
+# ANY run of them, not just a single `-C <path>` — otherwise `git -c x=y checkout -b`
+# sails past (issue #21 regression). GITPRE matches `git` + zero-or-more global options
+# (a `-x`/`--long`/`--long=val`/`-C <path>`/`-c <kv>` token, each optionally taking the
+# next word as its value) up to the subcommand.
+GITPRE='git[[:space:]]+((-[A-Za-z]|--[A-Za-z-]+)(=[^[:space:]]+)?[[:space:]]+([^-][^[:space:]]*[[:space:]]+)?)*'
+
+# Fast path: only inspect commands that touch checkout/switch/reset at all. Anything
+# else exits immediately WITHOUT any git probe (keeps the hook cheap on every Bash call).
+printf '%s' "$COMMAND" | grep -qE "${GITPRE}(checkout|switch|reset)([[:space:]]|\$)" || exit 0
+
+# Resolve which repo dir the command targets: honor `git -C <path>`, else the hook cwd.
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+[ -z "$CWD" ] && CWD=$(pwd)
+# Honor a GLOBAL `git -C <path>` (before the subcommand) only. Isolate the pre-subcommand
+# segment first so `switch -C`/`checkout -C` (create-force, AFTER the subcommand) is never
+# mistaken for a target-dir option.
+PRE=$(printf '%s' "$COMMAND" | sed -E 's/[[:space:]](checkout|switch|reset)[[:space:]].*$//')
+GC_PATH=$(printf '%s' "$PRE" | grep -oE '(^|[[:space:]])-C[[:space:]]+[^[:space:]]+' | head -1 | awk '{print $2}' || true)
+# A flag-shaped -C value (e.g. `-C --foo`) is not a real target dir → ignore it.
+case "$GC_PATH" in -*) GC_PATH="" ;; esac
+TARGET_DIR="${GC_PATH:-$CWD}"
+
+GIT_DIR=$(git -C "$TARGET_DIR" rev-parse --git-dir 2>/dev/null) || exit 0
+COMMON_DIR=$(git -C "$TARGET_DIR" rev-parse --git-common-dir 2>/dev/null) || exit 0
+GIT_DIR_ABS=$(cd "$TARGET_DIR" 2>/dev/null && cd "$GIT_DIR" 2>/dev/null && pwd) || exit 0
+COMMON_DIR_ABS=$(cd "$TARGET_DIR" 2>/dev/null && cd "$COMMON_DIR" 2>/dev/null && pwd) || exit 0
+
+# In a linked worktree git-dir != git-common-dir → branch ops are fine there.
+[ "$GIT_DIR_ABS" != "$COMMON_DIR_ABS" ] && exit 0
+
+# ── Default-branch set (dynamic — mirrors block-dangerous-commands.sh) ───────────
+# Seed main+master, add the configured init.defaultBranch. A switch/checkout TO any
+# of these names is "returning home" and always allowed.
+DEFAULT_BRANCHES="main master"
+GIT_DEFAULT=$(git -C "$TARGET_DIR" config --get init.defaultBranch 2>/dev/null || true)
+[ -n "$GIT_DEFAULT" ] && DEFAULT_BRANCHES="$DEFAULT_BRANCHES $GIT_DEFAULT"
+is_default_branch() {
+  for b in $DEFAULT_BRANCHES; do [ "$1" = "$b" ] && return 0; done
+  return 1
+}
+
+DENY_MSG="Blocked: the primary checkout's HEAD stays on the default branch — branch create/switch here silently redirects every other concurrent session's commits onto your branch (recurring clobber, issue #21). Do branch work in a worktree: bash .forge/bin/new-worktree.sh <slug> (or git worktree add). To operate on an existing worktree from here, use git -C <worktree-path>. Human escape hatch: ALLOW_MAIN_BRANCHING=1."
+
+# ── 1) Branch creation / orphan / detach / track: always deny in primary checkout ──
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}checkout[[:space:]]+((-[a-zA-Z]*[bB][a-zA-Z]*|--orphan|--detach|--track)([[:space:]=]|\$))"; then
+  emit_deny "$DENY_MSG"
+fi
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}switch[[:space:]]+((-[cC]|--create|--force-create|--orphan|--detach|--track)([[:space:]=]|\$))"; then
+  emit_deny "$DENY_MSG"
+fi
+
+# ── 2) hard/keep/merge reset in the primary checkout while worktrees are branched ──
+# Folded from the superseded forge-branch-guard.sh: a reset that rewrites HEAD +
+# working tree here can drop verified work committed under sibling worktrees. Gated
+# on >1 worktree (unlike the branch weld, which is unconditional).
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}reset[[:space:]]+(--hard|--keep|--merge)([[:space:]]|\$)"; then
+  wt_count=$(git -C "$TARGET_DIR" worktree list 2>/dev/null | wc -l | tr -d ' ')
+  if [ "${wt_count:-1}" -gt 1 ]; then
+    emit_deny "Refusing to move the shared primary HEAD via reset — $wt_count worktrees are branched off it (the 'burned twice' history-rewrite failure, issue #21). Reset inside a worktree, or stop the other sessions first. Human escape hatch: ALLOW_MAIN_BRANCHING=1."
+  fi
+  exit 0   # single-worktree hard-reset is the operator's own business — allow.
+fi
+
+# ── 3) checkout/switch to a ref other than the default branch ───────────────────
+# Only checkout/switch move HEAD to a ref. A reset that reached this far (--soft /
+# --mixed, or a hard/keep/merge reset in a single-worktree repo) is not a branch move
+# off the default → allow it and stop.
+printf '%s' "$COMMAND" | grep -qE "${GITPRE}(checkout|switch)([[:space:]]|\$)" || exit 0
+
+# `git checkout <ref> -- <paths>` and `git checkout -- <paths>` never move HEAD →
+# allow anything containing a ` -- ` pathspec separator.
+printf '%s' "$COMMAND" | grep -qE '[[:space:]]--([[:space:]]|$)' && exit 0
+
+# Extract the first non-flag argument after checkout/switch. Strip everything up to and
+# including the subcommand keyword — whatever git global options preceded it (`-c`,
+# `--no-pager`, `-C <path>`, …) are consumed by the greedy prefix. The trailing separator
+# is optional so a BARE `git checkout` (no target) yields empty ARGS → allowed below.
+ARGS=$(printf '%s' "$COMMAND" | sed -E 's/.*[[:space:]](checkout|switch)([[:space:]]+|$)/ /' | head -1)
+FIRST_REF=""
+for word in $ARGS; do
+  case "$word" in
+    -*) continue ;;                     # flags (creation flags already denied above)
+    \;|\&\&|\|\||\||\&) break ;;        # end of this git command
+    *) FIRST_REF="$word"; break ;;
+  esac
+done
+
+# Bare `git checkout`/`git switch` (no target) is a no-op/error → allow.
+[ -z "$FIRST_REF" ] && exit 0
+
+# Returning home (default branch) or file-restore forms → allow. Any other ref → deny.
+case "$FIRST_REF" in
+  HEAD|.) exit 0 ;;                      # file restore forms
+  *) is_default_branch "$FIRST_REF" && exit 0 || emit_deny "$DENY_MSG" ;;
+esac

package/template/.claude/hooks/tests/README.md

@@ -71,6 +71,26 @@ For a `deny`/`allow` style hook, every case file should include:
 - At least one **allow** that sits right next to a deny path (e.g. `git push origin main` denies, `git push origin feature/foo` allows) — proves the pattern is specific, not blanket.
 - One **no-op** case where the hook input does not match the shape the hook expects (e.g. `file_path` missing, `command` empty) — proves the hook fails open for irrelevant events.
 
+## Standalone git-fixture tests
+
+Some hooks need a real git repository (tracked files, merges, worktrees) rather
+than a single stdin payload, so they ship self-contained `*.test.sh` scripts run
+directly instead of through `run.sh`:
+
+```bash
+.claude/hooks/tests/forge-state-rollup.test.sh    # boot rollup (index.yml + active.yml)
+.claude/hooks/tests/forge-release-fold.test.sh    # release_state fold
+.claude/hooks/tests/forge-reserve.test.sh         # id reservation
+.claude/hooks/tests/verify-signoff.test.sh        # signed-tag verification
+.claude/hooks/tests/wu-done.test.sh               # done predicate
+```
+
+Each builds throwaway repos in `mktemp` dirs with no remote and isolated git
+config. `forge-state-rollup.test.sh` covers the #22 acceptance shape (a stale
+cache is regenerated regardless), fold-degrade → `release_state: unknown`, the
+main-only auto-close sweep, the linked-worktree guard (sweep skipped, caches
+still rendered), and the SessionStart stdin path.
+
 ## Why this lives here
 
 Hooks run on every tool call the agent makes. If they regress silently, either the agent starts bypassing real protections, or innocent edits start getting blocked and the hooks get disabled in frustration. A small test harness catches both before they land.