forge-orkes 0.74.0 → 0.77.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-reserve.test.sh

@@ -285,6 +285,98 @@ else
   fail "case10b --days 1 dropped the kind's max row"
 fi
 
+# --- Case 11: origin/main floor beats a lagging local main (#26) -------------
+# The local-main-first collision: origin/main carries a MERGED higher claim
+# (FR-300) that local main has not fast-forwarded to (local main still at FR-200).
+# A local-main-only floor would hand out FR-201 — an id origin/main already used.
+# The fix reads across {main, origin/main}, so the floor is FR-300 → next FR-301.
+origin_repo="$(new_repo case11-origin)"
+( cd "$origin_repo"
+  mkdir -p .forge
+  cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-300
+    milestone: m-sibling
+    reserved_at: "2026-02-01"
+    summary: "merged on origin/main, ahead of local main"
+YML
+  git add -A && git commit -qm "origin has FR-300" )
+# Clone it (clone's origin → the seed repo), then rewind the clone's LOCAL main to
+# an earlier commit carrying only FR-200 — simulating a primary checkout parked on a
+# stale main while sibling work merged FR-300 to origin.
+clone="$ROOT/repo.case11-clone"
+git clone -q "$origin_repo" "$clone"
+cd "$clone"
+git config user.email t@example.com; git config user.name tester
+# Build a divergent local main: reset to an orphan-free earlier state with FR-200.
+cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-200
+    milestone: m-x
+    reserved_at: "2026-01-01"
+    summary: "local main lags"
+YML
+git add -A && git commit -qm "local main at FR-200 (behind origin/main FR-300)"
+# origin/main (remote-tracking) still points at FR-300; local main is now at FR-200.
+# Allow the helper to fetch the local file:// origin (deterministic, no network).
+got="$(FORGE_RESERVE_NO_FETCH=1 "$HELPER" fr --milestone m-x)"
+check "case11 origin/main floor (FR-300) beats lagging local main (FR-200) -> FR-301" "$got" "FR-301"
+# Negative control: with the origin arm blind (simulate no remote-tracking ref by
+# reading a repo that has NO origin at all), the floor falls back to local main only.
+d="$(new_repo case11-noorigin)"; cd "$d"
+mkdir -p .forge
+cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-200
+    milestone: m-x
+    reserved_at: "2026-01-01"
+    summary: "no origin — local main is the only floor"
+YML
+git add -A && git commit -qm init
+rm .forge/reservations.yml
+got="$(FORGE_RESERVE_NO_FETCH=1 "$HELPER" fr --milestone m-x)"
+check "case11 no-origin repo still floors on local main (FR-200) -> FR-201" "$got" "FR-201"
+
+# --- Case 12: the fetch refreshes a STALE origin/main tracking ref (#26) ------
+# The end-to-end proof: a sibling merges a higher claim to origin AFTER this clone
+# was made, so the clone's origin/main remote-tracking ref is stale. Without the
+# best-effort fetch the floor would miss it; with the fetch (default, NOT skipped)
+# the helper refreshes origin/main and floors correctly. Uses a local file:// origin
+# so the "fetch" is a deterministic local operation, no network.
+seed="$(new_repo case12-seed)"
+( cd "$seed"
+  mkdir -p .forge
+  cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-200
+    milestone: m-x
+    reserved_at: "2026-01-01"
+    summary: "seed FR-200"
+YML
+  git add -A && git commit -qm "seed FR-200" )
+clone2="$ROOT/repo.case12-clone"
+git clone -q "$seed" "$clone2"
+# Sibling advances origin to FR-400 AFTER the clone → clone's origin/main is now stale.
+( cd "$seed"
+  cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-400
+    milestone: m-sibling
+    reserved_at: "2026-03-01"
+    summary: "merged to origin after the clone"
+YML
+  git add -A && git commit -qm "origin advances to FR-400" )
+cd "$clone2"
+git config user.email t@example.com; git config user.name tester
+# Do NOT set FORGE_RESERVE_NO_FETCH — the fetch is exactly what we are testing.
+got="$("$HELPER" fr --milestone m-x)"
+check "case12 fetch refreshes stale origin/main (FR-400) -> FR-401" "$got" "FR-401"
+
 # --- Report -----------------------------------------------------------------
 printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
 [ "$FAILED" -eq 0 ]

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

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

package/template/.claude/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/executing/SKILL.md

@@ -36,6 +36,29 @@ fi
 
 Surface the init if it ran (*"populated N uninitialised submodule(s) before baseline"*). A `+`/`U` line (divergent/conflicted submodule) is **not** an init case — STOP under Rule 4; it signals real submodule movement. (Desire-path: canvaz m-TIDES01 — empty `external/JUCE` failed the first CMake configure mid-task.)
 
+**Gitignored artifacts.** A fresh worktree is a clean checkout of *tracked* files only. Anything gitignored but required — `.mcp.json` (MCP server config, often secret-bearing so it MUST stay gitignored), `.env.local`, experimental hook configs — is simply **absent**, and the failure is silent: MCP servers that never appear, an env-dependent command that misbehaves — no clear "missing config" error. `orchestrating` hydrates these when *it* creates the worktree, but a worktree from any other origin (a manual `git worktree add`, a `chief-of-staff` stream, a fresh clone) does not. So assert it here, regardless of how the workspace was created. Advisory and guarded — a clean no-op when `orchestration.worktree_hydrate` is unset or nothing applies, so existing installs are unaffected:
+
+```bash
+# Copy required-but-gitignored artifacts named in orchestration.worktree_hydrate from the
+# superproject (the MAIN checkout, resolved from the shared git common dir — this assertion
+# runs INSIDE the worktree), guarded source-exists && dest-absent. Never overwrites, never
+# git-adds — the file stays gitignored/untracked in both trees (a secret like .mcp.json never
+# enters git history). No-op when the key is absent or nothing applies.
+repo_root=$(git rev-parse --show-toplevel)
+super=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null | sed 's#/\.git/modules/.*##;s#/\.git/worktrees/.*##;s#/\.git$##')
+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: robust across sh/bash/zsh; a path may contain spaces
+      [ -n "$rel" ] && [ -n "$super" ] && [ "$super" != "$repo_root" ] || continue  # no key / main checkout → no-op
+      [ -e "$super/$rel" ] && [ ! -e "$repo_root/$rel" ] || continue                # source-exists && dest-absent
+      mkdir -p "$(dirname "$repo_root/$rel")"; cp -p "$super/$rel" "$repo_root/$rel"
+      echo "hydrated: $rel"
+    done
+```
+
+The loop prints one `hydrated: {path}` line per artifact it copied — surface those before the baseline (*"hydrated N gitignored artifact(s) before baseline"*), mirroring the submodule surface line; no output means nothing needed hydrating. The `$super != $repo_root` guard makes this a natural no-op in a non-worktree (main) checkout — where superproject and checkout are the same tree and there is nothing to hydrate from.
+
 ## Baseline Snapshot
 
 Run **before the first task begins**. Makes failure causality mechanical — no self-assessment.

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

@@ -59,6 +59,8 @@ Where worktrees live and what they're named — single source of truth, base con
 
 **Recorded path is authoritative once set** — `lifecycle.worktree_path` (milestone) / `runtime.worktree` (stream) is read verbatim, never re-derived; changing `worktree_root` affects only new worktrees; move a live worktree only with `git worktree move` + update the record. No recorded path → resolve from the convention. `forge` boot and `chief-of-staff` adoption **validate advisorily**: recorded path outside the resolved root → warn (never block, never move); an explicit `worktree_root` is honored.
 
+**`orchestration.worktree_hydrate`** (optional, `project.yml`; forge#18) lists superproject-relative paths to required-but-gitignored artifacts (e.g. `.mcp.json`) a fresh worktree's tracked-only checkout lacks. Copy is guarded `source-exists && dest-absent` — never overwrites, never `git add`s, so the secret stays untracked in both trees. Applied by `orchestrating` at creation and re-asserted idempotently in `executing`'s Workspace Prerequisites, covering worktrees of any origin. Omit ⇒ no propagation. The per-worktree runtime counterpart of the install-time carve-out propagation below (State Ownership § Stable shared).
+
 ## Workflow Tiers
 
 Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
@@ -193,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)
@@ -214,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