forge-orkes 0.72.2 → 0.73.1

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/.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)`.
 

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-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

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

@@ -114,5 +114,58 @@ else
   bad 'unknown flag refused loudly (exit 2)' "rc=$RC out=$OUT"
 fi
 
+# --- 9-12. BARE BRANCH LOOSENING (issue #25): a worktree glob against REAL git worktrees on
+#     bare m-<id>-slug / m<digits>-slug branches (no forge/ prefix) — FORGE_JARVIS_REPO_ROOT
+#     points the git-worktree glob at a throwaway fixture repo instead of --worktree-root's
+#     root-scan (which bypasses branch matching entirely). ------------------------------------
+GITROOT="$ROOT/git-fixture"; mkdir -p "$GITROOT/main"
+(
+  cd "$GITROOT/main" || exit 1
+  git init -q .
+  git config user.email t@t.com; git config user.name test
+  mkdir -p .forge/state
+  printf 'id: 176\n'     > .forge/state/milestone-176.yml
+  printf 'id: 167\n'     > .forge/state/milestone-167.yml
+  printf 'id: R61-002\n' > .forge/state/milestone-R61-002.yml
+  git add .forge >/dev/null 2>&1 || : > .gitkeep
+  git add -A; git commit -q -m init
+  git worktree add -q -b m-176-marcy-mcp     "$GITROOT/bare-1" >/dev/null 2>&1
+  git worktree add -q -b m167-close-sync     "$GITROOT/bare-2" >/dev/null 2>&1
+  git worktree add -q -b m-R61-002-cleanup   "$GITROOT/bare-3" >/dev/null 2>&1
+  git worktree add -q -b fix-issue-2         "$GITROOT/guard-1" >/dev/null 2>&1
+) >/dev/null 2>&1
+
+OUT="$(FORGE_JARVIS_REPO_ROOT="$GITROOT/main" FORGE_JARVIS_FOLD="$FOLDSTUB" FORGE_JARVIS_BOARD="$BOARDSTUB" \
+       sh "$AWARE" --dry-run 2>&1)"
+
+# 9. bare branch m-176-marcy-mcp discovered with milestone id m-176 (previously silently absent)
+if printf '%s' "$OUT" | grep -qE 'm-176[[:space:]]+m-176-marcy-mcp'; then
+  ok 'bare branch m-176-marcy-mcp is discovered as milestone id m-176'
+else
+  bad 'bare branch m-176-marcy-mcp is discovered as milestone id m-176' "$OUT"
+fi
+
+# 10. bare branch m167-close-sync (no hyphen after m) discovered with milestone id m-167
+if printf '%s' "$OUT" | grep -qE 'm-167[[:space:]]+m167-close-sync'; then
+  ok 'bare branch m167-close-sync is discovered as milestone id m-167'
+else
+  bad 'bare branch m167-close-sync is discovered as milestone id m-167' "$OUT"
+fi
+
+# 11. hyphenated id: m-R61-002-cleanup resolves via the longest-matching state-file prefix,
+#     not the naive first-hyphen-segment (which would wrongly stop at m-R61)
+if printf '%s' "$OUT" | grep -qE 'm-R61-002[[:space:]]+m-R61-002-cleanup'; then
+  ok 'hyphenated milestone id: m-R61-002-cleanup resolves to m-R61-002 (longest state-file prefix)'
+else
+  bad 'hyphenated milestone id: m-R61-002-cleanup resolves to m-R61-002 (longest state-file prefix)' "$OUT"
+fi
+
+# 12. GUARD: a bare-number branch (fix-issue-2, no m- token) is NEVER discovered
+if ! printf '%s' "$OUT" | grep -q 'fix-issue-2'; then
+  ok 'guard: bare-number branch fix-issue-2 (no m- token) is not discovered'
+else
+  bad 'guard: bare-number branch fix-issue-2 (no m- token) is not discovered' "$OUT"
+fi
+
 printf '\nforge-jarvis-awareness.test.sh: %s passed, %s failed\n' "$PASSED" "$FAILED"
 [ "$FAILED" -eq 0 ]

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

@@ -403,6 +403,56 @@ if [ "$rc" = 0 ] && printf '%s' "$err24" | grep -q 'using it as-is'; then
 else
   bad "legacy materialized order" "rc=$rc err=$err24"
 fi
+
+# --- 25-27. BARE BRANCH LOOSENING (issue #25): the branch-derived milestone-dir pick also
+#     matches a bare m-<id>-slug / m<digits>-slug branch (no forge/ prefix) — same match family
+#     as awareness/relay. A bare slug can carry several descriptive words, so the pick walks
+#     truncations of the last hyphen-segment until an existing milestone dir is found.
+
+# 25. bare branch m-176-marcy-mcp (hyphenated id + 2-word slug) picks milestone-176 among
+#     several dirs
+BSLICE="$ROOT/bare-wt"
+mkdir -p "$BSLICE/.forge/phases/milestone-176/1-num" "$BSLICE/.forge/phases/milestone-5/1-decoy"
+printf 'bare plan\n' > "$BSLICE/.forge/phases/milestone-176/1-num/plan-01.md"
+printf 'decoy\n'     > "$BSLICE/.forge/phases/milestone-5/1-decoy/plan-01.md"
+mkbranch "$BSLICE" m-176-marcy-mcp
+err25="$(sh "$DISPATCH" --slice "$BSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && grep -q '^  - 1-num$' "$BSLICE/slice.yml" 2>/dev/null \
+   && grep -q 'bare plan' "$BSLICE/phases/1-num/plan.md" 2>/dev/null && [ ! -d "$BSLICE/phases/1-decoy" ]; then
+  ok "bare branch m-176-marcy-mcp: branch picks milestone-176 among several dirs (no forge/ prefix)"
+else
+  bad "bare-branch pick (hyphenated id)" "rc=$rc err=$err25"
+fi
+
+# 26. bare branch m167-close-sync (no hyphen after m, 2-word slug) picks milestone-167
+CSLICE="$ROOT/bare-wt2"
+mkdir -p "$CSLICE/.forge/phases/milestone-167/1-num" "$CSLICE/.forge/phases/milestone-9/1-decoy"
+printf 'bare plan\n' > "$CSLICE/.forge/phases/milestone-167/1-num/plan-01.md"
+printf 'decoy\n'     > "$CSLICE/.forge/phases/milestone-9/1-decoy/plan-01.md"
+mkbranch "$CSLICE" m167-close-sync
+err26="$(sh "$DISPATCH" --slice "$CSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && grep -q '^  - 1-num$' "$CSLICE/slice.yml" 2>/dev/null \
+   && grep -q 'bare plan' "$CSLICE/phases/1-num/plan.md" 2>/dev/null && [ ! -d "$CSLICE/phases/1-decoy" ]; then
+  ok "bare branch m167-close-sync: branch picks milestone-167 among several dirs (m immediately followed by digits)"
+else
+  bad "bare-branch pick (numeric, no hyphen)" "rc=$rc err=$err26"
+fi
+
+# 27. GUARD: a bare-number branch (fix-issue-2, no m- token) does NOT resolve — several
+#     milestone dirs with no branch-derived pick still refuses as ambiguous
+NSLICE="$ROOT/guard-wt"
+mkdir -p "$NSLICE/.forge/phases/milestone-1/1-a" "$NSLICE/.forge/phases/milestone-2/1-b"
+printf 'a\n' > "$NSLICE/.forge/phases/milestone-1/1-a/plan-01.md"
+printf 'b\n' > "$NSLICE/.forge/phases/milestone-2/1-b/plan-01.md"
+mkbranch "$NSLICE" fix-issue-2
+err27="$(sh "$DISPATCH" --slice "$NSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" != 0 ] && [ ! -f "$NSLICE/slice.yml" ] && printf '%s' "$err27" | grep -q 'REFUSED' \
+   && printf '%s' "$err27" | grep -q 'no forge/m-\* or bare m-<id> branch'; then
+  ok "guard: bare-number branch fix-issue-2 (no m- token) refuses ambiguous pick, names both accepted forms"
+else
+  bad "guard: bare-number branch fix-issue-2" "rc=$rc err=$err27"
+fi
+
 # --- summary -----------------------------------------------------------------
 printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
 [ "$FAILED" = 0 ]