forge-orkes 0.72.2 → 0.74.0

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

@@ -2,7 +2,7 @@
 # forge-reserve — allocate a collision-safe sequential id (ADR/DEF/FR/NFR/
 # milestone/refactor/phase/wave) or record a version claim.
 #
-# Implements ADR-021: the coordination point is a machine-local ledger in the
+# Implements ADR-021: the coordination point is a per-machine 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
@@ -11,6 +11,16 @@
 #   forge-reserve <kind> --milestone <id> [--summary <text>] [--value <X.Y.Z>]
 #     kind ∈ {adr|def|fr|nfr|milestone|refactor|phase|wave|version}
 #
+#   forge-reserve compact [--days N]
+#     R104: floor-preserving compaction of .forge/reservations.yml. Explicit
+#     invocation only — the reserve paths above NEVER auto-compact. Per kind,
+#     keeps the max-id row (the only row the arm (c) floor below needs) plus
+#     any row reserved in the last N days (default 14; version rows use the
+#     same rule against semver, not a timestamp order). Everything else moves
+#     VERBATIM to .forge/reservations-archive.yml (append-only, created on
+#     first use). Idempotent — a second run with nothing newly stale archives
+#     nothing. Prints a one-line kept/archived/bytes summary to stderr.
+#
 # phase/wave (ADR-029): roadmap phase ids + wave numbers are GLOBAL shared
 # spaces (the waves block keys phases globally) — the exact scan-and-increment
 # collision class ADR-021/023 killed elsewhere, observed 4x (m-34 x2, m-39,
@@ -41,71 +51,99 @@ 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
 
+# R106: the 9-kind vocabulary lives here ONCE and feeds both runtime error
+# messages below. The usage comment (top of file) and the seeded reservations.yml
+# heredoc stay manually written — a quoted heredoc can't interpolate a variable.
+KINDS='adr|def|fr|nfr|milestone|refactor|phase|wave|version'
+
+# --- 0. compact subcommand short-circuit (R104) ------------------------------
+# Explicit invocation only — kept OUTSIDE the kind vocabulary above so a normal
+# reserve call can never accidentally trigger it. Parsed before the kind/
+# milestone requirements below, which do not apply to compact.
+compact_mode=0
+days=14
+if [ "${1:-}" = "compact" ]; then
+  compact_mode=1
+  shift
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --days) shift; days="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --days=*) days="${1#*=}"; shift ;;
+      *) printf 'forge-reserve: unknown compact argument: %s\n' "$1" >&2; exit 2 ;;
+    esac
+  done
+  case "$days" in
+    ''|*[!0-9]*) printf 'forge-reserve: --days must be a non-negative integer, got: %s\n' "$days" >&2; exit 2 ;;
+  esac
+fi
+
 # --- 1. parse args ----------------------------------------------------------
 kind=""
 milestone=""
 summary=""
 value=""
-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 ;;
-    --value) shift; value="${1:-}"; [ $# -gt 0 ] && shift || true ;;
-    --value=*) value="${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" ;;
-  milestone) prefix="M" ;;      # ADR-023 — unpadded (M-26); ids used bare across the framework
-  refactor)  prefix="R" ;;      # ADR-023 — zero-padded R0NN, matching the backlog format
-  phase)     prefix="P" ;;      # ADR-029 — registry token P-0NN; roadmap.yml keeps the bare int
-  wave)      prefix="W" ;;      # ADR-029 — registry token W-0NN; roadmap.yml keeps the bare int
-  version)   prefix="" ;;       # ADR-029 — record-only; id IS the --value string verbatim
-  "") printf 'forge-reserve: missing kind (adr|def|fr|nfr|milestone|refactor|phase|wave|version)\n' >&2; exit 2 ;;
-  *) printf 'forge-reserve: unknown kind: %s (expected adr|def|fr|nfr|milestone|refactor|phase|wave|version)\n' "$kind" >&2; exit 2 ;;
-esac
-[ -n "$milestone" ] || { printf 'forge-reserve: --milestone <id> is required\n' >&2; exit 2; }
-if [ "$kind" = "version" ] && [ -z "$value" ]; then
-  printf 'forge-reserve: version kind requires --value <X.Y.Z>\n' >&2; exit 2
-fi
+if [ "$compact_mode" -eq 0 ]; then
+  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 ;;
+      --value) shift; value="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --value=*) value="${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
 
-# Reject control characters in the caller-supplied fields BEFORE the lock or any
-# write. milestone + id are printf'd UNescaped into both the ledger TSV (\t-
-# separated) and reservations.yml below; a newline or tab would split the ledger
-# row or inject a sibling YAML key, and (for version) forge a holder record that
-# spoofs the conflict check. summary's YAML scalar breaks on a raw newline too.
-# Nothing is written yet, so exit 2 is clean.
-CR="$(printf '\r')"
-NL="$(printf '\nX')"; NL="${NL%X}"
-TAB="$(printf '\tX')"; TAB="${TAB%X}"
-for _pair in "milestone=$milestone" "value=$value" "summary=$summary"; do
-  case "${_pair#*=}" in
-    *"$NL"*|*"$TAB"*|*"$CR"*)
-      printf 'forge-reserve: control characters are not allowed in --%s\n' "${_pair%%=*}" >&2
-      exit 2 ;;
+  # 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" ;;
+    milestone) prefix="M" ;;      # ADR-023 — unpadded (M-26); ids used bare across the framework
+    refactor)  prefix="R" ;;      # ADR-023 — zero-padded R0NN, matching the backlog format
+    phase)     prefix="P" ;;      # ADR-029 — registry token P-0NN; roadmap.yml keeps the bare int
+    wave)      prefix="W" ;;      # ADR-029 — registry token W-0NN; roadmap.yml keeps the bare int
+    version)   prefix="" ;;       # ADR-029 — record-only; id IS the --value string verbatim
+    "") printf 'forge-reserve: missing kind (%s)\n' "$KINDS" >&2; exit 2 ;;
+    *) printf 'forge-reserve: unknown kind: %s (expected %s)\n' "$kind" "$KINDS" >&2; exit 2 ;;
   esac
-done
+  [ -n "$milestone" ] || { printf 'forge-reserve: --milestone <id> is required\n' >&2; exit 2; }
+  if [ "$kind" = "version" ] && [ -z "$value" ]; then
+    printf 'forge-reserve: version kind requires --value <X.Y.Z>\n' >&2; exit 2
+  fi
+
+  # Reject control characters in the caller-supplied fields BEFORE the lock or any
+  # write. milestone + id are printf'd UNescaped into both the ledger TSV (\t-
+  # separated) and reservations.yml below; a newline or tab would split the ledger
+  # row or inject a sibling YAML key, and (for version) forge a holder record that
+  # spoofs the conflict check. summary's YAML scalar breaks on a raw newline too.
+  # Nothing is written yet, so exit 2 is clean.
+  CR="$(printf '\r')"
+  NL="$(printf '\nX')"; NL="${NL%X}"
+  TAB="$(printf '\tX')"; TAB="${TAB%X}"
+  for _pair in "milestone=$milestone" "value=$value" "summary=$summary"; do
+    case "${_pair#*=}" in
+      *"$NL"*|*"$TAB"*|*"$CR"*)
+        printf 'forge-reserve: control characters are not allowed in --%s\n' "${_pair%%=*}" >&2
+        exit 2 ;;
+    esac
+  done
 
-# version --value is the id verbatim (record-only kind), so it must match the
-# advertised X.Y.Z semver shape (optional -pre / +build) — enforce the contract
-# before the lock rather than writing an arbitrary string into the registries.
-if [ "$kind" = "version" ] \
-   && ! printf '%s' "$value" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.]+)?$'; then
-  printf 'forge-reserve: version --value must be X.Y.Z semver, got: %s\n' "$value" >&2
-  exit 2
+  # version --value is the id verbatim (record-only kind), so it must match the
+  # advertised X.Y.Z semver shape (optional -pre / +build) — enforce the contract
+  # before the lock rather than writing an arbitrary string into the registries.
+  if [ "$kind" = "version" ] \
+     && ! printf '%s' "$value" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.]+)?$'; then
+    printf 'forge-reserve: version --value must be X.Y.Z semver, got: %s\n' "$value" >&2
+    exit 2
+  fi
 fi
 
 # --- 2. resolve paths -------------------------------------------------------
@@ -115,13 +153,14 @@ mkdir -p "$common/forge"
 ledger="$common/forge/id-reservations"
 lock="$common/forge/id-reservations.lock"
 reservations="$top/.forge/reservations.yml"
+archive="$top/.forge/reservations-archive.yml"
 
-# reservations.yml is committed, semi-trusted repo content (sibling worktrees
-# write it). Refuse to write THROUGH a symlink — a symlinked target would
-# redirect our seed/append to an arbitrary path with partly caller-supplied
-# content. Absent or a regular file → proceed. Checked before the lock so a
-# hostile target fails fast having written nothing.
-for _p in "$ledger" "$reservations"; do
+# reservations.yml (and its compaction archive) is committed, semi-trusted repo
+# content (sibling worktrees write it). Refuse to write THROUGH a symlink — a
+# symlinked target would redirect our seed/append to an arbitrary path with
+# partly caller-supplied content. Absent or a regular file → proceed. Checked
+# before the lock so a hostile target fails fast having written nothing.
+for _p in "$ledger" "$reservations" "$archive"; do
   if [ -L "$_p" ]; then
     printf 'forge-reserve: refusing to write through symlink: %s\n' "$_p" >&2
     exit 2
@@ -135,18 +174,252 @@ 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) ----------
+# --- computed-kinds id allocation: three-way max(ledger ∪ in-tree ∪
+# main:reservations.yml) + 1, then per-kind id format (ADR-023, ADR-029).
+# Version never calls this — it records --value verbatim under the lock
+# (section 4 below). Reads the globals set during arg-parsing (kind, prefix)
+# and path resolution (top, ledger); prints the allocated id on stdout.
+compute_id() {
+  # 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).
+  # Extract the trailing number by stripping non-digits, NOT by split on "-": refactor
+  # ids (R100) carry no hyphen (ADR-023), so a hyphen-split would read them as 0 and
+  # reallocate a live id. gsub handles ADR-014, M-26, R100, FR-023, P-066 uniformly.
+  ledger_max=0
+  if [ -f "$ledger" ]; then
+    ledger_max="$(awk -F'\t' -v k="$kind" \
+      '$1==k { x=$2; gsub(/[^0-9]/,"",x); n=x+0; if(n>m)m=n } END{print m+0}' "$ledger")"
+  fi
+
+  # (b) in-tree — landed ids in THIS worktree. Exact-prefix match in awk ($1==p) so
+  # FR does not swallow NFR (FR is a substring of NFR). milestone + refactor (ADR-023)
+  # and phase (ADR-029) each scan BOTH live and archive locations so a burned id is
+  # never reallocated.
+  case "$kind" in
+    adr)
+      intree_max="$(ls "$top/docs/decisions" 2>/dev/null \
+        | awk -F- '/^ADR-[0-9]/ { n=$2+0; if(n>m)m=n } END{print m+0}')"
+      ;;
+    milestone)
+      # live state/milestone-<N>.yml  ∪  archived .forge/archive/milestone-<N>/
+      intree_max="$( { ls "$top/.forge/state"/milestone-*.yml 2>/dev/null; \
+                       ls -d "$top/.forge/archive"/milestone-*/ 2>/dev/null; } \
+        | grep -oE 'milestone-[0-9]+' \
+        | awk -F- '{ n=$2+0; if(n>m)m=n } END{print m+0}')"
+      ;;
+    refactor)
+      # live refactor-backlog.yml  ∪  refactor-backlog-archive.yml
+      intree_max="$(grep -hoE 'R[0-9]+' \
+          "$top/.forge/refactor-backlog.yml" \
+          "$top/.forge/refactor-backlog-archive.yml" 2>/dev/null \
+        | awk '{ n=substr($0,2)+0; if(n>m)m=n } END{print m+0}')"
+      ;;
+    phase)
+      # live roadmap.yml `- id: N` lines  ∪  archived phase dirs
+      # .forge/archive/milestone-*/phases/<N>-*. The roadmap scan deliberately
+      # takes ALL bare-int `- id:` values (milestone AND phase entries share the
+      # indent): over-counting can only RAISE the floor — safe; an under-count
+      # (a missed phase id) reintroduces the collision. Quoted milestone ids
+      # ("m-42") don't match the bare-int pattern. Archive-delete removes a
+      # milestone's roadmap entries, so the archive arm is what keeps its phase
+      # ids burned (ADR-029, mirroring the milestone arm above).
+      intree_max="$( { cat "$top/.forge/roadmap.yml" 2>/dev/null; \
+                       ls "$top/.forge/archive"/milestone-*/phases/ 2>/dev/null; } \
+        | awk '/^[ ]*- id: [0-9]+/ { n=$3+0; if(n>m)m=n }
+               /^[0-9]+-/ { x=$0; sub(/-.*/,"",x); n=x+0; if(n>m)m=n }
+               END{print m+0}')"
+      ;;
+    wave)
+      # live roadmap.yml waves-map KEYS only (`  N: [...]`) — never the phase ids
+      # inside the brackets. No archive arm: waves are removed with their roadmap
+      # entry on archive-delete; ledger + main floor cover the gap (ADR-029).
+      intree_max="$(cat "$top/.forge/roadmap.yml" 2>/dev/null \
+        | awk '/^[ ]+[0-9]+:[ ]*\[/ { k=$1; gsub(/[^0-9]/,"",k); n=k+0; if(n>m)m=n } END{print m+0}')"
+      ;;
+    *)
+      intree_max="$(grep -rhoE '[A-Z]+-[0-9]+' "$top/.forge/requirements/" 2>/dev/null \
+        | awk -F- -v p="$prefix" '$1==p { n=$2+0; if(n>m)m=n } END{print m+0}')"
+      ;;
+  esac
+
+  # (c) main:reservations.yml — cross-machine / cold-start floor (survives a
+  # .git/forge wipe; carries another machine's MERGED reservations). Absent → 0.
+  # Hyphen is OPTIONAL in the token ([A-Z]+-?[0-9]+): refactor ids (R100) carry none
+  # (ADR-023), so requiring a hyphen would hide them and drop the floor to 0. Split the
+  # alpha prefix from the digits in awk so R does not match e.g. FR (anchor ^prefix$).
+  main_max="$(git show main:.forge/reservations.yml 2>/dev/null \
+    | grep -oE '[A-Z]+-?[0-9]+' \
+    | awk -v p="$prefix" '{ a=$0; sub(/[-0-9].*$/,"",a); d=$0; gsub(/[^0-9]/,"",d);
+                            if(a==p){ n=d+0; if(n>m)m=n } } END{print m+0}')"
+  [ -n "$main_max" ] || main_max=0
+
+  next="$(awk -v a="$ledger_max" -v b="$intree_max" -v c="$main_max" \
+    'BEGIN{m=a; if(b>m)m=b; if(c>m)m=c; print m+1}')"
+  # Per-kind id format (ADR-023, ADR-029). The prefix-hyphen-paddednumber form
+  # (ADR-021's ADR-014, FR-023) is NOT universal:
+  #   milestone → M-26  : hyphen, UNPADDED — ids are used bare (milestone-26.yml, m-26)
+  #   refactor  → R064  : NO hyphen, zero-padded 3-wide — matches the backlog convention
+  #   adr/def/fr/nfr/phase/wave → ADR-014, P-066, W-046 : hyphen, zero-padded 3-wide
+  case "$kind" in
+    milestone) id="$(printf '%s-%d' "$prefix" "$next")" ;;
+    refactor)  id="$(printf '%s%03d' "$prefix" "$next")" ;;
+    *)         id="$(printf '%s-%03d' "$prefix" "$next")" ;;
+  esac
+  printf '%s\n' "$id"
+}
+
+# --- compact subcommand: floor-preserving rewrite of reservations.yml (R104) -
+# Per kind, keeps (a) the highest-id row — the ONLY row compute_id's arm (c)
+# three-way max above needs, so the floor is unchanged by construction — and
+# (b) any row reserved within the last $days days (default 14). Everything
+# else moves VERBATIM to reservations-archive.yml. Runs entirely inside one
+# awk pass (recency is a plain string compare against a same-width ISO8601
+# cutoff — no per-row date parsing needed) so there is nothing to keep in sync
+# between two scans. Called under the same mkdir lock as a normal reserve
+# (section 3), so it can never race a concurrent append. Reads/sets the
+# globals from sections 0/2: days, reservations, archive.
+do_compact() {
+  if [ ! -f "$reservations" ]; then
+    printf 'forge-reserve: nothing to compact — %s does not exist\n' "$reservations" >&2
+    return 0
+  fi
+
+  before_bytes="$(wc -c < "$reservations" | tr -d ' ')"
+
+  # BSD (macOS) vs GNU date, same ADR-021-point-3 platform branch as get_mtime.
+  cutoff_iso="$(date -u -v-"${days}"d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+    || date -u -d "-${days} days" +%Y-%m-%dT%H:%M:%SZ)"
+
+  tmp_keep="$(mktemp "${TMPDIR:-/tmp}/forge-reserve-compact-keep.XXXXXX")"
+  tmp_arch="$(mktemp "${TMPDIR:-/tmp}/forge-reserve-compact-arch.XXXXXX")"
+
+  counts="$(awk -v cutoff="$cutoff_iso" -v keepfile="$tmp_keep" -v archfile="$tmp_arch" '
+    BEGIN { n = 0; havedash = 0; header = "" }
+    /^  - kind: / {
+      if (havedash) { n++; blocks[n]=block; kinds[n]=curkind; ids[n]=curid; rats[n]=currat }
+      block = $0 "\n"
+      curkind = $0; sub(/^  - kind: */, "", curkind)
+      curid = ""; currat = ""
+      havedash = 1
+      next
+    }
+    havedash == 0 { header = header $0 "\n"; next }
+    {
+      block = block $0 "\n"
+      if ($0 ~ /^    id: /)          { curid = $0;  sub(/^    id: */, "", curid) }
+      if ($0 ~ /^    reserved_at: /) { currat = $0; sub(/^    reserved_at: *"?/, "", currat); sub(/"$/, "", currat) }
+    }
+    END {
+      if (havedash) { n++; blocks[n]=block; kinds[n]=curkind; ids[n]=curid; rats[n]=currat }
+
+      # Sort key per record: numeric id (non-digits stripped) for every kind
+      # except version, which compares the leading X.Y.Z semver triple —
+      # pre-release/build suffixes never affect ordering here.
+      for (i = 1; i <= n; i++) {
+        k = kinds[i]; idv = ids[i]
+        if (k == "version") {
+          if (match(idv, /^[0-9]+\.[0-9]+\.[0-9]+/)) {
+            s = substr(idv, RSTART, RLENGTH)
+            split(s, parts, ".")
+            key = parts[1] * 1000000 + parts[2] * 1000 + parts[3]
+          } else key = 0
+        } else {
+          numid = idv
+          gsub(/[^0-9]/, "", numid)
+          key = numid + 0
+        }
+        keys[i] = key
+        if (!(k in maxkey) || key > maxkey[k]) maxkey[k] = key
+      }
+
+      printf "%s", header > keepfile
+      kept = 0; archived = 0
+      for (i = 1; i <= n; i++) {
+        k = kinds[i]
+        if (keys[i] == maxkey[k] || rats[i] >= cutoff) {
+          printf "%s", blocks[i] >> keepfile
+          kept++
+        } else {
+          printf "%s", blocks[i] >> archfile
+          archived++
+        }
+      }
+      printf "%d %d", kept, archived
+    }
+  ' "$reservations")"
+
+  kept="${counts%% *}"
+  archived="${counts##* }"
+
+  mv "$tmp_keep" "$reservations"
+
+  if [ -s "$tmp_arch" ]; then
+    if [ ! -f "$archive" ]; then
+      cat > "$archive" <<'YML'
+# Forge ID Reservations — Archive (R104)
+#
+# Append-only overflow for .forge/reservations.yml, written ONLY by
+# `forge-reserve compact` (.claude/hooks/forge-reserve.sh). reservations.yml
+# has a 50KB size gate (FORGE.md Accumulating Artifacts); this file holds
+# every reservation row compaction has ever dropped from the working file,
+# byte-verbatim, so the durable audit trail is never lost. Never edit,
+# reorder, or hand-truncate existing entries.
+#
+# Floor invariant: compaction always keeps, per kind, the highest-id row (or
+# for `version`, the highest semver row) plus any row from the retention
+# window — so a max-scan over reservations.yml ALONE (never this archive)
+# always finds the true per-kind ceiling. See FORGE.md → ID Reservation
+# Protocol / Accumulating Artifacts.
+reservations:
+YML
+    fi
+    cat "$tmp_arch" >> "$archive"
+  fi
+  rm -f "$tmp_keep" "$tmp_arch" 2>/dev/null || true
+
+  after_bytes="$(wc -c < "$reservations" | tr -d ' ')"
+  printf 'forge-reserve: compact — kept %s, archived %s, reservations.yml %s -> %s bytes\n' \
+    "$kept" "$archived" "$before_bytes" "$after_bytes" >&2
+}
+
+# --- 3. acquire lock (atomic mkdir, bounded retry, ownable 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.
+#
+# R103: the lock is ownable. An owner stamp ("$$ epoch") is written inside the
+# lock dir once acquired. Before breaking a lock judged stale by mtime, the
+# breaker re-reads the mtime AND the owner stamp immediately before rmdir — if
+# either changed since the staleness read, another process refreshed this lock
+# in the gap, so the break is skipped and this iteration falls through to the
+# normal bounded wait instead. This shrinks the unsafe window from the full
+# STALE/WAIT budget down to the read-vs-rmdir instruction gap — not zero (no
+# flock on macOS, ADR-021 point 3), but far narrower than an unconditional
+# path-based rmdir. The EXIT/INT/TERM trap is guarded the same way: it only
+# tears down a lock this process' stamp still occupies, never a lock a racer
+# broke-and-re-acquired after us.
 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)"
+  broke=0
   if [ -n "$mt" ] && [ "$((now_epoch - mt))" -ge "$STALE" ]; then
+    seen_owner="$(cat "$lock/owner" 2>/dev/null || true)"
     printf 'forge-reserve: breaking stale lock (age %ss): %s\n' "$((now_epoch - mt))" "$lock" >&2
-    rmdir "$lock" 2>/dev/null || true
+    mt2="$(get_mtime "$lock")"
+    now_owner="$(cat "$lock/owner" 2>/dev/null || true)"
+    if [ "$mt2" = "$mt" ] && [ "$now_owner" = "$seen_owner" ]; then
+      rm -f "$lock/owner" 2>/dev/null || true
+      rmdir "$lock" 2>/dev/null || true
+      broke=1
+    else
+      printf 'forge-reserve: stale-lock owner changed just before break — treating as fresh, waiting: %s\n' "$lock" >&2
+    fi
+  fi
+  if [ "$broke" -eq 1 ]; then
     continue
   fi
   iters="$((iters + 1))"
@@ -156,124 +429,52 @@ while ! mkdir "$lock" 2>/dev/null; do
   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
+# The lock is ours: stamp an owner marker before installing the release trap
+# so the trap — and any future racer's stale-break identity check — can tell
+# this process apart from a later one that broke and re-acquired the same path.
+own_stamp="$$ $(date +%s)"
+printf '%s\n' "$own_stamp" > "$lock/owner"
+trap '
+  if [ "$(cat "$lock/owner" 2>/dev/null)" = "$own_stamp" ]; then
+    rm -f "$lock/owner" 2>/dev/null || true
+    rmdir "$lock" 2>/dev/null || true
+  fi
+' EXIT INT TERM
 
-# --- 4v. version kind: record-only claim (ADR-029) ---------------------------
+# --- 4a. compact subcommand: runs under the lock just acquired, then exits --
+if [ "$compact_mode" -eq 1 ]; then
+  do_compact
+  exit 0
+fi
+
+# --- 4. version kind: record-only claim (ADR-029) ----------------------------
 # No max computation — the caller derived the number from releases.yml + semver
 # bump; this block only makes the claim ledger-visible. Runs UNDER the lock so
 # two racing claims of the same string serialize: the second sees the first.
+# Single awk pass emits holder<TAB>held_at (R106); POSIX parameter expansion
+# splits the pair instead of two near-identical ledger scans.
 if [ "$kind" = "version" ]; then
   id="$value"
   if [ -f "$ledger" ]; then
-    holder="$(awk -F'\t' -v v="$id" '$1=="version" && $2==v { print $3; exit }' "$ledger")"
-    if [ -n "$holder" ]; then
+    out="$(awk -F'\t' -v v="$id" '$1=="version" && $2==v { printf "%s\t%s", $3, $4; exit }' "$ledger")"
+    if [ -n "$out" ]; then
+      holder="${out%%"$TAB"*}"
+      held_at="${out#*"$TAB"}"
       if [ "$holder" = "$milestone" ]; then
         # Idempotent re-claim by the same milestone: already recorded, write nothing.
         printf '%s\n' "$id"
         exit 0
       fi
-      held_at="$(awk -F'\t' -v v="$id" '$1=="version" && $2==v { print $4; exit }' "$ledger")"
       printf 'forge-reserve: version %s already claimed by %s (%s) — re-read max()+bump and take the next number\n' \
         "$id" "$holder" "$held_at" >&2
       exit 1
     fi
   fi
 else
-
-# --- 4/5. three-way max(ledger ∪ in-tree ∪ main:reservations.yml) + 1 --------
-# (computed kinds only — version above records verbatim.)
-# 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).
-# Extract the trailing number by stripping non-digits, NOT by split on "-": refactor
-# ids (R100) carry no hyphen (ADR-023), so a hyphen-split would read them as 0 and
-# reallocate a live id. gsub handles ADR-014, M-26, R100, FR-023, P-066 uniformly.
-ledger_max=0
-if [ -f "$ledger" ]; then
-  ledger_max="$(awk -F'\t' -v k="$kind" \
-    '$1==k { x=$2; gsub(/[^0-9]/,"",x); n=x+0; if(n>m)m=n } END{print m+0}' "$ledger")"
+  id="$(compute_id)"
 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). milestone + refactor (ADR-023)
-# and phase (ADR-029) each scan BOTH live and archive locations so a burned id is
-# never reallocated.
-case "$kind" in
-  adr)
-    intree_max="$(ls "$top/docs/decisions" 2>/dev/null \
-      | awk -F- '/^ADR-[0-9]/ { n=$2+0; if(n>m)m=n } END{print m+0}')"
-    ;;
-  milestone)
-    # live state/milestone-<N>.yml  ∪  archived .forge/archive/milestone-<N>/
-    intree_max="$( { ls "$top/.forge/state"/milestone-*.yml 2>/dev/null; \
-                     ls -d "$top/.forge/archive"/milestone-*/ 2>/dev/null; } \
-      | grep -oE 'milestone-[0-9]+' \
-      | awk -F- '{ n=$2+0; if(n>m)m=n } END{print m+0}')"
-    ;;
-  refactor)
-    # live refactor-backlog.yml  ∪  refactor-backlog-archive.yml
-    intree_max="$(grep -hoE 'R[0-9]+' \
-        "$top/.forge/refactor-backlog.yml" \
-        "$top/.forge/refactor-backlog-archive.yml" 2>/dev/null \
-      | awk '{ n=substr($0,2)+0; if(n>m)m=n } END{print m+0}')"
-    ;;
-  phase)
-    # live roadmap.yml `- id: N` lines  ∪  archived phase dirs
-    # .forge/archive/milestone-*/phases/<N>-*. The roadmap scan deliberately
-    # takes ALL bare-int `- id:` values (milestone AND phase entries share the
-    # indent): over-counting can only RAISE the floor — safe; an under-count
-    # (a missed phase id) reintroduces the collision. Quoted milestone ids
-    # ("m-42") don't match the bare-int pattern. Archive-delete removes a
-    # milestone's roadmap entries, so the archive arm is what keeps its phase
-    # ids burned (ADR-029, mirroring the milestone arm above).
-    intree_max="$( { cat "$top/.forge/roadmap.yml" 2>/dev/null; \
-                     ls "$top/.forge/archive"/milestone-*/phases/ 2>/dev/null; } \
-      | awk '/^[[:space:]]*- id: [0-9]+/ { n=$3+0; if(n>m)m=n }
-             /^[0-9]+-/ { x=$0; sub(/-.*/,"",x); n=x+0; if(n>m)m=n }
-             END{print m+0}')"
-    ;;
-  wave)
-    # live roadmap.yml waves-map KEYS only (`  N: [...]`) — never the phase ids
-    # inside the brackets. No archive arm: waves are removed with their roadmap
-    # entry on archive-delete; ledger + main floor cover the gap (ADR-029).
-    intree_max="$(cat "$top/.forge/roadmap.yml" 2>/dev/null \
-      | awk '/^[[:space:]]+[0-9]+:[[:space:]]*\[/ { k=$1; gsub(/[^0-9]/,"",k); n=k+0; if(n>m)m=n } END{print m+0}')"
-    ;;
-  *)
-    intree_max="$(grep -rhoE '[A-Z]+-[0-9]+' "$top/.forge/requirements/" 2>/dev/null \
-      | awk -F- -v p="$prefix" '$1==p { n=$2+0; if(n>m)m=n } END{print m+0}')"
-    ;;
-esac
-
-# (c) main:reservations.yml — cross-machine / cold-start floor (survives a
-# .git/forge wipe; carries another machine's MERGED reservations). Absent → 0.
-# Hyphen is OPTIONAL in the token ([A-Z]+-?[0-9]+): refactor ids (R100) carry none
-# (ADR-023), so requiring a hyphen would hide them and drop the floor to 0. Split the
-# alpha prefix from the digits in awk so R does not match e.g. FR (anchor ^prefix$).
-main_max="$(git show main:.forge/reservations.yml 2>/dev/null \
-  | grep -oE '[A-Z]+-?[0-9]+' \
-  | awk -v p="$prefix" '{ a=$0; sub(/[-0-9].*$/,"",a); d=$0; gsub(/[^0-9]/,"",d);
-                          if(a==p){ n=d+0; if(n>m)m=n } } END{print m+0}')"
-[ -n "$main_max" ] || main_max=0
-
-next="$(awk -v a="$ledger_max" -v b="$intree_max" -v c="$main_max" \
-  'BEGIN{m=a; if(b>m)m=b; if(c>m)m=c; print m+1}')"
-# Per-kind id format (ADR-023, ADR-029). The prefix-hyphen-paddednumber form
-# (ADR-021's ADR-014, FR-023) is NOT universal:
-#   milestone → M-26  : hyphen, UNPADDED — ids are used bare (milestone-26.yml, m-26)
-#   refactor  → R064  : NO hyphen, zero-padded 3-wide — matches the backlog convention
-#   adr/def/fr/nfr/phase/wave → ADR-014, P-066, W-046 : hyphen, zero-padded 3-wide
-case "$kind" in
-  milestone) id="$(printf '%s-%d' "$prefix" "$next")" ;;
-  refactor)  id="$(printf '%s%03d' "$prefix" "$next")" ;;
-  *)         id="$(printf '%s-%03d' "$prefix" "$next")" ;;
-esac
-
-fi # end computed-kinds branch (version skipped to the dual-write below)
-
-# --- 6. dual-write (still under the lock) -----------------------------------
+# --- 5. 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"
 
@@ -285,7 +486,7 @@ if [ ! -f "$reservations" ]; then
   mkdir -p "$(dirname "$reservations")"
   cat > "$reservations" <<'YML'
 # Forge ID Reservations — cross-worktree coordination for Forge sequential ids + version claims
-# Written by .claude/hooks/forge-reserve.sh (ADR-021). The machine-local ledger
+# Written by .claude/hooks/forge-reserve.sh (ADR-021). The per-machine 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
@@ -306,5 +507,5 @@ esc_summary="$(printf '%s' "$summary" | sed 's/\\/\\\\/g; s/"/\\"/g')"
   printf '    summary: "%s"\n' "$esc_summary"
 } >> "$reservations"
 
-# --- 7. emit the id (stdout only); trap releases the lock on exit ------------
+# --- 6. emit the id (stdout only); trap releases the lock on exit ------------
 printf '%s\n' "$id"