forge-orkes 0.71.0 → 0.72.2

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

@@ -7,7 +7,7 @@
 #           lint=fail          + finding=<rule>:<file>[:<line>] lines
 #           lint=justified justify="<trailer line>"
 #                              + "finding=<rule>:<file>[:<line>] justified" lines
-#           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.
 #   Range MUST be three-dot BASE...HEAD; scanned against merge-base(BASE, HEAD).
 #
@@ -28,17 +28,24 @@
 #              allowlist: still fires, still needs the operator act, only the label
 #              changes (partial source shrink keeps the stricter deleted-assertion);
 #          skip-marker — added .only(/.skip(/it.skip/describe.only/xit(/xdescribe(/
-#              @pytest.mark.skip/t.Skip() line.
+#              @pytest.mark.skip/t.Skip() line;
+#          driven-by-missing — CONFIG-GATED, default OFF: 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);
+#              finding's file slot = the offending commit's short SHA. Absent/
+#              false config = rule fully off. Base-side read: a PR cannot
+#              disable it for itself.
 #   Justification: a "Lint-Justify: <one line>" trailer in ANY commit message of
 #   merge-base..head (pure git). Lifts b/c/deleted-assertion/feature-removal/
-#   skip-marker → exit 0 lint=justified. NEVER lifts (a).
+#   skip-marker/driven-by-missing → exit 0 lint=justified. NEVER lifts (a).
 #
 # Offline by construction: remote-less mktemp fixture repos (NFR-032).
 #
 # Usage:
 #   ./.forge/checks/tests/forge-check-lint.test.sh                # all cases
 #   ./.forge/checks/tests/forge-check-lint.test.sh cannot-fail    # one tag
-# Filter tags: cannot-fail silent-fail existence-only deleted-assertion feature-removal skip-marker justify docs-only invocation
+# Filter tags: cannot-fail silent-fail existence-only deleted-assertion feature-removal skip-marker driven-by waiver-boundary justify docs-only invocation
 #
 # RED-phase friendly: missing helper → every selected case FAILS, suite exits
 # non-zero, no abort. Exits 0 iff every selected case passes. Self-cleans.
@@ -566,6 +573,121 @@ if running justify; then
   check "justify: trailer never saves a PR carrying rule a (exit 1)" "$RC" "1"
 fi
 
+# ---------------------------------------------------------------------------
+# driven-by — the config-gated Driven-by trailer rule (hold-waiver patch W2).
+# Default OFF; base-side project.yml attribution.driven_by: true turns it on.
+# ---------------------------------------------------------------------------
+if running driven-by; then
+  PROJ_ON='attribution:
+  driven_by: true'
+
+  # OFF (default): no config → a trailer-less commit is clean (zero behavior change)
+  R=$(new_repo db-off)
+  put "$R" src/app.js 'x'
+  pr "$R"
+  put "$R" src/app.js 'y'
+  run_lint "$R" 'main...pr'
+  check "driven-by OFF: no config, trailer-less commit is clean (exit 0)" "$RC" "0"
+  check_absent "driven-by OFF: no driven-by finding" "$OUT" "driven-by-missing"
+
+  # OFF (explicit false): rule stays off
+  R=$(new_repo db-false)
+  put "$R" .forge/project.yml 'attribution:
+  driven_by: false'
+  pr "$R"
+  put "$R" src/app.js 'y'
+  run_lint "$R" 'main...pr'
+  check "driven-by OFF: driven_by false stays off (exit 0)" "$RC" "0"
+
+  # ON: a commit missing the trailer fails, finding names its short SHA
+  R=$(new_repo db-on)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  put "$R" src/app.js 'y'
+  DB_SHA="$(git -C "$R" rev-parse --short pr)"
+  run_lint "$R" 'main...pr'
+  check "driven-by ON: missing trailer fails (exit 1)" "$RC" "1"
+  check_contains "driven-by ON: verdict" "$OUT" "lint=fail"
+  check_contains "driven-by ON: finding names the commit" "$OUT" "finding=driven-by-missing:$DB_SHA"
+
+  # ON: every commit carrying the trailer is clean (optional session ref allowed)
+  R=$(new_repo db-ok)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  put "$R" src/app.js 'y' 'Driven-by: zayne@zayne.co.za (session cse_01X)'
+  put "$R" src/app.js 'z' 'Driven-by: zayne@zayne.co.za'
+  run_lint "$R" 'main...pr'
+  check "driven-by ON: trailered commits are clean (exit 0)" "$RC" "0"
+  check "driven-by ON: verdict clean" "$OUT" "lint=clean"
+
+  # ON: a malformed trailer (no email shape) still fails
+  R=$(new_repo db-malformed)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  put "$R" src/app.js 'y' 'Driven-by: somebody'
+  run_lint "$R" 'main...pr'
+  check "driven-by ON: trailer without an email fails (exit 1)" "$RC" "1"
+  check_contains "driven-by ON: malformed finding" "$OUT" "finding=driven-by-missing:"
+
+  # ON, mixed: one trailered + one bare commit → only the bare one is named
+  R=$(new_repo db-mixed)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  put "$R" src/app.js 'y' 'Driven-by: zayne@zayne.co.za'
+  put "$R" src/other.js 'w'
+  DB_BARE="$(git -C "$R" rev-parse --short pr)"
+  DB_GOOD="$(git -C "$R" rev-parse --short pr~1)"
+  run_lint "$R" 'main...pr'
+  check "driven-by ON mixed: bare commit fails (exit 1)" "$RC" "1"
+  check_contains "driven-by ON mixed: bare commit named" "$OUT" "finding=driven-by-missing:$DB_BARE"
+  check_absent "driven-by ON mixed: trailered commit not named" "$OUT" "finding=driven-by-missing:$DB_GOOD"
+
+  # Base-side gate: a PR that deletes the config cannot switch the rule off for itself
+  R=$(new_repo db-evade)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  git -C "$R" rm -q .forge/project.yml
+  git -C "$R" commit -qm "drop attribution config"
+  run_lint "$R" 'main...pr'
+  check "driven-by ON: head-side config removal cannot evade (exit 1)" "$RC" "1"
+  check_contains "driven-by ON: evasion finding" "$OUT" "finding=driven-by-missing:"
+
+  # Lint-Justify lifts it (same operator-act channel as the other liftable rules)
+  R=$(new_repo db-justify)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  put "$R" src/app.js 'y' 'Lint-Justify: host-authored dependabot commit, attribution n/a'
+  run_lint "$R" 'main...pr'
+  check "driven-by ON: Lint-Justify lifts (exit 0)" "$RC" "0"
+  check_contains "driven-by ON: justified verdict" "$OUT" "lint=justified"
+  check_contains "driven-by ON: finding listed as justified" "$OUT" "finding=driven-by-missing:"
+fi
+
+# ---------------------------------------------------------------------------
+# waiver-boundary — the hold check's run-waiver binding must have ZERO effect
+# here: the waiver applies to the hold check only, never the lint.
+# ---------------------------------------------------------------------------
+if running waiver-boundary; then
+  R=$(new_repo wb)
+  put "$R" .forge/hold-config.yml 'version: 1
+operators: []
+irreversible_paths: []
+deploy_paths: []
+gating_tests: []
+waiver:
+  workflow: waive-hold.yml
+  ref: main'
+  put "$R" "$WF" 'jobs: {}'
+  pr "$R"
+  put "$R" "$WF" 'jobs:
+  gate:
+    steps:
+      - run: exit 0'
+  run_lint "$R" 'main...pr'
+  check "waiver-boundary: hold waiver binding never lifts a lint finding (exit 1)" "$RC" "1"
+  check_contains "waiver-boundary: finding intact" "$OUT" "finding=cannot-fail:$WF"
+fi
+
 # ---------------------------------------------------------------------------
 # docs-only — acceptance 6: a status on every PR
 # ---------------------------------------------------------------------------

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

@@ -25,6 +25,15 @@
 #                   suites)  (+config deploy_paths, gating_tests)
 #   Waiver: any --approvals login ∈ base-side config operators: → waived. Absent
 #   config / empty operators → NO waiver possible (raise-only safe default).
+#   Run-waiver (hold-waiver patch): OPTIONAL base-side `waiver: {workflow, ref}`
+#   binding — when a hold fired and no operator approval waives it, a host-queried
+#   run of that workflow waives iff ALL of: workflow path matches; run ref ==
+#   repo default branch (== configured ref); conclusion == success; display_title
+#   carries the PR head SHA. Output: hold=waived waiver_run=<url>. FAIL-CLOSED on
+#   every leg (unconfigured / gh missing / API unreachable / no match / wrong ref
+#   / config-ref drift / wrong path / non-success / superseded SHA → hold stands);
+#   unconfigured behavior is byte-identical to the pre-waiver check (no gh call).
+#   gh is env-overridable (FORGE_HOLD_GH) — fixtures stub it and stay offline.
 #
 # Builds throwaway git repos in mktemp dirs with NO remote configured anywhere —
 # offline by construction (NFR-032); any network dependency in the script breaks here.
@@ -32,7 +41,7 @@
 # Usage:
 #   ./.forge/checks/tests/forge-hold-check.test.sh              # all cases
 #   ./.forge/checks/tests/forge-hold-check.test.sh pain6        # one tag
-# Filter tags: irreversible structural pain6 waiver self-protect docs-only invocation multi
+# Filter tags: irreversible structural pain6 waiver run-waiver self-protect docs-only invocation multi
 #
 # RED-phase friendly (TDD): a missing/non-executable helper does NOT abort the
 # suite — every selected case FAILS with "(helper missing ...)" as the got-value
@@ -382,6 +391,162 @@ if running multi; then
   check_contains "multi: protected named" "$OUT" "fact=protected:.github/workflows/deploy.yml"
 fi
 
+# ---------------------------------------------------------------------------
+# run-waiver — the Environment-gated waiver run channel: pass-on-match plus a
+# neg-control per fail-closed leg. gh is stubbed offline via FORGE_HOLD_GH.
+# ---------------------------------------------------------------------------
+if running run-waiver; then
+  GH_STUB="$ROOT/gh-stub"
+  cat > "$GH_STUB" <<'STUB'
+#!/bin/sh
+# Offline gh stand-in for the run-waiver channel. Argv shapes the check uses:
+#   gh api repos/{owner}/{repo} --jq .default_branch
+#   gh api "repos/{owner}/{repo}/actions/workflows/<wf>/runs?..." --jq <projection>
+# Driven by env: STUB_DEFAULT_BRANCH (empty/unset => API failure, exit 1),
+# STUB_RUNS_FILE (TSV: conclusion, head_branch, path, html_url, display_title;
+# unset/missing => API failure), STUB_LOG (append argv per call when set).
+[ -n "${STUB_LOG:-}" ] && printf '%s\n' "$*" >> "$STUB_LOG"
+case "${2:-}" in
+  'repos/{owner}/{repo}')
+    [ -n "${STUB_DEFAULT_BRANCH:-}" ] || exit 1
+    printf '%s\n' "$STUB_DEFAULT_BRANCH" ;;
+  'repos/{owner}/{repo}/actions/workflows/'*)
+    [ -n "${STUB_RUNS_FILE:-}" ] && [ -f "$STUB_RUNS_FILE" ] || exit 1
+    cat "$STUB_RUNS_FILE" ;;
+  *) exit 1 ;;
+esac
+STUB
+  chmod +x "$GH_STUB"
+
+  CONFIG_WAIVER='version: 1
+operators: []
+irreversible_paths: []
+deploy_paths: []
+gating_tests: []
+waiver:
+  workflow: waive-hold.yml
+  ref: main'
+
+  WURL='https://host.example/actions/runs/101'
+  WPATH='.github/workflows/waive-hold.yml'
+
+  new_waiver_repo() { # name, config → repo whose pr branch carries a migration (hold fires)
+    nw_d=$(new_repo "$1")
+    put "$nw_d" .forge/hold-config.yml "$2"
+    pr "$nw_d"
+    put "$nw_d" app/migrations/010_waiver.py 'alter table'
+    printf '%s\n' "$nw_d"
+  }
+
+  # pass-on-match: approved success run on the default branch, title carries head SHA
+  R=$(new_waiver_repo rw-pass "$CONFIG_WAIVER")
+  SHA=$(git -C "$R" rev-parse pr)
+  printf 'success\tmain\t%s\t%s\twaive-hold sha=%s\n' "$WPATH" "$WURL" "$SHA" > "$ROOT/runs.pass"
+  export FORGE_HOLD_GH="$GH_STUB" STUB_DEFAULT_BRANCH=main STUB_RUNS_FILE="$ROOT/runs.pass"
+  run_hold "$R" 'main...pr'
+  check "run-waiver: approved matching run waives (exit 0)" "$RC" "0"
+  check_contains "run-waiver: verdict annotates the run URL" "$OUT" "hold=waived waiver_run=$WURL"
+  check_contains "run-waiver: lists what it waived" "$OUT" "fact=irreversible:app/migrations/010_waiver.py waived"
+
+  # neg fail-closed leg: UNCONFIGURED — no waiver block: no gh call, and the
+  # blocked output is byte-identical to a run with no stub env at all.
+  R=$(new_waiver_repo rw-unconf "$CONFIG_OPS")
+  export STUB_LOG="$ROOT/gh.unconf.log"
+  : > "$STUB_LOG"
+  run_hold "$R" 'main...pr'
+  UNCONF_OUT="$OUT"
+  check "run-waiver neg (unconfigured): hold stands (exit 1)" "$RC" "1"
+  check "run-waiver neg (unconfigured): gh never invoked" "$(cat "$STUB_LOG")" ""
+  unset FORGE_HOLD_GH STUB_DEFAULT_BRANCH STUB_RUNS_FILE STUB_LOG
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (unconfigured): output byte-identical to pre-waiver check" "$OUT" "$UNCONF_OUT"
+
+  # neg fail-closed leg: gh MISSING (no host CLI at all)
+  R=$(new_waiver_repo rw-nogh "$CONFIG_WAIVER")
+  export FORGE_HOLD_GH="$ROOT/definitely-no-such-gh"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (gh missing): hold stands (exit 1)" "$RC" "1"
+  check_contains "run-waiver neg (gh missing): blocked verdict" "$OUT" "hold=blocked"
+
+  # neg fail-closed leg: API UNREACHABLE (default-branch query fails)
+  export FORGE_HOLD_GH="$GH_STUB" STUB_DEFAULT_BRANCH="" STUB_RUNS_FILE="$ROOT/runs.pass"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (API unreachable): hold stands (exit 1)" "$RC" "1"
+
+  # neg fail-closed leg: NO MATCHING RUN (API reachable, zero runs)
+  : > "$ROOT/runs.empty"
+  export STUB_DEFAULT_BRANCH=main STUB_RUNS_FILE="$ROOT/runs.empty"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (no matching run): hold stands (exit 1)" "$RC" "1"
+
+  # neg fail-closed leg: WRONG REF — the only success run rode a PR-branch copy
+  # of the workflow (gate strippable), not the default branch.
+  SHA=$(git -C "$R" rev-parse pr)
+  printf 'success\tpr\t%s\t%s\twaive-hold sha=%s\n' "$WPATH" "$WURL" "$SHA" > "$ROOT/runs.wrongref"
+  export STUB_RUNS_FILE="$ROOT/runs.wrongref"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (wrong ref): PR-branch run cannot waive (exit 1)" "$RC" "1"
+
+  # neg fail-closed leg: CONFIG-REF DRIFT — configured ref != repo default branch
+  R=$(new_waiver_repo rw-drift 'version: 1
+operators: []
+irreversible_paths: []
+deploy_paths: []
+gating_tests: []
+waiver:
+  workflow: waive-hold.yml
+  ref: develop')
+  SHA=$(git -C "$R" rev-parse pr)
+  printf 'success\tmain\t%s\t%s\twaive-hold sha=%s\n' "$WPATH" "$WURL" "$SHA" > "$ROOT/runs.drift"
+  export STUB_RUNS_FILE="$ROOT/runs.drift"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (config-ref drift): waiver.ref != default branch (exit 1)" "$RC" "1"
+
+  # neg fail-closed leg: SUPERSEDED SHA — a new push after the approved run;
+  # the run's title carries the OLD head SHA, so it no longer matches.
+  R=$(new_waiver_repo rw-stale "$CONFIG_WAIVER")
+  OLD_SHA=$(git -C "$R" rev-parse pr)
+  printf 'success\tmain\t%s\t%s\twaive-hold sha=%s\n' "$WPATH" "$WURL" "$OLD_SHA" > "$ROOT/runs.stale"
+  put "$R" src/followup.js 'pushed after the waiver run'
+  export STUB_RUNS_FILE="$ROOT/runs.stale"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (superseded SHA): new push invalidates the waiver (exit 1)" "$RC" "1"
+  check_contains "run-waiver neg (superseded SHA): blocked verdict" "$OUT" "hold=blocked"
+
+  # neg fail-closed leg: WRONG WORKFLOW PATH — a same-shaped run of another workflow
+  R=$(new_waiver_repo rw-path "$CONFIG_WAIVER")
+  SHA=$(git -C "$R" rev-parse pr)
+  printf 'success\tmain\t.github/workflows/other.yml\t%s\twaive-hold sha=%s\n' "$WURL" "$SHA" > "$ROOT/runs.path"
+  export STUB_RUNS_FILE="$ROOT/runs.path"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (wrong workflow path): hold stands (exit 1)" "$RC" "1"
+
+  # neg fail-closed leg: NON-SUCCESS CONCLUSION — pending/rejected run never waives
+  printf 'failure\tmain\t%s\t%s\twaive-hold sha=%s\n' "$WPATH" "$WURL" "$SHA" > "$ROOT/runs.fail"
+  export STUB_RUNS_FILE="$ROOT/runs.fail"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (non-success run): hold stands (exit 1)" "$RC" "1"
+
+  # channel precedence: an operator PR approval still waives on its own — the
+  # run-waiver channel is additive, not a replacement.
+  R=$(new_waiver_repo rw-op 'version: 1
+operators:
+  - zayne
+irreversible_paths: []
+deploy_paths: []
+gating_tests: []
+waiver:
+  workflow: waive-hold.yml
+  ref: main')
+  AF=$(approvals rwop zayne)
+  export STUB_DEFAULT_BRANCH="" STUB_RUNS_FILE=""
+  run_hold "$R" 'main...pr' --approvals "$AF"
+  check "run-waiver: operator approval still waives independently (exit 0)" "$RC" "0"
+  check_contains "run-waiver: operator verdict unchanged" "$OUT" "hold=waived waived_by=zayne"
+
+  unset FORGE_HOLD_GH STUB_DEFAULT_BRANCH STUB_RUNS_FILE STUB_LOG
+fi
+
 # ---------------------------------------------------------------------------
 # invocation — exit 2 on bad usage, never a false verdict
 # ---------------------------------------------------------------------------

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

@@ -339,6 +339,70 @@ else
   bad "dry-run rotation" "dry-run had side effects"
 fi
 
+# 22. NEG: --work-dir refused loudly BEFORE the detach (R092) — a forwarded work dir
+#     would split-brain against the pinned notify.log/dispatch.out/rotation paths.
+#     Both arg forms; no slice.yml materialized, nothing dispatched.
+WSLICE="$ROOT/workdir-wt"
+mkdir -p "$WSLICE/.forge/phases/milestone-78/1-bbb"
+printf 'x\n' > "$WSLICE/.forge/phases/milestone-78/1-bbb/plan-01.md"
+err22="$(sh "$DISPATCH" --slice "$WSLICE" --work-dir "$ROOT/elsewhere" 2>&1 >/dev/null)"; rc=$?
+err22b="$(sh "$DISPATCH" --slice "$WSLICE" --work-dir="$ROOT/elsewhere" 2>&1 >/dev/null)"; rc2=$?
+if [ "$rc" = 2 ] && [ "$rc2" = 2 ] && [ ! -f "$WSLICE/slice.yml" ] \
+   && printf '%s' "$err22" | grep -q 'REFUSED' && printf '%s' "$err22b" | grep -q 'REFUSED'; then
+  ok "neg-control: --work-dir refused (both forms), nothing materialized"
+else
+  bad "work-dir refusal" "rc=$rc rc2=$rc2 err=$err22"
+fi
+
+# --- 23-24. STALENESS GUARD (live 2026-07-23: an amended source plan never reached the
+#     materialized work order — plain re-dispatch silently rebuilt the OLD spec). The
+#     materializer fingerprints each bundled plan-NN.md (`# source: ... cksum=N`); a plain
+#     re-dispatch re-checks them and refuses loudly on divergence. Refuse, never auto-rebuild
+#     (the honored-as-is branch serves resume paths whose runner-work must survive).
+
+# 23. NEG: amend a source plan after materialization → plain re-dispatch REFUSES loudly;
+#     slice.yml + runner-work untouched (no rotation — the operator decides)
+ZSLICE="$ROOT/stale-wt"
+mkdir -p "$ZSLICE/.forge/phases/milestone-77/1-aaa"
+printf 'original spec\n' > "$ZSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+sh "$DISPATCH" --slice "$ZSLICE" --materialize-only >/dev/null 2>&1
+mkdir -p "$ZSLICE/.forge/runner-work/pings"                           # seed AFTER — see case 19 note
+touch "$ZSLICE/.forge/runner-work/pings/k-done.marker"
+printf 'AMENDED spec\n' > "$ZSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+before23="$(cat "$ZSLICE/slice.yml")"
+err23="$(sh "$DISPATCH" --slice "$ZSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" != 0 ] && printf '%s' "$err23" | grep -q 'REFUSED' && printf '%s' "$err23" | grep -q 'STALE' \
+   && printf '%s' "$err23" | grep -q '1-aaa/plan-01.md' \
+   && [ "$(cat "$ZSLICE/slice.yml")" = "$before23" ] \
+   && [ -f "$ZSLICE/.forge/runner-work/pings/k-done.marker" ] \
+   && grep -q 'original spec' "$ZSLICE/phases/1-aaa/plan.md" 2>/dev/null; then
+  ok "staleness guard: amended source plan → plain re-dispatch refuses loudly, nothing touched"
+else
+  bad "staleness guard" "rc=$rc err=$err23"
+fi
+
+# 23b. the remedy the refusal names: --plan re-materializes the amended spec (and case 20's
+#      unchanged-source plain re-dispatch already proves the guard stays quiet when fresh)
+err23b="$(sh "$DISPATCH" --slice "$ZSLICE" --materialize-only --plan 1-aaa 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && grep -q 'AMENDED spec' "$ZSLICE/phases/1-aaa/plan.md" 2>/dev/null; then
+  ok "staleness remedy: --plan rebuilds the work order to the amended spec"
+else
+  bad "staleness remedy" "rc=$rc err=$err23b"
+fi
+
+# 24. NEG (lazy migration): a pre-guard materialized slice.yml (helper header, NO
+#     fingerprint lines) is still honored as-is — the guard never bricks an in-flight order
+GSLICE="$ROOT/legacy-wt"
+mkdir -p "$GSLICE/.forge/phases/milestone-77/1-aaa" "$GSLICE/phases/1-aaa"
+printf 'x\n' > "$GSLICE/.forge/phases/milestone-77/1-aaa/plan-01.md"
+printf 'x\n' > "$GSLICE/phases/1-aaa/plan.md"
+printf '# Materialized by forge-jarvis-dispatch from .forge/phases/milestone-77 (delete to re-materialize)\nphases:\n  - 1-aaa\n' > "$GSLICE/slice.yml"
+err24="$(sh "$DISPATCH" --slice "$GSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && printf '%s' "$err24" | grep -q 'using it as-is'; then
+  ok "lazy migration: pre-guard materialized slice.yml (no fingerprints) honored as-is"
+else
+  bad "legacy materialized order" "rc=$rc err=$err24"
+fi
 # --- summary -----------------------------------------------------------------
 printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
 [ "$FAILED" = 0 ]

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

@@ -13,11 +13,17 @@
 #   mode (post-UAT 2026-07-22): jarvis.spawn_permission_mode appends --permission-mode,
 #   env FORGE_JARVIS_SPAWN_PERMISSION_MODE beats config, unset = no flag. Refusals:
 #   jarvis.enabled: false, unknown spawn_permission_mode, or not a git repo →
-#   non-zero exit, NO command on stdout.
+#   non-zero exit, NO command on stdout. Double-start guard (firstmate-review
+#   adoption 2026-07-22): on REAL launch a live `claude remote-control` already
+#   holding the resolved sticky name → refusal naming the live pid; exact --name
+#   token match (a live prefix-sibling never blocks); unreadable ps → warn +
+#   proceed. --dry-run never runs the guard.
 #
-# Builds throwaway git repos in a mktemp dir, offline by construction; only ever
-# invokes --dry-run, so `claude`/`caffeinate` need not exist (dry-run is pure
-# resolution — that determinism is itself part of the contract).
+# Builds throwaway git repos in a mktemp dir, offline by construction; dry-run
+# cases need no `claude`/`caffeinate` (dry-run is pure resolution — that
+# determinism is itself part of the contract), and the real-launch guard cases
+# stub the ps read via FORGE_JARVIS_PS and put a fake `claude` first on PATH so
+# fall-through provably reaches the launch without ever starting a real server.
 #
 # Usage: ./.forge/checks/tests/forge-jarvis.test.sh
 # RED-phase friendly: a missing/non-executable script fails every case, exits non-zero.
@@ -176,6 +182,74 @@ else
   bad "neg-control non-repo" "rc=$rc out=$out"
 fi
 
+# --- double-start guard (real launch; firstmate-review adoption 2026-07-22) ---
+# Reset the fixture to a clean enabled config (sticky base is jarvis-proj again).
+cat > "$REPO/.forge/project.yml" <<'EOF'
+jarvis:
+  enabled: true
+EOF
+# Fake `claude` first on PATH: fall-through cases provably REACH the launch
+# (marker file written) without ever starting a real server. caffeinate, when
+# present, resolves `claude` through the same inherited PATH → still the fake.
+FAKEBIN="$ROOT/fakebin"
+mkdir -p "$FAKEBIN"
+cat > "$FAKEBIN/claude" <<EOF
+#!/bin/sh
+printf '%s\n' "\$*" > "$ROOT/launch.args"
+exit 0
+EOF
+chmod +x "$FAKEBIN/claude"
+
+# 13. a live same-name server → refusal naming the live pid, nothing launched
+STUB_DUP="$ROOT/stub-ps-dup"
+cat > "$STUB_DUP" <<'EOF'
+#!/bin/sh
+printf '  4242 caffeinate -s claude remote-control --name jarvis-proj --spawn worktree --capacity 4\n'
+printf '  4243 claude remote-control --name jarvis-proj --spawn worktree --capacity 4\n'
+EOF
+chmod +x "$STUB_DUP"
+rm -f "$ROOT/launch.args"
+out="$(cd "$REPO" && FORGE_JARVIS_PS="$STUB_DUP" PATH="$FAKEBIN:$PATH" sh "$JARVIS" 2>/dev/null)"; rc=$?
+err="$(cd "$REPO" && FORGE_JARVIS_PS="$STUB_DUP" PATH="$FAKEBIN:$PATH" sh "$JARVIS" 2>&1 >/dev/null)"
+if [ "$rc" != 0 ] && [ -z "$out" ] && [ ! -f "$ROOT/launch.args" ]; then
+  case "$err" in
+    *jarvis-proj*4242*) ok "double-start guard: live same-name server → refusal naming the live pid" ;;
+    *) bad "double-start refusal message" "err=$err" ;;
+  esac
+else
+  bad "double-start guard" "rc=$rc out=$out launched=$([ -f "$ROOT/launch.args" ] && echo yes || echo no)"
+fi
+
+# 14. NEG: prefix near-miss (jarvis-proj-personal live) must NOT trip the guard —
+#     exact --name token match; fall-through provably reaches the launch
+STUB_NEAR="$ROOT/stub-ps-nearmiss"
+cat > "$STUB_NEAR" <<'EOF'
+#!/bin/sh
+printf '  5151 caffeinate -s claude remote-control --name jarvis-proj-personal --spawn worktree --capacity 4\n'
+printf '  5152 vim notes-on-remote-control.md\n'
+EOF
+chmod +x "$STUB_NEAR"
+rm -f "$ROOT/launch.args"
+out="$(cd "$REPO" && FORGE_JARVIS_PS="$STUB_NEAR" PATH="$FAKEBIN:$PATH" sh "$JARVIS" 2>/dev/null)"; rc=$?
+if [ "$rc" = 0 ] && [ -f "$ROOT/launch.args" ] && grep -q -- "--name jarvis-proj --spawn" "$ROOT/launch.args"; then
+  ok "neg-control: live prefix-sibling name does not block — exact token match, launch reached"
+else
+  bad "neg-control prefix near-miss" "rc=$rc launched=$([ -f "$ROOT/launch.args" ] && cat "$ROOT/launch.args" || echo no)"
+fi
+
+# 15. unreadable ps → warn + proceed (advisory hygiene, never a hard fail)
+rm -f "$ROOT/launch.args"
+out="$(cd "$REPO" && FORGE_JARVIS_PS="$ROOT/no-such-stub" PATH="$FAKEBIN:$PATH" sh "$JARVIS" 2>/dev/null)"; rc=$?
+err="$(cd "$REPO" && FORGE_JARVIS_PS="$ROOT/no-such-stub" PATH="$FAKEBIN:$PATH" sh "$JARVIS" 2>&1 >/dev/null)"
+if [ "$rc" = 0 ] && [ -f "$ROOT/launch.args" ]; then
+  case "$err" in
+    *"duplicate-door check unavailable"*) ok "unreadable ps → stated warning + launch proceeds (fail-open, explicit)" ;;
+    *) bad "ps-failure warning wording" "err=$err" ;;
+  esac
+else
+  bad "ps-failure fail-open" "rc=$rc launched=$([ -f "$ROOT/launch.args" ] && echo yes || echo no)"
+fi
+
 # --- summary -----------------------------------------------------------------
 printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
 [ "$FAILED" = 0 ]