forge-orkes 0.74.0 → 0.77.0

package/experimental/m10/source/skills/orchestrating/SKILL.md

@@ -80,16 +80,45 @@ mkdir -p "$wt_root"
 git worktree prune
 git worktree add -b forge/${anchor} --lock --reason "forge session m-${milestone_id}" "$wt_root/${anchor}" main
 wt="$wt_root/${anchor}"
-# Submodules don't auto-populate in a new worktree — init them if present. Reuses the
+
+# --- Hydrate the worktree ---
+# A git worktree is a clean checkout of *tracked* files only. Everything required but
+# untracked — submodule working trees, gitignored config/secrets — is absent until we
+# put it there. Hydration is that ordered step; submodule init is one instance of it.
+
+# (1) Submodules don't auto-populate in a new worktree — init them if present. Reuses the
 # superproject's shared .git/modules object store (no re-clone, just a working-tree
 # checkout); ccache absorbs the subsequent rebuild cost across worktrees.
 if [ -n "$(git -C "$wt" submodule status 2>/dev/null)" ]; then
   ( cd "$wt" && git submodule update --init --recursive )
 fi
+
+# (2) Required-but-gitignored artifacts (e.g. .mcp.json — MCP config, often secret-bearing;
+# .env.local; experimental hook configs) named in orchestration.worktree_hydrate. A clean
+# checkout lacks them, and the failure is SILENT: MCP servers that never appear, an env-
+# dependent command that misbehaves. Copy each from the superproject, guarded source-exists
+# && dest-absent → never overwrites, and we NEVER `git add` a hydrated path: it stays
+# gitignored/untracked in both trees, so a secret like .mcp.json never enters git history.
+sed -n '/^orchestration:/,/^[^[:space:]#]/p' "$repo_root/.forge/project.yml" 2>/dev/null \
+  | sed -n '/^[[:space:]]*worktree_hydrate:/,/^[[:space:]]*[a-z_]*:/p' \
+  | sed -n 's/^[[:space:]]*-[[:space:]]*//p' | tr -d "\"'" \
+  | while IFS= read -r rel; do                   # line-based: a path may contain spaces; robust across sh/bash/zsh
+      [ -n "$rel" ] || continue
+      [ -e "$repo_root/$rel" ] || continue        # source-exists guard (no-op when nothing applies)
+      [ -e "$wt/$rel" ] && continue               # dest-absent guard (idempotent — never clobbers)
+      mkdir -p "$(dirname "$wt/$rel")"
+      cp -p "$repo_root/$rel" "$wt/$rel"
+    done
+
+# (3) Dependency install (node_modules etc.) is DEFERRED to the executing/verifying preflight
+# on purpose — Forge core owns no package-manager concept, and the node_modules desire path is
+# already handled there. That is where the false-green `tsc` class (a no-op tsc against a missing
+# node_modules reporting green) is closed — not here.
+
 ( cd "$wt" && git hook run pre-commit || true )
 ```
 
-Verify worktree dir exists, branch locked, and (if applicable) submodule dirs are non-empty. On failure → cleanup partial state, refuse mode.
+Verify worktree dir exists, branch locked, and (if applicable) submodule dirs are non-empty and each configured `worktree_hydrate` artifact that exists in the superproject is present in the worktree. On failure → cleanup partial state, refuse mode.
 
 `anchor` (= `m-{milestone_id}-{session_id}`) names the worktree dir **and** branch from here on; every reference below that used to be `{session_id}` is now `{anchor}`. `session_id` (the bare uuid) is retained only as the collision key + audit id in state.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.74.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-reserve.sh

@@ -249,10 +249,27 @@ compute_id() {
   # Hyphen is OPTIONAL in the token ([A-Z]+-?[0-9]+): refactor ids (R100) carry none
   # (ADR-023), so requiring a hyphen would hide them and drop the floor to 0. Split the
   # alpha prefix from the digits in awk so R does not match e.g. FR (anchor ^prefix$).
-  main_max="$(git show main:.forge/reservations.yml 2>/dev/null \
-    | grep -oE '[A-Z]+-?[0-9]+' \
-    | awk -v p="$prefix" '{ a=$0; sub(/[-0-9].*$/,"",a); d=$0; gsub(/[^0-9]/,"",d);
-                            if(a==p){ n=d+0; if(n>m)m=n } } END{print m+0}')"
+  #
+  # READ BOTH main AND origin/main (#26): in the local-main-first workflow (ADR-010 —
+  # primary checkout parked on main, all work in worktrees reaching main via PRs), local
+  # `main` routinely lags origin/main by whatever merged since the last fast-forward, so a
+  # local-only floor hands out ids origin/main already claimed — #19's collision class,
+  # relocated to the one input that still isn't machine-shared. Best-effort-fetch origin
+  # first, then take the max across whichever of {main, origin/main} resolve. Every leg
+  # degrades to nothing offline / with no remote (the same posture the rest of the script
+  # takes) — a fetch failure or a missing ref is never fatal, it just contributes 0.
+  # FORGE_RESERVE_NO_FETCH=1 skips the fetch (fixtures with a local file:// origin want the
+  # deterministic ref state they set up, not a network round-trip).
+  ref_reservations_max() {  # $1 = git ref → max reserved id for $prefix on that ref (0 if absent)
+    git show "$1:.forge/reservations.yml" 2>/dev/null \
+      | grep -oE '[A-Z]+-?[0-9]+' \
+      | awk -v p="$prefix" '{ a=$0; sub(/[-0-9].*$/,"",a); d=$0; gsub(/[^0-9]/,"",d);
+                              if(a==p){ n=d+0; if(n>m)m=n } } END{print m+0}'
+  }
+  [ "${FORGE_RESERVE_NO_FETCH:-0}" = 1 ] || git fetch --quiet origin main 2>/dev/null || true
+  main_local_max="$(ref_reservations_max main)";        [ -n "$main_local_max" ]  || main_local_max=0
+  main_origin_max="$(ref_reservations_max origin/main)"; [ -n "$main_origin_max" ] || main_origin_max=0
+  main_max="$(awk -v a="$main_local_max" -v b="$main_origin_max" 'BEGIN{print (a>b)?a:b}')"
   [ -n "$main_max" ] || main_max=0
 
   next="$(awk -v a="$ledger_max" -v b="$intree_max" -v c="$main_max" \

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