forge-orkes 0.71.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

@@ -25,9 +25,13 @@
 # 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 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).
+# --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.
@@ -55,9 +59,9 @@
 # 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. An explicitly
-# forwarded --work-dir is the caller's own state management and is NOT rotated; dispatching a
-# new order while the prior runner still lives in the worktree is operator error, unchanged.
+# 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
@@ -70,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)"
@@ -98,6 +111,12 @@ while [ "$argc" -gt 0 ]; do
       [ -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)
@@ -161,14 +180,43 @@ rotate_runner_work() {
 # caller sees it synchronously and must relay it to the operator.
 materialize_work_order() {
   if [ -f "$WORKTREE/slice.yml" ]; then
+    _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 "$(head -n 1 "$WORKTREE/slice.yml" 2>/dev/null)" in
+    case "$_hdr" in
       "# Materialized by forge-jarvis-dispatch"*)
         REPLACE_MATERIALIZED=1 ;;
       *)
@@ -273,6 +321,8 @@ PLAN_VALIDATE_EOF
   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).
@@ -319,6 +369,8 @@ PLAN_SELECT_EOF
         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))
@@ -330,6 +382,10 @@ 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; }

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

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

@@ -20,12 +20,18 @@
 #   exit: 0 = ok=clean; 1 = one or more findings; 2 = bad invocation (missing/unreadable file)
 #
 # Required fields (confirmed against the live file — zero false positives today):
-#   milestone entry: id, name, phases (non-empty)
+#   milestone entry: id, name, phases (non-empty — an empty list, `phases: []` or a
+#   block-style key with no items, raises missing-field:milestone:<id>:phases)
 #   phase entry:     id, name, goal, requirements, dependencies, success_criteria,
 #                    estimated_hours, status
 #   milestone_dir is DELIBERATELY not required — 17/65 live phase entries predate
 #   the nested-layout convention. Validated only when present (bad-milestone-dir).
 #
+# A milestone's phases: list is parsed in all three shapes YAML allows here:
+# one-line flow ([1, 2]), wrapped flow ([1,\n  2]), and block style (- 1 items).
+# Trailing "# comment" text on id/milestone_dir/phases lines is stripped before
+# capture (mirrors forge-check-lint.sh strip_comment).
+#
 # Pure POSIX sh + awk. No git-repo dependency (reads the file directly, unlike the
 # diff-scoped forge-hold-check.sh/forge-check-lint.sh). Collects every finding in
 # one pass before deciding exit code — a single run surfaces everything wrong.
@@ -51,6 +57,10 @@ function unquote(s) {
   gsub(/"/, "", s)
   return s
 }
+function strip_comment(s) {
+  sub(/[ \t]#.*$/, "", s)
+  return s
+}
 function bare_num(s,   n) {
   n = unquote(trim(s))
   if (n ~ /^m-/) n = substr(n, 3)
@@ -70,6 +80,7 @@ function finish_entry() {
     ph_mdir[ph_count] = cur_mdir
   }
   entry_open = 0
+  ph_collect = 0
   cur_id = ""; cur_fields = ""; cur_mdir = ""; cur_phaselist = ""
 }
 
@@ -107,13 +118,14 @@ block == "waves" && $0 ~ /^    [0-9]+:/ {
   entry_type = (block == "milestones" ? "milestone" : "phase")
   val = $0
   sub(/^    - id:[ \t]*/, "", val)
-  cur_id = unquote(trim(val))
+  cur_id = unquote(trim(strip_comment(val)))
   cur_fields = " id "
   next
 }
 
 # 6-space field line inside an open entry
 (block == "milestones" || block == "phases") && entry_open && $0 ~ /^      [A-Za-z_]+:/ {
+  ph_collect = 0
   line = $0
   sub(/^      /, "", line)
   match(line, /^[A-Za-z_]+/)
@@ -122,17 +134,45 @@ block == "waves" && $0 ~ /^    [0-9]+:/ {
   if (field == "milestone_dir") {
     val = line
     sub(/^milestone_dir:[ \t]*/, "", val)
-    cur_mdir = unquote(trim(val))
+    cur_mdir = unquote(trim(strip_comment(val)))
   }
   if (field == "phases" && entry_type == "milestone") {
-    rest = line
+    rest = strip_comment(line)
+    sub(/^phases:[ \t]*/, "", rest)
     if (match(rest, /\[[^]]*\]/)) {
       cur_phaselist = substr(rest, RSTART + 1, RLENGTH - 2)
+    } else if (rest ~ /^\[/) {
+      cur_phaselist = substr(rest, 2)
+      ph_collect = 1
+    } else if (rest == "") {
+      ph_collect = 2
     }
   }
   next
 }
 
+# wrapped flow list continuation: collect until the ] that closes phases: [...
+# (a new 6-space field line ends collection via the rule above — failsafe for
+# a bracket that never closes)
+block == "milestones" && entry_open && ph_collect == 1 && $0 ~ /^      / {
+  line = strip_comment($0)
+  if (match(line, /\]/)) {
+    cur_phaselist = cur_phaselist " " substr(line, 1, RSTART - 1)
+    ph_collect = 0
+  } else {
+    cur_phaselist = cur_phaselist " " line
+  }
+  next
+}
+
+# block-style list item under a bare "phases:" key: "        - 4"
+block == "milestones" && entry_open && ph_collect == 2 && $0 ~ /^        - / {
+  line = strip_comment($0)
+  sub(/^        - [ \t]*/, "", line)
+  cur_phaselist = cur_phaselist " " unquote(trim(line))
+  next
+}
+
 # any other 4-space line inside milestones:/phases: (not "- id:") -> malformed
 # dedent: closes the current entry without opening a new one.
 (block == "milestones" || block == "phases") && $0 ~ /^    [A-Za-z_-]/ {
@@ -140,13 +180,8 @@ block == "waves" && $0 ~ /^    [0-9]+:/ {
   next
 }
 
-END {
-  finish_entry()
-
-  required_ms = "name phases"
-  required_ph = "name goal requirements dependencies success_criteria estimated_hours status"
-
-  # 1. required fields
+# 1. required fields (+ non-empty phases list on milestones)
+function check_fields(   i, j, n, reqs, cnt, toks) {
   for (i = 1; i <= ms_count; i++) {
     n = split(required_ms, reqs, " ")
     for (j = 1; j <= n; j++) {
@@ -155,6 +190,15 @@ END {
         found++
       }
     }
+    if (index(ms_fields[i], " phases ") != 0) {
+      cnt = 0
+      n = split(ms_phaselist[i], toks, /[ ,]+/)
+      for (j = 1; j <= n; j++) if (trim(toks[j]) != "") cnt++
+      if (cnt == 0) {
+        print "finding=missing-field:milestone:" ms_id[i] ":phases"
+        found++
+      }
+    }
   }
   for (i = 1; i <= ph_count; i++) {
     n = split(required_ph, reqs, " ")
@@ -165,39 +209,60 @@ END {
       }
     }
   }
+}
 
-  # phase-id set + first-seen order tracking for duplicate detection
+# phase-id bookkeeping consumed by check_dups/check_refs/check_orphans:
+# dup_count (occurrences), dup_list (mdir detail per occurrence), phase_exists (set)
+function collect_phase_index(   i, id) {
   for (i = 1; i <= ph_count; i++) {
     id = ph_id[i]
-    phase_seen[id] = phase_seen[id] "" (phase_seen[id] == "" ? "" : ",")
     dup_list[id] = (dup_list[id] == "" ? "" : dup_list[id] ",") (ph_mdir[i] == "" ? "(none)" : ph_mdir[i])
     dup_count[id]++
     phase_exists[id] = 1
   }
+}
+
+# pre-pass: claimed_by[] must be fully populated before check_orphans reads it
+function collect_claimed(   i, j, m, claimed, pid) {
+  for (i = 1; i <= ms_count; i++) {
+    m = split(ms_phaselist[i], claimed, /[ ,]+/)
+    for (j = 1; j <= m; j++) {
+      pid = trim(claimed[j])
+      if (pid != "") claimed_by[pid] = 1
+    }
+  }
+}
 
-  # 2. duplicate phase ids
-  for (id in dup_count) {
-    if (dup_count[id] > 1) {
+# 2. duplicate phase ids — first-seen order over ph_id[] (stable across awk
+# impls, unlike for-in), one report per id via dup_reported[]
+function check_dups(   i, id) {
+  for (i = 1; i <= ph_count; i++) {
+    id = ph_id[i]
+    if (dup_count[id] > 1 && !(id in dup_reported)) {
+      dup_reported[id] = 1
       print "finding=duplicate-phase-id:" id ":" dup_list[id]
       found++
     }
   }
+}
 
-  # 3. dangling-phase-ref (milestone claims a phase id with no phase entry)
+# 3. dangling-phase-ref (milestone claims a phase id with no phase entry)
+function check_refs(   i, j, m, claimed, pid) {
   for (i = 1; i <= ms_count; i++) {
     m = split(ms_phaselist[i], claimed, /[ ,]+/)
     for (j = 1; j <= m; j++) {
       pid = trim(claimed[j])
       if (pid == "") continue
-      claimed_by[pid] = 1
       if (!(pid in phase_exists)) {
         print "finding=dangling-phase-ref:milestone:" ms_id[i] ":phase:" pid
         found++
       }
     }
   }
+}
 
-  # orphan-phase (phase entry claimed by zero milestones)
+# orphan-phase (phase entry claimed by zero milestones; reads claimed_by[])
+function check_orphans(   i, id) {
   for (i = 1; i <= ph_count; i++) {
     id = ph_id[i]
     if (!(id in claimed_by)) {
@@ -205,8 +270,10 @@ END {
       found++
     }
   }
+}
 
-  # 4. bad-milestone-dir (milestone_dir prefix must resolve to a real milestone id)
+# 4. bad-milestone-dir (milestone_dir prefix must resolve to a real milestone id)
+function check_mdirs(   i, prefix, numeral) {
   for (i = 1; i <= ms_count; i++) {
     ms_numeral[bare_num(ms_id[i])] = 1
   }
@@ -222,8 +289,10 @@ END {
       }
     }
   }
+}
 
-  # 5. dangling-wave-ref
+# 5. dangling-wave-ref
+function check_waves(   i, j, m, wids, pid) {
   for (i = 1; i <= wave_count; i++) {
     m = split(wave_ids[i], wids, /[ ,]+/)
     for (j = 1; j <= m; j++) {
@@ -235,6 +304,22 @@ END {
       }
     }
   }
+}
+
+END {
+  finish_entry()
+
+  required_ms = "name phases"
+  required_ph = "name goal requirements dependencies success_criteria estimated_hours status"
+
+  check_fields()
+  collect_phase_index()
+  collect_claimed()
+  check_dups()
+  check_refs()
+  check_orphans()
+  check_mdirs()
+  check_waves()
 
   if (found + 0 == 0) {
     print "ok=clean"
@@ -243,4 +328,3 @@ END {
   exit 1
 }
 ' "$FILE"
-exit $?