forge-orkes 0.70.0 → 0.72.2

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

@@ -14,7 +14,7 @@
 #     lint=clean
 #     lint=fail                                     + finding=<rule>:<file>[:<line>]
 #     lint=justified justify="<trailer line>"       + finding=<rule>:<file>[:<line>] justified
-#     rule ∈ cannot-fail|silent-fail|existence-only|deleted-assertion|feature-removal|skip-marker
+#     rule ∈ cannot-fail|silent-fail|existence-only|deleted-assertion|feature-removal|skip-marker|driven-by-missing
 #   exit: 0 = clean or justified; 1 = fail; 2 = bad invocation. Logs → stderr.
 #
 # Targets (nothing else is scanned):
@@ -48,11 +48,30 @@
 #                       shrink is ambiguous and keeps the stricter deleted-assertion.
 #   skip-marker       — an ADDED .only( / .skip( / it.skip / describe.only / xit( /
 #                       xdescribe( / @pytest.mark.skip / t.Skip() line.
+#   driven-by-missing — CONFIG-GATED, default OFF (hold-waiver patch, operator-
+#                       ruled 2026-07-22). When the BASE-side .forge/project.yml
+#                       carries:
+#                         attribution:
+#                           driven_by: true
+#                       every non-merge commit of merge-base..head must carry a
+#                         Driven-by: <email>
+#                       trailer (optional trailing session ref allowed) — the
+#                       durable per-commit record of the driving human, whatever
+#                       identity authors. Finding format: the file slot carries
+#                       the offending commit's short SHA
+#                       (finding=driven-by-missing:<short-sha>). Config absent or
+#                       false → rule fully off, zero behavior change. Read from
+#                       the BASE side, so a PR cannot disable the rule for
+#                       itself (and a project.yml edit raises a protected-path
+#                       hold in the sibling check anyway). Merge commits are
+#                       exempt (host- or tool-authored join points, not driven
+#                       work). SEVERABLE: this rule dies alone if it grows
+#                       friction; it shares only the justification channel.
 #
 # Justification channel (pure git, host-agnostic): a commit-message trailer
 #   Lint-Justify: <one line>
 # in ANY commit of merge-base..head lifts (b)/(c)/deleted-assertion/feature-removal/
-# skip-marker → exit 0 `lint=justified`. It never lifts (a).
+# skip-marker/driven-by-missing → exit 0 `lint=justified`. It never lifts (a).
 #
 # Host-agnostic + offline (NFR-032): POSIX sh over git plumbing only.
 set -u
@@ -358,6 +377,21 @@ done <<EOF
 $CHANGED
 EOF
 
+# --- Driven-by trailer rule (config-gated, default OFF; see header) -----------
+# Gate read from the BASE-side project.yml — a PR cannot disable the rule for
+# itself. Absent file / absent block / not-true value → rule fully off.
+DRIVEN_BY_ON="$(git show "$MB:.forge/project.yml" 2>/dev/null | awk '
+  /^[A-Za-z_]+:/ { insec = (index($0, "attribution:") == 1) ? 1 : 0; next }
+  insec && /^[[:space:]]+driven_by:[[:space:]]*true([[:space:]#]|$)/ { print "on"; exit }')"
+if [ "$DRIVEN_BY_ON" = "on" ]; then
+  for db_c in $(git rev-list --no-merges "$MB..$HEAD_REF" 2>/dev/null); do
+    if ! git log -1 --format=%B "$db_c" 2>/dev/null \
+      | grep -qE '^Driven-by:[[:space:]]*[^[:space:]@]+@[^[:space:]@]+'; then
+      add_finding driven-by-missing "$(git rev-parse --short "$db_c")" ""
+    fi
+  done
+fi
+
 FINDINGS="$(printf '%s' "$FINDINGS" | sort -u)"
 
 if [ -z "$FINDINGS" ]; then

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

@@ -14,6 +14,7 @@
 #     hold=blocked                                  facts, no recorded operator act
 #     fact=<class>:<path>                             one line per fact
 #     hold=waived waived_by=<login>                 facts + operator approval
+#     hold=waived waiver_run=<url>                  facts + approved waiver run (below)
 #     fact=<class>:<path> waived                      one line per waived fact
 #     class ∈ irreversible|structural|protected
 #   exit: 0 = clear or waived; 1 = blocked; 2 = bad invocation. All logs → stderr.
@@ -47,11 +48,49 @@
 # base-side config operators: list. Absent config / empty operators → no waiver
 # possible (raise-only safe default until the repo configures operators).
 #
+# Run-waiver (hold-waiver patch, operator-ruled 2026-07-22): OPTIONAL second
+# waiver channel — the Environment-gated waiver run. Base-side hold-config.yml
+# may carry:
+#   waiver:
+#     workflow: waive-hold.yml   # dispatchable workflow under .github/workflows/
+#     ref: main                  # MUST equal the repo's default branch
+# When configured AND the hold has fired AND no operator PR approval waives it,
+# the check queries the host ONCE (gh, the Actions runs API) for a run of that
+# workflow matching ALL of:
+#   - workflow path == .github/workflows/<workflow>  (querying by workflow file,
+#     re-asserted per run — a same-named run of another workflow never counts)
+#   - run ref (head_branch) == the repo's DEFAULT branch, which must also equal
+#     the configured ref (a dispatch runs the REF's copy of the file — a
+#     PR-branch copy with the gate stripped can never be the run that counts)
+#   - conclusion == success (an Environment-gated run cannot succeed unapproved
+#     — the approval IS why it ran)
+#   - display_title carries the PR HEAD SHA (the workflow's run-name templates
+#     the sha input in; a new push changes the head SHA, so a stale waiver run
+#     stops matching — superseded-SHA fail-closed leg)
+# Match → the check passes, annotated: hold=waived waiver_run=<run html_url>.
+# FAIL-CLOSED ON EVERY LEG: waiver unconfigured / unsafe config value / gh
+# missing / API unreachable / default branch unknown / config ref != default
+# branch / no matching run (wrong path, wrong ref, non-success, stale SHA) →
+# the hold stands (hold=blocked, exit 1). The waiver applies to THIS check
+# ONLY — never to the check-quality lint, never to CI test checks.
+#
+# Host access + CI permissions: the query runs through `gh` (env override
+# FORGE_HOLD_GH — fixtures stub it and stay offline). In CI the job needs the
+# default GITHUB_TOKEN exposed as GH_TOKEN with `actions: read` (the runs API)
+# in addition to `contents: read`; see docs/merge-floor-checks.md §5 wiring.
+# gh is used for transport + a PROJECTION-only --jq (no filtering in jq — every
+# matching leg is asserted in this script, so the offline fixtures exercise it).
+#
 # Host-agnostic + offline (NFR-032): pure POSIX sh over git plumbing. No GitHub/
-# GitLab API, no network, no node/python/jq. Heuristic manifest parsing is
-# documented inline; what it can't catch, UAT stands behind.
+# GitLab API, no network, no node/python/jq — with ONE opt-in exception: the
+# run-waiver query above, which only fires when `waiver:` is configured AND a
+# hold has already fired. With `waiver:` absent the check touches no network and
+# behaves byte-identically to the pre-waiver check. Heuristic manifest parsing
+# is documented inline; what it can't catch, UAT stands behind.
 set -u
 
+GH="${FORGE_HOLD_GH:-gh}"   # host CLI; fixtures point this at an offline stub
+
 usage() { printf 'usage: forge-hold-check.sh <base>...<head> [--approvals <file>]\n' >&2; }
 
 RANGE=""
@@ -106,10 +145,25 @@ conf_list() { # key → one value per line from the base-side config
     }'
 }
 
+conf_waiver() { # key → scalar under the base-side waiver: block (empty if absent)
+  [ -n "$CONF" ] || return 0
+  printf '%s\n' "$CONF" | awk -v k="$1" '
+    /^[A-Za-z_]+:/ { insec = (index($0, "waiver:") == 1) ? 1 : 0; next }
+    insec && index($0, k ":") > 0 && $0 ~ ("^[[:space:]]+" k ":") {
+      v = $0
+      sub(/^[[:space:]]*[A-Za-z_]+:[[:space:]]*/, "", v)
+      gsub(/["\047]/, "", v)
+      sub(/[[:space:]]*(#.*)?$/, "", v)
+      print v; exit
+    }'
+}
+
 CONF_IRREVERSIBLE="$(conf_list irreversible_paths)"
 CONF_DEPLOY="$(conf_list deploy_paths)"
 CONF_GATING="$(conf_list gating_tests)"
 CONF_OPERATORS="$(conf_list operators)"
+WAIVER_WF="$(conf_waiver workflow)"
+WAIVER_REF="$(conf_waiver ref)"
 
 glob_match() { # path, glob-list (newline) → 0 if any glob matches
   [ -n "$2" ] || return 1
@@ -252,6 +306,71 @@ if [ -n "$WAIVED_BY" ]; then
   exit 0
 fi
 
+# --- run-waiver (optional; FAIL-CLOSED on every leg — see header) -------------
+# Reached only when facts exist and no operator PR approval waived them. With
+# waiver: unconfigured this block is a no-op (no gh call, no network): the
+# blocked verdict below is byte-identical to the pre-waiver check.
+WAIVER_RUN_URL=""
+if [ -n "$WAIVER_WF" ] && [ -n "$WAIVER_REF" ]; then
+  # Config values reach gh argv — hard-validate the charset first (fail-closed:
+  # a malformed binding can never widen the query or smuggle flags).
+  W_OK=1
+  case "$WAIVER_WF" in *[!A-Za-z0-9._/-]*)
+    printf 'forge-hold-check: waiver.workflow carries unsafe characters — waiver ignored, hold stands\n' >&2; W_OK=0 ;;
+  esac
+  case "$WAIVER_REF" in *[!A-Za-z0-9._/-]*)
+    printf 'forge-hold-check: waiver.ref carries unsafe characters — waiver ignored, hold stands\n' >&2; W_OK=0 ;;
+  esac
+  if [ "$W_OK" = 1 ]; then
+    HEAD_SHA="$(git rev-parse "$HEAD_REF^{commit}" 2>/dev/null)"
+    DEFAULT_BRANCH="$("$GH" api 'repos/{owner}/{repo}' --jq .default_branch 2>/dev/null)" || DEFAULT_BRANCH=""
+    if [ -z "$DEFAULT_BRANCH" ]; then
+      printf 'forge-hold-check: waiver: default branch unknown (gh missing or API unreachable) — hold stands\n' >&2
+    elif [ "$WAIVER_REF" != "$DEFAULT_BRANCH" ]; then
+      printf 'forge-hold-check: waiver.ref (%s) != repo default branch (%s) — hold stands\n' "$WAIVER_REF" "$DEFAULT_BRANCH" >&2
+    else
+      case "$WAIVER_WF" in
+        */*) WF_PATH="$WAIVER_WF" ;;
+        *)   WF_PATH=".github/workflows/$WAIVER_WF" ;;
+      esac
+      # PROJECTION-only jq (no filtering there — every leg is asserted below so
+      # the offline fixture stub exercises each one). Fields tab-separated,
+      # display_title LAST (the one field that may contain spaces).
+      RUNS="$("$GH" api \
+        "repos/{owner}/{repo}/actions/workflows/$WAIVER_WF/runs?branch=$DEFAULT_BRANCH&status=success&per_page=100" \
+        --jq '.workflow_runs[] | [.conclusion, .head_branch, .path, .html_url, .display_title] | @tsv' \
+        2>/dev/null)" || RUNS=""
+      if [ -z "$RUNS" ]; then
+        printf 'forge-hold-check: waiver: no runs of %s on %s (or API unreachable) — hold stands\n' "$WF_PATH" "$DEFAULT_BRANCH" >&2
+      else
+        W_TAB="$(printf '\t')"
+        while IFS="$W_TAB" read -r r_concl r_branch r_path r_url r_title; do
+          [ -n "$r_concl" ] || continue
+          [ "$r_concl" = "success" ] || continue           # leg: approved (Environment-gated success)
+          [ "$r_branch" = "$DEFAULT_BRANCH" ] || continue  # leg: run ref == default branch
+          [ "$r_path" = "$WF_PATH" ] || continue           # leg: workflow path
+          case "$r_title" in                               # leg: run title carries the PR head SHA
+            *"$HEAD_SHA"*) WAIVER_RUN_URL="$r_url"; break ;;
+          esac
+        done <<WEOF
+$RUNS
+WEOF
+        [ -n "$WAIVER_RUN_URL" ] \
+          || printf 'forge-hold-check: waiver: no approved success run of %s on %s carries head SHA %s — hold stands\n' "$WF_PATH" "$DEFAULT_BRANCH" "$HEAD_SHA" >&2
+      fi
+    fi
+  fi
+fi
+
+if [ -n "$WAIVER_RUN_URL" ]; then
+  printf 'forge-hold-check: hold waived by approved run %s\n' "$WAIVER_RUN_URL" >&2
+  printf 'hold=waived waiver_run=%s\n' "$WAIVER_RUN_URL"
+  printf '%s\n' "$FACTS" | while IFS= read -r f; do
+    [ -n "$f" ] && printf 'fact=%s waived\n' "$f"
+  done
+  exit 0
+fi
+
 printf 'hold=blocked\n'
 printf '%s\n' "$FACTS" | while IFS= read -r f; do
   [ -n "$f" ] && printf 'fact=%s\n' "$f"

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env sh
-# forge-jarvis-dispatch.sh --slice <worktree> [runner args...] [--dry-run]
-#   (m-37, Brief-R2 step 4 B3; contract handoff-step4-jarvis.md REV2)
+# forge-jarvis-dispatch.sh --slice <worktree> [runner args...] [--dry-run] [--plan <spec>]...
+#   (m-37, Brief-R2 step 4 B3; contract handoff-step4-jarvis.md REV2; m-45 re-dispatch hygiene)
 #
 # On the operator's "go", Jarvis dispatches the slice runner DETACHED so the build
 # survives Jarvis's death (B1 probe viii: nohup-&). This helper owns ONLY the caller-side
@@ -25,12 +25,44 @@
 # this dispatch ever starts choosing models, STOP — routing is step 5.
 #
 # All non-flag args are forwarded to the runner unchanged (--slice <worktree>, and optionally
-# --work-dir / --config / --schema / --report-template — whatever the runner accepts). The only
-# arg this helper consumes for itself is --dry-run.
+# --config / --schema / --report-template — whatever the runner accepts). The args this helper
+# consumes for itself are --dry-run, --materialize-only, and --plan (the runner has no --plan;
+# forwarding it would be a routing-adjacent contract change — FR-198 boundary class).
+# EXCEPTION (R092): --work-dir is REFUSED, not forwarded — dispatch pins notify.log,
+# dispatch.out, and the runner-work rotation to <worktree>/.forge/runner-work, so a forwarded
+# --work-dir would split-brain the work dir (runner writes one place; dispatch, relay, and
+# rotation look at another). Callers managing their own work dir invoke the runner directly.
 #
 #   --dry-run   print the exact `nohup env ... runner ...` command + env on stdout and exit 0;
 #               never dispatches. Use it to show the operator what "go" will run.
 #
+#   --plan <spec>   (repeatable; m-45, canvaz desire path 2026-07-22 defect 2) scope the
+#               materialized work order instead of bundling EVERY phase dir + plan-NN.md:
+#                 --plan 72-bbb            → the whole phase dir 72-bbb (all its plan-NN.md)
+#                 --plan 72-bbb/plan-02    → exactly that plan file (.md optional)
+#               The mid-milestone re-dispatch tool: plan-01 landed, plan-02 next → dispatch
+#               --plan <phase>/plan-02 and only the next plan is bundled — never landed work.
+#               A spec that resolves to nothing REFUSES (exit 2, before the detach) — a typo
+#               must not dispatch the wrong work order. With an existing slice.yml: one this
+#               helper materialized (header line) is archived + re-materialized; a hand-
+#               authored one REFUSES — hand-authored work orders win, delete it yourself.
+#               Selected phases keep numeric order regardless of flag order.
+#
+# STALE-STATE ROTATION (m-45, canvaz desire path 2026-07-22 defect 3). Runner-work state is
+# per-WORK-ORDER: pings/{key}-{kind}.marker dedups pings across re-runs of the SAME order, and
+# index-keyed phase-{idx}/phase-report.yml verdicts derive its resume point. Dispatching a NEW
+# work order through the same worktree with that state in place is poison — the old done marker
+# silences the new run's done ping, and a stale verdict short-circuits the new phase as already
+# complete (observed live: silent phone, last_ping=none). So whenever this helper materializes a
+# NEW slice.yml it first rotates a non-empty .forge/runner-work WHOLE into
+# .forge/runner-work-archive/<UTC-ts>/ — whole because relay-markers are keyed by notify.log
+# LINE NUMBER (sibling dir); a partial reset would misalign relay offsets. Archive, never
+# delete: git commits are the durable evidence, runner-work is runtime. The resume paths are
+# untouched by construction — crash re-dispatch and park→answer→resume arrive with slice.yml
+# present and take the honored-as-is early return, so rotation never fires there. A --work-dir
+# arg is refused at the door (R092, see above) so rotation always matches the paths dispatch
+# owns; dispatching a new order while the prior runner still lives is operator error, unchanged.
+#
 # WORK-ORDER MATERIALIZATION (FR-197; walk run 4, 2026-07-22). The runner's contract
 # (consumed, never edited) is <worktree>/slice.yml listing phase names, each resolving to
 # <worktree>/phases/<name>/plan.md — but the Forge intake act writes plans under
@@ -42,6 +74,15 @@
 # REFUSES LOUDLY AND SYNCHRONOUSLY when it cannot — the failure surface is this exit code, not
 # a silent phone. An existing slice.yml is honored untouched (a hand-authored work order wins).
 #   --materialize-only   materialize (or refuse) and exit — no dispatch. Test hook + operator tool.
+#
+# STALENESS GUARD (live 2026-07-23). A materialized order SNAPSHOTS its source plans, so each
+# bundled plan-NN.md is fingerprinted into slice.yml (`# source: <phase>/<file> cksum=N`, after
+# the phases block). A plain re-dispatch (slice.yml present, no --plan) re-checksums them: any
+# divergence — an amended source plan — REFUSES loudly instead of silently building the old
+# spec (observed live: a full rebuild ran to the pre-amendment plan). Refuse, never auto-
+# rebuild: the honored-as-is branch also serves crash re-dispatch and park→answer→resume,
+# whose runner-work must survive rotation. Hand-authored orders are never checked; pre-guard
+# materialized orders (no fingerprints) skip the check — lazy migration.
 set -u
 
 SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -55,6 +96,8 @@ CHANNEL="$SELF_DIR/forge-jarvis-notify-logonly.sh"            # the log-only cha
 DRY_RUN=0
 MAT_ONLY=0
 WORKTREE=""
+PLAN_SPECS=""                                        # newline-separated --plan specs (may be empty)
+REPLACE_MATERIALIZED=0                               # set when --plan replaces a helper-materialized slice.yml
 argc=$#
 while [ "$argc" -gt 0 ]; do
   arg="$1"; shift; argc=$((argc - 1))
@@ -63,6 +106,17 @@ while [ "$argc" -gt 0 ]; do
       DRY_RUN=1 ;;                                   # ours — not forwarded
     --materialize-only)
       MAT_ONLY=1 ;;                                  # ours — not forwarded
+    --plan)                                          # ours — not forwarded (runner has no --plan)
+      _spec="${1:-}"; shift; argc=$((argc - 1))
+      [ -n "$_spec" ] || { printf 'forge-jarvis-dispatch: --plan requires a <phase>[/plan-NN] spec\n' >&2; exit 2; }
+      PLAN_SPECS="${PLAN_SPECS}${_spec}
+" ;;
+    --work-dir|--work-dir=*)                         # REFUSED (R092) — see header: a forwarded
+      # work dir splits the brain (runner writes there; notify.log/dispatch.out/rotation
+      # stay pinned to <worktree>/.forge/runner-work). Refuse loudly BEFORE the detach —
+      # the failure surface is this exit code, not a silent phone.
+      printf 'forge-jarvis-dispatch: REFUSED — --work-dir cannot be forwarded through dispatch (notify.log, dispatch.out and runner-work rotation are pinned to <worktree>/.forge/runner-work; a custom work dir would split-brain them). Invoke forge-slice-runner.sh directly to manage your own work dir.\n' >&2
+      exit 2 ;;
     --slice)
       WORKTREE="${1:-}"; shift; argc=$((argc - 1))
       set -- "$@" --slice "$WORKTREE" ;;             # forward it too (runner needs it)
@@ -78,15 +132,97 @@ WORKTREE="$(cd "$WORKTREE" && pwd)"                  # absolutize — the log pa
 [ -f "$RUNNER" ]  || { printf 'forge-jarvis-dispatch: runner not found: %s\n' "$RUNNER" >&2; exit 2; }
 [ -f "$CHANNEL" ] || { printf 'forge-jarvis-dispatch: log-only channel not found: %s\n' "$CHANNEL" >&2; exit 2; }
 
+# --- rotate stale runner state when a NEW work order lands (FR-235, m-45) --------------------
+# Called at exactly ONE point: right before materialize_work_order commits a new slice.yml —
+# every refusal path exits earlier, and the resume paths (crash re-dispatch, park→answer→
+# resume) take the honored-as-is early return and never reach it. The dir moves WHOLE (see
+# header: relay-markers are line-number-keyed siblings of notify.log). Archive, never delete.
+rotate_runner_work() {
+  _rw="$WORKTREE/.forge/runner-work"
+  _stale=0
+  if [ -d "$_rw" ] && [ -n "$(ls -A "$_rw" 2>/dev/null)" ]; then _stale=1; fi
+  [ "$_stale" = 1 ] || [ "$REPLACE_MATERIALIZED" = 1 ] || return 0
+  _parent="$WORKTREE/.forge/runner-work-archive"
+  _base="$_parent/$(date -u +%Y%m%dT%H%M%SZ)"
+  _dest="$_base"; _n=2
+  while [ -e "$_dest" ] || [ -L "$_dest" ]; do _dest="$_base-$_n"; _n=$((_n + 1)); done
+  mkdir -p "$_parent" || {
+    printf 'forge-jarvis-dispatch: REFUSED — cannot create %s; stale runner-work would poison the new work order. RELAY this refusal to the operator.\n' "$_parent" >&2
+    return 2
+  }
+  if [ "$_stale" = 1 ]; then
+    mv "$_rw" "$_dest" || {
+      printf 'forge-jarvis-dispatch: REFUSED — cannot rotate %s → %s; stale runner-work would poison the new work order. RELAY this refusal to the operator.\n' "$_rw" "$_dest" >&2
+      return 2
+    }
+  else
+    mkdir -p "$_dest" || {
+      printf 'forge-jarvis-dispatch: REFUSED — cannot create %s. RELAY this refusal to the operator.\n' "$_dest" >&2
+      return 2
+    }
+  fi
+  # A replaced helper-materialized slice.yml is part of the prior run — archive it alongside.
+  if [ "$REPLACE_MATERIALIZED" = 1 ] && [ -f "$WORKTREE/slice.yml" ]; then
+    mv "$WORKTREE/slice.yml" "$_dest/slice.yml" || {
+      printf 'forge-jarvis-dispatch: REFUSED — cannot archive the prior slice.yml into %s. RELAY this refusal to the operator.\n' "$_dest" >&2
+      return 2
+    }
+  fi
+  printf 'forge-jarvis-dispatch: rotated stale runner state -> %s\n' "$_dest" >&2
+  return 0
+}
+
 # --- materialize the work order from the milestone's locked plans (FR-197) -------------------
-# slice.yml present → honored untouched. Absent → build it from the single
-# .forge/phases/milestone-*/ dir: one phases/<name>/plan.md per phase subdir (plan-NN.md
-# concatenated in order), slice.yml listing the names numerically. Cannot → REFUSE, exit 2,
-# BEFORE the detach — the caller sees it synchronously and must relay it to the operator.
+# slice.yml present → honored untouched (unless --plan targets a helper-materialized one —
+# header doc). Absent → build it from the single .forge/phases/milestone-*/ dir: one
+# phases/<name>/plan.md per phase subdir (plan-NN.md concatenated in order), slice.yml listing
+# the names numerically; --plan scopes both. Cannot → REFUSE, exit 2, BEFORE the detach — the
+# caller sees it synchronously and must relay it to the operator.
 materialize_work_order() {
   if [ -f "$WORKTREE/slice.yml" ]; then
-    printf 'forge-jarvis-dispatch: slice.yml present — using it as-is\n' >&2
-    return 0
+    _hdr="$(head -n 1 "$WORKTREE/slice.yml" 2>/dev/null)"
+    if [ -z "$PLAN_SPECS" ]; then
+      # STALENESS GUARD (live 2026-07-23): a helper-materialized work order SNAPSHOTS
+      # the source plans at dispatch time; amend .forge/phases/.../plan-NN.md afterward
+      # and a plain re-dispatch would build the OLD spec silently (observed live: a full
+      # rebuild ran to the pre-amendment plan; the miss surfaced only because the
+      # operator poked). Materialization records one `# source: <phase>/<file> cksum=N`
+      # line per bundled plan; here each is re-checksummed and ANY divergence refuses
+      # LOUDLY. Refuse, never auto-rebuild: this branch also serves crash re-dispatch
+      # and park→answer→resume, and an auto-rotation would wipe the parked report the
+      # resume derives from. Hand-authored orders are never checked (they win, always);
+      # older materialized orders without fingerprints skip the check (lazy migration).
+      case "$_hdr" in
+        "# Materialized by forge-jarvis-dispatch from "*)
+          _srcrel="${_hdr#\# Materialized by forge-jarvis-dispatch from }"
+          _srcrel="${_srcrel% (delete to re-materialize)}"
+          _stale=""
+          while IFS= read -r _sl; do
+            case "$_sl" in "# source: "*) ;; *) continue ;; esac
+            _ref="${_sl#\# source: }"                    # <phase>/<file> cksum=<n>
+            _rf="${_ref% cksum=*}"; _rk="${_ref##* cksum=}"
+            _cur=""
+            [ -f "$WORKTREE/$_srcrel/$_rf" ] && _cur="$(cksum < "$WORKTREE/$_srcrel/$_rf" 2>/dev/null | cut -d' ' -f1)"
+            [ "$_cur" = "$_rk" ] || _stale="$_stale $_rf"
+          done < "$WORKTREE/slice.yml"
+          if [ -n "$_stale" ]; then
+            printf 'forge-jarvis-dispatch: REFUSED — materialized slice.yml is STALE:%s changed since materialization (source plan amended or removed). Re-dispatch with --plan to rebuild the work order (the prior one is archived), or delete slice.yml to re-materialize whole. RELAY this refusal to the operator.\n' "$_stale" >&2
+            return 2
+          fi ;;
+      esac
+      printf 'forge-jarvis-dispatch: slice.yml present — using it as-is\n' >&2
+      return 0
+    fi
+    # --plan asks for a NEW work order. Only a slice.yml this helper itself wrote may be
+    # replaced (and it is archived, not lost — rotate_runner_work); a hand-authored work
+    # order wins, always.
+    case "$_hdr" in
+      "# Materialized by forge-jarvis-dispatch"*)
+        REPLACE_MATERIALIZED=1 ;;
+      *)
+        printf 'forge-jarvis-dispatch: REFUSED — slice.yml present and not materialized by this helper; hand-authored work orders win. Delete it yourself to re-materialize with --plan. RELAY this refusal to the operator.\n' >&2
+        return 2 ;;
+    esac
   fi
   # Prefer the worktree's OWN milestone — .forge/phases/ carries the repo's whole milestone
   # history (32 dirs on the forge repo), so "the only milestone dir" is a fixture-world
@@ -128,6 +264,54 @@ materialize_work_order() {
       return 2
     fi
   fi
+  # --plan validation (FR-234): every spec must resolve inside the picked milestone dir —
+  # an unknown spec is a refusal, never a silent skip (a typo must not dispatch the wrong
+  # work order). Whole-phase specs must also hold at least one plan-NN.md, or the phase
+  # would silently vanish from the order below.
+  if [ -n "$PLAN_SPECS" ]; then
+    while IFS= read -r _s; do
+      [ -n "$_s" ] || continue
+      _sp="${_s%%/*}"
+      _pp=""; case "$_s" in */*) _pp="${_s#*/}" ;; esac
+      # Path hygiene (specs are semi-trusted operator input): the phase part must be a
+      # real dir NAME and the plan part a file NAME — a separator or dot-dir would let a
+      # crafted spec reach outside the milestone dir (case * matches / in sh patterns).
+      case "$_sp" in .|..)
+        printf 'forge-jarvis-dispatch: REFUSED — --plan %s: phase part must be a phase dir name. RELAY this refusal to the operator.\n' "$_s" >&2
+        return 2 ;;
+      esac
+      case "$_pp" in */*)
+        printf 'forge-jarvis-dispatch: REFUSED — --plan %s: the plan part must be a bare plan-NN name (no path separators). RELAY this refusal to the operator.\n' "$_s" >&2
+        return 2 ;;
+      esac
+      if [ ! -d "$_mdir/$_sp" ]; then
+        printf 'forge-jarvis-dispatch: REFUSED — --plan %s: no phase dir %s under %s. RELAY this refusal to the operator.\n' "$_s" "$_sp" "$_mdir" >&2
+        return 2
+      fi
+      if [ -n "$_pp" ]; then
+        case "$_pp" in *.md) : ;; *) _pp="$_pp.md" ;; esac
+        case "$_pp" in
+          plan-*.md) : ;;
+          *)
+            printf 'forge-jarvis-dispatch: REFUSED — --plan %s: the plan part must name a plan-NN file. RELAY this refusal to the operator.\n' "$_s" >&2
+            return 2 ;;
+        esac
+        if [ ! -f "$_mdir/$_sp/$_pp" ]; then
+          printf 'forge-jarvis-dispatch: REFUSED — --plan %s: no %s in %s. RELAY this refusal to the operator.\n' "$_s" "$_pp" "$_mdir/$_sp" >&2
+          return 2
+        fi
+      else
+        _has=0
+        for _f in "$_mdir/$_sp"/plan-*.md; do [ -f "$_f" ] && { _has=1; break; }; done
+        if [ "$_has" != 1 ]; then
+          printf 'forge-jarvis-dispatch: REFUSED — --plan %s: phase %s has no plan-*.md. RELAY this refusal to the operator.\n' "$_s" "$_sp" >&2
+          return 2
+        fi
+      fi
+    done <<PLAN_VALIDATE_EOF
+$PLAN_SPECS
+PLAN_VALIDATE_EOF
+  fi
   _tmp="$WORKTREE/slice.yml.tmp"
   # Write-target hygiene: refuse a pre-existing tmp (incl. a pre-committed symlink —
   # a redirect would follow it and truncate whatever it points at).
@@ -137,12 +321,34 @@ materialize_work_order() {
   fi
   printf '# Materialized by forge-jarvis-dispatch from %s (delete to re-materialize)\nphases:\n' "${_mdir#"$WORKTREE"/}" > "$_tmp"
   _count=0
+  _srcs=""             # per-plan source fingerprints — the staleness guard's record
+
   # Quoted glob iteration, numeric phase order — never word-split ls output
   # (phase/plan names are repo content; unquoted expansion would let a crafted
   # name pull arbitrary *.md into the runner's prompt).
   _names=$(for _d in "$_mdir"/*/; do [ -d "$_d" ] || continue; basename "$_d"; done | sort -n)
   while IFS= read -r _p; do
     [ -n "$_p" ] || continue
+    # --plan scoping (FR-234): with specs, only selected phases materialize; a whole-phase
+    # spec takes all its plans, plan-part specs take exactly those files. Numeric order
+    # comes from the sort -n pipeline above, regardless of --plan flag order.
+    _whole=1; _plansel=""
+    if [ -n "$PLAN_SPECS" ]; then
+      _sel=0; _whole=0
+      while IFS= read -r _s; do
+        [ -n "$_s" ] || continue
+        case "$_s" in
+          "$_p") _sel=1; _whole=1 ;;
+          "$_p"/*)
+            _sel=1
+            _f="${_s#*/}"; case "$_f" in *.md) : ;; *) _f="$_f.md" ;; esac
+            _plansel="$_plansel $_f" ;;
+        esac
+      done <<PLAN_SELECT_EOF
+$PLAN_SPECS
+PLAN_SELECT_EOF
+      [ "$_sel" = 1 ] || continue
+    fi
     _have=0
     for _f in "$_mdir/$_p"/plan-*.md; do [ -f "$_f" ] && { _have=1; break; }; done
     [ "$_have" = 1 ] || continue
@@ -156,7 +362,15 @@ materialize_work_order() {
     : > "$_pl"
     for _f in "$_mdir/$_p"/plan-*.md; do
       [ -f "$_f" ] || continue
+      if [ "$_whole" != 1 ]; then
+        case " $_plansel " in
+          *" $(basename "$_f") "*) : ;;
+          *) continue ;;
+        esac
+      fi
       cat "$_f" >> "$_pl"
+      _srcs="$_srcs# source: $_p/$(basename "$_f") cksum=$(cksum < "$_f" 2>/dev/null | cut -d' ' -f1)
+"
     done
     printf '  - %s\n' "$_p" >> "$_tmp"
     _count=$((_count + 1))
@@ -168,6 +382,13 @@ MATERIALIZE_EOF
     printf 'forge-jarvis-dispatch: REFUSED — %s has no phase plans (plan-*.md); nothing to dispatch. RELAY this refusal to the operator.\n' "$_mdir" >&2
     return 2
   fi
+  # Source fingerprints land AFTER the phases block (the runner's phases parser stops
+  # at the first non-list line — interleaving them would truncate the phase list).
+  # The staleness guard above re-checks them on the next plain re-dispatch.
+  printf '%s' "$_srcs" >> "$_tmp"
+  # Commit point: the new work order definitely lands. Rotate stale runner state first
+  # (FR-235) — this is the ONLY call site; every refusal above exits before it.
+  rotate_runner_work || { rm -f "$_tmp"; return 2; }
   mv "$_tmp" "$WORKTREE/slice.yml"
   printf 'forge-jarvis-dispatch: materialized slice.yml (%s phase(s)) from %s\n' "$_count" "${_mdir#"$WORKTREE"/}" >&2
   return 0
@@ -178,10 +399,13 @@ LOG="$WORKTREE/.forge/runner-work/notify.log"        # INTO the slice worktree (
 
 if [ "$DRY_RUN" = "1" ]; then
   # Side-effect-free: report work-order state to stderr, print the command to stdout.
-  if [ -f "$WORKTREE/slice.yml" ]; then
+  # (Materialization AND rotation both live behind the real dispatch — dry-run touches nothing.)
+  if [ -n "$PLAN_SPECS" ]; then
+    printf 'forge-jarvis-dispatch: (dry-run) --plan specs given — a real dispatch materializes a SCOPED work order (replacing a helper-materialized slice.yml, refusing a hand-authored one) and rotates stale runner-work\n' >&2
+  elif [ -f "$WORKTREE/slice.yml" ]; then
     printf 'forge-jarvis-dispatch: (dry-run) slice.yml present — will be used as-is\n' >&2
   else
-    printf 'forge-jarvis-dispatch: (dry-run) no slice.yml — a real dispatch materializes it from .forge/phases/milestone-*/\n' >&2
+    printf 'forge-jarvis-dispatch: (dry-run) no slice.yml — a real dispatch materializes it from .forge/phases/milestone-*/ and rotates stale runner-work\n' >&2
   fi
   # Print exactly what would run — greppable: worktree-scoped log, log-only channel, nohup, forwarded args.
   printf 'nohup env FORGE_SLICE_NOTIFY_LOG=%s FORGE_SLICE_NOTIFY=%s %s' "$LOG" "$CHANNEL" "$RUNNER"

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

@@ -54,6 +54,15 @@
 #   NO block → sensible defaults (the launcher is operator-invoked, not ambient — unlike
 #   the board, absence does not mean inert).
 #
+# ONE DOOR PER NAME (firstmate-review adoption, 2026-07-22): docs/jarvis.md has said
+# "two live presences must never share one name" since m-37 — discipline, no mechanism.
+# On REAL launch (never --dry-run, which stays pure resolution) this script scans live
+# processes for a `claude remote-control` already holding the resolved sticky name on
+# THIS machine and refuses loudly with the live pid. Exact --name token match, so a
+# live jarvis-<repo>-personal never blocks jarvis-<repo>. The ps read is env-overridable
+# (FORGE_JARVIS_PS — the FORGE_JARVIS_FOLD stub pattern) so tests inject fixtures; an
+# unreadable ps warns and proceeds — advisory hygiene, not a security gate.
+#
 # USAGE:
 #   .forge/checks/forge-jarvis.sh [--dry-run] [--name <full-name>] [--capacity <N>]
 #     --dry-run    print the fully resolved command on stdout and exit 0 — never executes.
@@ -165,6 +174,25 @@ fi
 # .claude/skills/jarvis/SKILL.md ("Session binding" / arm-the-watches). The launcher
 # stays presence-only and deliberately keeps no relay glue.
 
+# --- double-start guard: one door per name per machine ------------------------
+# The sticky name is the phone's ONLY discoverability anchor (probe ii); a second
+# same-name server on this machine would co-mingle two presences behind one list
+# entry. Checked before the toolchain check so the refusal is the first word.
+PS_OUT="$(${FORGE_JARVIS_PS:-ps -Ao pid=,args=} 2>/dev/null)" || {
+  printf 'forge-jarvis: duplicate-door check unavailable (ps read failed) — proceeding.\n' >&2
+  PS_OUT=""
+}
+LIVE_PID="$(printf '%s\n' "$PS_OUT" | awk -v name="$NAME" '
+  /remote-control/ {
+    for (i = 2; i <= NF; i++)
+      if (($i == "--name" && $(i+1) == name) || $i == ("--name=" name)) { print $1; exit }
+  }')"
+if [ -n "$LIVE_PID" ]; then
+  printf 'forge-jarvis: %s is already live on this machine (pid %s) — one door per name.\n' "$NAME" "$LIVE_PID" >&2
+  printf 'forge-jarvis: attach to the running door instead, or stop it first: kill %s\n' "$LIVE_PID" >&2
+  exit 2
+fi
+
 # --- launch ------------------------------------------------------------------
 command -v claude >/dev/null 2>&1 || {
   printf 'forge-jarvis: `claude` not found on PATH.\n' >&2