forge-orkes 0.63.0 → 0.64.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.63.0",
+  "version": "0.64.2",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/hooks/forge-release-fold.sh

@@ -200,8 +200,10 @@ case "$unit" in
   *) printf 'forge-release-fold: unit-id must be m-<N>, got: %s\n' "$unit" >&2; usage ;;
 esac
 num="${unit#m-}"
+# Numeric (m-8) and labeled (m-AUTO01, incl. letter sub-phases like m-3-1a) id
+# schemes are both valid; reject only empty ids and ids with unsafe characters.
 case "$num" in
-  ''|*[!0-9]*) printf 'forge-release-fold: unit-id must be m-<N>, got: %s\n' "$unit" >&2; usage ;;
+  ''|*[!A-Za-z0-9_-]*) printf 'forge-release-fold: unit-id must be m-<N> or m-<LABEL>, got: %s\n' "$unit" >&2; usage ;;
 esac
 
 # --- repo + main ref -------------------------------------------------------
@@ -217,6 +219,12 @@ if ! git -C "$root" rev-parse -q --verify "$main_ref^{commit}" >/dev/null 2>&1;
 fi
 
 state_path=".forge/state/milestone-$num.yml"
+# Labeled-id convention keeps the m- prefix in the filename (milestone-m-LABEL.yml);
+# prefer whichever spelling is tracked in the main tree.
+if ! git -C "$root" cat-file -e "$main_ref:$state_path" 2>/dev/null \
+   && git -C "$root" cat-file -e "$main_ref:.forge/state/milestone-$unit.yml" 2>/dev/null; then
+  state_path=".forge/state/milestone-$unit.yml"
+fi
 stream_path=".forge/streams/$unit.yml"
 
 # MAIN-TREE state read — never the working tree. Empty when not tracked.

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

@@ -0,0 +1,204 @@
+---
+name: jarvis
+description: "The per-repo front door (Brief-R2 step 4, kills P15). Conversational intake → spec → detached dispatch → callback relay → awareness → promotion voice, running in the standing Jarvis remote-control session. Triggers: /jarvis at conversation start (the reliable binding — invoke it in every RC conversation), intake from laptop or phone, 'go' to dispatch a specced slice, 'what's in play?', 'promote <sha>'. On 'go' the session dispatches detached via forge-jarvis-dispatch.sh — it never runs executing inline. Consumes existing primitives (slice runner, board, fold, promotion seam) — wiring, not machinery."
+---
+
+# Jarvis — the per-repo front door
+
+**The shape (state it exactly this simply):** Jarvis is the single door and comms interface for this repo. You design and spec work by talking to it — from the laptop or the phone; it hands the build off to detached agents, tells you when work is done or when your input is needed, and losing the session loses no work. Every state it speaks is recomputed from the host (fold / `gh` / board), never a session's claim.
+
+Jarvis is the **pre-created session** of the `claude remote-control` server that `.forge/checks/forge-jarvis.sh` starts. It is not a daemon and owns almost nothing: kill it and only the live connection + armed watches are lost, both re-established at restart from files (Amendment 2). The one exception is the relay-marker class (B4) — delivery bookkeeping, never authority over work state.
+
+## What Jarvis is NOT (boundaries — binding; the contract's "Not this step")
+
+Read these before acting on any intake. Jarvis **relays and triggers — it never decides or approves.**
+
+- **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.
+- **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.
+- **One presence per repo per machine.** No multi-repo hub (monitored, not built — DEF-193). On a multi-machine repo the awareness is per-machine by construction; say so, don't pretend.
+
+If intake ever wants to grow a routing brain, an approval, or a memory — **STOP and route out.** That is the concierge failure mode this door is built to refuse.
+
+## Session binding (start here)
+
+Skill loading is description-matched — nothing *forces* an RC conversation to load this skill, and an unbound session silently degrades to plain Forge: it specs beautifully, then builds inline on "go" — no dispatch, no notify log, nothing for the relay to watch, the operator's phone silent for the whole build (observed live, m-39 walk, 2026-07-22). Two rules close that hole:
+
+- **Operator side:** open each Jarvis conversation by invoking **`/jarvis`** (or naming the skill). The launcher's sticky `--name` makes the presence findable; `/jarvis` makes the session *be* Jarvis.
+- **Session side:** once this skill loads, you ARE the front door for the rest of the conversation. Driving other skills (`forge`, `discussing`, `planning`) during intake is exactly right — but every later step (dispatch, relay, awareness, promotion) stays under these rules, and the Dispatch section's "go means dispatch — never build" override outranks any other skill's routing.
+- **Binding is a restart moment — act on it immediately:** the instant this skill loads, (1) arm the watches (Callback relay → Arm the watches) and (2) run the **while-you-were-away catchup** (Callback relay → While you were away) across every live slice log. Any pending ping is the FIRST thing you tell the operator — before greeting, before asking what they want. WHY hard-anchored: in the live walk (run 6, 2026-07-22) a completed slice's `done` ping sat unmarked through a `/jarvis` bind AND a "what's happening?" — the section existed but no trigger invoked it; the operator learned of the finished work only from the host-side verifier.
+
+## Intake → spec (run the EXISTING act — do not rebuild it)
+
+Intake collaboration is already validated (Brief-R2 §1). Jarvis does **not** reimplement it — it drives the existing Forge skills from the conversation:
+
+1. **Listen.** The operator describes a small real slice conversationally — from the laptop or the phone (identical either way; see Phone parity).
+2. **Spec it together.** Route into the normal Forge flow: `Skill(forge)` for a new slice (which does the worktree entry + milestone declaration on main — the step-0 B3′ declaration split, ff-pushed so the work is sighted on main), then `Skill(discussing)` / `Skill(planning)` **in the work's own worktree**. The spec conversation *is* the value; Jarvis is the front door to it, not a second copy of it.
+3. **Confirm the spec back** to the operator before any build. A declaration lands on main; the plan lands in the worktree. Nothing has been dispatched yet.
+
+Jarvis owns none of this logic — it owns the *doorway*. The declaration/spec artifacts are written by the existing skills, in the worktree, exactly as they are today.
+
+## Dispatch (on the operator's "go")
+
+**"Go" means dispatch — never build.** In the front-door session, `Skill(executing)` is NEVER invoked for a specced slice, and no slice file is ever edited here after "go". Forge's own routing (`planning → executing`) still holds — but it is the **detached runner's** path, executed headless in the slice worktree; it is not this session's. This override outranks the forge routing table: when routing says "executing" for a dispatched slice, the front door's move is the dispatch helper, nothing else. If you notice yourself editing slice files or invoking executing after a "go" — STOP; that is the observed failure mode (m-39: built inline, no notify log, no pings, the entire relay dark).
+
+When the operator says **go** on a specced slice, dispatch the runner **detached** so it survives Jarvis's death (B1 probe viii). Do not run the runner in the foreground and do not reach into its loop — call the helper:
+
+```sh
+.forge/checks/forge-jarvis-dispatch.sh --slice <worktree-path>
+```
+
+The helper (see its header for the full contract) owns the caller-side environment and nothing else:
+
+- **`FORGE_SLICE_NOTIFY_LOG` points INTO the slice's worktree** — never the invoker's cwd (the main checkout), which would drop a shared `notify.log` invisible to the worktree glob and dirty the clean-main invariant (step 0; acceptance #5).
+- **`FORGE_SLICE_NOTIFY` points at a log-only channel** (`forge-jarvis-notify-logonly.sh`) so the default channel's per-ping headless `claude -p` micro-call stays quiet — the B4 relay is the single delivery path; a live default channel would risk a double-buzz (B1 probe x). This is the swappable channel seam used exactly as designed: the runner is untouched, the caller owns the env.
+- **The model map is forwarded verbatim.** The helper carries no model-selection logic (see Boundaries — routing is step 5).
+- **The work order is materialized at dispatch** (FR-197): the runner's contract is `<worktree>/slice.yml` + `phases/<name>/plan.md`; when `slice.yml` is absent the helper builds both from the milestone's locked `.forge/phases/milestone-{id}/` plans (an existing `slice.yml` is honored untouched). When it cannot, it **refuses synchronously, before the detach** — relay that refusal to the operator immediately. And shortly after any real dispatch, read `<worktree>/.forge/runner-work/dispatch.out` once: a runner refusal lands there and must be relayed — **a silent phone is never success** (walk run 4's failure mode: the runner declined instantly and nothing ever buzzed).
+
+After dispatch, the slice runs headless in its worktree, writing every ping to its notify log. That log is the event bus the callback relay watches (B4).
+
+`--dry-run` on the helper prints the exact command + env it would run, without running it — use it to show the operator what "go" will do.
+
+## Callback relay (B4) — the load-bearing half
+
+This is what makes Jarvis a front door and not just a launcher: a runner ping in a slice's notify log becomes a typed buzz on the operator's phone, and **every state it speaks is recomputed from the host, never from the session's own words.** The notify log is the event bus; `forge-jarvis-relay.sh` is the decision core; PushNotification (over the live RC connection — B1 probe v) is the delivery. No queue, no broker, no daemon (NFR-038).
+
+### Arm the watches (boot, and after every dispatch)
+
+The set of logs to tail is **recomputed from disk every time, never held in memory** (Amendment 2). Ask the relay helper for the current set and arm a Monitor `tail -F` on each:
+
+```sh
+.forge/checks/forge-jarvis-relay.sh --list-logs        # one notify-log path per live slice worktree
+```
+
+For each path, arm a **Monitor `tail -F`** (capital F — the log may not exist until the slice's first ping; `tail -f` on a missing file would kill the watch, F8). Re-run `--list-logs` and re-arm on boot and after each `go` dispatch — the watch set is a pure function of what's on disk, so it always reflects the live slices without a remembered list. Kill Jarvis and the armed watches vanish; they re-arm from this same glob at restart.
+
+### The handler (a new log line → a host-true buzz)
+
+When a watched log grows, pipe it back through the relay core — do **not** buzz the payload directly:
+
+```sh
+.forge/checks/forge-jarvis-relay.sh --scan <log> --milestone <m-id>    # m-id from the slice's forge/m-* branch
+```
+
+`--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);
+- **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 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:
+
+  ```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.
+
+- **Park → answer → resume.** When the operator answers a parked ambiguity (typed or from the phone), 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>"
+  ```
+
+  It lands the reply at `<work-dir>/phase-<N>/answer.md` (the exact m-35 convention) and re-dispatches the slice so the runner resumes past the park — no runner change. No answer content → nothing is written and nothing re-dispatches (the slice stays parked).
+
+### While you were away (restart / next contact)
+
+Relay state is durable **marker files keyed by log-line offset** — the ONE class of state Jarvis owns (NFR-036). A marker means "already buzzed"; its absence means "not yet." So on restart or the next time the operator makes contact, scan each live log in catch-up mode:
+
+```sh
+.forge/checks/forge-jarvis-relay.sh --scan <log> --milestone <m-id> --mode catchup
+```
+
+This surfaces every ping that landed while Jarvis was down as **one** "while you were away" line, writes their markers, and **re-buzzes nothing already marked** (at-most-once, no double-buzz; a crash between marking and buzzing re-surfaces the ping rather than losing it — no silent loss, NFR-040).
+
+### What dies with Jarvis (state it plainly)
+
+Kill Jarvis and you lose **only** the live RC connection and the armed `tail -F` watches — both re-establish from disk at restart (the watch set from the glob, the delivery bookkeeping from the markers). No work is lost, because Jarvis never owned the work: the slice runs detached in its worktree, the markers are delivery receipts, and every claim is the host's, recomputed on demand.
+
+## Phone parity
+
+Everything above works identically from the phone: the operator opens the named presence (the sticky `--name` the launcher set — the phone's only discoverability anchor, B1 probe ii) and specs + dispatches with zero laptop touches. Jarvis behaves the same on either surface; there is no laptop-only path.
+
+## Awareness + instruments (B5)
+
+Jarvis answers "how are things?" without remembering anything. Three helpers, each computing from a live host source at ask-time — nothing here is a Jarvis-owned status store (the drift class, pain 4; NFR-036).
+
+### "What's in play?"
+
+**Catchup first, always.** Any status contact — "what's in play?", "what's happening?", "status?" — runs the while-you-were-away catchup (Callback relay section) BEFORE the awareness answer: pending pings lead as the "while you were away" line, then the in-play summary. Awareness computes state; the catchup delivers debts — a status answer that omits an undelivered ping is a lie of omission (walk run 6).
+
+When the operator asks **what's in play?** (laptop or phone), run the awareness helper and relay its output verbatim — the answer **is** its computed result, not a remembered summary:
+
+```sh
+.forge/checks/forge-jarvis-awareness.sh
+```
+
+It computes three things live: a **disk glob** of git worktrees on `forge/m-*` branches (this machine's live/parked slices — NOT the RC session listing, which is blind to detached `claude -p` workers, B1 probe ix), each slice's **fold** `release_state`, and the **board projection** (`forge-board-render.sh --emit`). It prints a plain **per-machine** caveat: on this two-machine repo the glob is local, and the git-synced board + fold are the cross-machine truth — so a quiet local list never reads as "nothing in flight anywhere". If a question would need a remembered fact, that is the drift class: recompute it or route out.
+
+### Weekly instruments (the direction test)
+
+To answer Risk 1 — *did the door reduce operator touches, or just relocate them?* — read the week's numbers off what B4 already wrote (notify logs + relay markers); no new store:
+
+```sh
+.forge/checks/forge-jarvis-instruments.sh          # optionally --since <ISO-Z>
+```
+
+It emits four figures: pings relayed by type, relay latency (emit→relay, mean + max), discrepancies caught by host-verification (the standing lesson, counted), and a **presence proxy** — pings relayed live vs pings that landed while the relay was down — labelled a proxy, never a measured SLA. These are the numbers to glance at weekly to see whether the front door is earning its keep.
+
+### Presence-ops cleanup (orphaned bridge worktrees)
+
+RC on-demand `--spawn worktree` sessions leave `.claude/worktrees/bridge-{cse-id}` worktrees that do not auto-remove when the session dies (B1 probe ii). Reap the orphans — never a live one:
+
+```sh
+.forge/checks/forge-jarvis-bridge-clean.sh --dry-run     # see candidates first
+.forge/checks/forge-jarvis-bridge-clean.sh               # then reap
+```
+
+Liveness is decided in this order (FR-207 gap-closure): dirty = keep; a git lock naming a **live** server pid = keep; a lock with a **dead** pid = orphan even when freshly modified (unlock-then-remove — RC locks every spawned bridge under the server's pid, so a fresh-looking bridge whose server died is still reapable); mtime freshness applies only to **unlocked** bridges. `git worktree remove` refusing a dirty worktree stays the second net; only `bridge-*` basenames are ever eligible. Run it as light housekeeping, not on a timer — there is no daemon.
+
+### The hub trigger stays watched, not built
+
+B5 only **watches** for the DEF-193 signal (the operator juggling presences mid-thought, wanting one cross-repo hub). It is monitored, not built. If that friction shows up repeatedly in the instruments or in intake, that is the trigger to route a *new* milestone — not to grow a hub inside this door.
+
+## Promotion voice (B6)
+
+The last thing Jarvis does — and the sharpest boundary. On the operator's **explicit** `promote <sha>` (never proactively, never inferred), Jarvis shows what that SHA carries and triggers the step-2 promotion seam. It **triggers; it does not approve.**
+
+```sh
+.forge/checks/forge-jarvis-promote.sh <full-sha>            # show host state, then trigger the seam
+.forge/checks/forge-jarvis-promote.sh <full-sha> --dry-run  # show + print the trigger command, run nothing
+```
+
+The helper does exactly two things, in order:
+
+1. **Shows what the SHA carries** — recomputed live from the board projection (whose rows carry the fold-derived `release_state`), never a session's word. The merged-but-not-yet-validated units are the ones this promotion covers, **by containment**: a unit becomes `validated` when its landed SHA is an ancestor of the signed `promotion/<sha>` tag's commit (ADR-024), verified offline on the host.
+2. **Triggers the step-2 seam** — `gh workflow run promote.yml -f sha=<full-sha>` — and stops. The flow halts at GitHub's Environment gates (both taps: deploy + mint) until you press them there.
+
+### Jarvis never approves — it refuses if asked
+
+Triggering is not approving. The approval is **not Jarvis's to give**: it lives on GitHub's Environment surface, held behind a CI key no session can read (ADR-024). So:
+
+- Asked to **"promote it"**, Jarvis shows the state and fires the trigger — then points you at the gate.
+- Asked to **"approve it" / "waive the gate" / "just push it through"**, Jarvis **refuses** and names where the act belongs: the GitHub Environment gate is yours to press, not Jarvis's. It never approves, waives, or lowers a gate, and there is no approval path in the helper to reach for (the neg-control proves it).
+
+A full deploy SHA is required — Jarvis never invents or truncates one, because the promotion tag is `promotion/<full-sha>` and containment needs the exact sha.
+
+## This skill accretes across the milestone (m-37)
+
+B3 delivered intake → spec → detached dispatch; B4 added the callback relay; B5 added awareness + instruments; **B6 (above)** adds the promotion voice — the milestone's final phase. Each landed with its own acceptance evidence:
+
+- **B4 — callback relay** ✅: arm a Monitor `tail -F` per glob'd slice log; relay each typed ping (the five §8 types + `halt`) to the phone, host-truth-recomputed; offset-keyed at-most-once markers with a while-you-were-away catch-up; the bounded "merged, on staging — come try" PR watch and the answer-file round-trip.
+- **B5 — awareness + instruments** ✅: "what's in play?" from board/glob/fold (per-machine, computed live); weekly direction-test numbers off the existing markers/logs; orphaned-bridge cleanup. All own no status store — computed on ask.
+- **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.

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

@@ -47,6 +47,12 @@ json_escape() {
   printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' | tr '\n' ' '
 }
 
+# Milestone-file id → unit id. Numeric files (milestone-8.yml) need the m-
+# prefix added; labeled files (milestone-m-AUTO01.yml) already carry it.
+unit_id() {
+  case "$1" in m-*) printf '%s' "$1" ;; *) printf 'm-%s' "$1" ;; esac
+}
+
 # ---------------------------------------------------------------------------
 # Config: read a scalar under the top-level `board:` block of project.yml.
 # ---------------------------------------------------------------------------
@@ -135,8 +141,8 @@ emit_deferred() {
     base=$(basename "$f" .yml); id="${base#milestone-}"
     nm=$(yget "$f" milestone name); rs=$(yget "$f" lifecycle deferred_reason)
     [ "$first" = 1 ] && first=0 || printf ',\n'
-    printf '    {"surface": "milestone", "id": "m-%s", "name": "%s", "deferred_at": "%s", "reason": "%s"}' \
-      "$id" "$(json_escape "$nm")" "$(json_escape "$da")" "$(json_escape "$rs")"
+    printf '    {"surface": "milestone", "id": "%s", "name": "%s", "deferred_at": "%s", "reason": "%s"}' \
+      "$(unit_id "$id")" "$(json_escape "$nm")" "$(json_escape "$da")" "$(json_escape "$rs")"
   done
   # Surface 2: deferred REFACTOR-backlog items (status: deferred). Block-scan: accumulate
   # each `- id:` item's fields, emit when its status is deferred.
@@ -174,8 +180,8 @@ emit_deferred() {
     [ "$hit" = "1" ] || continue
     base=$(basename "$f" .yml); id="${base#milestone-}"
     [ "$first" = 1 ] && first=0 || printf ',\n'
-    printf '    {"surface": "active-milestone", "id": "m-%s", "name": "%s", "deferred_at": "", "reason": "phase/task deferred inside active milestone"}' \
-      "$id" "$(json_escape "$(yget "$f" milestone name)")"
+    printf '    {"surface": "active-milestone", "id": "%s", "name": "%s", "deferred_at": "", "reason": "phase/task deferred inside active milestone"}' \
+      "$(unit_id "$id")" "$(json_escape "$(yget "$f" milestone name)")"
   done
 }
 
@@ -200,7 +206,7 @@ emit_projection() {
   ufirst=1
   for f in "$FORGE"/state/milestone-*.yml; do
     [ -f "$f" ] || continue
-    base=$(basename "$f" .yml); id="${base#milestone-}"; unit="m-$id"
+    base=$(basename "$f" .yml); id="${base#milestone-}"; unit=$(unit_id "$id")
     nm=$(yget "$f" milestone name)
     status=$(yget "$f" current status)
     tier=$(yget "$f" current tier)

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

@@ -0,0 +1,85 @@
+#!/usr/bin/env sh
+# forge-jarvis-answer.sh — the park → answer → resume round-trip
+# (m-37, Brief-R2 step 4 B4(d); contract handoff-step4-jarvis.md REV2).
+#
+# When a slice PARKS on an ambiguity, the relay (B4) buzzes the operator the question. The
+# operator's reply comes back to Jarvis (typed or from the phone). This helper closes the loop:
+# it lands that reply as the runner's CONVENTIONED answer file, then re-dispatches the slice so
+# it resumes PAST the park — not a cold replay.
+#
+# THE CONVENTION IS FIXED (m-35, landed 0.61.0 — the named Prerequisite): the answer file is
+#     <work-dir>/phase-<N>/answer.md
+# beside that phase's phase-report.yml. Do NOT invent a new location. On its next invocation the
+# runner re-assembles that phase's prompt WITH the parked state + this answer and continues; a
+# fresh park after a new answer fires a new ping. All of that is m-35 runner behavior — consumed,
+# never changed (NFR-037: no runner edit).
+#
+# Re-dispatch goes through forge-jarvis-dispatch.sh (the detached-runner seam from B3), so the
+# resume runs headless in the slice worktree exactly like the original dispatch.
+#
+#   --work-dir <dir>    the runner's --work-dir for this slice (holds phase-<N>/)   [required]
+#   --phase <N>         the parked phase index (→ phase-<N>/answer.md)              [required]
+#   --slice <worktree>  the slice worktree to re-dispatch                           [required]
+#   --answer <text>     the operator's reply; or --answer-file <path>; or via stdin
+#   --dry-run           write nothing, dispatch nothing — print the resolved plan and exit
+# Extra args after `--` are forwarded to forge-jarvis-dispatch.sh verbatim.
+set -u
+
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+DISPATCH="${FORGE_JARVIS_DISPATCH:-$SELF_DIR/forge-jarvis-dispatch.sh}"
+
+WORK_DIR=""; PHASE=""; SLICE=""; ANSWER=""; ANSWER_FILE=""; DRY=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --work-dir)    WORK_DIR="${2:-}"; shift 2 ;;
+    --phase)       PHASE="${2:-}"; shift 2 ;;
+    --slice)       SLICE="${2:-}"; shift 2 ;;
+    --answer)      ANSWER="${2:-}"; shift 2 ;;
+    --answer-file) ANSWER_FILE="${2:-}"; shift 2 ;;
+    --dry-run)     DRY=1; shift ;;
+    --)            shift; break ;;
+    *) printf 'forge-jarvis-answer: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+# After `--`, the remaining "$@" is forwarded to dispatch verbatim — argument
+# boundaries preserved (never flattened to a string; args with spaces survive).
+
+[ -n "$WORK_DIR" ] && [ -n "$PHASE" ] && [ -n "$SLICE" ] || {
+  printf 'forge-jarvis-answer: --work-dir, --phase and --slice are all required\n' >&2; exit 2; }
+
+# The phase index comes from a park ping (semi-trusted runner log) and is built
+# into a write path — a non-numeric value could traverse out of the work dir.
+case "$PHASE" in
+  *[!0-9]*|'') printf 'forge-jarvis-answer: --phase must be a numeric phase index, got: %s\n' "$PHASE" >&2; exit 2 ;;
+esac
+
+# Resolve the answer text: --answer, else --answer-file, else stdin.
+if [ -z "$ANSWER" ]; then
+  if [ -n "$ANSWER_FILE" ] && [ -f "$ANSWER_FILE" ]; then
+    ANSWER="$(cat "$ANSWER_FILE")"
+  elif [ ! -t 0 ]; then
+    ANSWER="$(cat)"
+  fi
+fi
+
+# NEG-CONTROL: no answer content → write nothing, re-dispatch nothing (the slice stays parked).
+if [ -z "$ANSWER" ]; then
+  printf 'forge-jarvis-answer: no answer content — nothing written, slice stays parked\n' >&2
+  exit 3
+fi
+
+DEST="$WORK_DIR/phase-$PHASE/answer.md"        # the EXACT m-35 convention
+
+if [ "$DRY" = 1 ]; then
+  printf 'answer plan: write → %s ; then re-dispatch %s --slice %s --work-dir %s %s\n' \
+    "$DEST" "$DISPATCH" "$SLICE" "$WORK_DIR" "$*"
+  exit 0
+fi
+
+# 1) land the answer at the conventioned path
+mkdir -p "$WORK_DIR/phase-$PHASE" 2>/dev/null || true
+printf '%s\n' "$ANSWER" > "$DEST" || { printf 'forge-jarvis-answer: could not write %s\n' "$DEST" >&2; exit 1; }
+printf 'forge-jarvis-answer: answer landed at %s\n' "$DEST" >&2
+
+# 2) re-dispatch the slice so the runner resumes past the park (m-35 prompt re-assembly)
+"$DISPATCH" --slice "$SLICE" --work-dir "$WORK_DIR" "$@"

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

@@ -0,0 +1,133 @@
+#!/usr/bin/env sh
+# forge-jarvis-awareness.sh — "what's in play?" answered LIVE, never remembered (m-37,
+# Brief-R2 step 4 B5 awareness; contract handoff-step4-jarvis.md REV2; FR-203/204; NFR-036).
+#
+# The operator asks Jarvis "what's in play?" and every fact in the answer is COMPUTED from a
+# live host source at ask-time — there is no Jarvis-owned status store (NFR-036 / pain 4: the
+# drift class). Three live sources, three questions:
+#   1. WHICH SLICES ARE RUNNING (this machine) → a DISK GLOB of git worktrees on forge/m-*
+#      branches (`git worktree list`), NOT the RC session listing (which is blind to detached
+#      `claude -p` workers — B1 probe ix). Parked/dispatched slices are worktrees on disk, so a
+#      glob sees them; the session listing does not.
+#   2. WHERE EACH SLICE STANDS (cross-machine) → the fold (forge-release-fold.sh m-N) per slice:
+#      unmerged | merged | validated — git-derived, identical on any clone.
+#   3. THE BOARD PROJECTION (cross-machine)     → forge-board-render.sh --emit: the rollup's view
+#      of every unit, offline + deterministic.
+#
+# PER-MACHINE SCOPE (F11 — stated plainly in the output): the disk glob is THIS machine's live/
+# parked slices only; forge is a two-machine repo, so the other machine's in-flight worktrees are
+# invisible here. The git-synced board + fold ARE the cross-machine truth; the glob is the local
+# "what's spinning right now" layer. The answer says so, so a quiet glob is never mistaken for
+# "nothing in flight anywhere".
+#
+# 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).
+#
+#   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
+# 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
+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')"
+
+DRY_RUN=0
+WT_ROOT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run)       DRY_RUN=1; shift ;;
+    --worktree-root) WT_ROOT="${2:-}"; shift 2 ;;
+    *) printf 'forge-jarvis-awareness: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+# ── host truth: a slice's release_state from the fold (never remembered). Degrades to 'unknown'. ─
+fold_state() {  # fold_state <milestone-id>
+  _mid="${1:-}"
+  [ -n "$_mid" ] || { printf 'unknown'; return 0; }
+  [ -f "$FOLD" ] || { printf 'unknown'; return 0; }
+  _out="$(sh "$FOLD" "$_mid" 2>/dev/null)" || { printf 'unknown'; return 0; }
+  _rs="$(printf '%s\n' "$_out" | grep -m1 'release_state=' | sed 's/.*release_state=//; s/[[:space:]].*//')"
+  [ -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). ──────
+list_slices() {
+  if [ -n "$WT_ROOT" ]; then
+    for _wt in "$WT_ROOT"/*/; do
+      [ -d "$_wt" ] || continue
+      _b="$(basename "$_wt")"
+      printf '%s%s(root-scan)%s%s\n' "$_b" "$TAB" "$TAB" "${_wt%/}"
+    done
+  else
+    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
+        }
+      }'
+  fi
+}
+
+# ── render ──────────────────────────────────────────────────────────────────────────────────────
+printf '── What'\''s in play?  (host-verified, computed live) ──────────────────\n'
+
+printf '\n▸ Live / parked slices on THIS machine  (git worktree glob):\n'
+_slices="$(list_slices)"
+if [ -n "$_slices" ]; then
+  printf '%s\n' "$_slices" | while IFS="$TAB" read -r _m _br _pt; do
+    if [ "$DRY_RUN" -eq 1 ]; then _rs='(dry-run)'; else _rs="$(fold_state "$_m")"; fi
+    printf '   %-10s  %-26s  release_state=%-9s  %s\n' "$_m" "$_br" "$_rs" "$_pt"
+  done
+else
+  printf '   (none on this machine)\n'
+fi
+
+printf '\n▸ Board projection  (git-synced — cross-machine truth):\n'
+if [ "$DRY_RUN" -eq 1 ]; then
+  printf '   (--dry-run: forge-board-render.sh --emit not invoked)\n'
+elif [ -f "$BOARD" ]; then
+  _emit="$(sh "$BOARD" --emit 2>/dev/null)"
+  if [ -n "$_emit" ]; then
+    # In-flight is what's "in play": one line per non-complete unit. Line-oriented JSON → grep/sed,
+    # no jq dependency (Article X native-first).
+    _inflight="$(printf '%s\n' "$_emit" | grep '"forge_id"' | grep -vE '"status":[[:space:]]*"complete"')"
+    if [ -n "$_inflight" ]; then
+      # Order-independent field extraction — one sed per key, so a key-order change
+      # in the board emit degrades a field to '?' instead of silently dropping the line.
+      printf '%s\n' "$_inflight" | head -40 | while IFS= read -r _ln; do
+        _id="$(printf '%s' "$_ln" | sed -n 's/.*"forge_id":[[:space:]]*"\([^"]*\)".*/\1/p')"
+        _st="$(printf '%s' "$_ln" | sed -n 's/.*"status":[[:space:]]*"\([^"]*\)".*/\1/p')"
+        _rs="$(printf '%s' "$_ln" | sed -n 's/.*"release_state":[[:space:]]*"\([^"]*\)".*/\1/p')"
+        printf '   %s  status=%s  release_state=%s\n' "${_id:-?}" "${_st:-?}" "${_rs:-?}"
+      done
+    else
+      printf '   (all board units complete — nothing in flight)\n'
+    fi
+  else
+    printf '   (board projection unavailable — degraded, not fatal)\n'
+  fi
+else
+  printf '   (forge-board-render.sh not found — projection unavailable)\n'
+fi
+
+printf '\nScope: the slice list above is PER-MACHINE (this machine'\''s worktrees only).\n'
+printf 'On this two-machine repo the git-synced board + fold are the cross-machine truth;\n'
+printf 'a quiet slice list here does not mean nothing is in flight on the other machine.\n'
+
+exit 0