forge-orkes 0.71.0 → 0.73.1

package/template/.claude/hooks/forge-slice-runner.sh

@@ -80,13 +80,14 @@ cfg_get() {
   [ -n "$_v" ] && printf '%s' "$_v" || printf '%s' "$2"
 }
 MAX_TURNS="$(cfg_get max_turns_per_phase 60)"
-# per-phase budget cap: bounded by the per-slice cap for now. A per-phase
-# --max-budget-usd <= the slice cap.
-MAX_BUDGET="$(cfg_get per_slice_budget_usd 25)"
 # per-SLICE budget cap (plan-47 task 2): the runner accumulates usage.cost_usd
 # across phase reports and parks with a §8.4 `budget` ping when the running total
-# breaches this. Same config key as the per-phase bound (the cap IS the slice cap);
-# the accumulation is what makes it a slice-level guard, not a phase-level one.
+# breaches this. The SAME value is also passed as the launcher's per-phase
+# --max-budget-usd — one config key, deliberately: the per-phase cap IS the slice
+# cap, so a single phase may burn the whole slice budget before the launcher-level
+# cap trips; the accumulation is what makes this a slice-level guard. A genuinely
+# distinct per-phase bound would need its own max_phase_budget_usd key (R070
+# ruled: collapse to one variable, not a second knob).
 SLICE_BUDGET="$(cfg_get per_slice_budget_usd 25)"
 # phase-boundary refresh + divergence budget (plan-03).
 INT_BRANCH="$(cfg_get integration_branch main)"
@@ -109,7 +110,10 @@ PHASES="$(awk '
 
 # --- report readers (grep/sed, dependency-free) ------------------------------
 report_field() {  # report_field <file> <key> — a TOP-LEVEL `key:` (col 0)
-  grep -E "^$2:" "$1" 2>/dev/null | head -1 | sed -E "s/^$2:[[:space:]]*//; s/[[:space:]]*(#.*)?$//; s/^\"//; s/\"$//"
+  # Comment-strip requires whitespace BEFORE the '#': a '#' embedded in a token
+  # (an operator-authored fork-payload path like sketch.html#hero) is value, not
+  # comment — truncating it broke the payload existence check (R071).
+  grep -E "^$2:" "$1" 2>/dev/null | head -1 | sed -E "s/^$2:[[:space:]]*//; s/[[:space:]]+#.*$//; s/[[:space:]]+$//; s/^\"//; s/\"$//"
 }
 report_field_flat() {  # report_field_flat <file> <key> — report_field + YAML block scalars
   # A long interrupt question is naturally written as a block scalar (`key: |` /
@@ -140,7 +144,11 @@ report_nested() {  # report_nested <file> <key> — an INDENTED `key:` (checks.*
   # file, so a plain indented grep is enough. NOTE: usage.cost_usd/tokens are NO
   # longer read from the report — the authoritative numbers come from the launcher's
   # result.json (see result_num), because a phase can't know its own usage.
-  grep -E "^[[:space:]]+$2:" "$1" 2>/dev/null | head -1 | sed -E "s/^[[:space:]]+$2:[[:space:]]*//; s/[[:space:]]*(#.*)?$//; s/^\"//; s/\"$//"
+  grep -E "^[[:space:]]+$2:" "$1" 2>/dev/null | head -1 | sed -E "s/^[[:space:]]+$2:[[:space:]]*//; s/[[:space:]]+#.*$//; s/[[:space:]]+$//; s/^\"//; s/\"$//"
+}
+emit_result() {  # the LAST stdout line at every slice end (R069) — one writer, three globals
+  printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s
+' "$COMPLETED" "$TOUCHES" "$LAST_PING"
 }
 extract_session() {  # extract_session <result.json> — the launcher's session id
   # Fresh-context proof: a real `claude -p` mints a new session_id per call; the
@@ -541,7 +549,7 @@ for phase in $PHASES; do
       "$LAUNCHER" -p "$@" \
         --output-format json \
         --max-turns "$MAX_TURNS" \
-        --max-budget-usd "$MAX_BUDGET" \
+        --max-budget-usd "$SLICE_BUDGET" \
         --dangerously-skip-permissions \
         --append-system-prompt-file "$sysprompt" \
         < "$prompt" \
@@ -581,7 +589,7 @@ for phase in $PHASES; do
       slice_notify halt "$phase-crash" \
         "slice HALTED at phase $phase ($idx/$total) — launcher crash, no phase-report.yml written (attempt $attempt); see $wdir/result.json + $wdir/launch.err"
       printf '[runner] phase %s: no phase-report.yml written at %s — halting\n' "$phase" "$report" >&2
-      printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+      emit_result
       exit 1
     fi
 
@@ -603,7 +611,7 @@ for phase in $PHASES; do
       slice_notify halt slice \
         "slice HALTED at phase $phase ($idx/$total) after 1 retry — verdict=$verdict checks.failed=$cfailed; evidence: $report${_ev:+ ; $_ev}"
       printf '[runner] phase %s: HALTED after retry — failure evidence at %s\n' "$phase" "$report" >&2
-      printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+      emit_result
       exit 1
     fi
     break   # phase passed its own checks — proceed to the verdict branch below
@@ -636,6 +644,11 @@ for phase in $PHASES; do
   #        intended_model = what routing ASKED for (map value, "-" when unmapped)
   #        actual_model   = the PRIMARY model actually used (result.json modelUsage,
   #                         max outputTokens) — reality, not intent
+  #        NOTE (R090): intended_model is an operator-mapped ALIAS (`sonnet`);
+  #                     actual_model is the launcher-reported FULL id
+  #                     (`claude-sonnet-5`). Different spellings alone are the
+  #                     convention, not a routing mismatch — compare via the
+  #                     alias→id mapping, never string equality.
   #        fallback       = yes when a routed launch fell back unrouted (routed → fallback)
   #        cost_usd       = per-phase spend (result.json total_cost_usd) — the spend
   #                         the by-phase-type-and-model attribution surface sums
@@ -696,21 +709,21 @@ for phase in $PHASES; do
         slice_notify budget slice \
           "per-slice budget breached after phase $phase ($idx/$total): spent \$$ACCUM > cap \$$SLICE_BUDGET — split the slice or raise per_slice_budget_usd"
         printf '[runner] phase %s: BUDGET CAP breached ($%s > $%s) — parking slice\n' "$phase" "$ACCUM" "$SLICE_BUDGET" >&2
-        printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+        emit_result
         exit 3
       fi
       # Phase-boundary refresh + divergence budget. A non-zero return means the
       # slice PARKED (fork ping already fired) — STOP before the next phase.
       if ! slice_refresh_from_main "$phase"; then
         printf '[runner] phase %s: slice PARKED at phase boundary (fork ping) — stopping before next phase\n' "$phase" >&2
-        printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+        emit_result
         exit 3
       fi
       ;;
     done)
       COMPLETED=$((COMPLETED + 1))   # the final phase completed the slice
       slice_notify done slice "slice complete: $total phases, $COMPLETED run, 0 operator touches"
-      printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+      emit_result
       exit 0
       ;;
     park)
@@ -725,7 +738,7 @@ for phase in $PHASES; do
       # sketch/mockup PATH that exists, never prose describing a visual (§8).
       if [ "$interrupt" = "fork" ] && { [ -z "$ipayload" ] || [ ! -e "$ipayload" ]; }; then
         printf '[runner] phase %s: fork interrupt payload %s is not an existing path — a design fork must be a sketch/mockup to look at, not prose; rejecting\n' "$phase" "${ipayload:-<empty>}" >&2
-        printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+        emit_result
         exit 1
       fi
 
@@ -740,19 +753,19 @@ for phase in $PHASES; do
           [ -f "$wdir/answer.md" ] && _ans_fp="$(cksum "$wdir/answer.md" 2>/dev/null | cut -d' ' -f1)"
           slice_notify "$interrupt" "$phase-a$_ans_fp" "$ipayload"
           printf '[runner] phase %s: PARKED — §8 %s interrupt (stopping before next phase)\n' "$phase" "$interrupt" >&2
-          printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+          emit_result
           exit 3
           ;;
         *)
           printf '[runner] phase %s: park with interrupt %s — not one of the five §8 types (ambiguity|irreversible|fork|budget) — rejecting loudly\n' "$phase" "${interrupt:-<none>}" >&2
-          printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+          emit_result
           exit 1
           ;;
       esac
       ;;
     *)
       printf '[runner] phase %s: unrecognized verdict "%s" — halting\n' "$phase" "$verdict" >&2
-      printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+      emit_result
       exit 1
       ;;
   esac
@@ -761,7 +774,15 @@ set +f
 
 # The loop runs in the main shell, so a `done` verdict already `exit 0`'d above.
 # Reaching here means the phase list was exhausted WITHOUT a `done` verdict — the
-# slice ran every phase but the last one never marked itself done.
+# slice ran every phase but the last one never marked itself done. This is still a
+# slice END, so it MUST ping like the other ends — a silent phone is never success.
+# Live gap 2026-07-23: a --plan-scoped single-plan order (the m-45 re-dispatch
+# pattern) ended `proceed` — a phase can't know it is last — and the finished build
+# sat dark for an hour. Ping `done` on the shared `slice` key: the §8 surface stays
+# closed, and the append-once marker keeps a re-run (or an already-done-pinged
+# slice) from double-buzzing.
+slice_notify done slice \
+  "slice complete: all $total phase(s) ran ($COMPLETED completed, 0 operator touches) — no phase declared verdict=done (last was proceed); verify before landing"
 printf '[runner] phase list exhausted with no `done` verdict\n' >&2
-printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
+emit_result
 exit 0

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

@@ -116,6 +116,175 @@ 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"
 
+# --- Case 7: stale-lock break — identity unchanged -> break + clean re-acquire
+# (R103). A foreign owner stamp sits in a lock dir backdated past STALE with
+# nothing racing to change it: the breaker's re-read-before-rmdir sees the same
+# stamp it saw when it judged the lock stale, so it proceeds to break it and
+# allocate normally.
+d="$(new_repo case7)"; cd "$d"
+git commit --allow-empty -qm init
+lockdir=".git/forge/id-reservations.lock"
+mkdir -p "$lockdir"
+printf '999999 1700000000\n' > "$lockdir/owner"
+touch -t 202001010000 "$lockdir" 2>/dev/null || touch -d '2020-01-01' "$lockdir" 2>/dev/null || true
+out="$(FORGE_RESERVE_STALE=1 FORGE_RESERVE_WAIT=3 "$HELPER" adr --milestone m-x 2>case7-err.log)"; rc=$?
+check "case7 stale lock (unchanged owner) is broken and allocation succeeds" "$out" "ADR-001"
+check "case7 stale-break exits 0" "$rc" "0"
+if grep -qi 'stale' case7-err.log; then
+  pass "case7 stderr reports the stale-lock break"
+else
+  fail "case7 stderr missing stale-lock break message"
+fi
+
+# --- Case 8: stale-lock break — identity refreshed mid-wait -> no break ------
+# (R103). A lock dir is backdated past STALE (so every poll judges it stale by
+# mtime), but a background racer continuously rewrites the owner stamp inside
+# it — simulating the original holder renewing the lock. The breaker's
+# re-read-before-rmdir must never see a stable (seen == now) pair, so it never
+# tears the lock down; it falls through to the bounded wait and exits 3.
+# Racy-but-reliable, same style as case6's real concurrency: the writer refreshes
+# far faster than the breaker's poll interval, so cumulative miss probability
+# across the whole wait window is negligible.
+d="$(new_repo case8)"; cd "$d"
+git commit --allow-empty -qm init
+lockdir=".git/forge/id-reservations.lock"
+mkdir -p "$lockdir"
+printf 'racer-0\n' > "$lockdir/owner"
+touch -t 202001010000 "$lockdir" 2>/dev/null || touch -d '2020-01-01' "$lockdir" 2>/dev/null || true
+( i=0
+  while [ -d "$lockdir" ] && [ "$i" -lt 200000 ]; do
+    printf 'racer-%s\n' "$i" > "$lockdir/owner" 2>/dev/null
+    i=$((i + 1))
+  done
+) &
+writer_pid=$!
+out="$(FORGE_RESERVE_STALE=1 FORGE_RESERVE_WAIT=1 "$HELPER" adr --milestone m-x 2>case8-err.log)"; rc=$?
+kill "$writer_pid" 2>/dev/null
+wait "$writer_pid" 2>/dev/null
+check "case8 continuously-refreshed lock is never broken (no allocation)" "$out" ""
+check "case8 exits with lock-timeout (3)" "$rc" "3"
+[ -d "$lockdir" ] && pass "case8 lock dir still stands (never rmdir'd)" || fail "case8 lock dir was removed"
+
+# --- Case 9: compact — floor preserved, archive verbatim, idempotent (R104) --
+# One kind (fr) with three rows: an OLD low id (should archive), an OLD row
+# that happens to be the kind's MAX id (kept regardless of age — this is the
+# row the floor needs), and a RECENT low id (kept via the retention window,
+# not via max). Commit-then-remove-from-tree (same trick as case 3) proves the
+# post-compaction file still yields the correct arm (c) floor: a subsequent
+# reserve allocates immediately above the pre-compaction max, never reusing an
+# archived id. A second compact run must archive nothing further.
+d="$(new_repo case9)"; cd "$d"
+mkdir -p .forge
+now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+cat > .forge/reservations.yml <<YML
+reservations:
+  - kind: fr
+    id: FR-050
+    milestone: m-x
+    reserved_at: "2020-01-01T00:00:00Z"
+    summary: "old, not max -> archive"
+  - kind: fr
+    id: FR-300
+    milestone: m-x
+    reserved_at: "2020-06-01T00:00:00Z"
+    summary: "old but MAX -> keep"
+  - kind: fr
+    id: FR-105
+    milestone: m-x
+    reserved_at: "$now"
+    summary: "recent, not max -> keep"
+YML
+git add -A && git commit -qm init
+out="$("$HELPER" compact 2>compact-err.log)"; rc=$?
+check "case9 compact exits 0" "$rc" "0"
+if grep -q 'id: FR-300' .forge/reservations.yml; then
+  pass "case9 compact kept the old MAX row (FR-300)"
+else
+  fail "case9 compact dropped the kind's max row"
+fi
+if grep -q 'id: FR-105' .forge/reservations.yml; then
+  pass "case9 compact kept the recent non-max row (FR-105)"
+else
+  fail "case9 compact dropped a within-window row"
+fi
+if grep -q 'id: FR-050' .forge/reservations.yml; then
+  fail "case9 compact left the old non-max row (FR-050) in the working file"
+else
+  pass "case9 compact removed the old non-max row (FR-050) from the working file"
+fi
+if grep -q 'id: FR-050' .forge/reservations-archive.yml && grep -q 'summary: "old, not max -> archive"' .forge/reservations-archive.yml; then
+  pass "case9 compact archived FR-050 byte-verbatim (id + summary intact)"
+else
+  fail "case9 compact archive missing or corrupted the dropped FR-050 row"
+fi
+
+git add -A && git commit -qm "compact"
+rm .forge/reservations.yml
+got="$("$HELPER" fr --milestone m-x)"
+check "case9 compact preserves the floor: next fr id is FR-301, not a reuse" "$got" "FR-301"
+
+# Restore + idempotency: a second compact on the same (already-compacted)
+# registry must archive nothing new.
+git checkout -q .forge/reservations.yml
+arch_lines_before="$(wc -l < .forge/reservations-archive.yml | tr -d ' ')"
+"$HELPER" compact >/dev/null 2>compact-err2.log
+arch_lines_after="$(wc -l < .forge/reservations-archive.yml | tr -d ' ')"
+check "case9 second compact is a no-op (archive line count unchanged)" "$arch_lines_after" "$arch_lines_before"
+if grep -qi 'kept 2, archived 0' compact-err2.log; then
+  pass "case9 second compact summary reports archived 0"
+else
+  fail "case9 second compact summary did not report archived 0"
+fi
+
+# --- Case 10: compact --days override tightens the retention window ---------
+d="$(new_repo case10)"; cd "$d"
+mkdir -p .forge
+five_days_ago="$(date -u -v-5d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '-5 days' +%Y-%m-%dT%H:%M:%SZ)"
+cat > .forge/reservations.yml <<YML
+reservations:
+  - kind: nfr
+    id: NFR-001
+    milestone: m-x
+    reserved_at: "$five_days_ago"
+    summary: "5 days old, not max"
+  - kind: nfr
+    id: NFR-002
+    milestone: m-x
+    reserved_at: "$five_days_ago"
+    summary: "5 days old, MAX"
+YML
+git add -A && git commit -qm init
+"$HELPER" compact --days 14 >/dev/null 2>&1
+check "case10 --days 14 keeps a 5-day-old non-max row" \
+  "$(grep -c 'id: NFR-001' .forge/reservations.yml)" "1"
+d="$(new_repo case10b)"; cd "$d"
+mkdir -p .forge
+cat > .forge/reservations.yml <<YML
+reservations:
+  - kind: nfr
+    id: NFR-001
+    milestone: m-x
+    reserved_at: "$five_days_ago"
+    summary: "5 days old, not max"
+  - kind: nfr
+    id: NFR-002
+    milestone: m-x
+    reserved_at: "$five_days_ago"
+    summary: "5 days old, MAX"
+YML
+git add -A && git commit -qm init
+"$HELPER" compact --days 1 >/dev/null 2>&1
+if grep -q 'id: NFR-001' .forge/reservations.yml; then
+  fail "case10b --days 1 kept a 5-day-old non-max row it should have archived"
+else
+  pass "case10b --days 1 archives a 5-day-old non-max row"
+fi
+if grep -q 'id: NFR-002' .forge/reservations.yml; then
+  pass "case10b --days 1 still keeps the kind's max row"
+else
+  fail "case10b --days 1 dropped the kind's max row"
+fi
+
 # --- Report -----------------------------------------------------------------
 printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
 [ "$FAILED" -eq 0 ]

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

@@ -227,6 +227,7 @@ Resume:
 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.
+   - **On an EnterWorktree error/rejection** (not just tool absence) — e.g. a worktree→worktree relocation rejects the call under the tool's path constraint (ADR-010 roots live outside `.claude/worktrees/`) — fall back to the same printed `cd` instruction above, exactly as if the tool were unavailable.
    - 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.
 

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

@@ -157,6 +157,7 @@ Present the four resolutions and wait for an explicit choice:
 1. **Enter the worktree** *(recommended)* — relocate this session into the worktree **in place** (the operator no longer has to `cd` + re-run). This is the canonical **Native Worktree Entry** contract, reused verbatim at the `chief-of-staff` resume and `orchestrating` hand-back touch points:
    - **If the `EnterWorktree` tool is available**, call `EnterWorktree({path: {worktree_path}})` — always `{path}` into the recorded `lifecycle.worktree_path`, never `{name}` (Forge owns worktree creation; `{name}` would spawn a new one on the wrong branch convention). Then log one line — `Relocated into worktree {worktree_path} ({branch})` — **independent of any confirmation prompt**, so the cwd move is always visible in the transcript. Continue routing to the requested skill from inside the worktree: writes now land in the owner, and the ownership gate is satisfied because this session **is** the owner.
    - **If `EnterWorktree` is unavailable** (older Claude Code CLI, or a non-Claude-Code adapter), fall back to today's behavior: print the exact command (`cd {worktree_path}` then `/forge`); re-running there anchors to this milestone and writes land in the owner. This session does nothing further to the milestone.
+   - **On an EnterWorktree error/rejection** (not just tool absence) — e.g. a worktree→worktree relocation rejects the call under the tool's path constraint (ADR-010 roots live outside `.claude/worktrees/`) — fall back to the same printed `cd` instruction above, exactly as if the tool were unavailable.
    - Exit is always `ExitWorktree({action: "keep"})` — Forge never lets the native tool **remove** a worktree; teardown stays option 3 / `git worktree remove`.
 2. **Sync, then continue in the worktree** — bring main's commits in (`git -C {worktree_path} rebase main`, or merge), then work from the worktree. Use when main has changes the worktree needs first.
 3. **Retire the worktree** — only if it is dead/superseded. Close the stream, `git worktree remove {worktree_path}`, and clear `lifecycle.worktree_*` on the milestone — which ends its ownership so main may write. **Confirm before removing; never auto-remove a worktree.**
@@ -178,17 +179,18 @@ Check `.forge/refactor-backlog.yml`:
 **Promotion procedure (effort: standard only):**
 
 1. Read backlog item `id` (e.g. `R61-002`). Synthesize milestone id `m-{R-id}` (e.g. `m-R61-002`).
-2. **Enter the worktree first (R10 — this runs in Step 1, *before* Step 3's routing gate fires, so do not assume a worktree already exists):** if this session is still on the main checkout (`git rev-parse --git-dir` == `--git-common-dir`), `EnterWorktree` now; if R10 already entered one, this is simply the first write in it. Then write the declaration (`.forge/templates/streams/stream.yml` → `.forge/streams/{stream}.yml` — `stream.goal`, `stream.milestone: m-{R-id}`, `stream.status: draft`, `stream.tier: standard`, `runtime.branch`/`runtime.worktree` from the worktree just entered, best-known `ownership.owned_surfaces`/`shared_surfaces`) as the worktree's first commit and fast-forward-push it, per FORGE.md's Stream Integration Checkpoints intake-declaration trigger.
-3. Copy `.forge/templates/state/milestone.yml` → `.forge/state/milestone-{m-R-id}.yml`. Populate:
+2. **Re-check status before writing anything.** Re-read the item's current `status`/`promoted_to` from `.forge/refactor-backlog.yml` (the copy read for the "{N} refactors" prompt may be stale). If `status: in_progress` or `promoted_to` is already set, short-circuit: *"{R-id} already in_progress (promoted to {promoted_to})."* — no declaration, no milestone file, no roadmap append.
+3. **Enter the worktree first (R10 — this runs in Step 1, *before* Step 3's routing gate fires, so do not assume a worktree already exists):** if this session is still on the main checkout (`git rev-parse --git-dir` == `--git-common-dir`), `EnterWorktree` now; if R10 already entered one, this is simply the first write in it. Then write the declaration (`.forge/templates/streams/stream.yml` → `.forge/streams/{stream}.yml` — `stream.goal`, `stream.milestone: m-{R-id}`, `stream.status: draft`, `stream.tier: standard`, `runtime.branch`/`runtime.worktree` from the worktree just entered, best-known `ownership.owned_surfaces`/`shared_surfaces`) as the worktree's first commit and fast-forward-push it, per FORGE.md's Stream Integration Checkpoints intake-declaration trigger.
+4. Copy `.forge/templates/state/milestone.yml` → `.forge/state/milestone-{m-R-id}.yml`. Populate:
    - `milestone.id: m-{R-id}`
    - `milestone.name: "Promoted from {R-id}: {backlog item title}"`
    - `milestone.origin: {R-id}`
    - `current.tier: standard`, `current.status: researching`
    - `current.last_updated: {ISO date}`
-4. Run **Rollup (1.0)** — regenerates `index.yml` from the new milestone file (do not hand-append the registry entry). New milestone id is `m-{R-id}` from step 1; for numeric ids, allocate via `id=$(.claude/hooks/forge-reserve.sh milestone --milestone m-new)` (ADR-023) — never scan `milestone-*.yml` for max+1 inline. The three milestone-id call sites (here, `discussing`, `prototyping`) share this ledger-backed allocator so they cannot disagree, and it scans live **+ archived** milestones so a burned id is never reused.
-5. Append to `.forge/roadmap.yml` — one milestone entry + one phase (`refactor-{R-id}`, `requirements_source: refactor-backlog.yml#{R-id}`, `dependencies: []`).
-6. Update `.forge/refactor-backlog.yml` item: `status: in_progress`, add `promoted_to: m-{R-id}`.
-7. Confirm: *"Promoted {R-id} → milestone m-{R-id}. State + roadmap created. Routing to researching."*
+5. Run **Rollup (1.0)** — regenerates `index.yml` from the new milestone file (do not hand-append the registry entry). New milestone id is `m-{R-id}` from step 1; for numeric ids, allocate via `id=$(.claude/hooks/forge-reserve.sh milestone --milestone m-new)` (ADR-023) — never scan `milestone-*.yml` for max+1 inline. The three milestone-id call sites (here, `discussing`, `prototyping`) share this ledger-backed allocator so they cannot disagree, and it scans live **+ archived** milestones so a burned id is never reused.
+6. Append to `.forge/roadmap.yml` — one milestone entry + one phase (`refactor-{R-id}`, `requirements_source: refactor-backlog.yml#{R-id}`, `dependencies: []`).
+7. Update `.forge/refactor-backlog.yml` item: `status: in_progress`, add `promoted_to: m-{R-id}`.
+8. Confirm: *"Promoted {R-id} → milestone m-{R-id}. State + roadmap created. Routing to researching."*
 
 ```text
 backlog pickup → effort: standard

package/template/.claude/skills/notion-integration/SKILL.md

@@ -39,6 +39,7 @@ Single Notion database (topology: one workspace, per-repo views). Rows are Forge
 Every property has exactly one owner. **`render()` writes ONLY agent-owned properties**, addressed by `Forge ID`, and issues **no write, ever** to a human-owned property. Non-overlapping ownership ⇒ **overwrite-on-render is safe by construction** (a hand-edited agent-owned cell is corrected at the next render; a human-owned cell is never touched).
 
 - **Agent-owned** (overwritten every render): `Forge ID`, `Name`, `Layer`, `Status`, `Tier`, `Progress`, `Blockers`, `Parent`, `Rollup Summary`, `Release State`, `Repo`, `Last Rendered`.
+  - `Blockers`, `Parent`, and `Rollup Summary` are **reserved, not yet populated**: at the current milestone-only scope the renderer emits them empty (`blockers: []`, `parent: null`, no `rollup_summary`) — they gain real values only when finer-grained rows land (DEF-044/045). Ownership is declared now so the schema doesn't shift later (R084).
 - **Human-owned** (read as inbox proposals in `pull_inbox`, **never** written): `Priority`, `Queue Position`, `Triage Notes`, `Comments`.
 
 **No gate-read property exists.** Nothing on the board is read by any merge/deploy/promotion/fold path (acceptance test #6).

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

@@ -101,7 +101,7 @@ Never write to top-level `.forge/requirements.yml` -- that path is deprecated.
 
 ## Step 5: Create or Update Roadmap
 
-`.forge/roadmap.yml` is **multi-milestone by design** -- see `.forge/templates/roadmap.yml`. Top-level `milestones:` lists each milestone with its phase numbers; top-level `phases:` lists every phase. Phase IDs are scoped per-milestone via the dir naming `m{milestone_id}-{phase_num}-{name}/`, so phase `id: 1` can exist in m50 and m51 without collision.
+`.forge/roadmap.yml` is **multi-milestone by design** -- see `.forge/templates/roadmap.yml`. Top-level `milestones:` lists each milestone with its phase numbers; top-level `phases:` lists every phase. **Phase ids and wave numbers are GLOBAL shared spaces** (the `waves:` map keys phases globally), and under the declaration split a sibling worktree's allocations are invisible until its checkpoint — so **allocate every new phase id via `id=$(.claude/hooks/forge-reserve.sh phase --milestone <id>)` and every new wave number via `forge-reserve wave`** (strip the `P-`/`W-` prefix for the bare int written into roadmap.yml; N phases = N calls). NEVER scan-and-increment and NEVER hand-write an "allocated above true max" reconcile guard — the ledger sees sibling worktrees' unlanded claims; a guard structurally cannot (4x collision desire path, ADR-029).
 
 **Never overwrite existing roadmap content.** Read first, then route on three cases:
 
@@ -131,7 +131,7 @@ This is the common case when starting a new milestone alongside an existing one.
      name: "{milestone name from state/milestone-{N}.yml}"
      phases: [{list of phase ids you are about to add}]
    ```
-2. Append each new phase under `roadmap.phases:` with IDs scoped to this milestone (start at `1`, ignore IDs used by other milestones -- dir naming prevents collision).
+2. Append each new phase under `roadmap.phases:` with an id from `forge-reserve phase` (bare int in the roadmap; ids are globally unique across all milestones — ADR-029). Wave assignments take their numbers from `forge-reserve wave` the same way.
 3. Recompute `coverage_verified` against the union of all active milestones' `requirements/m{N}.yml` files. Every FR-ID in the active milestone must map to exactly one phase in that milestone.
 4. Update `waves:` only with the new milestone's phase wave assignments. Leave other milestones' wave entries alone.
 
@@ -473,7 +473,7 @@ Done when approved.
 ## Handoff
 
 1. **Persist** -- plans `.forge/phases/`, reqs `.forge/requirements/m{N}.yml`, roadmap `.forge/roadmap.yml`, context `.forge/context.md`
-2. **Reserve version (if delivery bumps the version)** -- if any plan in this milestone will bump `package.json`/the project version, append ONE entry to `.forge/releases.yml` (Version Reservation Protocol, FORGE.md): pull first, set `version` = highest reserved `max()` bumped by this change's semver level, append `{milestone, version, bump, reserved_at, summary}`. **Never edit prior entries.** No version bump in scope → skip. Surface the reserved number to the user.
+2. **Reserve version (if delivery bumps the version)** -- if any plan in this milestone will bump `package.json`/the project version: pull first, derive `version` = highest reserved `max()` bumped by this change's semver level, then **claim it in the ledger BEFORE editing releases.yml**: `.claude/hooks/forge-reserve.sh version --value <X.Y.Z> --milestone m-{N}` — a non-zero exit names the sibling milestone already holding that number (its reservation may be worktree-only and invisible in any file you can read): re-read `max()` counting the ledger's version claims and bump again (ADR-029). Then append ONE entry to `.forge/releases.yml` (Version Reservation Protocol, FORGE.md): `{milestone, version, bump, reserved_at, summary}`. **Never edit prior entries.** No version bump in scope → skip. Surface the reserved number to the user.
 3. **State** -- `current.status` = `executing` in `.forge/state/milestone-{id}.yml`
 4. **State-sync commit** (State Commit Protocol): `git -C {worktree_path} add .forge/` then `git -C {worktree_path} commit -m "chore(forge): sync state after planning — m{N} {phase-name}"` (worktree form — recorded `lifecycle.worktree_path` is authoritative over cwd; see FORGE.md State Commit Protocol. Scoped; never `git add .`). The `releases.yml` reservation rides in this commit — **push it** so a parallel session sees the number taken before they reserve.
 5. *"Plan written and synced. `/clear` then `/forge` to continue."*

package/template/.forge/FORGE.md

@@ -127,12 +127,12 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | `streams/{stream}.yml` | 15 KB | Stream state stays resumable without becoming history |
 | `streams/{stream}/brief.md` | 8 KB | Context packet must fit into active session context |
 | `streams/{stream}/packages/{id}.yml` | 10 KB | Delegated work contract stays bounded |
-| `reservations.yml` | 50 KB | One short line per reserved id |
+| `reservations.yml` | 50 KB | Compacts to `reservations-archive.yml` via `forge-reserve compact` — per-kind max + 14-day tail retained |
 | `prototypes/{slug}.md` | 8 KB | Current question + terse iteration log; terminal items archive |
 
 ### Accumulating Artifacts
 
-Every new accumulating artifact declares: owner, size gate, archive/compaction rule, `derived` vs source-of-truth status, and migration behavior. Defaults: `roadmap.yml`, `requirements/*.yml`, `releases.yml`, `reservations.yml` are source-of-truth — load scoped slices, not whole history. `phases/`, `audits/`, `research/`, `archive/`, `context-archive.md` are historical — load only by milestone/stream/package/version. `prototypes/{slug}.md` is single-owner mutable while `exploring|parked`; terminal statuses archive to `prototypes/archive/`. Runtime/generated files (`.mcp-server/*.db*`, logs, spike DBs, `.git/forge/*`) are excluded from framework context unless debugging them. The board (ADR-025): `.forge/notion/map.yml` is derived, git-ignored, rebuildable; board config is the `board:` block in `project.yml` (absent ⇒ inert). Template copies sync mechanically — not separate concepts.
+Every new accumulating artifact declares: owner, size gate, archive/compaction rule, `derived` vs source-of-truth status, and migration behavior. Defaults: `roadmap.yml`, `requirements/*.yml`, `releases.yml`, `reservations.yml` are source-of-truth — load scoped slices, not whole history. `phases/`, `audits/`, `research/`, `archive/`, `context-archive.md`, `reservations-archive.yml` are historical — load only by milestone/stream/package/version (R104: `reservations-archive.yml` holds every row `forge-reserve compact` has dropped from `reservations.yml`, verbatim; the working file alone still carries every kind's floor). `prototypes/{slug}.md` is single-owner mutable while `exploring|parked`; terminal statuses archive to `prototypes/archive/`. Runtime/generated files (`.mcp-server/*.db*`, logs, spike DBs, `.git/forge/*`) are excluded from framework context unless debugging them. The board (ADR-025): `.forge/notion/map.yml` is derived, git-ignored, rebuildable; board config is the `board:` block in `project.yml` (absent ⇒ inert). Template copies sync mechanically — not separate concepts.
 
 ### Fresh Agent Pattern
 Task touches 20+ files or complex subsystem → spawn fresh executor with isolated context. Prevents context rot.
@@ -204,7 +204,7 @@ State lives in `.forge/`. One line per artifact; protocol detail lives in the na
 - `phases/milestone-{id}/{phase}-{name}/plan-{NN}.md` — task plans with must_haves frontmatter (`{id}`=milestone, `{phase}`=phase# verbatim, `{name}`=kebab, `{NN}`=seq)
 - `refactor-backlog.yml` — refactoring catalog worked via quick-tasking; status vocab `pending | in_progress | done | dismissed | deferred`; terminal items auto-archive to `refactor-backlog-archive.yml` on the next reviewing/quick-tasking write
 - `releases.yml` — append-only version-reservation registry (Version Reservation Protocol)
-- `reservations.yml` — append-only id-reservation audit trail + cross-machine floor (ID Reservation Protocol)
+- `reservations.yml` — append-only id-reservation audit trail + cross-machine floor (ID Reservation Protocol); `forge-reserve compact` (R104) moves dropped rows verbatim to `reservations-archive.yml`, retaining each kind's max + a 14-day tail
 - `archive/milestone-{id}/` — archived milestone artifacts (archive-delete)
 - `prototypes/{slug}.md` — resumable disposable-mockup state (`exploring | parked | graduated | discarded`); terminal → `prototypes/archive/`. Single-owner, one driver. See `Skill(prototyping)`.
 
@@ -250,11 +250,11 @@ Ownership rules (quick reference):
 
 ### Version Reservation Protocol
 
-The project version + CHANGELOG slot are shared resources — `.forge/releases.yml` (append-only) removes the number from per-milestone scope. **Reserve early, at planning**: append ONE `{milestone, version, bump, reserved_at, summary}` entry — the highest reserved version bumped by this change's semver level — and **commit + push the reservation BEFORE editing the version file** so a parallel session sees the number taken. Never edit prior entries. **Delivery never invents a number** — write only the reserved version; no reservation → reserve at delivery (pull, `max() + bump`, append, push, then write). **Race:** the second push rebases onto the first (append-only → clean), re-reads `max()`, takes the next number. **Bump criteria (0.x):** patch = bug fix/doc/sync/refinement; minor = new skill/agent/routing-row/auto-trigger/state-artifact/capability; major = post-1.0 breaking. Default to minor when in doubt — a capability shipped as a patch drifts the version away from truth.
+The project version + CHANGELOG slot are shared resources — `.forge/releases.yml` (append-only) removes the number from per-milestone scope. **Reserve early, at planning**: derive `max() + bump`, **claim it in the ledger first** — `forge-reserve version --value <X.Y.Z>` (record-only; a conflict names the sibling milestone holding the number, its claim possibly worktree-only — re-read and re-bump; ADR-029) — then append ONE `{milestone, version, bump, reserved_at, summary}` entry and **commit + push the reservation BEFORE editing the version file** so a parallel session sees the number taken. Never edit prior entries. **Delivery never invents a number** — write only the reserved version; no reservation → reserve at delivery (pull, `max() + bump`, append, push, then write). **Race:** the second push rebases onto the first (append-only → clean), re-reads `max()`, takes the next number. **Bump criteria (0.x):** patch = bug fix/doc/sync/refinement; minor = new skill/agent/routing-row/auto-trigger/state-artifact/capability; major = post-1.0 breaking. Default to minor when in doubt — a capability shipped as a patch drifts the version away from truth.
 
 ### ID Reservation Protocol
 
-Sequential ids — `ADR-NNN`, `DEF-NNN`, `FR-`/`NFR-NNN`, milestone `M-NN`, refactor `R0NN` — are shared cross-worktree resources; scan-and-increment sees only committed state, so concurrent worktrees claim the same number and collide silently until merge. **Reserve with the helper before creating the artifact**: `forge-reserve <kind> --milestone <id> [--summary <text>]` (`.claude/hooks/forge-reserve.sh`, kinds `adr|def|fr|nfr|milestone|refactor`; id formats per [ADR-023](../docs/decisions/ADR-023-extend-id-reservation-to-milestone-refactor-ids.md)) prints the id and dual-writes the **machine-local ledger** (`.git/forge/id-reservations`, git common dir — the same-machine coordination point, written under a `mkdir` lock) plus the tracked `.forge/reservations.yml` (durable audit trail + cross-machine floor; the caller commits it with the work). **Next number = `max(ledger ∪ in-tree ∪ main:reservations.yml) + 1`** per kind — the in-tree scan includes archives, so a compacted id is never reallocated. Reserve points: `architecting` (adr), `planning` (fr/nfr/def), `forge` Rollup / `discussing` / `prototyping` (milestone), `reviewing` (refactor). Deferred issues are counter-free per-issue files (`.forge/deferred-issues/{date}-{milestone}-{slug}.md`) — no DI-NNN, nothing to collide on. Accepted gap: concurrent reserves on *different machines* fall back to merge-time renumber, bounded by the floor. On any residual collision (legacy/un-reserved ids), **keep the older milestone's id and renumber the newer**. Lazy migration — the ledger self-creates on first reserve. Full rationale: [ADR-021](../docs/decisions/ADR-021-id-reservation-ledger-git-common-dir.md) (supersedes ADR-016) + ADR-023. Versions stay in `releases.yml` (separate semver/CHANGELOG semantics).
+Sequential ids — `ADR-NNN`, `DEF-NNN`, `FR-`/`NFR-NNN`, milestone `M-NN`, refactor `R0NN`, roadmap phase/wave numbers — are shared cross-worktree resources; scan-and-increment sees only committed state, so concurrent worktrees claim the same number and collide silently until merge. **Reserve with the helper before creating the artifact**: `forge-reserve <kind> --milestone <id> [--summary <text>]` (`.claude/hooks/forge-reserve.sh`, kinds `adr|def|fr|nfr|milestone|refactor|phase|wave|version`; id formats per [ADR-023](../docs/decisions/ADR-023-extend-id-reservation-to-milestone-refactor-ids.md) + ADR-029 — phase/wave registry tokens are `P-0NN`/`W-0NN` while roadmap.yml keeps bare ints; `version` is record-only via `--value` (the ledger makes in-flight claims sibling-visible; `releases.yml` stays the durable registry)) prints the id and dual-writes the **machine-local ledger** (`.git/forge/id-reservations`, git common dir — the same-machine coordination point, written under a `mkdir` lock) plus the tracked `.forge/reservations.yml` (durable audit trail + cross-machine floor; the caller commits it with the work). **Next number = `max(ledger ∪ in-tree ∪ main:reservations.yml) + 1`** per kind — the in-tree scan includes archives, so a compacted id is never reallocated. Reserve points: `architecting` (adr), `planning` (fr/nfr/def, phase/wave, version), `forge` Rollup / `discussing` / `prototyping` (milestone), `reviewing` (refactor). Deferred issues are counter-free per-issue files (`.forge/deferred-issues/{date}-{milestone}-{slug}.md`) — no DI-NNN, nothing to collide on. Accepted gap: concurrent reserves on *different machines* fall back to merge-time renumber, bounded by the floor. On any residual collision (legacy/un-reserved ids), **keep the older milestone's id and renumber the newer**. Lazy migration — the ledger self-creates on first reserve. Full rationale: [ADR-021](../docs/decisions/ADR-021-id-reservation-ledger-git-common-dir.md) (supersedes ADR-016) + ADR-023 + ADR-029. Versions stay in `releases.yml` (separate semver/CHANGELOG semantics); the ledger only carries their claims.
 
 ## Deviation Rules
 

package/template/.forge/checks/forge-board-render.sh

@@ -43,8 +43,12 @@ FOLD="$ROOT/.forge/checks/forge-release-fold.sh"
 # JSON string escaping (POSIX; escapes \, ", and control chars via tab/newline).
 # ---------------------------------------------------------------------------
 json_escape() {
-  # reads $1, prints a JSON-safe string body (no surrounding quotes)
-  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' | tr '\n' ' '
+  # reads $1, prints a JSON-safe string body (no surrounding quotes). Raw C0
+  # controls other than tab/newline/CR are dropped FIRST — a stray control char
+  # must not yield invalid JSON that jq then rejects, silently skipping the unit
+  # in --deliver (R081); tab escapes, newline AND CR (CRLF checkouts) → spaces.
+  printf '%s' "$1" | tr -d '\000-\010\013\014\016-\037' \
+    | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' | tr '\n\r' '  '
 }
 
 # Milestone-file id → unit id. Numeric files (milestone-8.yml) need the m-
@@ -56,18 +60,8 @@ unit_id() {
 # ---------------------------------------------------------------------------
 # Config: read a scalar under the top-level `board:` block of project.yml.
 # ---------------------------------------------------------------------------
-board_cfg() { # $1 = key under board:
-  [ -f "$PROJECT" ] || return 0
-  awk -v k="$1" '
-    /^board:/ { inb=1; next }
-    inb && /^[A-Za-z]/ { inb=0 }
-    inb && $0 ~ "^[[:space:]]+"k":" {
-      sub(/^[[:space:]]*[^:]+:[[:space:]]*/, "")
-      sub(/[[:space:]]*#.*/, "")
-      gsub(/^["'"'"']|["'"'"']$/, "")
-      print; exit
-    }
-  ' "$PROJECT"
+board_cfg() { # $1 = key under board: — same block/key/strip semantics as yget, so it IS yget (R082)
+  yget "$PROJECT" board "$1"
 }
 
 board_enabled() { # 0 = enabled, 1 = disabled
@@ -97,7 +91,7 @@ yget() { # $1=file $2=parent $3=key  → scalar value of parent.key
 # The fold prints `release_state=<state> [reason=<code>]`; take ONLY the state token.
 unit_release_state() { # $1 = unit id (e.g. m-32)
   rs=""
-  if [ -x "$FOLD" ] || [ -f "$FOLD" ]; then
+  if [ -f "$FOLD" ]; then   # always run via `sh` below — an -x check was dead weight (R082)
     rs=$(sh "$FOLD" "$1" 2>/dev/null | sed -n 's/^release_state=\([A-Za-z_-]*\).*/\1/p' | head -1)
   fi
   [ -n "$rs" ] || { rs="unknown"; printf 'board-render: release fold unavailable for %s — release_state: unknown\n' "$1" >&2; }
@@ -214,6 +208,9 @@ emit_projection() {
     rstate=$(unit_release_state "$unit")
     prog=$(unit_progress "$id" "$cphase" "$status")
     [ "$ufirst" = 1 ] && ufirst=0 || printf ',\n'
+    # blockers/parent hardcoded empty and rollup_summary not emitted: Parent,
+    # Blockers, Rollup Summary are RESERVED properties at the milestone-only
+    # scope — they populate when finer-grained rows land (DEF-044/045; R084).
     printf '    {"forge_id": "%s", "layer": "Milestone", "name": "%s", "status": "%s", "release_state": "%s", "tier": "%s", "progress": "%s", "blockers": [], "parent": null}' \
       "$unit" "$(json_escape "$nm")" "$(json_escape "$status")" "$(json_escape "$rstate")" "$(json_escape "$tier")" "$(json_escape "$prog")"
   done
@@ -240,10 +237,16 @@ NOTION_VERSION="2022-06-28"
 
 log_deliver() { printf 'board-render: %s\n' "$1" >&2; }
 
+# The env-var NAME holding the token — board.ci_token_env, default FORGE_NOTION_TOKEN.
+# Single source for the default (R082); the token VALUE never passes through here.
+token_env_name() {
+  var="$(board_cfg ci_token_env)"; [ -n "$var" ] || var="FORGE_NOTION_TOKEN"
+  printf '%s' "$var"
+}
+
 # The token, read by DYNAMIC env-var name via awk ENVIRON — never eval, never a file.
 deliver_token() {
-  var="$(board_cfg ci_token_env)"; [ -n "$var" ] || var="FORGE_NOTION_TOKEN"
-  awk -v n="$var" 'BEGIN { v = ENVIRON[n]; if (v != "") print v }'
+  awk -v n="$(token_env_name)" 'BEGIN { v = ENVIRON[n]; if (v != "") print v }'
 }
 
 # curl wrapper. Prints "<response-body>\n<http_code>" (code is the LAST line).
@@ -311,7 +314,7 @@ unit_properties() { # stdin unit  $1 repo  $2 ts  $3 set_forge_id
 
 deliver_headless() {
   board_enabled || { log_deliver "board disabled (board.enabled != true) — deliver skipped"; return 0; }
-  var="$(board_cfg ci_token_env)"; [ -n "$var" ] || var="FORGE_NOTION_TOKEN"
+  var="$(token_env_name)"
   tok="$(deliver_token)"
   [ -n "$tok" ] || { log_deliver "token env \$$var unset — deliver skipped (non-blocking)"; return 0; }
   db="$(board_cfg database_id)"