forge-orkes 0.44.0 → 0.46.0

package/package.json

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

@@ -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-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/`:
 

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

@@ -76,11 +76,11 @@ Resolve current milestone ID from `.forge/state/index.yml` (active milestone) or
 
 If missing, create from `.forge/templates/requirements.yml`:
 1. Extract from user description + research
-2. IDs: FR-001, FR-002... **Globally unique across milestones.** Allocate via the **ID Reservation Protocol** (FORGE.md). **This is a blocking gate, not advisory: do not write an `FR-`/`NFR-`/`DEF-` ID into any artifact until its reservation is appended and committed.** Per ID: next = `max(highest `kind: fr` in `.forge/reservations.yml`, highest FR in `.forge/requirements/*.yml`) + 1; append `{kind: fr, id, milestone, reserved_at, summary}` to `.forge/reservations.yml`, **commit + push**, *then* write the FR. Skipping the reserve step is the exact failure ADR-016 exists to prevent — bare scan-and-increment sees only committed state, so two worktrees branched from one baseline claim the same number and collide silently until merge (a multi-file renumber). No `reservations.yml` yet ⇒ scan as before; the first reservation creates it (lazy migration), but once it exists the gate is mandatory.
+2. IDs: FR-001, FR-002... **Globally unique across milestones.** Allocate with the `forge-reserve` helper (ADR-021, supersedes ADR-016). **This is a blocking gate, not advisory: do not write an `FR-`/`NFR-`/`DEF-` ID into any artifact until `forge-reserve` has printed it.** Per ID: run `id=$(.claude/hooks/forge-reserve.sh fr --milestone <id> --summary "<one-line>")` and use its stdout, *then* write the FR; `.forge/reservations.yml` commits with the plan (the helper writes it uncommitted — the caller commits). WHY: the id is allocated against a machine-local ledger (`.git/forge/id-reservations`) every sibling worktree shares the moment it is written, so two worktrees branched from one baseline can no longer claim the same number and collide silently until merge (a multi-file renumber) — the exact failure ADR-016's "commit + push" could not prevent, because reservations sat on unmerged branches nothing else reads. The helper self-heals a missing ledger (lazy migration).
 3. Acceptance: Given/When/Then
 4. Uncertain: `[NEEDS CLARIFICATION]`
 5. P1 (must) / P2 (should) / P3 (nice)
-6. Deferred: DEF-001..., and NFR-001... — **also globally unique; reserve the same way** (`kind: def` / `kind: nfr`) before writing.
+6. Deferred: DEF-001..., and NFR-001... — **also globally unique; reserve the same way** via `forge-reserve def` / `forge-reserve nfr` before writing.
 
 **E2E gate (M9):** For each functional requirement being added or refined:
 1. Decide `e2e: true|false` -- does this story need a post-validation e2e test?

package/template/.forge/FORGE.md

@@ -106,6 +106,7 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | Systematic debugging | `debugging` | When stuck |
 | Upgrade Forge files | `upgrading` | On-demand |
 | Cross-session memory | `beads-integration` | When Beads installed |
+| Project/read Forge work in Notion | `notion-integration` | When Notion configured |
 | Multi-agent backend (experimental) | `orchestrating` | Optional, usually selected by Chief/Streams |
 
 > Experimental skills require opt-in install — see `packages/create-forge/experimental/m10/README.md`.
@@ -136,8 +137,9 @@ Every new accumulating artifact needs: owner, size gate, archive/compaction rule
   source-of-truth; load scoped slices, not whole history.
 - `phases/`, `audits/`, `research/`, `archive/`, and `context-archive.md` are
   historical; load only by milestone/stream/package/version.
-- Runtime/generated files (`.mcp-server/*.db*`, logs, spike DBs) are excluded
-  from framework context and packages unless debugging them.
+- Runtime/generated files (`.mcp-server/*.db*`, logs, spike DBs, and the
+  `.git/forge/*` machine-local files — the id-reservation ledger + integration
+  flag) are excluded from framework context and packages unless debugging them.
 - Template copies sync mechanically; do not treat them as separate concepts.
 
 ### Fresh Agent Pattern
@@ -211,7 +213,7 @@ State lives in `.forge/`:
 - `project.yml` — Vision, stack, design system, verification, constraints (<5KB)
 - `constitution.md` — Active architectural gates
 - `design-system.md` — Component mapping table
-- `requirements/m{N}.yml` — Per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. **FR-IDs, DEF-IDs, and NFR-IDs are globally unique across all milestone files** — `FR-001` may exist in exactly one `m{N}.yml`. Before adding a new ID, **reserve it via the ID Reservation Protocol** (append to `.forge/reservations.yml`, commit+push, then write) — the next number is `max(highest reserved, highest in `.forge/requirements/*.yml`) + 1`. That reservation is what makes the shared ID space safe across **concurrent worktrees**: bare scan-and-increment sees only committed state, so two worktrees branched from one baseline claim the same number and collide silently until merge (see ADR-016). On a residual collision (legacy/un-reserved, e.g. during a migration), keep the older milestone's ID and renumber the newer. Concurrent milestones each own their file — no cross-stream contention on file writes, but ID space is shared. Functional requirements may carry M9 e2e gate fields (`e2e`, `observable_outcome`, `observable_outcome_hash`, `validated`) — lazy migration, absent fields default to `e2e:false`/`validated:false`.
+- `requirements/m{N}.yml` — Per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. **FR-IDs, DEF-IDs, and NFR-IDs are globally unique across all milestone files** — `FR-001` may exist in exactly one `m{N}.yml`. Before adding a new ID, **reserve it via the ID Reservation Protocol** — run `forge-reserve fr|nfr|def --milestone <id>` and use the id it prints (the helper dual-writes the machine-local ledger + `.forge/reservations.yml`; you commit `reservations.yml` with the work). The next number is `max(ledger ∪ in-tree ∪ main:reservations.yml) + 1`. The machine-local ledger is what makes the shared ID space safe across **concurrent worktrees**: bare scan-and-increment (or a branch-local `reservations.yml`) sees only committed/merged state, so two worktrees branched from one baseline claim the same number and collide silently until merge (see ADR-021, supersedes ADR-016). On a residual collision (legacy/un-reserved, e.g. during a migration), keep the older milestone's ID and renumber the newer. Concurrent milestones each own their file — no cross-stream contention on file writes, but ID space is shared. Functional requirements may carry M9 e2e gate fields (`e2e`, `observable_outcome`, `observable_outcome_hash`, `validated`) — lazy migration, absent fields default to `e2e:false`/`validated:false`.
 - `roadmap.yml` — Phases, milestones, dependencies
 - `state/index.yml` — DERIVED registry rolled up from milestone files (id, name, status, last_updated). Never hand-edited; never written by worktree agents.
 - `state/milestone-{id}.yml` — Per-milestone cursor (single source of truth): position, progress, decisions, blockers. One owner at a time.
@@ -227,7 +229,7 @@ State lives in `.forge/`:
 - `refactor-backlog.yml` — Refactoring catalog (actionable items only), worked via quick-tasking. Canonical status vocab: `pending | in_progress | done | dismissed | deferred`. Terminal items auto-archive on the next reviewing/quick-tasking write (compaction-on-write).
 - `refactor-backlog-archive.yml` — Append-only terminal-item archive (`done`/`dismissed`); keeps the audit trail out of the working backlog.
 - `releases.yml` — Append-only version-reservation registry (cross-session coordination point; see Version Reservation Protocol)
-- `reservations.yml` — Append-only ID-reservation registry for ADR/DEF/FR/NFR numbers (cross-worktree coordination point; see ID Reservation Protocol)
+- `reservations.yml` — Append-only ID-reservation audit trail + cross-machine floor for ADR/DEF/FR/NFR numbers, written by `forge-reserve` (ADR-021). The same-machine cross-worktree coordination point is the machine-local ledger `.git/forge/id-reservations`; see ID Reservation Protocol.
 - `archive/milestone-{id}/` — Archived milestone artifacts (archive-delete)
 
 **Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions. Can be deferred (frozen in place) or archive-deleted.
@@ -265,7 +267,8 @@ with the work it describes. Every artifact has a sharing class:
 | **Single-owner mutable** | `state/milestone-{id}.yml`, `phases/milestone-{id}/`, `research/milestone-{id}.md` | Exactly one writer at a time — the worktree (or main session) currently driving that milestone. **Other worktrees never touch it**, not even to read-then-write — they pull from main if they need it. |
 | **Single-owner mutable (per stream)** | `streams/{stream}.yml`, `streams/{stream}/brief.md`, `streams/{stream}/packages/*.yml` | The stream's **current driver** writes them — one writer at a time, like the milestone file. Distinct streams own distinct files (no cross-stream contention). `active.yml` is **derived** from them: a worktree driving a stream may write its own stream file but **never** `active.yml` or a peer stream's file. |
 | **Derived** | `state/index.yml`, `streams/active.yml` | Never hand-edited. Regenerated by rollup from their sources (`index.yml` ← `milestone-*.yml` via Rollup 1.0; `active.yml` ← per-stream files + active milestones via the Stream Rollup). Only the main/orchestrator session (and `chief-of-staff` for `active.yml`) runs rollup. |
-| **Append-only shared** | `releases.yml` (version reservations), `reservations.yml` (ADR/DEF/FR/NFR id reservations), `state/desire-paths/*` (one file per observation) | Many writers OK; structure prevents collision. `releases.yml` + `reservations.yml` use the reservation protocols (append + commit + push before depending on the number); desire-paths use distinct filenames so two writers never touch the same file. |
+| **Append-only shared** | `releases.yml` (version reservations), `reservations.yml` (ADR/DEF/FR/NFR id **audit trail + cross-machine floor**), `state/desire-paths/*` (one file per observation) | Many writers OK; structure prevents collision. `releases.yml` uses the Version Reservation Protocol (append + commit + push). `reservations.yml` is written by `forge-reserve` (ADR-021) and committed with the caller's work — it is no longer the id *coordination* point (the machine-local ledger is), just the durable committed shadow. Desire-paths use distinct filenames so two writers never touch the same file. |
+| **Machine-local runtime** | `.git/forge/id-reservations` (id-reservation ledger), `.git/forge/integration-pending` (integration flag) | In the git common dir, shared across a repo's worktrees on one machine, **not** git-tracked. `forge-reserve` writes the ledger under a `mkdir` lock; excluded from framework context. Machine-local by design (cross-machine falls back to the `main:reservations.yml` floor). |
 | **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` (ID space `FR-`/`DEF-`/`NFR-` is globally shared even though each milestone owns its file) | Write only to your milestone/stream block. Within a block, append-only; strike through instead of rewriting. |
 | **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md`, `.claude/skills/`, `.claude/agents/` | Rarely changes except via `/upgrading`. Canonical on main; worktrees lag until they rebase. An upgrade run touches **only the checkout it runs in**, so after upgrading in main, live worktrees keep their branch-point framework files — `upgrading` **Step 8** enumerates live `forge/m-*` worktrees and offers to rebase each (never auto), and the opt-in `forge.worktree_rebase_check` watches these files as a boot-time safety net. Gitignored carve-outs (`.mcp.json`, experimental hooks) don't rebase — re-run the experimental installer if the upgrade changed them. |
 
@@ -300,15 +303,16 @@ The project version + CHANGELOG slot are **shared resources** — when two miles
 
 ### ID Reservation Protocol
 
-Sequential IDs — `ADR-NNN` (decision records), `DEF-NNN` (deferred issues), `FR-NNN`/`NFR-NNN` (requirements) — are **shared cross-worktree resources** the same way the version number is. "Scan the tree for the highest and increment" only sees *committed* state, so two streams branched from the same baseline each claim the same next number and collide **silently until merge** — a costly multi-file renumber pass (see [ADR-016](../docs/decisions/ADR-016-id-reservation-protocol.md)). `.forge/reservations.yml` removes the number from per-stream scope, exactly as `releases.yml` does for versions.
+Sequential IDs — `ADR-NNN` (decision records), `DEF-NNN` (deferred issues), `FR-NNN`/`NFR-NNN` (requirements) — are **shared cross-worktree resources** the same way the version number is. "Scan the tree for the highest and increment" only sees *committed* state, so two worktrees branched from the same baseline each claim the same next number and collide **silently until merge** — a costly multi-file renumber pass. [ADR-016](../docs/decisions/ADR-016-id-reservation-protocol.md) tried to fix this by reserving in the branch-tracked `reservations.yml` and *committing + pushing before allocating*, but a reservation on an unmerged branch is invisible to every sibling worktree (they share `.git`, not branches) — so collisions continued. [ADR-021](../docs/decisions/ADR-021-id-reservation-ledger-git-common-dir.md) (**supersedes ADR-016**) moves the coordination point to a **machine-local ledger in the git common dir**, the same primitive as the integration flag: every sibling worktree of the repo on a machine sees it the moment it is written — no push, no pull, no merge.
 
-- **Reserve before allocating.** Before authoring a new ADR or writing a new DEF/FR/NFR ID, append ONE entry to `.forge/reservations.yml` — `{kind, id, milestone, reserved_at, summary}`, `kind ∈ {adr, def, fr, nfr}` — then **commit + push it BEFORE creating the artifact**. A parallel worktree pulls and sees the number taken.
-- **Next number = `max(reserved, in-tree) + 1` per kind.** The higher of (a) the highest reservation for that kind in `reservations.yml` and (b) the highest ID of that kind actually landed in the tree. Taking both keeps it backward-compatible — landed IDs that were never reserved are still respected.
-- **Append-only — never edit prior entries.** Distinct lines = no contention. Race resolution: the second of two near-simultaneous reservations rebases onto the first (append-only → clean), re-reads `max()`, takes the next number.
-- **Reserve points.** `architecting` reserves an `adr` before authoring it; `planning` reserves `fr`/`nfr`/`def` before writing them into requirements. (Out of scope: `executing`'s `DI-NNN` deferred-*issue* ids in `deferred-issues.md` are a separate, more local namespace — not reserved here.)
-- **Lazy migration.** No `reservations.yml` ⇒ allocate as before (scan in-tree max); the first reservation creates the file. Existing projects are unaffected until they next allocate an ID.
+- **Reserve with the helper.** `forge-reserve <kind> --milestone <id> [--summary <text>]` (`.claude/hooks/forge-reserve.sh`, `kind ∈ {adr, def, fr, nfr}`) allocates the next number under a portable `mkdir` lock and prints it on stdout. It **dual-writes**: one TSV line to `.git/forge/id-reservations` (the machine-local coordination ledger) and one `{kind, id, milestone, reserved_at, summary}` block to the tracked `.forge/reservations.yml`. Neither is committed by the helper — **the caller commits `reservations.yml` with its work** (unchanged handoff). Reserve *before* creating the artifact; the printed id is the one to use.
+- **Next number = `max(ledger ∪ in-tree ∪ main:reservations.yml) + 1` per kind.** Three inputs, unioned: the **ledger** (same-machine siblings, *including uncommitted* — the input ADR-016 could not see), the **in-tree** landed ids (`docs/decisions/ADR-NNN*`; `.forge/requirements/*.yml` for fr/nfr/def), and **`main:reservations.yml`** (the cross-machine / cold-start floor). Taking all three keeps it backward-compatible (landed & pre-ledger IDs respected) while giving the ledger authority for the same-machine hot path.
+- **`reservations.yml` is now the durable audit trail + cross-machine floor**, not the coordination mechanism. Append-only, distinct lines → it unions cleanly at merge (it stops being a merge-conflict source). An optional `forge-reserve --verify` can diff ledger vs. `reservations.yml`.
+- **Reserve points.** `architecting` reserves an `adr` before authoring it; `planning` reserves `fr`/`nfr`/`def` before writing them into requirements — both via `forge-reserve`. (Out of scope: `executing`'s `DI-NNN` deferred-*issue* ids in `deferred-issues.md` are a separate, more local namespace — not reserved here.)
+- **Cross-machine gap (accepted).** The ledger is machine-local (like `integration-pending`). Two *concurrent* worktrees on *different* laptops, both reserving before either merges, still fall back to merge-time renumber — bounded by the `main:reservations.yml` floor, so no worse than ADR-016.
+- **Lazy migration.** No ledger ⇒ the helper creates it on first reserve, seeded by the `max()` (which reads in-tree + `main:reservations.yml`). Existing `reservations.yml` is untouched and still respected. Projects that never run concurrent worktrees see no behavior change.
 
-This is the cross-worktree mechanism the FR/DEF/NFR "globally unique" rule (State Management, above) previously lacked, and the first reservation rule ADR numbers have ever had. Versions stay in `releases.yml` (separate semver/CHANGELOG semantics); everything else reserves here.
+This is the cross-worktree mechanism the FR/DEF/NFR "globally unique" rule (State Management, above) previously lacked, now made collision-safe for same-machine worktrees. Versions stay in `releases.yml` (separate semver/CHANGELOG semantics); everything else reserves through `forge-reserve`.
 
 ## Deviation Rules
 

package/template/.forge/migrations/0.46.0-id-reservation-ledger.md

@@ -0,0 +1,44 @@
+# Migration Guide: ID Reservation Ledger in the Git Common Dir (Forge 0.46.0)
+
+Forge 0.46.0 moves the ID-reservation **coordination point** from the branch-tracked `.forge/reservations.yml` to a **machine-local ledger in the git common dir** — `.git/forge/id-reservations` — written by a new `forge-reserve` POSIX-sh helper. This fixes the cross-worktree collisions ADR-016 could not (a reservation on an unmerged branch is invisible to sibling worktrees, which share `.git`, not branches). See [ADR-021](../../docs/decisions/ADR-021-id-reservation-ledger-git-common-dir.md) (supersedes ADR-016) and [issue #19](https://github.com/Attuned-Media/forge/issues/19).
+
+**It is backward-compatible and zero-touch.** The helper is installed + `chmod +x`'d by the upgrade's additive hooks sync. The ledger self-creates on the **first** `forge-reserve` run, seeded implicitly by the allocation `max()` (which reads in-tree IDs + `main:.forge/reservations.yml`). Your existing `reservations.yml` is untouched and still respected as a `max()` input. A project that never runs concurrent worktrees sees no behavior change and needs no action.
+
+## What changed (no action needed)
+
+- **`forge-reserve` helper** allocates the next `ADR/DEF/FR/NFR` number under a portable `mkdir` lock and prints it on stdout; `planning` (fr/nfr/def) and `architecting` (adr) now call it instead of hand-scanning.
+- **Allocation is `max(ledger ∪ in-tree ∪ main:reservations.yml) + 1`** per kind — the ledger gives same-machine worktrees authority (including *uncommitted* siblings), while `main:reservations.yml` remains the durable cross-machine floor.
+- **`reservations.yml` is reclassified** from the coordination mechanism to a **durable audit trail + cross-machine floor**, still committed with your work by the helper.
+
+These take effect the moment the framework files are synced. No per-project state changes.
+
+## Detection
+
+Prints `MIGRATE` only if a project predates the helper (has `.forge/` but no `forge-reserve.sh`). Silent + exit 0 once the helper is present.
+
+```bash
+[ -d .forge ] || exit 0                                  # not a Forge project
+[ -f .claude/hooks/forge-reserve.sh ] && exit 0          # helper present → already migrated, silent
+echo "MIGRATE — ID reservation now uses .git/forge/id-reservations via forge-reserve; run 'npx forge-orkes upgrade' to install the helper (ADR-021, issue #19)"
+exit 0
+```
+
+## Migration steps (normally none)
+
+The upgrade installs the helper; the ledger self-creates on first reserve. Two optional cleanups:
+
+- **Backfill un-reserved IDs (recommended for concurrent-worktree projects).** `forge` boot's ID-reservation preflight lists landed `ADR-`/`FR-`/`NFR-`/`DEF-` IDs that have no `reservations.yml` entry. Appending them keeps `main:reservations.yml` a complete floor.
+- **ADR location caveat.** `forge-reserve`'s in-tree ADR scan reads `docs/decisions/ADR-NNN*` (per ADR-021). Projects that keep ADRs under **`.forge/decisions/`** should ensure those ADRs are represented in `reservations.yml` (via the backfill above) so the `main:reservations.yml` floor covers them — the ledger + floor still prevent collisions, but the in-tree ADR *input* won't see a `.forge/decisions/` file directly.
+
+## Cross-machine caveat (accepted)
+
+The ledger is machine-local (like the integration flag). Two *concurrent* worktrees on *different* laptops, both reserving before either merges, still fall back to merge-time renumber — bounded by the `main:reservations.yml` floor, so no worse than ADR-016. Tracked as DEF-046 (land-time detector deferred).
+
+## Validation
+
+```bash
+[ -x .claude/hooks/forge-reserve.sh ] && echo "OK: forge-reserve present + executable" || echo "FAIL: helper missing/not executable"
+id=$(.claude/hooks/forge-reserve.sh fr --milestone m-smoke --summary "migration smoke") && echo "OK: allocated $id" || echo "FAIL: forge-reserve did not run"
+# revert the smoke reservation: drop the last reservations.yml block + the ledger line for $id
+echo "validation complete"
+```