forge-orkes 0.68.1 → 0.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.68.1",
+  "version": "0.71.0",
   "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-slice-runner.sh

@@ -571,7 +571,15 @@ for phase in $PHASES; do
 
     # (4) REQUIRE the on-disk phase-report.yml. Absent = crash → halt now (do NOT
     #     spend the retry on a crash; the resume path re-runs it from files).
+    #     This is a slice END, so it MUST ping like the other two ends (checks-failed
+    #     halt below, done) — a silent phone is never success. Live gap: canvaz
+    #     2026-07-23, m-EVT01 hit error_max_turns and the slice died dark. Key is
+    #     per-phase ("$phase-crash"), NOT the shared "slice" key: a crash marker on
+    #     the shared key would suppress a LATER legitimate checks-failed halt after
+    #     resume; a re-crash of the same phase stays deduped (append-once semantics).
     if [ ! -f "$report" ]; then
+      slice_notify halt "$phase-crash" \
+        "slice HALTED at phase $phase ($idx/$total) — launcher crash, no phase-report.yml written (attempt $attempt); see $wdir/result.json + $wdir/launch.err"
       printf '[runner] phase %s: no phase-report.yml written at %s — halting\n' "$phase" "$report" >&2
       printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
       exit 1

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

@@ -56,6 +56,8 @@ The helper (see its header for the full contract) owns the caller-side environme
 - **`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).
+- **Mid-milestone re-dispatch is `--plan`** (FR-234): a later "go" through the same worktree (plan-01 landed, plan-02 next) adds `--plan <phase>/plan-02` (or `--plan <phase>` for a whole phase; repeatable) so only the named work is bundled — never landed plans. A typo'd spec refuses loudly; a hand-authored `slice.yml` always wins (`--plan` refuses to replace it — only a helper-materialized one is archived and rebuilt). No more hand-authoring a scoped `slice.yml` per re-dispatch.
+- **A new work order starts pristine** (FR-235): materializing a new `slice.yml` automatically rotates stale `<worktree>/.forge/runner-work/` into `.forge/runner-work-archive/<ts>/` — old ping markers and phase reports would otherwise silence the new run's done ping and skip its phases. A resume (crash, or park→answer→resume) keeps the existing `slice.yml` and is never rotated. Nothing is deleted; the archive keeps the prior run's evidence.
 - **Runner artifacts live at knowable paths — never walk the filesystem for them** (a walk rooted at `/` or the bare home is refused by the Bash guard): work dir `<worktree>/.forge/runner-work/`, per-phase `phase-<N>/result.json` (with `phase-report.yml` and `answer.md`), ping log `notify.log`, dispatch/refusal output `dispatch.out` — state these paths to any session you spawn about a slice.
 
 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).

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

@@ -139,6 +139,8 @@ If a sibling milestone (e.g. m50) has state + requirements but is missing from `
 
 **Promoted-from-backlog milestone (`milestone.origin` set).** If `state/milestone-{N}.yml` carries `milestone.origin: {R-id}` (set by `forge` Step 1.2 when promoting a Standard-tier refactor item), no extra bookkeeping is needed here — the originating backlog item is flipped to `done` automatically when the milestone completes (see `reviewing` → **Promoted Milestone Completion Hook**). Just plan it as a normal milestone.
 
+**Roadmap integrity check (advisory, m-39).** After writing or updating `roadmap.yml` in any of the three cases above, run `.forge/checks/forge-roadmap-check.sh`. If it exits non-zero, surface every `finding=...` line to the operator as one advisory note (e.g. *"roadmap-check found {N} issue(s): {lines}"*). This NEVER blocks — Step 9 Present and the handoff proceed regardless of findings; it is a signal, not a gate (same advisory posture as `verification.commands` in FORGE.md → Verification Gates). Script absent (pre-m-39 install) → skip silently.
+
 ## Step 6: Decompose Tasks
 
 ### Step 6.1: Cross-Layer Contract Detection

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,40 @@
 # 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.
+# --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).
 #
 #   --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. 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.
+#
 # 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
@@ -55,6 +83,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 +93,11 @@ 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}
+" ;;
     --slice)
       WORKTREE="${1:-}"; shift; argc=$((argc - 1))
       set -- "$@" --slice "$WORKTREE" ;;             # forward it too (runner needs it)
@@ -78,15 +113,68 @@ 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
+    if [ -z "$PLAN_SPECS" ]; then
+      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
+      "# 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 +216,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).
@@ -143,6 +279,26 @@ materialize_work_order() {
   _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,6 +312,12 @@ 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"
     done
     printf '  - %s\n' "$_p" >> "$_tmp"
@@ -168,6 +330,9 @@ 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
+  # 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 +343,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-roadmap-check.sh

@@ -0,0 +1,246 @@
+#!/usr/bin/env sh
+# forge-roadmap-check.sh — structural integrity check for .forge/roadmap.yml (m-39).
+#
+# Validates the roadmap against the drift class that caused the m-34/m-36 phase-id
+# collision: two independent renumbering passes both picked phase id 63. A flat
+# grep over "id: N" cannot tell a milestone's id from a phase's id from an
+# unrelated numeral (estimated_hours: 63), and cannot catch a field that drifted
+# to the wrong indentation depth. This check instead walks the file as a small
+# indentation-keyed state machine over roadmap.yml's three fixed second-level
+# blocks (milestones:/phases:/waves:) — HONEST LIMIT: it understands exactly this
+# one fixed shape, not arbitrary YAML.
+#
+#   forge-roadmap-check.sh [<roadmap-file>]      # default: <git-root>/.forge/roadmap.yml
+#
+#   stdout (machine-parseable, fold style):
+#     ok=clean                                   # no findings
+#     finding=<rule>:<detail>                     # one line per problem
+#     rule ∈ missing-field | duplicate-phase-id | dangling-phase-ref | orphan-phase
+#          | bad-milestone-dir | dangling-wave-ref
+#   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)
+#   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).
+#
+# 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.
+set -u
+
+FILE="${1:-}"
+if [ -z "$FILE" ]; then
+  ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+  FILE="$ROOT/.forge/roadmap.yml"
+fi
+
+if [ ! -f "$FILE" ] || [ ! -r "$FILE" ]; then
+  echo "roadmap-check: $FILE: not found or unreadable" >&2
+  exit 2
+fi
+
+awk '
+function trim(s) {
+  gsub(/^[ \t]+|[ \t]+$/, "", s)
+  return s
+}
+function unquote(s) {
+  gsub(/"/, "", s)
+  return s
+}
+function bare_num(s,   n) {
+  n = unquote(trim(s))
+  if (n ~ /^m-/) n = substr(n, 3)
+  return n
+}
+function finish_entry() {
+  if (!entry_open) return
+  if (entry_type == "milestone") {
+    ms_count++
+    ms_id[ms_count] = cur_id
+    ms_fields[ms_count] = cur_fields
+    ms_phaselist[ms_count] = cur_phaselist
+  } else if (entry_type == "phase") {
+    ph_count++
+    ph_id[ph_count] = cur_id + 0
+    ph_fields[ph_count] = cur_fields
+    ph_mdir[ph_count] = cur_mdir
+  }
+  entry_open = 0
+  cur_id = ""; cur_fields = ""; cur_mdir = ""; cur_phaselist = ""
+}
+
+# 2-space block header
+$0 ~ /^  (milestones|phases|waves):[ \t]*$/ {
+  finish_entry()
+  block = trim($0)
+  gsub(/:$/, "", block)
+  next
+}
+
+# waves block: "    N: [a, b, c]"
+block == "waves" && $0 ~ /^    [0-9]+:/ {
+  line = $0
+  sub(/^    /, "", line)
+  split(line, kv, ":")
+  wnum = trim(kv[1])
+  rest = line
+  sub(/^[^:]*:/, "", rest)
+  if (match(rest, /\[[^]]*\]/)) {
+    ids = substr(rest, RSTART + 1, RLENGTH - 2)
+  } else {
+    ids = ""
+  }
+  wave_count++
+  wave_num[wave_count] = wnum
+  wave_ids[wave_count] = ids
+  next
+}
+
+# entry open: "    - id: 36" / "    - id: \"m-33\""
+(block == "milestones" || block == "phases") && $0 ~ /^    - id:/ {
+  finish_entry()
+  entry_open = 1
+  entry_type = (block == "milestones" ? "milestone" : "phase")
+  val = $0
+  sub(/^    - id:[ \t]*/, "", val)
+  cur_id = unquote(trim(val))
+  cur_fields = " id "
+  next
+}
+
+# 6-space field line inside an open entry
+(block == "milestones" || block == "phases") && entry_open && $0 ~ /^      [A-Za-z_]+:/ {
+  line = $0
+  sub(/^      /, "", line)
+  match(line, /^[A-Za-z_]+/)
+  field = substr(line, RSTART, RLENGTH)
+  cur_fields = cur_fields field " "
+  if (field == "milestone_dir") {
+    val = line
+    sub(/^milestone_dir:[ \t]*/, "", val)
+    cur_mdir = unquote(trim(val))
+  }
+  if (field == "phases" && entry_type == "milestone") {
+    rest = line
+    if (match(rest, /\[[^]]*\]/)) {
+      cur_phaselist = substr(rest, RSTART + 1, RLENGTH - 2)
+    }
+  }
+  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_-]/ {
+  finish_entry()
+  next
+}
+
+END {
+  finish_entry()
+
+  required_ms = "name phases"
+  required_ph = "name goal requirements dependencies success_criteria estimated_hours status"
+
+  # 1. required fields
+  for (i = 1; i <= ms_count; i++) {
+    n = split(required_ms, reqs, " ")
+    for (j = 1; j <= n; j++) {
+      if (index(ms_fields[i], " " reqs[j] " ") == 0) {
+        print "finding=missing-field:milestone:" ms_id[i] ":" reqs[j]
+        found++
+      }
+    }
+  }
+  for (i = 1; i <= ph_count; i++) {
+    n = split(required_ph, reqs, " ")
+    for (j = 1; j <= n; j++) {
+      if (index(ph_fields[i], " " reqs[j] " ") == 0) {
+        print "finding=missing-field:phase:" ph_id[i] ":" reqs[j]
+        found++
+      }
+    }
+  }
+
+  # phase-id set + first-seen order tracking for duplicate detection
+  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
+  }
+
+  # 2. duplicate phase ids
+  for (id in dup_count) {
+    if (dup_count[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)
+  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)
+  for (i = 1; i <= ph_count; i++) {
+    id = ph_id[i]
+    if (!(id in claimed_by)) {
+      print "finding=orphan-phase:" id ":" (ph_mdir[i] == "" ? "(none)" : ph_mdir[i])
+      found++
+    }
+  }
+
+  # 4. bad-milestone-dir (milestone_dir prefix must resolve to a real milestone id)
+  for (i = 1; i <= ms_count; i++) {
+    ms_numeral[bare_num(ms_id[i])] = 1
+  }
+  for (i = 1; i <= ph_count; i++) {
+    if (ph_mdir[i] == "") continue
+    if (match(ph_mdir[i], /^milestone-[^\/]+/)) {
+      prefix = substr(ph_mdir[i], RSTART, RLENGTH)
+      numeral = prefix
+      sub(/^milestone-/, "", numeral)
+      if (!(numeral in ms_numeral)) {
+        print "finding=bad-milestone-dir:" ph_id[i] ":" ph_mdir[i]
+        found++
+      }
+    }
+  }
+
+  # 5. dangling-wave-ref
+  for (i = 1; i <= wave_count; i++) {
+    m = split(wave_ids[i], wids, /[ ,]+/)
+    for (j = 1; j <= m; j++) {
+      pid = trim(wids[j])
+      if (pid == "") continue
+      if (!(pid in phase_exists)) {
+        print "finding=dangling-wave-ref:" wave_num[i] ":" pid
+        found++
+      }
+    }
+  }
+
+  if (found + 0 == 0) {
+    print "ok=clean"
+    exit 0
+  }
+  exit 1
+}
+' "$FILE"
+exit $?

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

@@ -192,6 +192,153 @@ else
   bad "numeric-id branch pick" "rc=$rc err=$err14"
 fi
 
+# --- 15-18. --plan WORK-ORDER SCOPING (FR-234; canvaz desire path 2026-07-22 defect 2:
+#     materialization bundled ALL phase dirs + ALL plan-NN.md, so a mid-milestone re-dispatch
+#     re-bundled landed work). --plan <phase> takes a whole phase, <phase>/plan-NN one plan
+#     file; unknown specs and hand-authored slice.yml refuse loudly. mktemp fixtures — a
+#     single milestone dir exercises the (branch-free) fallback pick.
+
+# 15. single-plan spec: only the named plan file lands in the phase's plan.md
+PSLICE="$ROOT/plan-one-wt"
+mkdir -p "$PSLICE/.forge/phases/milestone-77/1-aaa"
+printf 'LANDED plan one\n' > "$PSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+printf 'NEXT plan two\n'   > "$PSLICE/.forge/phases/milestone-77/1-aaa/plan-02.md"
+err15="$(sh "$DISPATCH" --slice "$PSLICE" --materialize-only --plan 1-aaa/plan-02 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && grep -q '^  - 1-aaa$' "$PSLICE/slice.yml" 2>/dev/null \
+   && grep -q 'NEXT plan two' "$PSLICE/phases/1-aaa/plan.md" 2>/dev/null \
+   && ! grep -q 'LANDED plan one' "$PSLICE/phases/1-aaa/plan.md" 2>/dev/null; then
+  ok "--plan <phase>/plan-NN scopes to exactly that plan (landed sibling NOT re-bundled)"
+else
+  bad "--plan single-plan scoping" "rc=$rc err=$err15 plan.md=$(cat "$PSLICE/phases/1-aaa/plan.md" 2>/dev/null)"
+fi
+
+# 16. whole-phase specs + ordering: numeric slice order regardless of flag order; unselected
+#     phases do NOT materialize
+OSLICE="$ROOT/plan-order-wt"
+mkdir -p "$OSLICE/.forge/phases/milestone-77/71-aaa" "$OSLICE/.forge/phases/milestone-77/72-bbb" "$OSLICE/.forge/phases/milestone-77/73-ccc"
+printf 'plan A\n' > "$OSLICE/.forge/phases/milestone-77/71-aaa/plan-01.md"
+printf 'plan B\n' > "$OSLICE/.forge/phases/milestone-77/72-bbb/plan-01.md"
+printf 'decoy\n'  > "$OSLICE/.forge/phases/milestone-77/73-ccc/plan-01.md"
+err16="$(sh "$DISPATCH" --slice "$OSLICE" --materialize-only --plan 72-bbb --plan 71-aaa 2>&1)"; rc=$?
+if [ "$rc" = 0 ] \
+   && [ "$(grep -E '^  - ' "$OSLICE/slice.yml" 2>/dev/null | tr -d ' -')" = "71aaa
+72bbb" ] \
+   && grep -q 'plan A' "$OSLICE/phases/71-aaa/plan.md" 2>/dev/null \
+   && grep -q 'plan B' "$OSLICE/phases/72-bbb/plan.md" 2>/dev/null \
+   && [ ! -d "$OSLICE/phases/73-ccc" ]; then
+  ok "--plan whole-phase specs keep numeric order (flag order ignored); unselected phase skipped"
+else
+  bad "--plan ordering" "rc=$rc err=$err16 slice.yml=$(cat "$OSLICE/slice.yml" 2>/dev/null)"
+fi
+
+# 17. NEG: unknown spec → loud refusal, no slice.yml (a typo must not dispatch the wrong order)
+USLICE="$ROOT/plan-unknown-wt"
+mkdir -p "$USLICE/.forge/phases/milestone-77/1-aaa"
+printf 'x\n' > "$USLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+err17="$(sh "$DISPATCH" --slice "$USLICE" --materialize-only --plan 2-nope 2>&1)"; rc=$?
+if [ "$rc" != 0 ] && [ ! -f "$USLICE/slice.yml" ] && printf '%s' "$err17" | grep -q 'REFUSED'; then
+  ok "neg-control: unknown --plan spec → loud refusal, no slice.yml"
+else
+  bad "unknown --plan spec" "rc=$rc err=$err17"
+fi
+
+# 18. NEG: --plan vs a HAND-AUTHORED slice.yml (no materializer header) → refusal; slice.yml
+#     byte-unchanged, seeded runner-work untouched (hand-authored work orders win, always)
+HPSLICE="$ROOT/plan-hand-wt"
+mkdir -p "$HPSLICE/.forge/phases/milestone-77/1-aaa" "$HPSLICE/.forge/runner-work/pings"
+printf 'x\n' > "$HPSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+printf 'phases:\n  - hand-rolled\n' > "$HPSLICE/slice.yml"
+touch "$HPSLICE/.forge/runner-work/pings/k-done.marker"
+before18="$(cat "$HPSLICE/slice.yml")"
+err18="$(sh "$DISPATCH" --slice "$HPSLICE" --materialize-only --plan 1-aaa 2>&1)"; rc=$?
+if [ "$rc" != 0 ] && printf '%s' "$err18" | grep -q 'REFUSED' \
+   && [ "$(cat "$HPSLICE/slice.yml")" = "$before18" ] \
+   && [ -f "$HPSLICE/.forge/runner-work/pings/k-done.marker" ]; then
+  ok "neg-control: --plan refuses a hand-authored slice.yml; nothing touched"
+else
+  bad "--plan vs hand-authored" "rc=$rc err=$err18"
+fi
+
+# 18b. NEG (path hygiene): a plan part carrying a separator (traversal shape) refuses —
+#      sh case patterns let * match /, so plan-../x.md would pass the plan-*.md form check
+#      and reach outside the milestone dir without this guard.
+TSLICE="$ROOT/plan-traverse-wt"
+mkdir -p "$TSLICE/.forge/phases/milestone-77/1-aaa"
+printf 'x\n' > "$TSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+err18b="$(sh "$DISPATCH" --slice "$TSLICE" --materialize-only --plan '1-aaa/plan-../x' 2>&1)"; rc=$?
+if [ "$rc" != 0 ] && [ ! -f "$TSLICE/slice.yml" ] && printf '%s' "$err18b" | grep -q 'REFUSED'; then
+  ok "neg-control: --plan file part with a path separator → loud refusal (no traversal)"
+else
+  bad "--plan traversal guard" "rc=$rc err=$err18b"
+fi
+
+# --- 19-21. RUNNER-WORK ROTATION (FR-235; canvaz desire path 2026-07-22 defect 3: stale
+#     pings/{key}-{kind}.marker silenced the new run's done ping and index-keyed
+#     phase-{idx}/phase-report.yml verdict:done short-circuited the new phase). A NEW work
+#     order rotates runner-work WHOLE (relay-markers are line-number-keyed siblings of
+#     notify.log — a partial reset would misalign offsets); resume paths keep slice.yml and
+#     are never rotated; archive, never delete.
+
+# 19. materializing a NEW order rotates seeded state into runner-work-archive; a replaced
+#     helper-materialized slice.yml is archived alongside
+RSLICE="$ROOT/rotate-wt"
+mkdir -p "$RSLICE/.forge/phases/milestone-77/1-aaa"
+printf 'LANDED\n' > "$RSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+printf 'NEXT\n'   > "$RSLICE/.forge/phases/milestone-77/1-aaa/plan-02.md"
+sh "$DISPATCH" --slice "$RSLICE" --materialize-only >/dev/null 2>&1   # first order (all plans) — seeds a materialized slice.yml
+# Seed the "run happened" state AFTER the first materialization (a dispatch with stale
+# runner-work already present would rotate it — exactly the behavior under test in 19).
+mkdir -p "$RSLICE/.forge/runner-work/pings" "$RSLICE/.forge/runner-work/phase-1" "$RSLICE/.forge/runner-work/relay-markers"
+touch "$RSLICE/.forge/runner-work/pings/k-done.marker"
+printf 'verdict: done\n' > "$RSLICE/.forge/runner-work/phase-1/phase-report.yml"
+touch "$RSLICE/.forge/runner-work/relay-markers/1.relayed"
+err19="$(sh "$DISPATCH" --slice "$RSLICE" --materialize-only --plan 1-aaa/plan-02 2>&1)"; rc=$?
+if [ "$rc" = 0 ] \
+   && [ ! -e "$RSLICE/.forge/runner-work/pings/k-done.marker" ] \
+   && [ ! -e "$RSLICE/.forge/runner-work/phase-1/phase-report.yml" ] \
+   && ls "$RSLICE/.forge/runner-work-archive/"*/pings/k-done.marker >/dev/null 2>&1 \
+   && ls "$RSLICE/.forge/runner-work-archive/"*/phase-1/phase-report.yml >/dev/null 2>&1 \
+   && ls "$RSLICE/.forge/runner-work-archive/"*/relay-markers/1.relayed >/dev/null 2>&1 \
+   && ls "$RSLICE/.forge/runner-work-archive/"*/slice.yml >/dev/null 2>&1 \
+   && grep -q 'NEXT' "$RSLICE/phases/1-aaa/plan.md" 2>/dev/null \
+   && ! grep -q 'LANDED' "$RSLICE/phases/1-aaa/plan.md" 2>/dev/null; then
+  ok "new work order rotates runner-work WHOLE (pings+report+relay-markers) + archives replaced slice.yml"
+else
+  bad "rotation on new order" "rc=$rc err=$err19"
+fi
+
+# 20. NEG (resume preserved): existing materialized slice.yml, NO --plan → honored as-is,
+#     runner-work untouched, no archive (crash-resume / park→answer→resume path)
+KSLICE="$ROOT/keep-wt"
+mkdir -p "$KSLICE/.forge/phases/milestone-77/1-aaa"
+printf 'x\n' > "$KSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+sh "$DISPATCH" --slice "$KSLICE" --materialize-only >/dev/null 2>&1   # materialized header slice.yml
+mkdir -p "$KSLICE/.forge/runner-work/pings"                            # seed AFTER — see case 19 note
+touch "$KSLICE/.forge/runner-work/pings/k-done.marker"
+before20="$(cat "$KSLICE/slice.yml")"
+err20="$(sh "$DISPATCH" --slice "$KSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && [ "$(cat "$KSLICE/slice.yml")" = "$before20" ] \
+   && [ -f "$KSLICE/.forge/runner-work/pings/k-done.marker" ] \
+   && [ ! -d "$KSLICE/.forge/runner-work-archive" ]; then
+  ok "neg-control: existing slice.yml honored → NO rotation (resume state survives)"
+else
+  bad "resume preserved" "rc=$rc err=$err20"
+fi
+
+# 21. NEG: --dry-run stays fully side-effect-free — no slice.yml, no rotation, even with
+#     stale runner-work present (extends case 12)
+YSLICE="$ROOT/dry-rotate-wt"
+mkdir -p "$YSLICE/.forge/phases/milestone-77/1-aaa" "$YSLICE/.forge/runner-work/pings"
+printf 'x\n' > "$YSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+touch "$YSLICE/.forge/runner-work/pings/k-done.marker"
+sh "$DISPATCH" --slice "$YSLICE" --dry-run >/dev/null 2>&1
+if [ ! -f "$YSLICE/slice.yml" ] && [ ! -d "$YSLICE/.forge/runner-work-archive" ] \
+   && [ -f "$YSLICE/.forge/runner-work/pings/k-done.marker" ]; then
+  ok "neg-control: --dry-run rotates nothing, writes nothing"
+else
+  bad "dry-run rotation" "dry-run had side effects"
+fi
+
 # --- summary -----------------------------------------------------------------
 printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
 [ "$FAILED" = 0 ]