forge-orkes 0.49.0 → 0.53.0

package/package.json

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

@@ -51,8 +51,10 @@ case "$kind" in
   def) prefix="DEF" ;;
   fr)  prefix="FR" ;;
   nfr) prefix="NFR" ;;
-  "") printf 'forge-reserve: missing kind (adr|def|fr|nfr)\n' >&2; exit 2 ;;
-  *) printf 'forge-reserve: unknown kind: %s (expected adr|def|fr|nfr)\n' "$kind" >&2; exit 2 ;;
+  milestone) prefix="M" ;;      # ADR-023 — unpadded (M-26); ids used bare across the framework
+  refactor)  prefix="R" ;;      # ADR-023 — zero-padded R0NN, matching the backlog format
+  "") printf 'forge-reserve: missing kind (adr|def|fr|nfr|milestone|refactor)\n' >&2; exit 2 ;;
+  *) printf 'forge-reserve: unknown kind: %s (expected adr|def|fr|nfr|milestone|refactor)\n' "$kind" >&2; exit 2 ;;
 esac
 [ -n "$milestone" ] || { printf 'forge-reserve: --milestone <id> is required\n' >&2; exit 2; }
 
@@ -99,33 +101,67 @@ trap 'rmdir "$lock" 2>/dev/null || true' EXIT INT TERM
 # Everything numeric goes through awk (n+0) so leading-zero ids like 021 are read
 # as decimal 21, never octal — no shell $(( )) octal trap.
 
-# (a) ledger — same-machine siblings, INCLUDING uncommitted (the ADR-016-blind input)
+# (a) ledger — same-machine siblings, INCLUDING uncommitted (the ADR-016-blind input).
+# Extract the trailing number by stripping non-digits, NOT by split on "-": refactor
+# ids (R100) carry no hyphen (ADR-023), so a hyphen-split would read them as 0 and
+# reallocate a live id. gsub handles ADR-014, M-26, R100, FR-023 uniformly.
 ledger_max=0
 if [ -f "$ledger" ]; then
   ledger_max="$(awk -F'\t' -v k="$kind" \
-    '$1==k { split($2,a,"-"); n=a[2]+0; if(n>m)m=n } END{print m+0}' "$ledger")"
+    '$1==k { x=$2; gsub(/[^0-9]/,"",x); n=x+0; if(n>m)m=n } END{print m+0}' "$ledger")"
 fi
 
 # (b) in-tree — landed ids in THIS worktree. Exact-prefix match in awk ($1==p) so
-# FR does not swallow NFR (FR is a substring of NFR).
-if [ "$kind" = "adr" ]; then
-  intree_max="$(ls "$top/docs/decisions" 2>/dev/null \
-    | awk -F- '/^ADR-[0-9]/ { n=$2+0; if(n>m)m=n } END{print m+0}')"
-else
-  intree_max="$(grep -rhoE '[A-Z]+-[0-9]+' "$top/.forge/requirements/" 2>/dev/null \
-    | awk -F- -v p="$prefix" '$1==p { n=$2+0; if(n>m)m=n } END{print m+0}')"
-fi
+# FR does not swallow NFR (FR is a substring of NFR). milestone + refactor (ADR-023)
+# each scan BOTH live and archive locations so a burned id is never reallocated.
+case "$kind" in
+  adr)
+    intree_max="$(ls "$top/docs/decisions" 2>/dev/null \
+      | awk -F- '/^ADR-[0-9]/ { n=$2+0; if(n>m)m=n } END{print m+0}')"
+    ;;
+  milestone)
+    # live state/milestone-<N>.yml  ∪  archived .forge/archive/milestone-<N>/
+    intree_max="$( { ls "$top/.forge/state"/milestone-*.yml 2>/dev/null; \
+                     ls -d "$top/.forge/archive"/milestone-*/ 2>/dev/null; } \
+      | grep -oE 'milestone-[0-9]+' \
+      | awk -F- '{ n=$2+0; if(n>m)m=n } END{print m+0}')"
+    ;;
+  refactor)
+    # live refactor-backlog.yml  ∪  refactor-backlog-archive.yml
+    intree_max="$(grep -hoE 'R[0-9]+' \
+        "$top/.forge/refactor-backlog.yml" \
+        "$top/.forge/refactor-backlog-archive.yml" 2>/dev/null \
+      | awk '{ n=substr($0,2)+0; if(n>m)m=n } END{print m+0}')"
+    ;;
+  *)
+    intree_max="$(grep -rhoE '[A-Z]+-[0-9]+' "$top/.forge/requirements/" 2>/dev/null \
+      | awk -F- -v p="$prefix" '$1==p { n=$2+0; if(n>m)m=n } END{print m+0}')"
+    ;;
+esac
 
 # (c) main:reservations.yml — cross-machine / cold-start floor (survives a
 # .git/forge wipe; carries another machine's MERGED reservations). Absent → 0.
+# 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 -F- -v p="$prefix" '$1==p { n=$2+0; if(n>m)m=n } END{print m+0}')"
+  | 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}')"
 [ -n "$main_max" ] || main_max=0
 
 next="$(awk -v a="$ledger_max" -v b="$intree_max" -v c="$main_max" \
   'BEGIN{m=a; if(b>m)m=b; if(c>m)m=c; print m+1}')"
-id="$(printf '%s-%03d' "$prefix" "$next")"
+# Per-kind id format (ADR-023). The prefix-hyphen-paddednumber form (ADR-021's
+# ADR-014, FR-023) is NOT universal:
+#   milestone → M-26  : hyphen, UNPADDED — ids are used bare (milestone-26.yml, m-26)
+#   refactor  → R064  : NO hyphen, zero-padded 3-wide — matches the backlog convention
+#   adr/def/fr/nfr → ADR-014 : hyphen, zero-padded 3-wide (unchanged)
+case "$kind" in
+  milestone) id="$(printf '%s-%d' "$prefix" "$next")" ;;
+  refactor)  id="$(printf '%s%03d' "$prefix" "$next")" ;;
+  *)         id="$(printf '%s-%03d' "$prefix" "$next")" ;;
+esac
 
 # --- 6. dual-write (still under the lock) -----------------------------------
 now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

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.**
@@ -200,7 +208,11 @@ Resume:
 1. Run the Stream Rollup, then load the stream file and brief.
 2. Surface status, blockers, owned surfaces, shared surfaces, and next action.
 3. Set the **stream file's** `status` to `active`, then regenerate `active.yml`.
-4. Run conflict detection before continuing.
+4. **Relocate into the stream worktree (Native Worktree Entry).** When the resumed stream's file records a `runtime.worktree`, apply the canonical Native Worktree Entry contract (identical to the forge ownership-gate option 1):
+   - **If the `EnterWorktree` tool is available**, call `EnterWorktree({path: {runtime.worktree}})` to relocate this session into the stream worktree **in place**, then log `Relocated into worktree {runtime.worktree} ({runtime.branch})` (independent of any prompt, so the cwd move is visible) and continue the resume from inside the worktree.
+   - **If `EnterWorktree` is unavailable** (older Claude Code CLI, or a non-Claude-Code adapter), fall back to printing the `cd {path}` instruction (here `cd {runtime.worktree}`) — today's implicit behavior made explicit.
+   - Streams with no `runtime.worktree` resume unchanged — no relocation attempted. Exit is always `ExitWorktree({action: "keep"})`; the Chief never lets the native tool remove a worktree (teardown/merge stays the Chief's existing flow).
+5. Run conflict detection before continuing.
 
 ## Delegate Flow
 

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)