forge-orkes 0.75.0 → 0.77.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.75.0",
+  "version": "0.77.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

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

@@ -113,3 +113,124 @@ primary coordination point.
 - "internal error at line N" on every edit → corrupt DB or missing tool. Run doctor. Common: `jq` not on PATH.
 - No collisions detected → confirm `CLAUDE_SESSION_ID` set and `claims.db` exists; otherwise hook fail-opens.
 - macOS `timeout: command not found` → `brew install coreutils` for `gtimeout`, or skip (DB busy_timeout still applies).
+
+## `forge-state-rollup.sh` — SessionStart state rollup
+
+Makes the boot rollup mechanical (issue #22). Ports **State Rollup 1.0** and the
+**Stream Rollup** (ADR-015 addendum) from advisory skill prose into an
+executable that a SessionStart hook runs on every boot, so a session can no
+longer skip the render and work from a stale cache or hand-reconstruct the
+registries — the failure mode filed against #22.
+
+### Behavior
+
+Renders two git-ignored render-on-read caches (0.53.0) and never commits
+either:
+
+| Renders | From | Notes |
+|---|---|---|
+| `.forge/state/index.yml` | `.forge/state/milestone-*.yml` | Derived registry status (`deferred`/`complete`/`not_started`/`active`); `last_updated` falls back to legacy `progress.last_update`; per-row `release_state` is fetched by shelling to `forge-release-fold.sh` — the fold is the **only** source, never re-derived here |
+| `.forge/streams/active.yml` | `.forge/streams/*.yml` + active milestones | Stream Rollup join: per-stream coordination rows, milestone-derived `phase`, `implicit` coverage rows for active milestones with no stream file, derived `merge_queue` (only rendered if `.forge/streams/` exists) |
+
+A **step-0 completed-stream auto-close sweep** runs before the stream join and
+edits committed stream files (`streams/{stream}.yml`) — a milestone-backed
+stream whose milestone is `complete`, not already `closed`, with no live
+worktree gets auto-closed. This step is **main-checkout only**
+(`git rev-parse --git-dir` == `--git-common-dir`); a linked worktree skips the
+sweep but still renders both caches locally.
+
+Deterministic and idempotent — two runs against the same sources produce
+byte-identical output.
+
+**Fold dependency and degrade.** `release_state` comes exclusively from
+`.claude/hooks/forge-release-fold.sh`. If the fold script is missing or exits
+non-zero for a unit, that row gets `release_state: unknown` plus one advisory
+stderr line (`forge-state-rollup: release fold unavailable for m-N —
+release_state: unknown`) — a broken fold degrades a single row, it never
+breaks boot.
+
+**Non-blocking contract.** Exit `0` **always** — SessionStart hooks are
+non-blocking, so every failure path (not a git repo, no `.forge/`, no
+`.forge/state/`) degrades to a silent no-op rather than surfacing an error.
+stdout carries one terse summary line (unless `--quiet`) that is injected into
+the model's context — e.g. `[forge-state-rollup] rendered index.yml (3
+milestones) + active.yml (2 stream rows). Registries are fresh — READ them,
+do not regenerate by hand.` stderr carries advisories (auto-close, fold
+degrade) and is visible in the transcript but not injected into context.
+
+### Why `cwd`, not `$CLAUDE_PROJECT_DIR`
+
+`$CLAUDE_PROJECT_DIR` resolves to the repo **root** (main checkout) even when
+the session started inside a linked worktree. Rendering against it from a
+worktree session would write the caches into the wrong tree. The hook instead
+resolves the target repo from the SessionStart payload's `cwd` (read from
+stdin JSON), falling back to `$PWD` if `--project` isn't passed and stdin/`jq`
+aren't available. Each worktree therefore renders **its own** gitignored
+caches; a worktree's boot never touches main's.
+
+### Prerequisites
+
+- POSIX `sh` + `git` + `awk`/`sed` (mirrors `forge-release-fold.sh`) — no other
+  runtime dependency.
+- `jq` — used only to parse the SessionStart stdin JSON (`cwd`). Absent `jq`
+  degrades to a no-stdin path (falls back to `--project` or `$PWD`); it does
+  not disable the hook.
+- No network calls.
+
+### CLI usage
+
+```bash
+.claude/hooks/forge-state-rollup.sh [--project <path>] [--quiet]
+```
+
+- `--project <path>` — operate on the repo containing `<path>` instead of the
+  SessionStart payload's `cwd`. Useful for manually re-rendering a specific
+  worktree or repo outside a session.
+- `--quiet` — suppress the stdout summary line; caches are still written.
+
+Run it manually any time the caches look stale — it is safe to re-run and
+always produces the same output for the same sources.
+
+### Registration
+
+Wired as a `SessionStart` hook in `.claude/settings.json` (and the
+`create-forge` template copy), matcher `startup|resume|clear`:
+
+```json
+{
+  "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"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The `[ -x ... ] && ... || true` guard means a repo without the hook file (or
+with it non-executable) boots exactly as before — the hook is additive, not a
+new hard dependency.
+
+### Disabling
+
+Remove the `SessionStart` block above from `.claude/settings.json`, or make
+the script non-executable: `chmod -x .claude/hooks/forge-state-rollup.sh`.
+Without it, boot falls back to the advisory skill-prose rollup (`forge` /
+`chief-of-staff` render-then-read) — correct but no longer mechanically
+enforced.
+
+### Tests
+
+`.claude/hooks/tests/forge-state-rollup.test.sh` — a standalone git-fixture
+suite (36 cases) run directly (not through `tests/run.sh`), building throwaway
+repos in `mktemp` dirs. 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. See `tests/README.md`.

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/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.

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/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",

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/.forge/FORGE.md

@@ -195,12 +195,12 @@ State lives in `.forge/`. One line per artifact; protocol detail lives in the na
 - `design-system.md` — component mapping table
 - `requirements/m{N}.yml` — per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. **FR/DEF/NFR ids are globally unique across all milestone files** — reserve via the ID Reservation Protocol before writing. M9 e2e gate fields (`e2e`, `observable_outcome`, `validated`, hash) lazy-migrate; absent ⇒ `false`.
 - `roadmap.yml` — phases, milestones, dependencies
-- `state/index.yml` — DERIVED milestone registry, **git-ignored render-on-read cache** (0.53.0): regenerated at every boot by Rollup 1.0 (`forge` SKILL Step 1.0) from the milestone files; never committed, never hand-edited, never written by worktree agents; absent on a fresh clone (the project sentinel is `project.yml`). Rows carry the derived `release_state`.
+- `state/index.yml` — DERIVED milestone registry, **git-ignored render-on-read cache** (0.53.0): regenerated at every boot by the **`forge-state-rollup.sh` SessionStart hook** (the mechanical port of Rollup 1.0 — issue #22; skill prose only *reads* it) from the milestone files; never committed, never hand-edited; the hook renders it in any checkout (gitignored local write), but worktree agents still never write the *committed* derived-source state; absent on a fresh clone (the project sentinel is `project.yml`). Rows carry the derived `release_state`.
 - **Derived `release_state`** ([ADR-024](../docs/decisions/ADR-024-merged-validated-fold.md)) — `{unmerged, merged, validated}` computed at rollup by `.claude/hooks/forge-release-fold.sh` (git-only, offline; the fold binary is the only source — agent prose never re-derives it), never stored. Validation binding via `forge.validation_event`: `in_session_signoff` (default; absent ⇒ this) or `promotion_approval` (CI-signed `promotion/{sha}` tag). Inert until a repo opts in; full spec in ADR-024 + the fold header.
 - `state/milestone-{id}.yml` — per-milestone cursor (**single source of truth**): position, decisions, blockers. One owner at a time.
 - `state/desire-paths/` — append-only framework-usage observations, one file per observation, `scope: project|framework` (absent ⇒ project); occurrence counts derived by globbing. **`forge` boot is the single review owner** — surfaces groups at 3+, persists declines (no re-nag), routes `framework`-scope signals upstream ([ADR-012](../docs/decisions/ADR-012-upstream-desire-path-feedback-channel.md)); `verifying` captures but never surfaces.
 - `context.md` — active locked decisions + deferred ideas (≤12 KB); history archives to `context-archive.md`
-- `streams/active.yml` — DERIVED Project Chief traffic map, git-ignored render-on-read cache — see Stream Rollup below ([ADR-015](../docs/decisions/ADR-015-derived-stream-registry.md))
+- `streams/active.yml` — DERIVED Project Chief traffic map, git-ignored render-on-read cache, rendered by the same `forge-state-rollup.sh` hook — see Stream Rollup below ([ADR-015](../docs/decisions/ADR-015-derived-stream-registry.md))
 - `streams/{stream}.yml` (+ `brief.md`, `packages/{id}.yml`) — per-stream **source of truth**: coordination lifecycle, ownership, shared surfaces, blockers, merge readiness, optional `stream.milestone` link (milestone-backed streams omit workflow phase — the rollup reads it from the milestone)
 - `research/milestone-{id}.md` — dated immutable findings snapshot
 - `phases/milestone-{id}/{phase}-{name}/plan-{NN}.md` — task plans with must_haves frontmatter (`{id}`=milestone, `{phase}`=phase# verbatim, `{name}`=kebab, `{NN}`=seq)
@@ -216,7 +216,7 @@ State lives in `.forge/`. One line per artifact; protocol detail lives in the na
 
 ### Stream Rollup
 
-`active.yml` is a pure projection — regenerated, never hand-edited — by a deterministic, idempotent **join**: per-stream files contribute coordination state; active milestones contribute `phase` (any active milestone with no stream file gets a derived `implicit` row — coverage is computed, not maintained); `merge_queue` derives from `merge.readiness: ready`. A **step-0 completed-stream auto-close sweep** runs first: a milestone-backed stream whose milestone is `complete`, not yet `closed`, with no live worktree is auto-closed — a done-and-merged milestone can never leave a zombie "ready to merge" row. Run by the main/orchestrator session at `forge` boot and `chief-of-staff` Show/Sync; worktrees never write it; milestone Rollup 1.0 runs **first** (the join reads the fresh `index.yml`). **Numbered procedure: the ADR-015 addendum.** Because each field has exactly one source and coverage is computed, two-registry drift cannot occur — supersedes the old advisory Registry Drift Check.
+`active.yml` is a pure projection — regenerated, never hand-edited — by a deterministic, idempotent **join**: per-stream files contribute coordination state; active milestones contribute `phase` (any active milestone with no stream file gets a derived `implicit` row — coverage is computed, not maintained); `merge_queue` derives from `merge.readiness: ready`. A **step-0 completed-stream auto-close sweep** runs first: a milestone-backed stream whose milestone is `complete`, not yet `closed`, with no live worktree is auto-closed — a done-and-merged milestone can never leave a zombie "ready to merge" row. Rendered mechanically by the **`forge-state-rollup.sh` SessionStart hook** at boot (issue #22 — an executable, not agent prose), and re-run via that same executable at `chief-of-staff` Show/Sync and after any mid-session milestone CRUD; the hook runs the milestone Rollup 1.0 **first** (the join reads the fresh `index.yml`), and confines the committed-source step-0 sweep to the main checkout. **Numbered procedure: the ADR-015 addendum.** Because each field has exactly one source and coverage is computed, two-registry drift cannot occur — supersedes the old advisory Registry Drift Check.
 
 ### State Commit Protocol
 

package/template/.forge/migrations/0.77.0-state-rollup-executable.md

@@ -0,0 +1,120 @@
+# Migration Guide: State rollup made mechanical (Forge 0.77.0)
+
+Applies to projects upgrading to 0.77.0 or later. State Rollup 1.0 and the
+Stream Rollup (ADR-015 addendum) — previously advisory skill prose that an
+agent had to remember to run at boot — are now an executable,
+`.claude/hooks/forge-state-rollup.sh`, invoked mechanically by a `SessionStart`
+hook. A boot session can no longer skip the render and fall back to reading a
+stale `.forge/state/index.yml` / `.forge/streams/active.yml` cache, or
+hand-reconstruct the registries from memory — the exact failure mode filed as
+issue #22.
+
+`/upgrading` ships the new hook file (`.claude/hooks/forge-state-rollup.sh`)
+like any other framework file. It does **not** wire the `SessionStart`
+registration, because `.claude/settings.json` is a **user-owned file** —
+upgrades never overwrite it (FORGE.md → State Ownership, "Stable shared"
+class notes settings.json is gitignored-carve-out territory, propagated only
+via explicit installer steps, never blanket overwrite). Without this
+migration's one manual step, the hook ships but is never invoked: the
+executable exists, nothing mechanically triggers it.
+
+Projects that ran `initializing` fresh on 0.77.0+ (or already carry the
+`SessionStart` block from an earlier partial adoption) need nothing further.
+
+## Prerequisites
+
+1. On the new version's framework files (`npx forge-orkes upgrade`, or the
+   `upgrading` skill) — so `.claude/hooks/forge-state-rollup.sh` and
+   `.claude/hooks/forge-release-fold.sh` are present and executable.
+2. Working tree clean or changes committed — this migration edits
+   `.claude/settings.json`, a tracked file.
+
+## Detection
+
+Keyed on **the executable existing (or the version already at/above 0.77.0)
+while the SessionStart wiring is absent** — the shipped-but-unwired gap. Uses
+`jq` to inspect `.claude/settings.json`'s `hooks.SessionStart` array for an
+entry referencing `forge-state-rollup`; degrades to a plain-text grep if `jq`
+is not installed. Silent in a non-Forge / non-git tree, silent once the hook
+is wired:
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+[ -x .claude/hooks/forge-state-rollup.sh ] || exit 0
+
+settings=".claude/settings.json"
+[ -f "$settings" ] || {
+  echo "MIGRATE — forge-state-rollup.sh is present but $settings does not exist; add it with the SessionStart hook below"
+  exit 0
+}
+
+if command -v jq >/dev/null 2>&1; then
+  wired="$(jq -r '
+    (.hooks.SessionStart // []) as $entries
+    | [$entries[].hooks[]?.command // "" | select(contains("forge-state-rollup"))]
+    | length > 0
+  ' "$settings" 2>/dev/null)"
+  if [ "$wired" != "true" ]; then
+    echo "MIGRATE — $settings has no SessionStart hook referencing forge-state-rollup.sh; the executable shipped but nothing mechanically triggers it"
+  fi
+else
+  if ! grep -q "forge-state-rollup" "$settings" 2>/dev/null; then
+    echo "MIGRATE — $settings has no reference to forge-state-rollup.sh (jq unavailable, ran plain-text check); add the SessionStart hook below"
+  fi
+fi
+```
+
+## Migration steps
+
+### 1. Add the SessionStart hook block
+
+Open `.claude/settings.json` and add (or merge into) a `hooks.SessionStart`
+array entry:
+
+```json
+{
+  "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"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If `hooks.SessionStart` already has other entries (e.g. from a project-local
+customization), append this object to the existing array rather than
+replacing it. If `hooks` exists but has no `SessionStart` key yet, add the key
+alongside the existing `PreToolUse`/`PostToolUse` blocks.
+
+The `[ -x ... ] && ... || true` guard means the hook is a no-op — never a
+boot failure — on any checkout where the script is absent or not executable
+(SessionStart hooks are non-blocking; `forge-state-rollup.sh` itself also
+always exits 0).
+
+### 2. Commit the settings change
+
+```bash
+git add .claude/settings.json
+git commit -m "chore(forge): wire forge-state-rollup SessionStart hook (0.77.0)"
+```
+
+## Validation
+
+- Start a new session, or run `/clear` — the boot summary line should include
+  `[forge-state-rollup] rendered index.yml (…) …` (plus an `active.yml` clause
+  if `.forge/streams/` exists), confirming the hook actually ran.
+- `jq '.hooks.SessionStart' .claude/settings.json` prints a non-null array
+  containing the `forge-state-rollup` command, not `null`.
+- Re-running the Detection block above now prints nothing (exits silently) —
+  the gap is closed.
+- `.forge/state/index.yml` and `.forge/streams/active.yml` (if applicable)
+  exist on disk and are fresh — their mtimes update on every boot, since the
+  hook re-renders unconditionally.