forge-orkes 0.50.1 → 0.55.0

package/template/.claude/hooks/tests/verify-signoff.test.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env sh
+# Self-contained unit test for .claude/hooks/verify-signoff.sh (Contract M0 / D1).
+#
+# Builds throwaway git repos with real SSH-signed tags (a fresh keypair per test
+# run, registered as an allowed signer) and asserts exit code + reason for the
+# four negative cases plus the one positive case. Needs ssh-keygen + git built
+# with SSH signing support (git >= 2.34). Run:
+#   ./.claude/hooks/tests/verify-signoff.test.sh
+# Exits 0 iff every case passes; non-zero on any failure. Self-cleans on exit.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/../verify-signoff.sh"
+
+[ -x "$HELPER" ] || { printf 'FATAL: helper not executable: %s\n' "$HELPER" >&2; exit 1; }
+command -v ssh-keygen >/dev/null 2>&1 || { printf 'FATAL: ssh-keygen not found\n' >&2; exit 1; }
+
+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() { # desc, actual, expected
+  if [ "$2" = "$3" ]; then pass "$1"; else fail "$1 (got '$2', want '$3')"; fi
+}
+
+# One allowed-signer keypair (the "operator") + one non-allowed keypair (the
+# "agent") shared across cases.
+gen_key() { # path
+  ssh-keygen -t ed25519 -N "" -C "$2" -f "$1" -q
+}
+gen_key "$ROOT/operator_key" "operator@example.com"
+gen_key "$ROOT/agent_key" "agent@example.com"
+
+allowed_signers="$ROOT/allowed_signers"
+printf 'operator@example.com namespaces="git" %s\n' "$(cat "$ROOT/operator_key.pub")" > "$allowed_signers"
+
+new_repo() { # name
+  d="$ROOT/repo.$1"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" symbolic-ref HEAD refs/heads/main
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name tester
+  printf '%s\n' "$d"
+}
+
+# Mint a signoff tag with an arbitrary key + arbitrary head:/evidence: body.
+mint_tag() { # repo, wu-id, signing-key, head, evidence
+  repo="$1"; wu="$2"; key="$3"; head="$4"; evidence="$5"
+  body="wu: $wu
+head: $head
+evidence: $evidence"
+  git -C "$repo" -c gpg.format=ssh -c "user.signingkey=$key" \
+    tag -s "signoff/$wu" -m "$body"
+}
+
+evidence_file="$ROOT/evidence.txt"
+printf 'evidence payload\n' > evidence_tmp && mv evidence_tmp "$evidence_file" 2>/dev/null || printf 'evidence payload\n' > "$evidence_file"
+evidence_hash="$(shasum -a 256 "$evidence_file" 2>/dev/null | awk '{print $1}')"
+[ -n "$evidence_hash" ] || evidence_hash="$(sha256sum "$evidence_file" | awk '{print $1}')"
+
+# --- Positive case: correctly signed tag at HEAD, matching evidence ---------
+d="$(new_repo pos)"; cd "$d"
+git commit --allow-empty -qm init
+head_sha="$(git rev-parse HEAD)"
+mint_tag "$d" "wu-pos" "$ROOT/operator_key" "$head_sha" "$evidence_hash"
+out="$("$HELPER" wu-pos --head "$head_sha" --evidence "$evidence_hash" --allowed-signers "$allowed_signers")"; rc=$?
+check "positive: exit 0" "$rc" "0"
+check "positive: stdout ok" "$out" "ok"
+
+# Same, using --evidence-file instead of a precomputed hash.
+out2="$("$HELPER" wu-pos --head "$head_sha" --evidence-file "$evidence_file" --allowed-signers "$allowed_signers")"; rc2=$?
+check "positive (evidence-file): exit 0" "$rc2" "0"
+
+# --- Negative 1: no-signoff (tag absent) ------------------------------------
+d="$(new_repo neg1)"; cd "$d"
+git commit --allow-empty -qm init
+head_sha="$(git rev-parse HEAD)"
+out="$("$HELPER" wu-neg1 --head "$head_sha" --evidence "$evidence_hash" --allowed-signers "$allowed_signers" 2>/dev/null)"; rc=$?
+check "no-signoff: exit 1" "$rc" "1"
+check "no-signoff: reason" "$out" "reason=no-signoff"
+
+# --- Negative 2: bad-signature (signed by a non-allowed key) ----------------
+d="$(new_repo neg2)"; cd "$d"
+git commit --allow-empty -qm init
+head_sha="$(git rev-parse HEAD)"
+mint_tag "$d" "wu-neg2" "$ROOT/agent_key" "$head_sha" "$evidence_hash"
+out="$("$HELPER" wu-neg2 --head "$head_sha" --evidence "$evidence_hash" --allowed-signers "$allowed_signers" 2>/dev/null)"; rc=$?
+check "bad-signature: exit 1" "$rc" "1"
+check "bad-signature: reason" "$out" "reason=bad-signature"
+
+# --- Negative 3: stale (head: does not match landed commit) -----------------
+d="$(new_repo neg3)"; cd "$d"
+git commit --allow-empty -qm init
+head_sha="$(git rev-parse HEAD)"
+mint_tag "$d" "wu-neg3" "$ROOT/operator_key" "0000000000000000000000000000000000000000" "$evidence_hash"
+out="$("$HELPER" wu-neg3 --head "$head_sha" --evidence "$evidence_hash" --allowed-signers "$allowed_signers" 2>/dev/null)"; rc=$?
+check "stale: exit 1" "$rc" "1"
+check "stale: reason" "$out" "reason=stale"
+
+# --- Negative 4: evidence-mismatch ------------------------------------------
+d="$(new_repo neg4)"; cd "$d"
+git commit --allow-empty -qm init
+head_sha="$(git rev-parse HEAD)"
+mint_tag "$d" "wu-neg4" "$ROOT/operator_key" "$head_sha" "deadbeef"
+out="$("$HELPER" wu-neg4 --head "$head_sha" --evidence "$evidence_hash" --allowed-signers "$allowed_signers" 2>/dev/null)"; rc=$?
+check "evidence-mismatch: exit 1" "$rc" "1"
+check "evidence-mismatch: reason" "$out" "reason=evidence-mismatch"
+
+# --- Bad invocation: missing wu-id / missing evidence exits 2 ---------------
+out="$("$HELPER" 2>/dev/null)"; rc=$?
+check "missing wu-id: exit 2" "$rc" "2"
+d="$(new_repo badinvoke)"; cd "$d"
+git commit --allow-empty -qm init
+out="$("$HELPER" wu-x --allowed-signers "$allowed_signers" 2>/dev/null)"; rc=$?
+check "missing evidence: exit 2" "$rc" "2"
+
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]

package/template/.claude/hooks/tests/wu-done.test.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env sh
+# Self-contained unit test for .claude/hooks/wu-done.sh (Contract M0 / D2).
+#
+# Asserts the fold stub reports done=true only for a valid signoff, and that
+# replacing a good tag with a bad-signature one flips done back to false —
+# the contract's verification #4. Run:
+#   ./.claude/hooks/tests/wu-done.test.sh
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/../wu-done.sh"
+
+[ -x "$HELPER" ] || { printf 'FATAL: helper not executable: %s\n' "$HELPER" >&2; exit 1; }
+command -v ssh-keygen >/dev/null 2>&1 || { printf 'FATAL: ssh-keygen not found\n' >&2; exit 1; }
+
+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() { # desc, actual, expected
+  if [ "$2" = "$3" ]; then pass "$1"; else fail "$1 (got '$2', want '$3')"; fi
+}
+
+ssh-keygen -t ed25519 -N "" -C "operator@example.com" -f "$ROOT/operator_key" -q
+ssh-keygen -t ed25519 -N "" -C "agent@example.com" -f "$ROOT/agent_key" -q
+allowed_signers="$ROOT/allowed_signers"
+printf 'operator@example.com namespaces="git" %s\n' "$(cat "$ROOT/operator_key.pub")" > "$allowed_signers"
+
+d="$ROOT/repo"
+mkdir -p "$d"
+git -C "$d" init -q
+git -C "$d" symbolic-ref HEAD refs/heads/main
+git -C "$d" config user.email t@example.com
+git -C "$d" config user.name tester
+cd "$d"
+git commit --allow-empty -qm init
+head_sha="$(git rev-parse HEAD)"
+evidence="deadbeefcafe"
+
+mint() { # signing-key
+  git -c gpg.format=ssh -c "user.signingkey=$1" \
+    tag -sf "signoff/wu-flip" -m "wu: wu-flip
+head: $head_sha
+evidence: $evidence"
+}
+
+# --- Before any tag: done=false, reason=no-signoff --------------------------
+out="$("$HELPER" wu-flip --head "$head_sha" --evidence "$evidence" --allowed-signers "$allowed_signers")"; rc=$?
+check "no tag: exit 1" "$rc" "1"
+check "no tag: reason" "$out" "done=false reason=no-signoff"
+
+# --- Good signature: done=true ----------------------------------------------
+mint "$ROOT/operator_key"
+out="$("$HELPER" wu-flip --head "$head_sha" --evidence "$evidence" --allowed-signers "$allowed_signers")"; rc=$?
+check "good signoff: exit 0" "$rc" "0"
+check "good signoff: stdout" "$out" "done=true"
+
+# --- Flip: re-tag the same wu-id with a non-allowed key — done flips false --
+mint "$ROOT/agent_key"
+out="$("$HELPER" wu-flip --head "$head_sha" --evidence "$evidence" --allowed-signers "$allowed_signers")"; rc=$?
+check "flipped to bad signature: exit 1" "$rc" "1"
+check "flipped to bad signature: reason" "$out" "done=false reason=bad-signature"
+
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]

package/template/.claude/hooks/verify-signoff.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env sh
+# verify-signoff — check that a work unit's completion is backed by a valid,
+# SSH-signed sign-off tag. Implements the Contract M0 sign-off convention
+# (docs/sign-off-convention.md): "done" for a work unit is true iff this
+# script exits 0 for that work unit's id. No YAML `human_verified` field is
+# the source of truth — a stored copy of that value is a derived echo only.
+#
+# Convention: the sign-off is an SSH-signed annotated tag `signoff/<wu-id>` at
+# the landed commit, message body:
+#   wu: <wu-id>
+#   head: <full-sha>
+#   evidence: <evidence-set-hash>
+# Minted by the operator (or a process holding the operator's signing key),
+# never from an agent context:
+#   git -c gpg.format=ssh -c user.signingkey=<operator key> \
+#     tag -s signoff/<wu-id> -m "wu: <wu-id>\nhead: <sha>\nevidence: <hash>"
+#
+#   verify-signoff.sh <wu-id> [--head <sha>] [--evidence <hash>]
+#                             [--evidence-file <path>] [--allowed-signers <path>]
+#
+#     --head <sha>            expected landed commit. Default: `git rev-parse HEAD`.
+#     --evidence <hash>       expected evidence-set hash, compared verbatim.
+#     --evidence-file <path>  compute the expected hash as `sha256(path)` instead
+#                             of passing it directly. Exactly one of --evidence /
+#                             --evidence-file is required.
+#     --allowed-signers <path>  SSH allowed-signers file. Default:
+#                             `git config --get gpg.ssh.allowedSignersFile`.
+#
+# stdout on success: `ok`. stdout on failure: `reason=<code>` (machine-parseable;
+# nothing else on stdout). Human-readable detail always goes to stderr.
+#
+# Exit codes:
+#   0  signed, verified, and matching — the work unit is done.
+#   1  a verification check failed; stdout carries the reason code:
+#        no-signoff        no signoff/<wu-id> tag exists
+#        bad-signature     tag exists but signature is missing/unknown/invalid
+#        stale             tag's `head:` does not match the expected commit
+#        evidence-mismatch tag's `evidence:` does not match the expected hash
+#   2  bad invocation (missing wu-id, missing evidence input, bad flag) — no
+#      verification was attempted.
+#
+# Portable: no network calls; only git (must support `gpg.format=ssh`, i.e.
+# git >= 2.34) plus standard POSIX utilities (awk/sed/grep) and shasum/sha256sum
+# for --evidence-file. Works with no remote at all — the tag is local git state.
+set -eu
+
+usage() {
+  printf 'usage: verify-signoff.sh <wu-id> [--head <sha>] [--evidence <hash> | --evidence-file <path>] [--allowed-signers <path>]\n' >&2
+  exit 2
+}
+
+wu_id=""
+head_arg=""
+evidence_arg=""
+evidence_file=""
+allowed_signers=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --head) shift; head_arg="${1:-}"; [ $# -gt 0 ] && shift || usage ;;
+    --head=*) head_arg="${1#*=}"; shift ;;
+    --evidence) shift; evidence_arg="${1:-}"; [ $# -gt 0 ] && shift || usage ;;
+    --evidence=*) evidence_arg="${1#*=}"; shift ;;
+    --evidence-file) shift; evidence_file="${1:-}"; [ $# -gt 0 ] && shift || usage ;;
+    --evidence-file=*) evidence_file="${1#*=}"; shift ;;
+    --allowed-signers) shift; allowed_signers="${1:-}"; [ $# -gt 0 ] && shift || usage ;;
+    --allowed-signers=*) allowed_signers="${1#*=}"; shift ;;
+    -*) printf 'verify-signoff: unknown option: %s\n' "$1" >&2; usage ;;
+    *)
+      if [ -z "$wu_id" ]; then wu_id="$1"; shift
+      else printf 'verify-signoff: unexpected argument: %s\n' "$1" >&2; usage; fi
+      ;;
+  esac
+done
+
+[ -n "$wu_id" ] || usage
+if [ -n "$evidence_arg" ] && [ -n "$evidence_file" ]; then
+  printf 'verify-signoff: pass exactly one of --evidence / --evidence-file, not both\n' >&2
+  exit 2
+fi
+if [ -z "$evidence_arg" ] && [ -z "$evidence_file" ]; then
+  printf 'verify-signoff: --evidence <hash> or --evidence-file <path> is required\n' >&2
+  exit 2
+fi
+
+[ -n "$head_arg" ] || head_arg="$(git rev-parse HEAD)"
+
+if [ -n "$evidence_file" ]; then
+  [ -f "$evidence_file" ] || { printf 'verify-signoff: evidence file not found: %s\n' "$evidence_file" >&2; exit 2; }
+  if command -v shasum >/dev/null 2>&1; then
+    evidence_arg="$(shasum -a 256 "$evidence_file" | awk '{print $1}')"
+  elif command -v sha256sum >/dev/null 2>&1; then
+    evidence_arg="$(sha256sum "$evidence_file" | awk '{print $1}')"
+  else
+    printf 'verify-signoff: need shasum or sha256sum to hash --evidence-file\n' >&2
+    exit 2
+  fi
+fi
+
+if [ -z "$allowed_signers" ]; then
+  allowed_signers="$(git config --get gpg.ssh.allowedSignersFile || true)"
+fi
+[ -n "$allowed_signers" ] || { printf 'verify-signoff: no --allowed-signers given and gpg.ssh.allowedSignersFile is unset\n' >&2; exit 2; }
+[ -f "$allowed_signers" ] || { printf 'verify-signoff: allowed-signers file not found: %s\n' "$allowed_signers" >&2; exit 2; }
+
+tag_ref="refs/tags/signoff/$wu_id"
+
+fail() { # reason
+  printf 'reason=%s\n' "$1"
+  printf 'verify-signoff: FAIL (%s) for %s\n' "$1" "$wu_id" >&2
+  exit 1
+}
+
+# --- 1. resolve the tag ------------------------------------------------------
+git rev-parse -q --verify "$tag_ref" >/dev/null 2>&1 || fail no-signoff
+
+# --- 2. verify the SSH signature (self-contained: pass format + signers file
+# explicitly so this doesn't depend on the caller's git config, e.g. a scrubbed
+# worker environment that has no signing key but must still be ABLE to verify).
+if ! git -c gpg.format=ssh -c "gpg.ssh.allowedSignersFile=$allowed_signers" \
+      tag -v "signoff/$wu_id" >/dev/null 2>&1; then
+  fail bad-signature
+fi
+
+# --- 3. parse the message body and compare head:/evidence: ------------------
+# Raw tag object: headers, blank line, message, then (for a signed tag) an
+# embedded "-----BEGIN SSH SIGNATURE-----" block appended after the message.
+# Strip headers up to the first blank line, then stop at the signature marker.
+msg="$(git cat-file -p "$tag_ref" | awk 'f{ if ($0 ~ /-----BEGIN SSH SIGNATURE-----/) exit; print } /^$/{ f=1 }')"
+
+tag_head="$(printf '%s\n' "$msg" | sed -n 's/^head: *//p' | head -1)"
+tag_evidence="$(printf '%s\n' "$msg" | sed -n 's/^evidence: *//p' | head -1)"
+
+[ "$tag_head" = "$head_arg" ] || fail stale
+[ "$tag_evidence" = "$evidence_arg" ] || fail evidence-mismatch
+
+# --- 4. all checks passed -----------------------------------------------------
+printf 'ok\n'
+exit 0

package/template/.claude/hooks/wu-done.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env sh
+# wu-done — minimal fold stub wiring the `done` predicate to verify-signoff.
+#
+# Contract M0 (D2): "Wherever the program's fold computes work-unit state,
+# `done` is true iff `verify-signoff <wu-id>` exits 0." Forge's own repo has
+# no executable fold (workflow state is derived by the verifying/reviewing
+# SKILLs, not by a code module) — this script IS the fold, scoped to exactly
+# this predicate. A project with a real fold (e.g. pi-forge's package/stream
+# state) wires its own `done` computation to `verify-signoff.sh` the same way
+# this script does; it does not need to shell out to this file specifically.
+#
+# See docs/sign-off-convention.md. `current.human_verified` in a milestone
+# state file is a DERIVED ECHO of this predicate for human readability — it
+# is never the source of truth, and this script never reads or writes it.
+#
+#   wu-done.sh <wu-id> [same flags as verify-signoff.sh]
+#
+# stdout: `done=true` or `done=false reason=<code>`. Exit 0 iff done=true —
+# same convention as verify-signoff.sh, so `wu-done.sh <id> && ...` composes.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+VERIFY="$SCRIPT_DIR/verify-signoff.sh"
+
+[ $# -ge 1 ] || { printf 'usage: wu-done.sh <wu-id> [verify-signoff flags]\n' >&2; exit 2; }
+
+# Only stdout is captured (the reason= line); verify-signoff's stderr detail
+# flows straight through to our own stderr so a bad-invocation usage message
+# is never swallowed. The `if` guards the assignment from `set -e` — under
+# errexit a bare `out=$(...); rc=$?` would abort THIS script the instant
+# verify-signoff exits non-zero, before rc=$? ever ran.
+if out="$("$VERIFY" "$@")"; then rc=0; else rc=$?; fi
+
+if [ "$rc" -eq 0 ]; then
+  printf 'done=true\n'
+  exit 0
+fi
+
+if [ "$rc" -eq 1 ]; then
+  printf 'done=false %s\n' "$out"
+  exit 1
+fi
+
+# rc 2 (or anything else): bad invocation, not a verification verdict — the
+# fold could not even ask the question, so it must not report false as if it
+# had. verify-signoff already printed the usage error to stderr; just
+# propagate the same exit code.
+exit "$rc"

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

@@ -86,9 +86,17 @@ linked milestone, emit `stream: implicit` coverage rows, derive `merge_queue` fr
 hand-edit `active.yml`. Beyond that deterministic write, the Chief adds two
 **interactive** steps the boot-time rollup omits:
 
-- **Deferred/complete linked milestone** → when a stream's `stream.milestone`
-  points at a `deferred`/`complete` milestone, surface it: the stream should
-  likely pause — offer it.
+- **Complete linked milestone → auto-close (not a prompt).** The rollup's **step
+  0 sweep** (FORGE.md → Stream Rollup) already ran: a stream whose
+  `stream.milestone` is `complete`, that is not already `closed`, with no live
+  worktree, was auto-closed to `status: closed` / `merge.readiness: merged` before
+  the join — so it never reaches Merge Cadence as a false "ready to merge". Just
+  report it: *"auto-closed stale stream {id} — milestone m-{id} complete, on main."*
+  (A `complete` milestone that still has a live worktree is left for forge-boot's
+  finalize path.)
+- **Deferred linked milestone** → when a stream's `stream.milestone` points at a
+  `deferred` milestone, surface it: the stream should likely **pause** (not close —
+  the milestone can resume) — offer it.
 - **Implicit row needs coordination** → when an active milestone has no stream
   file (the rollup emits a `stream: implicit` row for coverage), offer to
   materialize a stream file for it. **Never auto-create.**

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

@@ -10,19 +10,21 @@ Read-only. Surface all deferred work across three storage surfaces so user need
 
 Three surfaces:
 
-1. **Milestones** — `.forge/state/index.yml` entries with `status: deferred`. Strategic punts (whole milestone frozen).
+1. **Milestones** — milestones whose derived `status` is `deferred` (from `.forge/state/milestone-*.yml`; `index.yml` is a render-on-read cache of the same). Strategic punts (whole milestone frozen).
 2. **Refactor backlog** — `.forge/refactor-backlog.yml` items with `status: deferred`. Code-quality punts.
 3. **Inside active milestones** — phase/task entries with `status: deferred` or `deferred: true` inside `.forge/state/milestone-*.yml`. Tactical punts within in-flight work.
 
 ## Step 1: Read three surfaces
 
-**Surface 1 — Deferred milestones.** Read `.forge/state/index.yml`. Collect every entry under `milestones:` where `status: deferred`. Pull `id`, `name`, `lifecycle.deferred_at` (if present at top level fall back to `last_updated`), `lifecycle.deferred_reason` (may live in the milestone state file — read `.forge/state/milestone-{id}.yml → lifecycle.deferred_at / deferred_reason` for accuracy).
+**Render-on-read (0.53.0).** `.forge/state/index.yml` is a **git-ignored derived cache**, not a committed file — it may be **absent** (fresh clone, no boot yet) or **stale**. Never read it as authoritative and never treat its absence as "not a Forge project". Derive each milestone's `id`/`name`/`status` from its source, `.forge/state/milestone-{id}.yml` (the same inputs the `forge` Rollup uses): `status` = `deferred` if `lifecycle.deferred_at` is set and not superseded by a later `resumed_at`, else `complete`/`not_started` from `current.status`, else `active`. (If `index.yml` is present and you trust it fresh, it is a valid fast-path — but the milestone files are the source of truth here.) The project sentinel is `.forge/project.yml` (below).
+
+**Surface 1 — Deferred milestones.** Glob `.forge/state/milestone-*.yml` (or read a fresh `.forge/state/index.yml` cache) and collect every milestone whose derived `status` is `deferred`. Pull `id`, `name`, `lifecycle.deferred_at` (fall back to `current.last_updated`), `lifecycle.deferred_reason` (read `.forge/state/milestone-{id}.yml → lifecycle.deferred_at / deferred_reason` for accuracy).
 
 **Surface 2 — Deferred refactor items.** Read `.forge/refactor-backlog.yml`. Collect every item with `status: deferred`. Pull `id` (e.g. R-007), `description` (first line, truncate ≤80 chars), `deferred_at`, `deferred_reason`.
 
 **Surface 3 — Deferred phases/tasks inside active milestones.** Glob `.forge/state/milestone-*.yml`. For each file:
 
-- Look up that milestone's status in `index.yml`.
+- Determine that milestone's derived status from its `milestone-{id}.yml` (`current.status` / `lifecycle`), not a possibly-absent `index.yml`.
 - **Only process if `status: active`.** Skip `complete` and `deferred` milestones.
 - *Why:* a deferred milestone's own `lifecycle.deferred_at` block is already counted by Surface 1. Including it here double-counts. Skipping `complete` avoids historical noise.
 - Within the file, find phase or task entries with `status: deferred` or `deferred: true`. Pull milestone id, phase/task name, `deferred_at`, `deferred_reason`.
@@ -71,7 +73,9 @@ Then exit.
 
 ## Graceful degradation
 
-- Missing `.forge/state/index.yml` → cannot proceed. Print `No forge state found in this project.` exit.
+- Missing `.forge/project.yml` → not a Forge project. Print `No forge state found in this project.` and exit. (Key the sentinel on `project.yml`, a committed file — **not** on `.forge/state/index.yml`, which since 0.53.0 is a git-ignored render-on-read cache and is legitimately absent on a fresh clone until the first `/forge` boot renders it.)
+- Missing/stale `.forge/state/index.yml` → it is a derived cache, not a source. Derive milestone statuses from `.forge/state/milestone-*.yml` directly (or run a `/forge` boot to render the cache). Never error on its absence.
+- No `.forge/state/milestone-*.yml` matches → Surface 1 renders `(none)`. Continue.
 - Missing `.forge/refactor-backlog.yml` → Surface 2 renders `(none)`. Continue.
 - No `milestone-*.yml` matches → Surface 3 renders `(none)`. Continue.
 - Malformed YAML in any source → skip that source, render `(unreadable)` beneath header, continue others.

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

@@ -20,6 +20,7 @@ Structured conversation: approach, trade-offs, decisions. Clarity, not artifacts
 - No plans or code
 - Writes `context.md` progressively (after each confirmed decision, not just at handoff)
 - No phase/plan required
+- Entered via a worktree already, for new work (R10, `forge/SKILL.md` Step 3) — if this skill is somehow invoked directly on the main checkout for new work, enter one now before writing anything.
 
 ## Progressive Persistence
 
@@ -307,8 +308,9 @@ If no milestone exists (advisory discussion — forge routed here without tier/m
    - Multi-file, refactor, feature, service changes → **Standard**
    - Major architectural, multi-subsystem, multi-phase → **Full**
 3. **Create milestone.**
-   - Next ID = (max id across existing `.forge/state/milestone-*.yml`) + 1 (or 1 if none)
-   - Create `milestone-{id}.yml` from `.forge/templates/state/milestone.yml`:
+   - Allocate the milestone id via `id=$(.claude/hooks/forge-reserve.sh milestone --milestone m-new)` (ADR-023) — never scan `milestone-*.yml` for max+1 inline (collides across concurrent worktrees; the helper is ledger-backed and scans live + archived milestones).
+   - **Write the declaration** (R10/B3' — FORGE.md → Stream Integration Checkpoints, "Producer — publish at intake") — **Standard/Full only; SKIP for Quick** (a quick fix registers no stream, matching context.md M28; it routes to quick-tasking at step 5): copy `.forge/templates/streams/stream.yml` → `.forge/streams/{stream}.yml`, populate `stream.id`, `stream.goal` (one-line summary of the discussion topic), `stream.milestone: m-{id}`, `stream.status: draft`, `stream.tier` = detected tier, `runtime.branch`/`runtime.worktree` from the worktree in use, best-known `ownership.owned_surfaces`/`shared_surfaces` (coarse is fine — claims may go stale as scope evolves; amend later). Commit it — this should be the worktree's first commit if `forge` boot's R10 step already entered one; if this skill is somehow reached before that (direct invoke), enter the worktree now, then commit the declaration. Fast-forward-push it per the FORGE.md mechanic just referenced — do not re-explain the git plumbing here.
+   - Create `milestone-{id}.yml` from `.forge/templates/state/milestone.yml` — **worktree-only from here, landing at this milestone's own checkpoint, not pushed immediately**:
      - `milestone.id` = {id}, `milestone.name` = brief summary of discussion topic
      - `current.tier` = detected tier
      - `current.status` = `planning` (Standard) / `architecting` (Full) / `not_started` (Quick)

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

@@ -36,9 +36,9 @@ Run **before the first task begins**. Makes failure causality mechanical — no
 1. Run all non-advisory verification commands
 2. Record which tests/checks pass and which fail — this is the baseline
 3. After each commit: failures **not in baseline** = introduced by this task = **must fix under Rule 3**
-4. Failures **present in baseline** = pre-existing → append to `.forge/deferred-issues.md`, mark `status: pending`
+4. Failures **present in baseline** = pre-existing → log a file under `.forge/deferred-issues/`, `status: pending` (see Deferred Issues Format)
 
-Skip only if re-entering an in-progress execution and `deferred-issues.md` already documents all current failures.
+Skip only if re-entering an in-progress execution and `.forge/deferred-issues/` (or legacy `deferred-issues.md`) already documents all current failures.
 
 ## Plan Anchor Re-Derivation
 
@@ -63,7 +63,7 @@ Execution-phase operational guidance below supplements the rules — it does not
 3 auto-fix attempts on a single task → STOP. Document remaining issues. Move to next task.
 
 ### Scope Boundary
-Only fix issues DIRECTLY caused by the current task. Pre-existing warnings, tech debt, unrelated bugs → log to `.forge/deferred-issues.md`.
+Only fix issues DIRECTLY caused by the current task. Pre-existing warnings, tech debt, unrelated bugs → log a file under `.forge/deferred-issues/`.
 
 ### Slice Integrity (Execution-Side)
 
@@ -203,14 +203,14 @@ For each command, in order:
 Attempt 1:
   1. Read error output
   2. In baseline snapshot?
-     - YES (pre-existing) → mark advisory for this session; append to .forge/deferred-issues.md; continue
+     - YES (pre-existing) → mark advisory for this session; log a file under .forge/deferred-issues/; continue
      - NO (introduced by this task) → fix code, stage fixes, amend commit
   3. Re-run command
   4. Pass → next command
   5. Fail → next attempt (up to max_retries)
 
 After max_retries exhausted:
-  → Append to .forge/deferred-issues.md
+  → Log a file under .forge/deferred-issues/
   → Log failure in execution summary
   → Continue to next task
 ```
@@ -219,26 +219,30 @@ After max_retries exhausted:
 Verification retries count toward the task's 3-strike limit. 2 strikes used = 1 verification retry max.
 
 ### Do NOT Fix
-- **Pre-existing failures** present in baseline snapshot → mark advisory; append to `.forge/deferred-issues.md`
+- **Pre-existing failures** present in baseline snapshot → mark advisory; log a file under `.forge/deferred-issues/`
 - **Flaky tests** passing on re-run without changes → note in summary, no strike
 - **Unrelated warnings** (deprecation, non-blocking lint) → ignore
 
 ### Deferred Issues Format
 
-Append one entry per failure to `.forge/deferred-issues.md` (create if missing):
+**One file per failure** (ADR-023 — no DI-NNN counter). Copy `.forge/templates/deferred-issue.md`
+→ `.forge/deferred-issues/{YYYY-MM-DD}-{milestone}-{slug}.md`, where `{slug}` is a short kebab of
+the failure (e.g. `redis-unavailable`). Distinct filenames mean concurrent worktrees never collide —
+the same anti-collision property as `.forge/state/desire-paths/`.
 
 ```yaml
-issues:
-  - id: DI-001
-    type: test_failure | lint_failure | build_failure
-    command: "npm test"
-    summary: "HealthEndpointTest — Redis unavailable in test env"
-    first_seen: "2026-04-14"
-    milestone: "m3"
-    status: pending
+# .forge/deferred-issues/2026-04-14-m3-redis-unavailable.md
+type: test_failure          # test_failure | lint_failure | build_failure
+command: "npm test"
+summary: "HealthEndpointTest — Redis unavailable in test env"
+first_seen: "2026-04-14"
+milestone: "m3"
+status: pending
 ```
 
-ID = `DI-{N}` where N = next integer after existing max (or 001 if new file).
+**Legacy read (lazy migration):** if `.forge/deferred-issues/` is absent, the old single-file
+`.forge/deferred-issues.md` (DI-NNN `issues[]` entries) is still read — no data loss before migration.
+Never allocate a DI-NNN number; the filename slug is the id.
 
 ### Quick Tier
 Run all non-advisory verification commands once after commit. 1 retry max.
@@ -307,7 +311,7 @@ After completing all tasks in a plan:
 
 ## Notes
 [Genuine handoff context only: environment requirements, seed data, external services needed (e.g. "Redis must be running for auth tests").
-Do NOT list test failures here — pre-existing failures belong in deferred-issues.md; task-introduced failures must be fixed before committing.]
+Do NOT list test failures here — pre-existing failures belong in `.forge/deferred-issues/`; task-introduced failures must be fixed before committing.]
 ```
 
 ## State Updates

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

@@ -65,13 +65,13 @@ 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. `active.yml` is derived — never read it as authoritative without rolling up first, and never hand-edit it. Runs in the main checkout (worktrees never write `active.yml`). No `streams/` dir → skip.
+**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.
 
-**Ready-to-merge nudge (main checkout / streams without checkpoints).** From the just-regenerated `active.yml`, scan for streams with `coordination: ready` or a non-empty `merge_queue` **that are not auto-publishing via checkpoints**. Any present → one line: *"{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.
+**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)
 
-`index.yml` is a **derived registry** — regenerate it from the milestone files before reading, and after any milestone CRUD (promote/defer/resume/delete). **Never hand-edit `index.yml`.**
+`index.yml` is a **derived registry** — regenerate it from the milestone files 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).
 
 Rollup procedure (deterministic + idempotent):
 1. Glob `.forge/state/milestone-*.yml`.
@@ -176,16 +176,17 @@ Check `.forge/refactor-backlog.yml`:
 **Promotion procedure (effort: standard only):**
 
 1. Read backlog item `id` (e.g. `R61-002`). Synthesize milestone id `m-{R-id}` (e.g. `m-R61-002`).
-2. Copy `.forge/templates/state/milestone.yml` → `.forge/state/milestone-{m-R-id}.yml`. Populate:
+2. **Enter the worktree first (R10 — this runs in Step 1, *before* Step 3's routing gate fires, so do not assume a worktree already exists):** if this session is still on the main checkout (`git rev-parse --git-dir` == `--git-common-dir`), `EnterWorktree` now; if R10 already entered one, this is simply the first write in it. Then write the declaration (`.forge/templates/streams/stream.yml` → `.forge/streams/{stream}.yml` — `stream.goal`, `stream.milestone: m-{R-id}`, `stream.status: draft`, `stream.tier: standard`, `runtime.branch`/`runtime.worktree` from the worktree just entered, best-known `ownership.owned_surfaces`/`shared_surfaces`) as the worktree's first commit and fast-forward-push it, per FORGE.md's Stream Integration Checkpoints intake-declaration trigger.
+3. Copy `.forge/templates/state/milestone.yml` → `.forge/state/milestone-{m-R-id}.yml`. Populate:
    - `milestone.id: m-{R-id}`
    - `milestone.name: "Promoted from {R-id}: {backlog item title}"`
    - `milestone.origin: {R-id}`
    - `current.tier: standard`, `current.status: researching`
    - `current.last_updated: {ISO date}`
-3. Run **Rollup (1.0)** — regenerates `index.yml` from the new milestone file (do not hand-append the registry entry). New milestone id is `m-{R-id}` from step 1; for numeric ids, allocate by scanning existing `milestone-*.yml` for the max id + 1.
-4. Append to `.forge/roadmap.yml` — one milestone entry + one phase (`refactor-{R-id}`, `requirements_source: refactor-backlog.yml#{R-id}`, `dependencies: []`).
-5. Update `.forge/refactor-backlog.yml` item: `status: in_progress`, add `promoted_to: m-{R-id}`.
-6. Confirm: *"Promoted {R-id} → milestone m-{R-id}. State + roadmap created. Routing to researching."*
+4. Run **Rollup (1.0)** — regenerates `index.yml` from the new milestone file (do not hand-append the registry entry). New milestone id is `m-{R-id}` from step 1; for numeric ids, allocate via `id=$(.claude/hooks/forge-reserve.sh milestone --milestone m-new)` (ADR-023) — never scan `milestone-*.yml` for max+1 inline. The three milestone-id call sites (here, `discussing`, `prototyping`) share this ledger-backed allocator so they cannot disagree, and it scans live **+ archived** milestones so a burned id is never reused.
+5. Append to `.forge/roadmap.yml` — one milestone entry + one phase (`refactor-{R-id}`, `requirements_source: refactor-backlog.yml#{R-id}`, `dependencies: []`).
+6. Update `.forge/refactor-backlog.yml` item: `status: in_progress`, add `promoted_to: m-{R-id}`.
+7. Confirm: *"Promoted {R-id} → milestone m-{R-id}. State + roadmap created. Routing to researching."*
 
 ```text
 backlog pickup → effort: standard
@@ -357,6 +358,8 @@ Tier + state → invoke via `Skill` tool. All phases use `Skill()`.
 
 **CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
+**CRITICAL: New work enters its worktree before anything else (R10).** When routing genuinely NEW work — `current.status: not_started` about to detect tier and start, or any session about to invoke `researching`/`discussing`/`planning`/`quick-tasking`/`prototyping` for a request that has no milestone yet — call `EnterWorktree` (Worktree Convention, FORGE.md) BEFORE invoking that skill. The main checkout is for orchestration and reads. Applies to every tier, including Quick and Prototyping: one `EnterWorktree` call, no heavier ceremony — a Quick fix or a disposable mockup gets a worktree but no milestone/stream declaration (nothing is being registered until, for a prototype, it graduates). A mockup is disposable but not weightless — it writes flag-gated app code + a prototype state file the team shares and may fold into a feature-toggled section — so its initial entry is worktree-first like the rest. Earlier practice held off on worktree isolation until implementation began, on the theory that research/discussion/planning don't touch code — that theory doesn't hold: discussing/planning/researching write `.forge` state too (context.md, plans, research notes), and per P17 those writes left untracked droppings on main that broke other worktrees' landings. No phase may hold off on worktree entry for new work. Milestone/stream intake itself is a deliberate exception with its own mechanic — see FORGE.md → Stream Integration Checkpoints for the declaration/content split (B3'). Pure read-only sessions that start no work need no worktree. This governs the FIRST write of new work; resuming an in-flight milestone already routes through the Live-Worktree Ownership Gate (1.1a) / branch-anchor path (Step 1.1) instead.
+
 **Experimental — M10 orchestration backend.** Chief/Streams is the preferred
 user-facing orchestration model. M10 remains an optional backend for streams
 that need worktree isolation, merge-queue discipline, or experimental file
@@ -364,7 +367,7 @@ claims. Route through `Skill(orchestrating)` first when **all** hold:
 - **Selected:** Project Chief chooses M10 for a stream, user explicitly asks for multi-agent/worktree mode, or legacy `orchestration.auto` is enabled.
 - **Installed:** `.claude/skills/orchestrating/` present + `forge-orchestrator` in `.mcp.json` + `.claude/hooks/forge-claim-check.sh` present.
 - **Not opted out:** `orchestration.auto` in `project.yml` ≠ `false` for legacy auto-routing; explicit Project Chief selection can still use M10 when installed.
-- **Tier is Standard or Full.** Quick never auto-orchestrates (a worktree per typo is the wrong trade).
+- **Tier is Standard or Full.** Quick never auto-orchestrates — the *orchestration backend* (MCP file-claims, merge queue, bootstrap) is the wrong trade for a typo. (The plain worktree is not the cost: per R10 a Quick fix already runs in one — `EnterWorktree` is ~instant. What Quick skips here is the M10 machinery on top, not the worktree.)
 - **Not already in a session:** active milestone has no `lifecycle.worktree_mode: active|degraded` (don't re-bootstrap inside a live session).
 
 `orchestrating` bootstrap stays the safety net — incompatible repo → it refuses, writes `worktree_mode: refused`, and `forge` continues single-agent. Absent install → standard routing. Manual `Skill(orchestrating)` still works for explicit backend control; set `orchestration.auto: false` in `project.yml` to opt out of legacy auto-routing.
@@ -411,7 +414,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 
 | `current.status` | Route To |
 |-------------------|----------|
-| `not_started` | Detect tier, start |
+| `not_started` | EnterWorktree (R10), then detect tier, start |
 | `researching` | `Skill(researching)` → discussing |
 | `discussing` | `Skill(discussing)` → planning (or architecting if Full) |
 | `architecting` | `Skill(architecting)` → planning |