forge-orkes 0.72.2 → 0.74.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/jarvis/SKILL.md

@@ -15,6 +15,7 @@ Read these before acting on any intake. Jarvis **relays and triggers — it neve
 
 - **No routing.** Dispatch passes the model map (`model_by_phase_type`) through **untouched** — per-phase model selection is step 5. If intake starts *choosing models*, STOP: that is not this door's job.
 - **No approval, ever.** Jarvis never approves, waives, lowers, or carries an approval. Promotions are approved on GitHub's Environment surface (step 2); holds are waived by your recorded host acts. Jarvis *tells* you an approval is waiting and *where* — the act happens there.
+- **UAT is the human's act — Jarvis never stands in for it.** UAT = the **operator** tests the work locally, with their own eyes and hands. An agent's browser/Playwright run, an e2e suite, or green CI is *automated verification* — necessary, **never sufficient, and never called UAT**. Agents are not users of the system, so "the agent tested it" can never satisfy UAT. The invariant this door holds: **a PR exists only after the operator's explicit in-session UAT confirmation** — there is **no agent-attestation path to PR-open**. This is Forge's Human Verification Gate (`in_session_signoff`) applied at the **merge boundary** instead of milestone-close. The failure mode it refuses: a session self-attesting "Real browser UAT" in a PR body and auto-merging on green CI — the agent's own run is not the human's acceptance. If you catch yourself about to open a PR because *you* checked the work, STOP: that is the gate this door exists to hold.
 - **No status memory.** "What's in play?" is **computed** from board / disk-glob / fold every time (B5), never remembered. If a question seems to need a Jarvis-owned status store, that is the drift class (pain 4): compute it or route out. The ONLY durable Jarvis state is the B4 relay markers.
 - **No new notification infrastructure.** PushNotification + the Monitor `tail -F` + the runner's existing log. No queue, no broker, no third-party service.
 - **No runner changes.** Jarvis consumes the runner's seams (env vars, the notify log, the m-35 answer-file convention) and never edits the loop. Runner work lives in its own milestone.
@@ -89,24 +90,56 @@ When a watched log grows, pipe it back through the relay core — do **not** buz
 `--scan` relays every **unmarked** line and prints the relay text (one line per new ping); fire **PushNotification** with each. Inside, the helper recomputes host truth (the fold / `gh` / board) before building any state claim, so:
 
 - an **ambiguity** reaches the phone as the question verbatim (it is a question, not a claim);
-- a **done/halt** is phrased from the host's `release_state`, and a payload that claims a merge the host does not show is relayed as a **loud discrepancy** (the standing lesson — host truth wins);
+- a **`done`** means **"ready for the operator's local UAT"** — the slice's work is built in its worktree and **no PR exists yet**. It is a *cue to UAT*, not a merge claim; relay it as such and hand off to the UAT gate (below). A payload that claims a merge or a PR at `done` contradicts the flow and is relayed as a **loud discrepancy** (host truth wins — and under this flow the host shows no PR at `done`);
+- a **halt** is phrased from the host's `release_state`, named as a halt;
 - **fork / irreversible / budget** relay verbatim, named.
 
 The `--milestone` is derived per slice from its worktree branch (`forge/m-<id>`); it is what the fold recomputes against. Jarvis holds no status of its own — if a buzz would need a remembered fact, that is the drift class: recompute it or route out.
 
+### The UAT gate (post-`done`) — no PR until the operator accepts
+
+A `done` ping is the cue that the work is ready for the operator's **local UAT**, not that it shipped. There is no PR yet, and Jarvis opens one **only** after the operator's explicit in-session confirmation (the hard boundary in "What Jarvis is NOT"). On a relayed `done`, run this sequence **in order** — never skip ahead to a PR:
+
+1. **Spin up the slice's local dev server** so the operator can actually try it. Read the project's dev-lane command from `project.yml`:
+
+   ```sh
+   # jarvis.dev_lane_cmd — the stack-specific command that starts THIS slice's local dev server.
+   # Run it in the slice worktree (the work under test lives there), detached like the runner.
+   ```
+
+   If `jarvis.dev_lane_cmd` is **set**, run it in the slice worktree and tell the operator where it's up. If it is **absent**, do not fail — tell the operator to start their dev lane manually for this worktree (Forge owns no dev-server concept; the "how" is the project's, per FR-248). Either way, name the worktree so the operator knows what they're testing.
+2. **Relay "ready for your UAT."** Buzz the operator: the work is built and the local server is up (or ask them to start it) — *"ready for your UAT on the local server."* This is a cue to the human, phrased as such.
+3. **Wait for the operator's explicit confirmation.** Do nothing irreversible until the operator says, in session, that they've tested it and it's good (a plain "looks good" / "ship it" / "approved"). **Your own browser run, a passing e2e suite, or green CI never substitutes** — see the UAT boundary. No confirmation → the slice sits; you do not open a PR.
+4. **On explicit confirmation only — open the PR and arm the merge.** This is a **trigger on the operator's word**, not an approval Jarvis grants (the "relays and triggers, never decides" boundary):
+
+   ```sh
+   gh pr create --fill --head <slice-branch>        # open the PR now that the human has accepted
+   gh pr merge <num> --auto --squash                # arm auto-merge; CI + branch protection gate the actual merge
+   ```
+
+   Then, and only then, arm the come-try watch on that PR number (below). The order is load-bearing: dev lane → ready-for-UAT → **explicit confirmation** → PR-open + arm merge → come-try. A PR that exists before step 3 is the failure this gate refuses.
+
+**On UAT failure — findings become an answer, and the slice re-dispatches.** If the operator says UAT failed, their findings are the fix instructions: land them as the runner's answer for the slice's `done` phase and re-dispatch, exactly like a parked-ambiguity answer (below) — no PR is opened, no new machinery:
+
+```sh
+.forge/checks/forge-jarvis-answer.sh --work-dir <dir> --phase <N> --slice <worktree> --answer "<operator's UAT findings>"
+```
+
+The runner resumes the slice with the findings in hand and fixes them; the next `done` re-enters this same UAT gate. (`<N>` is the slice's final/`done` phase — the one the operator just tested.)
+
 ### The come-try tap and the answer round-trip
 
 Two moments need a second source beyond the log line:
 
-- **"Merged, on staging — come try."** The runner's `done` ping fires at PR-open, but the step-2 auto-merge and the staging deploy land minutes later — that moment is never in the log. So when the handler relays a `done` that carries a PR, arm the bounded watch:
+- **"Merged, on staging — come try."** After the operator has accepted the work and Jarvis has opened + armed the PR (the UAT gate, above), the step-2 auto-merge and the staging deploy land minutes later — that moment is never in the log. So **once the PR is open (post-UAT), never at `done`**, arm the bounded watch on that PR number:
 
   ```sh
   .forge/checks/forge-jarvis-prwatch.sh --pr <num> [--staging-env <name>]
   ```
 
-  It polls `gh` (merge + staging-deploy) under a hard iteration/wall bound and self-terminates on merge+deploy (firing the come-try tap once, at-most-once by a PR-keyed marker), on a closed PR, or on the bound — never a standing daemon. It reads host truth only.
+  It polls `gh` (merge + staging-deploy) under a hard iteration/wall bound and self-terminates on merge+deploy (firing the come-try tap once, at-most-once by a PR-keyed marker), on a closed PR, or on the bound — never a standing daemon. It reads host truth only. The come-try moment therefore lands *after* the operator's own acceptance, so nothing reaches staging unverified.
 
-- **Park → answer → resume.** When the operator answers a parked ambiguity (typed or from the phone), close the loop through the runner's own convention:
+- **Park → answer → resume.** When the operator answers a parked ambiguity (typed or from the phone) — or supplies UAT-failure findings (the UAT gate, above) — close the loop through the runner's own convention:
 
   ```sh
   .forge/checks/forge-jarvis-answer.sh --work-dir <dir> --phase <N> --slice <worktree> --answer "<reply>"
@@ -205,3 +238,5 @@ B3 delivered intake → spec → detached dispatch; B4 added the callback relay;
 - **B6 — promotion voice** ✅ (this phase): on explicit `promote <sha>`, show what the SHA carries and trigger the step-2 seam — **trigger, never approve** (Promotion voice, above).
 
 The front door is now whole: intake, spec, detached dispatch, the callback relay, awareness + instruments, and the promotion voice — every state claim host-recomputed, no owned state beyond the B4 relay markers.
+
+**m-48 — UAT-gated dispatch** (later refinement, 0.74.0): the callback relay's back-half was re-sequenced so a `done` ping means "ready for the operator's local UAT" (no PR yet), Jarvis spins up the slice's local dev server (`jarvis.dev_lane_cmd`), waits for the operator's **explicit in-session UAT confirmation**, and only then triggers PR-open + arm merge — with the come-try PR watch re-armed *after* that operator-confirmed PR-open, and UAT failures routed back through the answer-file re-dispatch. The hard boundary — UAT is the human's act, no agent-attestation path to PR-open — lives in "What Jarvis is NOT". Nothing reaches staging unverified.

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.
@@ -188,7 +188,7 @@ Quick tier skips init.
 
 State lives in `.forge/`. One line per artifact; protocol detail lives in the named ADRs and skills:
 
-- `project.yml` — vision, stack, design system, verification, constraints (<5 KB)
+- `project.yml` — vision, stack, design system, verification, constraints (<5 KB). Optional `jarvis.dev_lane_cmd` (m-48) is the stack-agnostic seam Jarvis runs to spin up a slice's local dev server for operator UAT before a PR opens; absent ⇒ manual lane start. See `docs/jarvis.md`.
 - `constitution.md` — active architectural gates
 - `design-system.md` — component mapping table
 - `requirements/m{N}.yml` — per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. **FR/DEF/NFR ids are globally unique across all milestone files** — reserve via the ID Reservation Protocol before writing. M9 e2e gate fields (`e2e`, `observable_outcome`, `validated`, hash) lazy-migrate; absent ⇒ `false`.
@@ -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)`.
 

package/template/.forge/checks/forge-check-lint.sh

@@ -104,6 +104,8 @@ JUSTIFY="$(git log --format=%B "$MB..$HEAD_REF" 2>/dev/null \
   | sed -n 's/^Lint-Justify:[[:space:]]*//p' | head -1 | tr '"' "'")"
 
 # Base-side gating_tests globs (same additive config the hold check reads).
+# Twin parser: keep in sync with forge-hold-check.sh:conf_list() —
+# duplicated deliberately (R075, self-contained-hooks convention).
 GATING="$(git show "$MB:.forge/hold-config.yml" 2>/dev/null \
   | awk '
       /^[A-Za-z_]+:/ { insec = (index($0, "gating_tests:") == 1) ? 1 : 0; next }
@@ -314,6 +316,13 @@ add_finding() { # rule, file, line("" ok)
 CHANGED="$(git diff --name-only "$MB" "$HEAD_REF" 2>/dev/null)" \
   || { printf 'forge-check-lint: git diff failed for %s\n' "$RANGE" >&2; exit 2; }
 
+# Scratch file for classify_units | while-read (escapes the pipe subshell so
+# add_finding's FINDINGS/HAS_A accumulation survives past the loop). No
+# predictable path (R077): allocated on first use, trap-cleaned.
+FCL_SCRATCH=""
+cleanup_fcl_scratch() { [ -n "$FCL_SCRATCH" ] && rm -f "$FCL_SCRATCH"; }
+trap cleanup_fcl_scratch EXIT INT TERM
+
 while IFS= read -r path; do
   [ -n "$path" ] || continue
   base_name="$(basename "$path")"
@@ -323,6 +332,7 @@ while IFS= read -r path; do
     .github/workflows/*.yml|.github/workflows/*.yaml|.gitlab-ci.yml)
       ADDED="$(added_lines "$path")"
       [ -n "$ADDED" ] || continue
+      [ -n "$FCL_SCRATCH" ] || FCL_SCRATCH="$(mktemp)" || { printf 'forge-check-lint: mktemp failed\n' >&2; exit 2; }
       classify_units "$path" | while IFS=' ' read -r cls ustart uend; do
         [ "$cls" != "clean" ] || continue
         hit=""
@@ -333,11 +343,10 @@ while IFS= read -r path; do
 $ADDED
 EOF2
         [ -n "$hit" ] && printf '%s %s %s\n' "$cls" "$path" "$ustart"
-      done > "${TMPDIR:-/tmp}/fcl_units.$$" || true
+      done > "$FCL_SCRATCH" || true
       while IFS=' ' read -r cls p ln; do
         [ -n "$cls" ] && add_finding "$cls" "$p" "$ln"
-      done < "${TMPDIR:-/tmp}/fcl_units.$$"
-      rm -f "${TMPDIR:-/tmp}/fcl_units.$$"
+      done < "$FCL_SCRATCH"
       continue
       ;;
   esac

package/template/.forge/checks/forge-hold-check.sh

@@ -132,6 +132,8 @@ fi
 # --- base-side config (additive; the PR cannot rewrite the rules it is judged by)
 CONF="$(git show "$MB:.forge/hold-config.yml" 2>/dev/null || true)"
 
+# Twin parser: keep in sync with forge-check-lint.sh:GATING awk block —
+# duplicated deliberately (R075, self-contained-hooks convention).
 conf_list() { # key → one value per line from the base-side config
   [ -n "$CONF" ] || return 0
   printf '%s\n' "$CONF" | awk -v k="$1" '

package/template/.forge/checks/forge-jarvis-awareness.sh

@@ -23,20 +23,28 @@
 # NO OWNED STATE: nothing here is persisted; the next ask recomputes from disk + git. The only
 # durable Jarvis state anywhere is B4's relay markers (a different helper).
 #
+# BARE BRANCH LOOSENING (issue #25): the disk glob also matches a bare `m-<id>-slug` or
+# `m<digits>-slug` branch (no `forge/` prefix) — a worktree created by hand or by another tool,
+# not just the Worktree Convention's `forge/{anchor}`. Its milestone id is derived from the
+# LONGEST-matching `.forge/state/milestone-*.yml` filename in that worktree, else the id's first
+# hyphen-segment. A bare NUMBER alone (no `m` token) never matches — see derive_milestone_id.
+#
 #   forge-jarvis-awareness.sh [--dry-run] [--worktree-root <dir>]
 #     --dry-run          resolve + print structure without shelling to the fold/board (fast
 #                        plumbing check); tests and quick sanity checks use it.
 #     --worktree-root    override the worktree scan root (tests); default: real `git worktree list`.
 #
 # Host-truth commands are env-overridable so tests inject stubs and degradation is explicit:
-#   FORGE_JARVIS_FOLD   default .claude/hooks/forge-release-fold.sh
-#   FORGE_JARVIS_BOARD  default .forge/checks/forge-board-render.sh
+#   FORGE_JARVIS_FOLD       default .claude/hooks/forge-release-fold.sh
+#   FORGE_JARVIS_BOARD      default .forge/checks/forge-board-render.sh
+#   FORGE_JARVIS_REPO_ROOT  default the repo root derived from this script's own path (test seam:
+#                        points the git-worktree glob at a throwaway fixture repo)
 # BEST-EFFORT: a missing fold/board degrades to a stated 'unknown' / '(unavailable)', never a hard
 # fail — the awareness answer always renders.
 set -u
 
 SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"                 # .forge/checks → repo root
+REPO_ROOT="${FORGE_JARVIS_REPO_ROOT:-$(cd "$SELF_DIR/../.." && pwd)}"   # .forge/checks → repo root
 FOLD="${FORGE_JARVIS_FOLD:-$REPO_ROOT/.claude/hooks/forge-release-fold.sh}"
 BOARD="${FORGE_JARVIS_BOARD:-$REPO_ROOT/.forge/checks/forge-board-render.sh}"
 TAB="$(printf '\t')"
@@ -61,9 +69,50 @@ fold_state() {  # fold_state <milestone-id>
   [ -n "$_rs" ] && printf '%s' "$_rs" || printf 'unknown'
 }
 
-# ── 1. live/parked slices — a DISK GLOB of worktrees on forge/m-* branches. Same on-disk registry
-#       the relay's --list-logs arms tail -F on; recomputed here, never stored. Emits TSV:
-#       <milestone-id>\t<branch>\t<path>. --worktree-root globs a given dir instead (tests). ──────
+# ── milestone id derivation for a matched branch (issue #25, bare-branch loosening). A
+#    forge/m-* branch keeps its original textual derivation unchanged (strip forge/, strip the
+#    8-hex session suffix). A bare branch (m-<id>-slug | m<digits>-slug) derives the id from the
+#    LONGEST-matching .forge/state/milestone-*.yml file name in that worktree, else falls back to
+#    the id's first hyphen-segment. Same rule text as forge-jarvis-dispatch.sh's branch-derived
+#    milestone-dir pick (there against .forge/phases/milestone-*/ dirs instead of state files). ──
+derive_milestone_id() {  # derive_milestone_id <branch> <worktree-path>
+  _b="$1"; _p="$2"
+  case "$_b" in
+    forge/*)
+      _m="${_b#forge/}"                                          # m-37[-<session>]
+      case "$_m" in
+        *-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f])
+          _m="${_m%-*}" ;;                                        # → m-37
+      esac
+      printf '%s' "$_m"
+      return 0 ;;
+  esac
+  _base="$_b"
+  case "$_base" in
+    *-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f])
+      _base="${_base%-*}" ;;                                      # strip an 8-hex session suffix
+  esac
+  _best=""
+  for _f in "$_p"/.forge/state/milestone-*.yml; do
+    [ -f "$_f" ] || continue
+    _id="$(basename "$_f" .yml)"; _id="${_id#milestone-}"
+    case "$_base" in
+      "m-$_id"|"m-$_id"-*|"m$_id"|"m$_id"-*)
+        [ "${#_id}" -gt "${#_best}" ] && _best="$_id" ;;
+    esac
+  done
+  if [ -n "$_best" ]; then
+    printf 'm-%s' "$_best"
+  else
+    _seg="${_base#m}"; _seg="${_seg#-}"; _seg="${_seg%%-*}"       # first hyphen-segment fallback
+    printf 'm-%s' "$_seg"
+  fi
+}
+
+# ── 1. live/parked slices — a DISK GLOB of worktrees on forge/m-* branches OR a bare m-<id>
+#       branch (issue #25). Same on-disk registry the relay's --list-logs arms tail -F on;
+#       recomputed here, never stored. Emits TSV: <milestone-id>\t<branch>\t<path>.
+#       --worktree-root globs a given dir instead (tests). ─────────────────────────────────────
 list_slices() {
   if [ -n "$WT_ROOT" ]; then
     for _wt in "$WT_ROOT"/*/; do
@@ -75,12 +124,14 @@ list_slices() {
     git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | awk -v tab="$TAB" '
       /^worktree / { p = substr($0, 10) }   # full remainder — paths may contain spaces
       /^branch /   {
-        if ($2 ~ /refs\/heads\/forge\/m-/) {
-          b = $2; sub(/refs\/heads\//, "", b)          # forge/m-37[-<session>]
-          m = b; sub(/^forge\//, "", m); sub(/-[0-9a-f]{8}$/, "", m)   # → m-37
-          print m tab b tab p
+        b = $2; sub(/refs\/heads\//, "", b)
+        if (b ~ /^forge\/m-/ || b ~ /^m-[0-9A-Za-z]/ || b ~ /^m[0-9]/) {
+          print b tab p
         }
-      }'
+      }' | while IFS="$TAB" read -r _b _p; do
+        _m="$(derive_milestone_id "$_b" "$_p")"
+        printf '%s%s%s%s%s\n' "$_m" "$TAB" "$_b" "$TAB" "$_p"
+      done
   fi
 }
 

package/template/.forge/checks/forge-jarvis-dispatch.sh

@@ -233,6 +233,14 @@ materialize_work_order() {
   # unconditionally missed milestone-m-EVT01 and fell through to a 38-dir refusal. Try the
   # anchor verbatim before the m--stripped form, then both again minus one trailing
   # -{session} token; first existing dir wins (exact/longer forms first).
+  #
+  # BARE BRANCH LOOSENING (issue #25): a worktree may also sit on a bare `m-<id>-slug` or
+  # `m<digits>-slug` branch (no `forge/` prefix) — same match family as the awareness/relay
+  # glob. Unlike the forge/ convention (id + at most one session token), a bare branch's slug
+  # can carry several descriptive words (m-176-marcy-mcp), so the id is found by repeatedly
+  # truncating the LAST hyphen-segment and testing for an existing milestone dir at each
+  # length — the longest-matching truncation wins (mirrors awareness's state-file prefix
+  # match, here against .forge/phases/milestone-*/ dirs instead).
   _mdir=""
   _branch="$(git -C "$WORKTREE" branch --show-current 2>/dev/null)"
   case "$_branch" in
@@ -246,6 +254,22 @@ materialize_work_order() {
           break
         fi
       done ;;
+    m-*|m[0-9]*)
+      _cand="$_branch"
+      while [ -n "$_cand" ]; do
+        for _try in "$_cand" "${_cand#m-}" "${_cand#m}"; do
+          [ -n "$_try" ] || continue
+          if [ -d "$WORKTREE/.forge/phases/milestone-$_try" ]; then
+            _mdir="$WORKTREE/.forge/phases/milestone-$_try"
+            break
+          fi
+        done
+        [ -n "$_mdir" ] && break
+        case "$_cand" in
+          *-*) _cand="${_cand%-*}" ;;                 # drop the last hyphen-segment, retry shorter
+          *) break ;;
+        esac
+      done ;;
   esac
   # Fallback (non-git fixture dirs / unconventional branches): a SINGLE milestone dir is
   # unambiguous; several without a branch-derived pick is a refusal, never a guess.
@@ -260,7 +284,7 @@ materialize_work_order() {
       return 2
     fi
     if [ "$_mdirs" -gt 1 ]; then
-      printf 'forge-jarvis-dispatch: REFUSED — %s milestone plan dirs in %s and no forge/m-* branch to pick by; ambiguous work order. Write slice.yml explicitly. RELAY this refusal to the operator.\n' "$_mdirs" "$WORKTREE" >&2
+      printf 'forge-jarvis-dispatch: REFUSED — %s milestone plan dirs in %s and no forge/m-* or bare m-<id> branch to pick by; ambiguous work order. Write slice.yml explicitly. RELAY this refusal to the operator.\n' "$_mdirs" "$WORKTREE" >&2
       return 2
     fi
   fi

package/template/.forge/checks/forge-jarvis-prwatch.sh

@@ -1,11 +1,14 @@
 #!/usr/bin/env sh
 # forge-jarvis-prwatch.sh — the bounded "merged, on staging — come try" watch
-# (m-37, Brief-R2 step 4 B4(c); contract handoff-step4-jarvis.md REV2).
+# (m-37, Brief-R2 step 4 B4(c); contract handoff-step4-jarvis.md REV2; re-sequenced m-48).
 #
-# The runner's `done` ping fires at PR-open; step-2 auto-merge + the staging deploy land minutes
-# LATER, so that flagship "come try it" moment never appears in the notify log. This watch is the
-# SECOND bounded source for it: on a `done`, poll `gh` for the PR's merge + staging-deploy state
-# with a HARD bound and, on merge+deploy, emit the come-try text once.
+# Under UAT-gated dispatch (m-48) a PR is opened by Jarvis ONLY after the operator's explicit
+# in-session UAT confirmation — never at the runner's `done` (which now means "ready for the
+# operator's local UAT", no PR yet). This watch is armed on THAT post-UAT PR: step-2 auto-merge +
+# the staging deploy land minutes LATER, so the flagship "come try it" moment never appears in the
+# notify log. On the opened PR, poll `gh` for its merge + staging-deploy state with a HARD bound
+# and, on merge+deploy, emit the come-try text once. Because it arms only after the operator has
+# accepted the work, nothing reaches staging unverified.
 #
 # STRICTLY BOUNDED + self-terminating (NFR-036 / Fork 3): it stops on merge+deploy, on a closed
 # PR, or when the iteration/wall bound is hit — it NEVER becomes a standing daemon and owns no

package/template/.forge/checks/forge-jarvis-relay.sh

@@ -31,16 +31,22 @@
 #                                              the payload rather than fold/gh/board (acceptance #3).
 #
 # HOST-TRUTH COMMANDS (env-overridable so tests inject stubs, and so degradation is explicit):
-#   FORGE_JARVIS_FOLD   default .claude/hooks/forge-release-fold.sh  (release_state recompute)
+#   FORGE_JARVIS_FOLD       default .claude/hooks/forge-release-fold.sh  (release_state recompute)
+#   FORGE_JARVIS_REPO_ROOT  default the repo root derived from this script's own path (test seam:
+#                        points --list-logs's git-worktree glob at a throwaway fixture repo)
 #   (gh-based facts live in forge-jarvis-prwatch.sh, which documents its own FORGE_JARVIS_GH;
 #    the board recompute lives in awareness/promote — this helper consults the fold only.)
 #
+# BARE BRANCH LOOSENING (issue #25): --list-logs also matches a bare `m-<id>-slug` or
+# `m<digits>-slug` worktree branch (no `forge/` prefix), same match rule as the awareness glob —
+# it only needs the notify-log PATH, not the milestone id, so no id derivation lives here.
+#
 # BEST-EFFORT: a fold/gh/board that is absent or errors degrades to release_state=unknown and
 # says so — never a silent success, never a hard fail of the relay path.
 set -u
 
 SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"                 # .forge/checks → repo root
+REPO_ROOT="${FORGE_JARVIS_REPO_ROOT:-$(cd "$SELF_DIR/../.." && pwd)}"   # .forge/checks → repo root
 FOLD="${FORGE_JARVIS_FOLD:-$REPO_ROOT/.claude/hooks/forge-release-fold.sh}"
 
 # ── host truth: the slice's release_state, recomputed from the fold (never the payload) ───────
@@ -148,12 +154,15 @@ mode_list_logs() {
     done
   else
     # live path: `git worktree list` is the on-disk registry of worktrees; glob it to the
-    # forge/m-* slice branches and emit each slice's notify-log path. Pinned with -C so the
-    # watch list never depends on the caller's cwd (the cwd-reset footgun: a snapped cwd
-    # would silently arm ZERO watches).
+    # forge/m-* slice branches (OR a bare m-<id>-slug / m<digits>-slug branch, issue #25) and
+    # emit each slice's notify-log path. Pinned with -C so the watch list never depends on the
+    # caller's cwd (the cwd-reset footgun: a snapped cwd would silently arm ZERO watches).
     git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | awk '
       /^worktree /  { p=substr($0, 10) }   # full remainder — paths may contain spaces
-      /^branch /    { if ($2 ~ /refs\/heads\/forge\/m-/) print p "/.forge/runner-work/notify.log" }
+      /^branch /    {
+        b=$2; sub(/refs\/heads\//, "", b)
+        if (b ~ /^forge\/m-/ || b ~ /^m-[0-9A-Za-z]/ || b ~ /^m[0-9]/) print p "/.forge/runner-work/notify.log"
+      }
     '
   fi
   exit 0