forge-orkes 0.44.0 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.44.0",
+  "version": "0.49.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/agents/verifier.md

@@ -24,9 +24,9 @@ Plan+must_haves (`.forge/phases/milestone-{id}/{phase}-{name}/plan.md`), executi
 **Status**: PASS | FAIL | PARTIAL
 
 ## Observable Truths
-| Truth | Status | Evidence |
-|-------|--------|----------|
-| {from must_haves} | PASS/FAIL | {observed} |
+| Truth | Evidence (command → exit code; output excerpt) | Status |
+|-------|-----------------------------------------------|--------|
+| {from must_haves} | {executed command} → {exit}; {excerpt} | PASS/FAIL/UNCERTAIN/HUMAN |
 
 ## Artifacts
 | Artifact | Exists | Substantive | Wired | Evidence |
@@ -64,7 +64,10 @@ Read: .forge/deferred-issues.md → known pre-existing failures (if exists; trea
 ```
 
 ### 2. Truths
-Per truth: determine method, execute, record PASS+evidence or FAIL+actual.
+Per truth, three branches (executed-evidence rule — canonical statement: verifying SKILL Level 1):
+1. Declared `check:` in must_haves → EXECUTE it. Exit 0 = PASS, non-zero = FAIL. Record command + exit code + output excerpt.
+2. No declared check → run your OWN command and record the same evidence triple — executed evidence qualifies regardless of plan vintage.
+3. No executed evidence → UNCERTAIN, or HUMAN for `manual:`-routed truths (never execute the route text as shell). **Never PASS on judgment alone** — the exit code, not your assessment, is the verdict.
 
 ### 3. Artifacts
 Per artifact:
@@ -138,6 +141,7 @@ gaps:
 
 ## Anti-Patterns
 - **Fix-while-verifying**: Report, don't fix
+- **Evidence-free PASS**: No executed command recorded → verdict must be UNCERTAIN, never PASS
 - **Surface-level**: Exists != substantive
 - **Skip wired**: Code exists but unused
 - **Trust count**: Passing != correct coverage

package/template/.claude/hooks/forge-model-outcome.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env sh
+# forge-model-outcome — advisory per-task model-routing outcome log + promotion
+# ladder (M24 phases 37-38).
+#
+#   forge-model-outcome.sh record [--repo R] [--milestone M] [--skill S]
+#     [--task-type T] [--complexity C] [--model MO] [--first-try-pass true|false]
+#     [--check-exit N]
+#
+# Appends ONE printf-built JSON line to ${FORGE_HOME:-$HOME}/.forge/model-outcomes.jsonl
+# (honors $HOME so tests can redirect it). Lazily creates the dir + file.
+#
+# ADVISORY, always: any failure (unwritable home, etc.) is swallowed and this
+# helper still exits 0 — logging must never block or fail a task. The write
+# path is dependency-free (printf only, no jq/python — NFR-026).
+#
+#   forge-model-outcome.sh recommend
+#
+# Reads the log and prints an untested -> probation -> proven promotion ladder
+# per (model, task_type), plus concrete routing recommendations for proven
+# buckets. The READ path may use jq (unlike record's write path). Degrades to
+# an "insufficient data" message + exit 0 when jq is absent or the log is
+# absent/empty — never errors (NFR-026).
+#
+# Pinned field set (contract between record + recommend; keep names stable):
+#   ts repo milestone skill task_type complexity model first_try_pass check_exit
+set -u
+
+usage() {
+  cat <<'EOF' >&2
+usage: forge-model-outcome.sh record [--repo R] [--milestone M] [--skill S]
+         [--task-type T] [--complexity C] [--model MO] [--first-try-pass true|false]
+         [--check-exit N]
+       forge-model-outcome.sh recommend
+EOF
+}
+
+log_path() {
+  home="${FORGE_HOME:-$HOME}"
+  printf '%s/.forge/model-outcomes.jsonl' "$home"
+}
+
+do_record() {
+  # --- parse flags (ALL optional — missing -> empty string / null) ---------
+  repo=""; milestone=""; skill=""; task_type=""; complexity=""; model=""
+  first_try_pass=""; check_exit=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --repo) shift; repo="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --repo=*) repo="${1#*=}"; shift ;;
+      --milestone) shift; milestone="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --milestone=*) milestone="${1#*=}"; shift ;;
+      --skill) shift; skill="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --skill=*) skill="${1#*=}"; shift ;;
+      --task-type) shift; task_type="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --task-type=*) task_type="${1#*=}"; shift ;;
+      --complexity) shift; complexity="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --complexity=*) complexity="${1#*=}"; shift ;;
+      --model) shift; model="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --model=*) model="${1#*=}"; shift ;;
+      --first-try-pass) shift; first_try_pass="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --first-try-pass=*) first_try_pass="${1#*=}"; shift ;;
+      --check-exit) shift; check_exit="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --check-exit=*) check_exit="${1#*=}"; shift ;;
+      -*) printf 'forge-model-outcome: unknown option: %s (ignored)\n' "$1" >&2; shift ;;
+      *) shift ;;
+    esac
+  done
+
+  dir="$(dirname "$(log_path)")"
+  log="$(log_path)"
+
+  # Escape backslash then double-quote for a JSON string value — these are
+  # controlled enums/basenames, so this minimal escape is enough (no jq).
+  esc() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)"
+
+  fp="false"
+  case "$first_try_pass" in
+    true|1|yes) fp="true" ;;
+    *) fp="false" ;;
+  esac
+
+  ce="null"
+  case "$check_exit" in
+    ''|*[!0-9-]*) ce="null" ;;
+    *) ce="$check_exit" ;;
+  esac
+
+  line=$(printf '{"ts":"%s","repo":"%s","milestone":"%s","skill":"%s","task_type":"%s","complexity":"%s","model":"%s","first_try_pass":%s,"check_exit":%s}' \
+    "$(esc "$ts")" "$(esc "$repo")" "$(esc "$milestone")" "$(esc "$skill")" \
+    "$(esc "$task_type")" "$(esc "$complexity")" "$(esc "$model")" "$fp" "$ce")
+
+  # The whole create+append is best-effort: swallow any failure (unwritable
+  # home, read-only fs, a ".forge" that's a regular file, ...) and exit 0
+  # regardless — a task must never be blocked or failed by this log.
+  ( mkdir -p "$dir" && printf '%s\n' "$line" >> "$log" ) 2>/dev/null
+  exit 0
+}
+
+do_recommend() {
+  # Promotion-ladder thresholds (Ringer parity) — documented constants.
+  VOLUME_MIN=5          # count < VOLUME_MIN -> untested
+  PROVEN_CUTOFF=0.90    # count >= VOLUME_MIN and pass_rate >= PROVEN_CUTOFF -> proven; else probation
+
+  log="$(log_path)"
+
+  if ! command -v jq >/dev/null 2>&1; then
+    printf 'recommendations unavailable: jq not found (insufficient data)\n'
+    exit 0
+  fi
+  if [ ! -s "$log" ]; then
+    printf 'recommendations unavailable: no outcome data yet (insufficient data)\n'
+    exit 0
+  fi
+
+  buckets="$(jq -sc --argjson min "$VOLUME_MIN" --argjson cutoff "$PROVEN_CUTOFF" '
+    group_by([.model, .task_type])
+    | map(
+        {
+          model: .[0].model,
+          task_type: .[0].task_type,
+          count: length,
+          pass_rate: (([ .[] | select(.first_try_pass == true) ] | length) / length)
+        }
+        | . + {
+            status: (
+              if .count < $min then "untested"
+              elif .pass_rate >= $cutoff then "proven"
+              else "probation"
+              end
+            )
+          }
+      )
+    | .[]
+  ' "$log" 2>/dev/null)"
+
+  if [ -z "$buckets" ]; then
+    printf 'recommendations unavailable: no outcome data yet (insufficient data)\n'
+    exit 0
+  fi
+
+  cutoff_pct="$(awk -v c="$PROVEN_CUTOFF" 'BEGIN{printf "%.0f", c*100}')"
+  printf 'Model-outcome promotion ladder (volume >= %s runs, proven cutoff >= %s%% first-try):\n\n' "$VOLUME_MIN" "$cutoff_pct"
+
+  printf '%s\n' "$buckets" | while IFS= read -r b; do
+    model="$(printf '%s' "$b" | jq -r '.model')"
+    task_type="$(printf '%s' "$b" | jq -r '.task_type')"
+    count="$(printf '%s' "$b" | jq -r '.count')"
+    status="$(printf '%s' "$b" | jq -r '.status')"
+    pct="$(printf '%s' "$b" | jq -r '.pass_rate' | awk '{printf "%.0f", $1*100}')"
+    printf '  model=%-10s task_type=%-14s status=%-10s count=%-4s first-try=%s%%\n' "$model" "$task_type" "$status" "$count" "$pct"
+  done
+
+  printf '\nRouting recommendations:\n'
+  printf '%s\n' "$buckets" | while IFS= read -r b; do
+    status="$(printf '%s' "$b" | jq -r '.status')"
+    [ "$status" = "proven" ] || continue
+    model="$(printf '%s' "$b" | jq -r '.model')"
+    task_type="$(printf '%s' "$b" | jq -r '.task_type')"
+    count="$(printf '%s' "$b" | jq -r '.count')"
+    pct="$(printf '%s' "$b" | jq -r '.pass_rate' | awk '{printf "%.0f", $1*100}')"
+    printf '  %s is proven on %s tasks (%s runs, %s%% first-try) -> route %s tasks to %s\n' "$model" "$task_type" "$count" "$pct" "$task_type" "$model"
+  done
+
+  exit 0
+}
+
+cmd="${1:-}"
+[ $# -gt 0 ] && shift || true
+
+case "$cmd" in
+  record) do_record "$@" ;;
+  recommend) do_recommend ;;
+  ""|-h|--help) usage; exit 0 ;;
+  *) printf 'forge-model-outcome: unknown subcommand: %s\n' "$cmd" >&2; usage; exit 2 ;;
+esac

package/template/.claude/hooks/forge-reserve.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env sh
+# forge-reserve — allocate a collision-safe sequential id (ADR/DEF/FR/NFR).
+#
+# Implements ADR-021: the coordination point is a machine-local ledger in the
+# git COMMON dir (.git/forge/id-reservations), shared instantly across every
+# sibling worktree of the repo on this machine — the input ADR-016's
+# branch-tracked reservations.yml could not see. Same primitive as the
+# integration flag (.git/forge/integration-pending).
+#
+#   forge-reserve <kind> --milestone <id> [--summary <text>]
+#     kind ∈ {adr|def|fr|nfr}
+#
+# stdout: the allocated id and NOTHING else (e.g. ADR-022). All logs → stderr.
+# exit:   0 success; 2 bad/missing kind or args; 3 lock timeout. On non-zero
+#         exit nothing is written.
+#
+# Side effects (both UNcommitted — the caller commits reservations.yml with its
+# work): appends one TSV line to the common-dir ledger and one YAML block to the
+# worktree's .forge/reservations.yml, both under a portable mkdir lock.
+#
+# Pure POSIX sh — no bashisms, no flock (absent on macOS, ADR-021 point 3),
+# no node/python. Only git/mkdir/awk/grep/sed/date/stat.
+set -eu
+
+WAIT="${FORGE_RESERVE_WAIT:-5}"    # seconds: bounded lock-acquire budget
+STALE="${FORGE_RESERVE_STALE:-15}" # seconds: a lock older than this is broken
+SLEEP="0.1"                         # retry interval while the lock is held
+
+# --- 1. parse args ----------------------------------------------------------
+kind=""
+milestone=""
+summary=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --milestone) shift; milestone="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+    --milestone=*) milestone="${1#*=}"; shift ;;
+    --summary) shift; summary="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+    --summary=*) summary="${1#*=}"; shift ;;
+    -*) printf 'forge-reserve: unknown option: %s\n' "$1" >&2; exit 2 ;;
+    *)
+      if [ -z "$kind" ]; then kind="$1"; shift
+      else printf 'forge-reserve: unexpected argument: %s\n' "$1" >&2; exit 2; fi
+      ;;
+  esac
+done
+
+# Validate kind BEFORE touching git, the lock, or any file — a bad kind must
+# exit non-zero having written nothing (must_have truth #3).
+case "$kind" in
+  adr) prefix="ADR" ;;
+  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 ;;
+esac
+[ -n "$milestone" ] || { printf 'forge-reserve: --milestone <id> is required\n' >&2; exit 2; }
+
+# --- 2. resolve paths -------------------------------------------------------
+common="$(git rev-parse --git-common-dir)"
+top="$(git rev-parse --show-toplevel)"
+mkdir -p "$common/forge"
+ledger="$common/forge/id-reservations"
+lock="$common/forge/id-reservations.lock"
+reservations="$top/.forge/reservations.yml"
+
+# Portable mtime → epoch: BSD/macOS `stat -f %m`, GNU `stat -c %Y`. This is the
+# one place a platform branch is warranted (ADR-021 point 3: macOS is a
+# first-class platform and its stat flags differ from GNU's).
+get_mtime() {
+  stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null || true
+}
+
+# --- 3. acquire lock (atomic mkdir, bounded retry, staleness-break) ----------
+# mkdir is POSIX-atomic: it succeeds for exactly one racer and fails if the dir
+# already exists — a lock without flock. A crashed helper's lock is broken after
+# STALE seconds so it can't wedge the namespace forever.
+max_iters="$(awk -v w="$WAIT" -v s="$SLEEP" 'BEGIN{print int(w/s)}')"
+iters=0
+while ! mkdir "$lock" 2>/dev/null; do
+  mt="$(get_mtime "$lock")"
+  now_epoch="$(date +%s)"
+  if [ -n "$mt" ] && [ "$((now_epoch - mt))" -ge "$STALE" ]; then
+    printf 'forge-reserve: breaking stale lock (age %ss): %s\n' "$((now_epoch - mt))" "$lock" >&2
+    rmdir "$lock" 2>/dev/null || true
+    continue
+  fi
+  iters="$((iters + 1))"
+  if [ "$iters" -ge "$max_iters" ]; then
+    printf 'forge-reserve: lock timeout after ~%ss: %s\n' "$WAIT" "$lock" >&2
+    exit 3
+  fi
+  sleep "$SLEEP"
+done
+# Only now that the lock is ours do we install the release trap.
+trap 'rmdir "$lock" 2>/dev/null || true' EXIT INT TERM
+
+# --- 4/5. three-way max(ledger ∪ in-tree ∪ main:reservations.yml) + 1 --------
+# 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)
+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")"
+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
+
+# (c) main:reservations.yml — cross-machine / cold-start floor (survives a
+# .git/forge wipe; carries another machine's MERGED reservations). Absent → 0.
+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}')"
+[ -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")"
+
+# --- 6. dual-write (still under the lock) -----------------------------------
+now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+printf '%s\t%s\t%s\t%s\n' "$kind" "$id" "$milestone" "$now" >> "$ledger"
+
+# reservations.yml missing → seed the 0.42.0 starter HEADER, but with a bare
+# `reservations:` key (not the guide's `reservations: []`) so the block items we
+# append below form a valid sequence — appending `- kind:` under a `[]` flow list
+# is malformed YAML. Existing repo files already use the bare-key block form.
+if [ ! -f "$reservations" ]; then
+  mkdir -p "$(dirname "$reservations")"
+  cat > "$reservations" <<'YML'
+# Forge ID Reservations — cross-worktree coordination for ADR / DEF / FR / NFR numbers
+# Written by .claude/hooks/forge-reserve.sh (ADR-021). The machine-local ledger
+# (.git/forge/id-reservations) is the same-machine coordination point; this file
+# is the durable committed audit trail + cross-machine floor. Append-only; never
+# edit prior entries. Next number for a kind = max(ledger, in-tree, main) + 1.
+# kind ∈ {adr,def,fr,nfr}. See FORGE.md → ID Reservation Protocol + ADR-021.
+reservations:
+YML
+fi
+
+# YAML double-quoted scalar: escape backslash then double-quote.
+esc_summary="$(printf '%s' "$summary" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+{
+  printf '  - kind: %s\n' "$kind"
+  printf '    id: %s\n' "$id"
+  printf '    milestone: %s\n' "$milestone"
+  printf '    reserved_at: "%s"\n' "$now"
+  printf '    summary: "%s"\n' "$esc_summary"
+} >> "$reservations"
+
+# --- 7. emit the id (stdout only); trap releases the lock on exit ------------
+printf '%s\n' "$id"

package/template/.claude/hooks/tests/forge-model-outcome.test.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env sh
+# Self-contained unit test for .claude/hooks/forge-model-outcome.sh (M24 phase 37).
+#
+# Needs no network and no fixtures beyond a temp dir. Each case runs the helper
+# with an isolated $HOME and asserts its exit code + the jsonl file's contents.
+# jq is used HERE to parse the helper's output for assertions — the helper's
+# own write path never uses jq (printf only; see forge-model-outcome.sh, NFR-026).
+# Run:
+#   ./.claude/hooks/tests/forge-model-outcome.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/../forge-model-outcome.sh"
+
+[ -x "$HELPER" ] || { printf 'FATAL: helper not executable: %s\n' "$HELPER" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { printf 'FATAL: jq required for test assertions\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; }
+
+# --- Case 1: record appends one valid jsonl line with the pinned fields -----
+d="$ROOT/case1"; mkdir -p "$d"
+HOME="$d" "$HELPER" record --repo forge --milestone m24 --skill executing \
+  --task-type docs --complexity trivial --model haiku --first-try-pass true --check-exit 0 >/dev/null
+if [ -f "$d/.forge/model-outcomes.jsonl" ]; then
+  pass "case1 log file created"
+else
+  fail "case1 log file not created"
+fi
+line="$(tail -1 "$d/.forge/model-outcomes.jsonl" 2>/dev/null)"
+if printf '%s' "$line" | jq -e \
+  '.task_type=="docs" and .complexity=="trivial" and .model=="haiku" and .first_try_pass==true and .check_exit==0 and .repo=="forge" and .milestone=="m24" and .skill=="executing"' \
+  >/dev/null 2>&1; then
+  pass "case1 line carries pinned fields"
+else
+  fail "case1 line missing/incorrect fields: $line"
+fi
+
+# --- Case 2: unwritable home degrades to exit 0, never blocks ---------------
+d="$ROOT/case2"; mkdir -p "$d"
+: > "$d/.forge"   # regular file where a dir is expected -> mkdir -p fails
+HOME="$d" "$HELPER" record --repo forge --milestone m24 --skill executing --model haiku >/dev/null 2>&1
+rc=$?
+check_rc() { [ "$1" -eq "$2" ] && pass "$3" || fail "$3 (got exit $1, want $2)"; }
+check_rc "$rc" 0 "case2 unwritable home still exits 0"
+
+# --- Case 3: two record calls append, they do not overwrite -----------------
+d="$ROOT/case3"; mkdir -p "$d"
+HOME="$d" "$HELPER" record --repo forge --milestone m24 --skill executing --model haiku --task-type docs >/dev/null
+HOME="$d" "$HELPER" record --repo forge --milestone m24 --skill executing --model opus --task-type code-feature >/dev/null
+lines="$(wc -l < "$d/.forge/model-outcomes.jsonl" | tr -d ' ')"
+if [ "$lines" = "2" ]; then
+  pass "case3 two calls -> two lines (append, not overwrite)"
+else
+  fail "case3 expected 2 lines, got $lines"
+fi
+
+# --- Case 4: recommend — proven bucket (volume met, high pass rate) --------
+d="$ROOT/case4"; mkdir -p "$d"
+i=1
+while [ "$i" -le 6 ]; do
+  HOME="$d" "$HELPER" record --repo x --milestone m24 --skill executing \
+    --task-type docs --complexity trivial --model haiku --first-try-pass true --check-exit 0 >/dev/null
+  i=$((i + 1))
+done
+out="$(HOME="$d" "$HELPER" recommend)"
+if printf '%s' "$out" | grep -qi 'proven' && printf '%s' "$out" | grep -qi 'docs' && printf '%s' "$out" | grep -qi 'haiku'; then
+  pass "case4 recommend marks (haiku,docs) proven + recommends routing"
+else
+  fail "case4 recommend missing proven/docs/haiku: $out"
+fi
+
+# --- Case 5: recommend — probation bucket (volume met, sub-cutoff pass rate) -
+d="$ROOT/case5"; mkdir -p "$d"
+i=1
+while [ "$i" -le 5 ]; do
+  fp="true"; [ "$i" -le 2 ] && fp="false"   # 3/5 = 60% < 90% cutoff
+  HOME="$d" "$HELPER" record --repo x --milestone m24 --skill executing \
+    --task-type code-fix --complexity standard --model sonnet --first-try-pass "$fp" --check-exit 0 >/dev/null
+  i=$((i + 1))
+done
+out="$(HOME="$d" "$HELPER" recommend)"
+if printf '%s' "$out" | grep -qi 'probation'; then
+  pass "case5 recommend marks sub-cutoff bucket probation"
+else
+  fail "case5 recommend did not mark bucket probation: $out"
+fi
+
+# --- Case 6: recommend degrades on an empty/absent log — exit 0 ------------
+d="$ROOT/case6"; mkdir -p "$d"
+out="$(HOME="$d" "$HELPER" recommend)"
+rc=$?
+check_rc "$rc" 0 "case6 recommend on absent log exits 0"
+if printf '%s' "$out" | grep -qiE 'insufficient|unavailable|no data|not enough'; then
+  pass "case6 recommend on absent log prints insufficient-data message"
+else
+  fail "case6 recommend missing insufficient-data message: $out"
+fi
+
+# --- Report -----------------------------------------------------------------
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]

package/template/.claude/hooks/tests/forge-reserve.test.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env sh
+# Self-contained unit test for .claude/hooks/forge-reserve.sh (ADR-021).
+#
+# Needs no network and no fixtures beyond a temp dir. Each case builds a throwaway
+# git repo, seeds ids, and asserts the helper's stdout + file side effects. Run:
+#   ./.claude/hooks/tests/forge-reserve.test.sh
+# Exits 0 iff every case passes; non-zero on any failure. Self-cleans on exit.
+set -u
+
+# Resolve the helper from THIS script's own location so the test works from any cwd.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/../forge-reserve.sh"
+
+[ -x "$HELPER" ] || { printf 'FATAL: helper not executable: %s\n' "$HELPER" >&2; exit 1; }
+
+# One temp root; every throwaway repo lives under it; single cleanup.
+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
+}
+
+# Fresh repo on branch `main` (symbolic-ref sets the unborn branch name portably,
+# no git ≥2.28 -b flag needed). Prints its path.
+new_repo() {
+  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"
+}
+
+# --- Case 1: allocation from in-tree ADR ------------------------------------
+d="$(new_repo case1)"; cd "$d"
+mkdir -p docs/decisions
+: > docs/decisions/ADR-005-something.md
+git add -A && git commit -qm init
+got="$("$HELPER" adr --milestone m-x)"
+check "case1 in-tree ADR-005 -> ADR-006" "$got" "ADR-006"
+
+# --- Case 2: ledger beats tree (uncommitted sibling — the ADR-016-blind case) -
+d="$(new_repo case2)"; cd "$d"
+mkdir -p docs/decisions
+: > docs/decisions/ADR-005-something.md
+git add -A && git commit -qm init
+mkdir -p .git/forge
+printf 'adr\tADR-050\tm-x\t2026-01-01T00:00:00Z\n' > .git/forge/id-reservations
+got="$("$HELPER" adr --milestone m-x)"
+check "case2 ledger(ADR-050) beats tree(ADR-005) -> ADR-051" "$got" "ADR-051"
+
+# --- Case 3: main:reservations.yml floor (committed, then removed from tree) --
+d="$(new_repo case3)"; 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: "seed"
+YML
+git add -A && git commit -qm init
+rm .forge/reservations.yml   # gone from the working tree; survives only on main
+got="$("$HELPER" fr --milestone m-x)"
+check "case3 main floor FR-200 -> FR-201" "$got" "FR-201"
+
+# --- Case 4: dual-write side effects + no commit made by the helper ----------
+d="$(new_repo case4)"; cd "$d"
+git commit --allow-empty -qm init
+ledger=".git/forge/id-reservations"
+before=0; [ -f "$ledger" ] && before="$(wc -l < "$ledger" | tr -d ' ')"
+got="$("$HELPER" nfr --milestone m-x --summary "dual write check")"
+after="$(wc -l < "$ledger" | tr -d ' ')"
+check "case4 ledger grew by exactly 1" "$((after - before))" "1"
+if grep -q "id: $got" .forge/reservations.yml; then
+  pass "case4 reservations.yml has a $got block"
+else
+  fail "case4 reservations.yml missing $got block"
+fi
+check "case4 no new commit (HEAD count still 1)" "$(git rev-list --count HEAD)" "1"
+if [ -n "$(git status --porcelain .forge/reservations.yml)" ]; then
+  pass "case4 reservations.yml is uncommitted (dirty)"
+else
+  fail "case4 reservations.yml unexpectedly clean"
+fi
+
+# --- Case 5: unknown kind — non-zero exit, empty stdout, nothing written -----
+d="$(new_repo case5)"; cd "$d"
+git commit --allow-empty -qm init
+out="$("$HELPER" zzz --milestone m-x 2>/dev/null)"; rc=$?
+check "case5 unknown kind exits non-zero" "$( [ "$rc" -ne 0 ] && echo yes || echo no )" "yes"
+check "case5 unknown kind prints nothing on stdout" "$out" ""
+[ ! -f .git/forge/id-reservations ] && pass "case5 ledger not created" || fail "case5 ledger was created"
+[ ! -f .forge/reservations.yml ] && pass "case5 reservations.yml not created" || fail "case5 reservations.yml was created"
+
+# --- Case 6: N-way concurrency yields N distinct ids, N ledger lines ---------
+d="$(new_repo case6)"; cd "$d"
+git commit --allow-empty -qm init
+outdir="$d/outs"; mkdir -p "$outdir"
+N=8
+i=1
+while [ "$i" -le "$N" ]; do
+  ( "$HELPER" fr --milestone m-x > "$outdir/out.$i" 2>/dev/null ) &
+  i=$((i + 1))
+done
+wait
+distinct="$(cat "$outdir"/out.* | sort -u | grep -c .)"
+check "case6 $N concurrent runs -> $N distinct ids" "$distinct" "$N"
+ledger_lines="$(grep -c '^fr	' .git/forge/id-reservations)"
+check "case6 $N distinct ledger fr lines" "$ledger_lines" "$N"
+
+# --- Report -----------------------------------------------------------------
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]

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

@@ -28,7 +28,7 @@ When an architectural decision conflicts with vertical slicing (e.g., a framewor
 
 ## Architecture Decision Record (ADR)
 
-**Reserve the ADR number first (cross-worktree safety — blocking gate).** Before authoring a new ADR, allocate its number via the **ID Reservation Protocol** (FORGE.md). **Do not create the ADR file until its reservation is appended and committed** — the reserve step is mandatory, not advisory. The next number is `max(highest `kind: adr` in `.forge/reservations.yml`, highest `ADR-NNN` in `.forge/decisions/`) + 1; append one `{kind: adr, id, milestone, reserved_at, summary}` entry to `.forge/reservations.yml`, **commit + push it**, *then* write the ADR file. Bare "scan `decisions/` for the highest + increment" only sees committed state, so two worktrees architecting in parallel both pick the same `ADR-NNN` and collide silently until merge (a multi-file renumber). See FORGE.md → **ID Reservation Protocol** for the full rule. No `reservations.yml` yet ⇒ scan as before and the first reservation creates it (lazy migration).
+**Reserve the ADR number first (cross-worktree safety — blocking gate).** Before authoring a new ADR, allocate its number with the `forge-reserve` helper (ADR-021, supersedes ADR-016): run `id=$(.claude/hooks/forge-reserve.sh adr --milestone <id> --summary "<one-line>")`, then author `docs/decisions/$id-*.md` and commit `.forge/reservations.yml` **with** the ADR (unchanged handoff — the helper writes `reservations.yml` uncommitted; the caller commits it alongside the work). **This reserve step is mandatory, not advisory: do not create the ADR file until `forge-reserve` has printed its id.** WHY: the number is allocated against a machine-local ledger (`.git/forge/id-reservations`) that every sibling worktree of the repo shares the moment it is written, so two worktrees architecting in parallel can no longer pick the same `ADR-NNN` and collide silently until merge (a multi-file renumber) — the exact failure ADR-016's "commit + push before allocating" could not prevent, because reservations sat on unmerged branches nothing else reads. The helper self-heals a missing ledger (lazy migration). See FORGE.md → **ID Reservation Protocol** and ADR-021 for the mechanism.
 
 Record every significant decision in `.forge/decisions/`: