forge-orkes 0.62.0 → 0.64.0

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

@@ -0,0 +1,94 @@
+#!/usr/bin/env sh
+# Fixture test for .forge/checks/forge-jarvis-bridge-clean.sh (m-37 B5; FR-206; B1 probe ii).
+#
+# Builds a REAL throwaway repo with two REAL bridge worktrees (one "live", one orphaned), then
+# asserts the orphan is reaped from disk AND git's registry while the live one is untouched — and
+# that --dry-run removes nothing and never flags the live one. Liveness is pinned deterministically
+# via FORGE_JARVIS_BRIDGE_LIVECHECK so the test never depends on wall-clock mtime.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLEAN="$SCRIPT_DIR/../forge-jarvis-bridge-clean.sh"
+[ -f "$CLEAN" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$CLEAN" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0; FAILED=0
+ok()  { PASSED=$((PASSED+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAILED=$((FAILED+1)); printf '  FAIL %s\n     %s\n' "$1" "$2"; }
+
+# --- a real repo with two real bridge worktrees ------------------------------------------------
+REPO="$ROOT/repo"; mkdir -p "$REPO"
+git -C "$REPO" init -q
+git -C "$REPO" config user.email t@t.test
+git -C "$REPO" config user.name  tester
+printf 'seed\n' > "$REPO/f"; git -C "$REPO" add f; git -C "$REPO" commit -qm init
+
+WTR="$REPO/.claude/worktrees"; mkdir -p "$WTR"
+git -C "$REPO" worktree add -q "$WTR/bridge-alive" 2>/dev/null || bad "setup" "could not add bridge-alive worktree"
+git -C "$REPO" worktree add -q "$WTR/bridge-dead"  2>/dev/null || bad "setup" "could not add bridge-dead worktree"
+
+# livecheck stub: ONLY bridge-alive is live.
+LIVE="$ROOT/livecheck.sh"
+printf '#!/usr/bin/env sh\ncase "$1" in *bridge-alive*) exit 0 ;; *) exit 1 ;; esac\n' > "$LIVE"
+chmod +x "$LIVE"
+
+run() { FORGE_JARVIS_BRIDGE_LIVECHECK="$LIVE" sh "$CLEAN" --worktrees-root "$WTR" "$@" 2>/dev/null; }
+
+# 1. dry-run flags the orphan, removes nothing
+out="$(run --dry-run)"
+case "$out" in *bridge-dead*candidate*) ok "dry-run flags bridge-dead as an orphan candidate" ;; *) bad "dry-run candidate" "$out" ;; esac
+[ -d "$WTR/bridge-dead" ] && ok "dry-run removed nothing (bridge-dead still on disk)" || bad "dry-run non-removal" "bridge-dead gone after dry-run"
+
+# 2. dry-run never flags the live one (line-scoped: the bridge-alive line must not say "candidate")
+if printf '%s\n' "$out" | grep 'bridge-alive' | grep -q 'candidate'; then
+  bad "dry-run live safety" "flagged the live worktree: $out"
+else
+  ok "dry-run keeps the live worktree out of candidates"
+fi
+
+# 3. real run reaps the orphan, keeps the live one
+out="$(run)"
+[ ! -d "$WTR/bridge-dead" ] && ok "orphan bridge-dead reaped (removed from disk)" || bad "orphan removal" "bridge-dead still present: $out"
+[ -d "$WTR/bridge-alive" ] && ok "live bridge-alive untouched" || bad "live safety" "live worktree was removed"
+
+# 4. reaped from git's worktree registry too (not just the directory)
+if git -C "$REPO" worktree list --porcelain 2>/dev/null | grep -q 'bridge-dead'; then
+  bad "registry" "bridge-dead still in git worktree list"
+else
+  ok "bridge-dead gone from git's worktree registry too"
+fi
+
+# 5. re-run is a clean no-op (only the live one remains, and it is kept)
+out="$(run)"
+case "$out" in *'0 reaped'*) ok "re-run reaps nothing (idempotent — only the live worktree left)" ;; *) bad "idempotent" "$out" ;; esac
+
+# --- 6+7. LOCK-AWARE liveness — the REAL RC substrate: bridges are git-LOCKED under the server pid.
+# No injected livecheck here, so this exercises default_livecheck's lock-pid path AND unlock-on-reap
+# (the fixtures 1-5 used unlocked worktrees + a stubbed livecheck, which masked both — the gap the
+# FR-207 human-verification walk surfaced against a live RC server).
+REPO2="$ROOT/repo2"; mkdir -p "$REPO2"
+git -C "$REPO2" init -q
+git -C "$REPO2" config user.email t@t.test
+git -C "$REPO2" config user.name  tester
+printf 'seed\n' > "$REPO2/f"; git -C "$REPO2" add f; git -C "$REPO2" commit -qm init
+WTR2="$REPO2/.claude/worktrees"; mkdir -p "$WTR2"
+git -C "$REPO2" worktree add -q "$WTR2/bridge-livepid" 2>/dev/null || bad "setup2" "add bridge-livepid"
+git -C "$REPO2" worktree add -q "$WTR2/bridge-deadpid" 2>/dev/null || bad "setup2" "add bridge-deadpid"
+
+# a definitely-DEAD pid (background a no-op, reap it, reuse its pid); a definitely-LIVE pid (this shell)
+( : ) & DEADPID=$!; wait "$DEADPID" 2>/dev/null
+LIVEPID=$$
+git -C "$REPO2" worktree lock --reason "claude agent bridge-livepid (pid $LIVEPID start now)" "$WTR2/bridge-livepid" 2>/dev/null || bad "setup2" "lock bridge-livepid"
+git -C "$REPO2" worktree lock --reason "claude agent bridge-deadpid (pid $DEADPID start now)" "$WTR2/bridge-deadpid" 2>/dev/null || bad "setup2" "lock bridge-deadpid"
+
+# Both are FRESH (mtime ~now): under the OLD mtime rule both would be "live". The fix classifies by
+# the lock pid, so the dead-pid one must reap (despite fresh mtime) and the live-pid one must stay —
+# AND the reap must succeed against a LOCKED worktree (unlock-before-remove).
+out2="$(sh "$CLEAN" --worktrees-root "$WTR2" 2>/dev/null)"
+[ ! -d "$WTR2/bridge-deadpid" ] && ok "dead-pid lock reaped despite fresh mtime (lock beats mtime; unlock-then-remove worked)" || bad "lock-pid orphan" "bridge-deadpid still present: $out2"
+[ -d "$WTR2/bridge-livepid" ]  && ok "live-pid lock kept (the server still owns it)" || bad "lock-pid live" "live-pid worktree was removed: $out2"
+
+printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
+[ "$FAILED" = 0 ]

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

@@ -0,0 +1,162 @@
+#!/usr/bin/env sh
+# Fixture test suite for .forge/checks/forge-jarvis-dispatch.sh --dry-run (m-37, step 4 B3).
+#
+# Contract under test (handoff-step4-jarvis.md REV2 B3(b)/(c); FR-197/FR-198; acceptance #5):
+#   --dry-run prints the exact `nohup env ... runner ...` command and NEVER dispatches:
+#     - FORGE_SLICE_NOTIFY_LOG lands INSIDE the slice worktree (<slice>/.forge/runner-work/
+#       notify.log), NEVER the invoker's cwd — the clean-main invariant (step 0; acceptance #5).
+#     - FORGE_SLICE_NOTIFY points at the log-only channel (forge-jarvis-notify-logonly.sh) —
+#       the relay is the one delivery path; the default channel's push stays quiet (probe x).
+#     - the runner is dispatched DETACHED (nohup-& — survives Jarvis's death, probe viii).
+#     - every runner arg (incl --config carrying model_by_phase_type) is forwarded VERBATIM;
+#       the helper carries NO model-selection logic (routing is step 5, FR-198).
+#   Refusal: missing --slice → non-zero exit, no command on stdout.
+#
+# Only ever invokes --dry-run (pure resolution — `claude`/the runner need not run); the real
+# runner + channel are resolved relative to the real script dir, so both exist. Slices are
+# throwaway mktemp dirs.
+#
+# Usage: ./.forge/checks/tests/forge-jarvis-dispatch.test.sh
+# RED-phase friendly: a missing/non-executable script fails every case, exits non-zero.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DISPATCH="$SCRIPT_DIR/../forge-jarvis-dispatch.sh"
+
+[ -f "$DISPATCH" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$DISPATCH" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0; FAILED=0
+ok()  { PASSED=$((PASSED+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAILED=$((FAILED+1)); printf '  FAIL %s\n     %s\n' "$1" "$2"; }
+
+# --- fixture slice worktree (just a dir — --dry-run needs [ -d ], not a real git worktree) ---
+SLICE="$ROOT/slice-wt"
+mkdir -p "$SLICE"
+LOGWANT="$SLICE/.forge/runner-work/notify.log"
+CHECKS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"                 # resolve — the dispatch emits a canonical path
+CHANWANT="$CHECKS_DIR/forge-jarvis-notify-logonly.sh"
+
+# 1. notify-log lands INSIDE the slice worktree (not cwd) — the acceptance #5 core
+out="$(cd "$ROOT" && sh "$DISPATCH" --slice "$SLICE" --dry-run 2>/dev/null)"; rc=$?
+case "$out" in
+  *"FORGE_SLICE_NOTIFY_LOG=$LOGWANT "*) ok "notify-log points INTO the slice worktree ($LOGWANT)" ;;
+  *) bad "notify-log placement" "rc=$rc out=$out" ;;
+esac
+
+# 2. FORGE_SLICE_NOTIFY points at the log-only channel
+case "$out" in
+  *"FORGE_SLICE_NOTIFY=$CHANWANT "*) ok "notify channel is the log-only channel (no double-buzz, probe x)" ;;
+  *) bad "log-only channel" "rc=$rc out=$out" ;;
+esac
+
+# 3. dispatched DETACHED — the command begins with nohup (survives Jarvis's death, probe viii)
+case "$out" in
+  "nohup "*) ok "runner dispatched detached (nohup-&)" ;;
+  *) bad "nohup detach" "out=$out" ;;
+esac
+
+# 4. model map passed through untouched — a caller --config reaches the runner verbatim
+out4="$(cd "$ROOT" && sh "$DISPATCH" --slice "$SLICE" --config /tmp/mymap.yml --dry-run 2>/dev/null)"; rc=$?
+case "$out4" in
+  *"--config /tmp/mymap.yml"*) ok "model map: --config forwarded to the runner VERBATIM (FR-198)" ;;
+  *) bad "config passthrough" "rc=$rc out=$out4" ;;
+esac
+
+# 5. --slice forwarded to the runner (the runner needs it too, not just this helper)
+case "$out" in
+  *"--slice $SLICE"*) ok "--slice forwarded to the runner" ;;
+  *) bad "slice forward" "out=$out" ;;
+esac
+
+# 6. NEG-CONTROL (step-0 invariant): run from a DIFFERENT cwd (a stand-in 'main checkout');
+#    the log must STILL be the slice's, never <cwd>/notify.log. Without the override the
+#    runner's default would drop notify.log in cwd — this is why the override exists (#5).
+FAKEMAIN="$ROOT/fake-main-checkout"
+mkdir -p "$FAKEMAIN"
+out6="$(cd "$FAKEMAIN" && sh "$DISPATCH" --slice "$SLICE" --dry-run 2>/dev/null)"; rc=$?
+case "$out6" in
+  *"FORGE_SLICE_NOTIFY_LOG=$FAKEMAIN/notify.log"*)
+    bad "step-0 neg-control" "log leaked into cwd: $out6" ;;
+  *"FORGE_SLICE_NOTIFY_LOG=$LOGWANT "*)
+    ok "step-0 neg-control: dispatched from another cwd, log STILL in the slice (not cwd)" ;;
+  *) bad "step-0 neg-control" "rc=$rc out=$out6" ;;
+esac
+
+# 7. NEG: missing --slice → clean refusal (non-zero, no command emitted)
+out7="$(cd "$ROOT" && sh "$DISPATCH" --dry-run 2>/dev/null)"; rc=$?
+if [ "$rc" != 0 ] && [ -z "$out7" ]; then
+  ok "neg-control: missing --slice → refusal, no command emitted"
+else
+  bad "neg-control missing --slice" "rc=$rc out=$out7"
+fi
+
+# 8. SOURCE AUDIT: the helper carries NO model-selection logic (routing is step 5, FR-198).
+#    Analogue of the launcher's no-token case — grep the script itself, not the output.
+if grep -inE 'choose.*model|select.*model|pick.*model|route.*model|model_by_phase_type[[:space:]]*=' "$DISPATCH" >/dev/null 2>&1; then
+  bad "no routing brain" "model-selection logic found in $DISPATCH"
+else
+  ok "no model-selection logic in the dispatch helper (routing stays step 5)"
+fi
+
+# --- 9-12. WORK-ORDER MATERIALIZATION (FR-197; walk run 4: runner refused 'no slice.yml',
+#     refusal visible only in dispatch.out — phone silent). The helper bridges the Forge plan
+#     layout (.forge/phases/milestone-{id}/{phase}-{name}/plan-NN.md) to the runner contract
+#     (slice.yml + phases/<name>/plan.md), refusing loudly BEFORE the detach when it cannot.
+
+# 9. materialize from milestone plans: ordered slice.yml + concatenated plan.md per phase
+MSLICE="$ROOT/mat-wt"
+mkdir -p "$MSLICE/.forge/phases/milestone-77/71-aaa" "$MSLICE/.forge/phases/milestone-77/72-bbb"
+printf 'plan A part1\n' >  "$MSLICE/.forge/phases/milestone-77/71-aaa/plan-01.md"
+printf 'plan A part2\n' >  "$MSLICE/.forge/phases/milestone-77/71-aaa/plan-02.md"
+printf 'plan B\n'       >  "$MSLICE/.forge/phases/milestone-77/72-bbb/plan-01.md"
+err9="$(sh "$DISPATCH" --slice "$MSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && [ -f "$MSLICE/slice.yml" ] \
+   && grep -q '^  - 71-aaa$' "$MSLICE/slice.yml" && grep -q '^  - 72-bbb$' "$MSLICE/slice.yml" \
+   && grep -q 'plan A part1' "$MSLICE/phases/71-aaa/plan.md" && grep -q 'plan A part2' "$MSLICE/phases/71-aaa/plan.md" \
+   && grep -q 'plan B' "$MSLICE/phases/72-bbb/plan.md"; then
+  ok "materializes slice.yml (ordered) + phases/<name>/plan.md (plan-NN concatenated) from milestone plans"
+else
+  bad "materialize" "rc=$rc err=$err9 slice.yml=$(cat "$MSLICE/slice.yml" 2>/dev/null)"
+fi
+
+# 10. an existing slice.yml is honored untouched (hand-authored work order wins)
+HSLICE="$ROOT/hand-wt"
+mkdir -p "$HSLICE/.forge/phases/milestone-88/1-x"
+printf 'x\n' > "$HSLICE/.forge/phases/milestone-88/1-x/plan-01.md"
+printf 'phases:\n  - hand-rolled\n' > "$HSLICE/slice.yml"
+before="$(cat "$HSLICE/slice.yml")"
+sh "$DISPATCH" --slice "$HSLICE" --materialize-only >/dev/null 2>&1; rc=$?
+after="$(cat "$HSLICE/slice.yml")"
+if [ "$rc" = 0 ] && [ "$before" = "$after" ]; then
+  ok "existing slice.yml honored untouched (hand-authored wins)"
+else
+  bad "hand-authored slice.yml" "rc=$rc before/after differ or refusal"
+fi
+
+# 11. NEG: nothing to dispatch (no slice.yml, no milestone plans) → loud SYNCHRONOUS refusal
+ESLICE="$ROOT/empty-wt"
+mkdir -p "$ESLICE"
+err11="$(sh "$DISPATCH" --slice "$ESLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" != 0 ] && [ ! -f "$ESLICE/slice.yml" ] && printf '%s' "$err11" | grep -q 'REFUSED'; then
+  ok "neg-control: nothing to dispatch → loud refusal BEFORE the detach (no silent phone)"
+else
+  bad "empty refusal" "rc=$rc err=$err11"
+fi
+
+# 12. --dry-run stays side-effect-free (reports, but writes no slice.yml)
+DSLICE="$ROOT/dry-wt"
+mkdir -p "$DSLICE/.forge/phases/milestone-99/1-y"
+printf 'y\n' > "$DSLICE/.forge/phases/milestone-99/1-y/plan-01.md"
+sh "$DISPATCH" --slice "$DSLICE" --dry-run >/dev/null 2>&1
+if [ ! -f "$DSLICE/slice.yml" ] && [ ! -d "$DSLICE/phases" ]; then
+  ok "--dry-run is side-effect-free (no slice.yml/phases written)"
+else
+  bad "dry-run side effects" "dry-run wrote work-order files"
+fi
+
+# --- summary -----------------------------------------------------------------
+printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
+[ "$FAILED" = 0 ]

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env sh
+# Fixture test for .forge/checks/forge-jarvis-instruments.sh (m-37 B5; FR-205).
+#
+# Builds a notify.log + a relay-markers dir BY HAND in the exact TSV formats the runner's
+# notify channel (-notify-logonly.sh) and the relay (-relay.sh) write, then asserts the four
+# week-zero numbers fall out. No real repo/slices/network needed — pure fixtures.
+#
+# Fixture design (4 pings emitted at :00,:01,:02,:03; only 1-3 relayed):
+#   offset 1  ambiguity, relayed +30s   → live
+#   offset 2  done,      relayed +5s    → live, host says unmerged (no discrepancy)
+#   offset 3  halt,      relayed +30min → landed-while-away, DISCREPANCY (payload lied about merge)
+#   offset 4  ambiguity, NOT relayed (no marker) → excluded from every number
+# Expected: 3 relayed total; ambiguity=1/done=1/halt=1; latency max 1800s; discrepancy=1;
+# presence 2/3 live, 1 landed while away.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+INSTR="$SCRIPT_DIR/../forge-jarvis-instruments.sh"
+[ -f "$INSTR" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$INSTR" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0; FAILED=0
+ok()  { PASSED=$((PASSED+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAILED=$((FAILED+1)); printf '  FAIL %s\n     %s\n' "$1" "$2"; }
+TAB="$(printf '\t')"
+
+LOG="$ROOT/notify.log"
+MK="$ROOT/relay-markers"; mkdir -p "$MK"
+
+# notify.log — emit-ts <TAB> type <TAB> payload
+printf '2026-07-21T10:00:00Z%sambiguity%sJWT or sessions?\n'         "$TAB" "$TAB" >> "$LOG"   # 1
+printf '2026-07-21T10:01:00Z%sdone%sPhases complete, PR opened\n'    "$TAB" "$TAB" >> "$LOG"   # 2
+printf '2026-07-21T10:02:00Z%shalt%sAll done and merged to main!\n'  "$TAB" "$TAB" >> "$LOG"   # 3
+printf '2026-07-21T10:03:00Z%sambiguity%sretry or fail?\n'           "$TAB" "$TAB" >> "$LOG"   # 4 (unrelayed)
+
+# relay-markers — relay-ts <TAB> offset=N <TAB> relay-text  (only 1,2,3 relayed)
+printf '2026-07-21T10:00:30Z%soffset=1%s❓ Needs you (ambiguity): JWT or sessions?\n' "$TAB" "$TAB" > "$MK/1.relayed"
+printf '2026-07-21T10:01:05Z%soffset=2%s✅ Slice done — host: release_state=unmerged. PR opened\n' "$TAB" "$TAB" > "$MK/2.relayed"
+printf '2026-07-21T10:32:00Z%soffset=3%s⚠️ DISCREPANCY — payload claims landed/merged, but host shows release_state=unmerged. 🛑 Slice HALTED (host truth wins). Payload said: All done and merged to main!\n' "$TAB" "$TAB" > "$MK/3.relayed"
+
+OUT="$(sh "$INSTR" --log "$LOG" --marker-dir "$MK" --live-window 120 2>/dev/null)"
+
+# 1. by type — only relayed pings; offset 4 (ambiguity, unrelayed) excluded
+printf '%s\n' "$OUT" | grep -qE '3 total'                 && ok "total relayed = 3 (unrelayed offset 4 excluded)"       || bad "total"            "$OUT"
+printf '%s\n' "$OUT" | grep -qE 'ambiguity[[:space:]]+1'  && ok "type: ambiguity=1 (only the relayed one)"             || bad "type ambiguity"   "$OUT"
+printf '%s\n' "$OUT" | grep -qE 'done[[:space:]]+1'       && ok "type: done=1"                                          || bad "type done"        "$OUT"
+printf '%s\n' "$OUT" | grep -qE 'halt[[:space:]]+1'       && ok "type: halt=1"                                          || bad "type halt"        "$OUT"
+
+# 2. latency — max is the +30min catch-up ping
+printf '%s\n' "$OUT" | grep -qE 'max 1800s'               && ok "latency max = 1800s (the catch-up ping)"              || bad "latency max"      "$OUT"
+
+# 3. discrepancy — the lying halt
+printf '%s\n' "$OUT" | grep -qE 'Discrepancies caught.*: 1' && ok "discrepancy count = 1 (payload claimed a merge the host denied)" || bad "discrepancy" "$OUT"
+
+# 4. presence proxy — 1 & 2 within window, 3 landed while away
+printf '%s\n' "$OUT" | grep -qE '2/3 relayed live'        && ok "presence proxy: 2/3 live, 1 landed while away"        || bad "presence proxy"   "$OUT"
+
+# 5. the presence line labels itself a proxy (never a measured SLA)
+printf '%s\n' "$OUT" | grep -qiE 'proxy'                  && ok "presence figure is labelled a proxy, not an SLA"      || bad "proxy label"      "$OUT"
+
+printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
+[ "$FAILED" = 0 ]

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env sh
+# Fixture test suite for .forge/checks/forge-jarvis-promote.sh (m-37, step 4 B6; plan 70-01).
+#
+# Contract under test (handoff-step4-jarvis.md REV2 B6; FR-208; NFR-038; operator ruling 3
+# "trigger-not-approve"; acceptance #7 is the manual human gate, not here):
+#   - SHOWS host state (the board projection) BEFORE triggering — reuses the B4/B5 host-truth
+#     env contract (FORGE_JARVIS_BOARD), degrades cleanly when the board is unavailable.
+#   - TRIGGERS the step-2 seam via `gh workflow run promote.yml -f sha=<full-sha>` and nothing
+#     else — a real (non-dry-run) run actually invokes gh (proven with a recording stub).
+#   - NEG-CONTROL: the helper contains NO Environment-approval path (no --approve, no
+#     `gh api ... environments ... approve`, no approve-a-deployment call). Triggering != approving.
+#   - refuses a non-full sha (Jarvis never invents/truncates a sha).
+#
+# The board + gh are stubbed via env so no real repo/main/gh state is needed. Each assertion
+# prints WHY. RED-friendly: a missing/broken script fails every case and exits non-zero.
+#
+# Usage: ./.forge/checks/tests/forge-jarvis-promote.test.sh
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROMOTE="$SCRIPT_DIR/../forge-jarvis-promote.sh"
+[ -f "$PROMOTE" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$PROMOTE" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0; FAILED=0
+ok()  { PASSED=$((PASSED+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAILED=$((FAILED+1)); printf '  FAIL %s\n     %s\n' "$1" "$2"; }
+
+SHA="0123456789abcdef0123456789abcdef01234567"   # a well-formed full 40-hex sha
+
+# --- stub board: emit line-oriented JSON with one merged + one complete unit ------------------
+BOARD_OK="$ROOT/board-ok.sh"
+cat > "$BOARD_OK" <<'EOF'
+#!/usr/bin/env sh
+# emulate forge-board-render.sh --emit: one line per unit
+printf '{"forge_id":"m-30","status":"complete","release_state":"merged"}\n'
+printf '{"forge_id":"m-99","status":"complete","release_state":"complete"}\n'
+EOF
+chmod +x "$BOARD_OK"
+
+# --- recording gh stub: append its args so we can prove the trigger actually fired ------------
+GH_REC="$ROOT/gh-rec.sh"
+GH_LOG="$ROOT/gh-args.log"
+cat > "$GH_REC" <<EOF
+#!/usr/bin/env sh
+printf '%s\n' "\$*" >> "$GH_LOG"
+exit 0
+EOF
+chmod +x "$GH_REC"
+
+# 1. dry-run SHOWS the board state BEFORE the trigger line (show-then-trigger ordering)
+out="$(FORGE_JARVIS_BOARD="$BOARD_OK" FORGE_JARVIS_GH=gh sh "$PROMOTE" "$SHA" --dry-run 2>/dev/null)"
+show_ln="$(printf '%s\n' "$out" | grep -n 'm-30' | head -1 | cut -d: -f1)"
+trig_ln="$(printf '%s\n' "$out" | grep -n 'would run' | head -1 | cut -d: -f1)"
+if [ -n "$show_ln" ] && [ -n "$trig_ln" ] && [ "$show_ln" -lt "$trig_ln" ]; then
+  ok "shows host state (merged unit m-30) BEFORE the trigger command"
+else
+  bad "show-then-trigger" "show line=$show_ln trigger line=$trig_ln; out: $out"
+fi
+
+# 2. dry-run prints the step-2 seam command: gh workflow run promote.yml -f sha=<sha>
+case "$out" in
+  *"gh workflow run promote.yml -f sha=$SHA"*) ok "dry-run prints 'gh workflow run promote.yml -f sha=<sha>' (the step-2 seam)" ;;
+  *) bad "trigger command" "no 'gh workflow run promote.yml -f sha=$SHA' in: $out" ;;
+esac
+
+# 3. a real (non-dry-run) run ACTUALLY invokes gh with the workflow trigger (recording stub)
+: > "$GH_LOG"
+FORGE_JARVIS_BOARD="$BOARD_OK" FORGE_JARVIS_GH="$GH_REC" sh "$PROMOTE" "$SHA" >/dev/null 2>&1
+if grep -qF "workflow run promote.yml -f sha=$SHA" "$GH_LOG"; then
+  ok "real run invokes gh: 'workflow run promote.yml -f sha=<sha>' recorded"
+else
+  bad "real trigger" "gh stub not called with the trigger args; log: $(cat "$GH_LOG" 2>/dev/null)"
+fi
+
+# 4. NEG-CONTROL — the helper has NO Environment-approval path anywhere in the file
+if grep -qiE 'gh api.*environments.*approve|approve.*deployment|--approve' "$PROMOTE"; then
+  bad "no-approval neg-control" "an approval path exists in $PROMOTE (triggering must never approve)"
+else
+  ok "neg-control: no approval API path in the helper (triggers, never approves)"
+fi
+
+# 5. refuses a non-full sha (never invents/truncates one)
+if FORGE_JARVIS_BOARD="$BOARD_OK" sh "$PROMOTE" "abc123" --dry-run >/dev/null 2>&1; then
+  bad "short-sha refusal" "a short sha was accepted; promotion needs the full 40-hex sha"
+else
+  ok "refuses a non-full (short) sha — containment needs the full deploy sha"
+fi
+
+# 6. board unavailable degrades: dry-run still renders + still prints the trigger (exit 0)
+out="$(FORGE_JARVIS_BOARD="$ROOT/does-not-exist.sh" FORGE_JARVIS_GH=gh sh "$PROMOTE" "$SHA" --dry-run 2>/dev/null)"
+rc=$?
+case "$out" in
+  *"projection unavailable"*"would run: gh workflow run promote.yml"*) [ "$rc" -eq 0 ] && ok "board-down degrades: show still renders and the trigger still prints (exit 0)" || bad "degrade exit" "rc=$rc" ;;
+  *) bad "board-down degrade" "expected a degraded projection note + the trigger; got: $out" ;;
+esac
+
+# --- summary -----------------------------------------------------------------
+printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
+[ "$FAILED" = 0 ]

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env sh
+# Fixture test suite for .forge/checks/forge-jarvis-prwatch.sh (m-37, step 4 B4(c); plan 68-02).
+#
+# Contract under test (handoff-step4-jarvis.md REV2 B4(c); NFR-036/Fork 3; acceptance #1/#6):
+#   - merged + staging-deploy success → the come-try text fires ONCE (at-most-once marker).
+#   - bound reached (PR stays OPEN) → clean exit, NO fire (never a standing daemon).
+#   - PR closed without a live deploy → self-terminate, no fire.
+#   - host truth only: merge + deploy come from gh (stubbed here via FORGE_JARVIS_GH).
+#
+# All runs use --interval 0 + a tiny --max-iterations so nothing sleeps or hangs. Each assertion
+# prints WHY. RED-friendly: a missing script fails every case and exits non-zero.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PRWATCH="$SCRIPT_DIR/../forge-jarvis-prwatch.sh"
+[ -f "$PRWATCH" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$PRWATCH" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+PASSED=0; FAILED=0
+ok()  { PASSED=$((PASSED+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAILED=$((FAILED+1)); printf '  FAIL %s\n     %s\n' "$1" "$2"; }
+
+# stub gh: `pr view` → $STUB_STATE ; `api .../deployments` → statuses_url / state per $STUB_DEPLOY
+STUB="$ROOT/gh-stub.sh"
+cat > "$STUB" <<'EOF'
+#!/usr/bin/env sh
+case "$1" in
+  pr)  printf '%s\n' "${STUB_STATE:-OPEN}" ;;
+  api) case "$2" in
+         *deployments\?environment*) [ "${STUB_DEPLOY:-no}" = yes ] && printf 'https://x/statuses\n' || printf '\n' ;;
+         *statuses*)                 [ "${STUB_DEPLOY:-no}" = yes ] && printf 'success\n' || printf 'pending\n' ;;
+       esac ;;
+esac
+EOF
+chmod +x "$STUB"
+MK="$ROOT/markers"
+
+run() { FORGE_JARVIS_GH="$STUB" sh "$PRWATCH" --max-iterations 3 --interval 0 --marker-dir "$MK" "$@" 2>/dev/null; }
+
+# 1. merged + deployed → come-try fires
+out="$(STUB_STATE=MERGED STUB_DEPLOY=yes run --pr 42)"
+case "$out" in *"come try"*"#42"*) ok "merged + staging deploy → come-try tap fires, names the PR" ;; *) bad "come-try fire" "$out" ;; esac
+
+# 2. at-most-once: a second run does NOT fire again (marker suppresses)
+out="$(STUB_STATE=MERGED STUB_DEPLOY=yes run --pr 42)"
+[ -z "$out" ] && ok "come-try is at-most-once (marker suppresses the re-fire)" || bad "double come-try" "$out"
+
+# 3. OPEN forever → bound reached, clean exit (rc 0), NO fire (not a daemon)
+out="$(STUB_STATE=OPEN run --pr 99)"; rc=$?
+if [ "$rc" = 0 ] && [ -z "$out" ]; then ok "OPEN → hard bound reached, clean exit, no fire (self-terminating)"; else bad "bound self-terminate" "rc=$rc out=$out"; fi
+
+# 4. merged but NOT deployed → within the bound it does not fire (waits for the deploy, then stops)
+out="$(STUB_STATE=MERGED STUB_DEPLOY=no run --pr 55)"; rc=$?
+if [ "$rc" = 0 ] && [ -z "$out" ]; then ok "merged w/o deploy → no premature come-try; bound stops it cleanly"; else bad "merged-no-deploy" "rc=$rc out=$out"; fi
+
+# 5. CLOSED → self-terminate immediately, no fire
+out="$(STUB_STATE=CLOSED run --pr 77)"; rc=$?
+if [ "$rc" = 0 ] && [ -z "$out" ]; then ok "closed PR → self-terminate, no fire"; else bad "closed terminate" "rc=$rc out=$out"; fi
+
+# 6. --dry-run prints the resolved plan and never polls
+out="$(sh "$PRWATCH" --pr 7 --staging-env prod --dry-run 2>/dev/null)"
+case "$out" in *"pr=7"*"env=prod"*) ok "--dry-run prints the resolved plan (pr, env, bound), no polling" ;; *) bad "dry-run plan" "$out" ;; esac
+
+printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
+[ "$FAILED" = 0 ]

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

@@ -0,0 +1,135 @@
+#!/usr/bin/env sh
+# Fixture test suite for .forge/checks/forge-jarvis-relay.sh (m-37, step 4 B4; plan 68-01).
+#
+# Contract under test (handoff-step4-jarvis.md REV2 B4(a/b/e); FR-200..202; NFR-036/040;
+# acceptance #2/#3/#4):
+#   - each §8 type + halt → correct TYPED text; ambiguity relays the question VERBATIM.
+#   - HOST-TRUTH recompute wins: a payload claiming a merge the fold DENIES relays a loud
+#     DISCREPANCY (the standing lesson) — the state claim is never sourced from the payload.
+#   - markers are at-most-once (a re-scan of unchanged log re-buzzes NOTHING; a new line still
+#     relays — no double-buzz, no silent loss), keyed by log-line offset.
+#   - --mode catchup surfaces pending pings as ONE "while you were away" line, then marks them.
+#   - --audit-sources passes (no state claim sourced from the payload).
+#
+# The fold is stubbed via FORGE_JARVIS_FOLD so no real repo/main state is needed. Each assertion
+# prints WHY. RED-friendly: a missing/broken script fails every case and exits non-zero.
+#
+# Usage: ./.forge/checks/tests/forge-jarvis-relay.test.sh   [--markers]   (both run by default)
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RELAY="$SCRIPT_DIR/../forge-jarvis-relay.sh"
+[ -f "$RELAY" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$RELAY" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0; FAILED=0
+ok()  { PASSED=$((PASSED+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAILED=$((FAILED+1)); printf '  FAIL %s\n     %s\n' "$1" "$2"; }
+
+# --- stub folds: echo a fixed release_state so the relay recomputes against a KNOWN host truth --
+FOLD_UNMERGED="$ROOT/fold-unmerged.sh"
+printf '#!/usr/bin/env sh\necho "release_state=unmerged reason=not-on-main"\n' > "$FOLD_UNMERGED"
+FOLD_VALIDATED="$ROOT/fold-validated.sh"
+printf '#!/usr/bin/env sh\necho "release_state=validated reason=signed-off"\n' > "$FOLD_VALIDATED"
+chmod +x "$FOLD_UNMERGED" "$FOLD_VALIDATED"
+
+# one(): run --one with a given TSV line + stub fold; echo the relay text
+one() {  # one <fold> <tsv-line>
+  FORGE_JARVIS_FOLD="$1" sh "$RELAY" --one "$2" --milestone m-37 2>/dev/null
+}
+TAB="$(printf '\t')"
+
+# 1. ambiguity → the QUESTION verbatim, no host state leaked in
+out="$(one "$FOLD_UNMERGED" "2026-07-21T10:00:00Z${TAB}ambiguity${TAB}JWT or sessions?")"
+case "$out" in
+  *"JWT or sessions?"*) case "$out" in *release_state*) bad "ambiguity verbatim" "leaked host state: $out" ;; *) ok "ambiguity relays the question verbatim (not a state claim)" ;; esac ;;
+  *) bad "ambiguity verbatim" "question missing: $out" ;;
+esac
+
+# 2. fork → names the sketch path
+out="$(one "$FOLD_UNMERGED" "2026-07-21T10:00:00Z${TAB}fork${TAB}/tmp/sketch-a.png")"
+case "$out" in *"/tmp/sketch-a.png"*) ok "fork names the sketch path to look at" ;; *) bad "fork path" "$out" ;; esac
+
+# 3. irreversible → verbatim, named
+out="$(one "$FOLD_UNMERGED" "2026-07-21T10:00:00Z${TAB}irreversible${TAB}force-push to main?")"
+case "$out" in *"force-push to main?"*) ok "irreversible relays the action, named" ;; *) bad "irreversible" "$out" ;; esac
+
+# 4. budget → verbatim, named (runner's own tally — no host source)
+out="$(one "$FOLD_UNMERGED" "2026-07-21T10:00:00Z${TAB}budget${TAB}cap \$25 reached")"
+case "$out" in *"cap \$25 reached"*) ok "budget relays the runner's tally, named" ;; *) bad "budget" "$out" ;; esac
+
+# 5. honest done (payload makes NO merge claim), fold=unmerged → host truth, NO discrepancy
+out="$(one "$FOLD_UNMERGED" "2026-07-21T10:00:00Z${TAB}done${TAB}Phases complete, PR opened")"
+case "$out" in
+  *DISCREPANCY*) bad "honest done" "false discrepancy on an honest ping: $out" ;;
+  *"release_state=unmerged"*) ok "honest done phrased from host release_state (no false discrepancy)" ;;
+  *) bad "honest done" "no host state in text: $out" ;;
+esac
+
+# 6. LYING halt: payload claims merged, fold says unmerged → LOUD discrepancy, host wins
+out="$(one "$FOLD_UNMERGED" "2026-07-21T10:00:00Z${TAB}halt${TAB}All done and merged to main!")"
+case "$out" in
+  *DISCREPANCY*"release_state=unmerged"*) ok "lying halt → discrepancy; host truth (unmerged) wins over the payload's merge claim" ;;
+  *) bad "lying halt discrepancy" "expected DISCREPANCY + release_state=unmerged, got: $out" ;;
+esac
+
+# 7. done claims merged AND fold=validated → host CONFIRMS, no discrepancy
+out="$(one "$FOLD_VALIDATED" "2026-07-21T10:00:00Z${TAB}done${TAB}merged and validated")"
+case "$out" in
+  *DISCREPANCY*) bad "confirmed merge" "false discrepancy when host agrees: $out" ;;
+  *"release_state=validated"*) ok "merge claim + host agrees (validated) → confirmed, no discrepancy" ;;
+  *) bad "confirmed merge" "$out" ;;
+esac
+
+# 8. --audit-sources passes (no state claim sourced from the payload)
+if FORGE_JARVIS_FOLD="$FOLD_UNMERGED" sh "$RELAY" --audit-sources >/dev/null 2>&1; then
+  ok "--audit-sources: relay speaks host truth only"
+else
+  bad "--audit-sources" "static source audit failed"
+fi
+
+# --- markers: at-most-once, no double-buzz, no silent loss ------------------------------------
+WT="$ROOT/slice-wt"; mkdir -p "$WT/.forge/runner-work"
+LOG="$WT/.forge/runner-work/notify.log"; MK="$WT/.forge/runner-work/relay-markers"
+printf '2026-07-21T10:00:00Z\tambiguity\tfirst?\n'  >> "$LOG"
+printf '2026-07-21T10:01:00Z\tdone\tPR opened\n'    >> "$LOG"
+
+scan() { FORGE_JARVIS_FOLD="$FOLD_UNMERGED" sh "$RELAY" --scan "$LOG" --marker-dir "$MK" --milestone m-37 2>/dev/null; }
+
+# 9. first scan relays BOTH lines
+out="$(scan)"; n="$(printf '%s\n' "$out" | grep -c .)"
+[ "$n" -eq 2 ] && ok "first --scan relays all unmarked lines ($n)" || bad "first scan count" "expected 2 got $n: $out"
+
+# 10. re-scan of UNCHANGED log relays NOTHING (at-most-once — no double-buzz)
+out="$(scan)"; n="$(printf '%s\n' "$out" | grep -c .)"
+[ "$n" -eq 0 ] && ok "re-scan of unchanged log re-buzzes nothing (at-most-once markers)" || bad "double-buzz" "expected 0 got $n: $out"
+
+# 11. a NEW line still relays (no silent loss of a genuinely-new ping)
+printf '2026-07-21T10:02:00Z\thalt\tstuck\n' >> "$LOG"
+out="$(scan)"; n="$(printf '%s\n' "$out" | grep -c .)"
+[ "$n" -eq 1 ] && ok "a new line still relays after prior lines were marked (no silent loss)" || bad "new-line relay" "expected 1 got $n: $out"
+
+# 12. markers exist keyed by offset (line number)
+if [ -f "$MK/1.relayed" ] && [ -f "$MK/2.relayed" ] && [ -f "$MK/3.relayed" ]; then
+  ok "markers written keyed by log-line offset (1,2,3)"
+else
+  bad "offset markers" "missing marker(s): $(ls "$MK" 2>/dev/null | tr '\n' ' ')"
+fi
+
+# 13. --mode catchup surfaces pending pings as ONE while-you-were-away line
+WT2="$ROOT/slice-wt2"; mkdir -p "$WT2/.forge/runner-work"
+LOG2="$WT2/.forge/runner-work/notify.log"
+printf '2026-07-21T09:00:00Z\tbudget\tcap hit\n'          >> "$LOG2"
+printf '2026-07-21T09:05:00Z\tirreversible\tdrop table?\n' >> "$LOG2"
+out="$(FORGE_JARVIS_FOLD="$FOLD_UNMERGED" sh "$RELAY" --scan "$LOG2" --milestone m-37 --mode catchup 2>/dev/null)"
+lines="$(printf '%s\n' "$out" | grep -c .)"
+case "$out" in
+  *"While you were away"*) [ "$lines" -eq 1 ] && ok "catchup surfaces pending pings as ONE while-you-were-away line" || bad "catchup one-line" "got $lines lines: $out" ;;
+  *) bad "catchup summary" "no while-you-were-away line: $out" ;;
+esac
+
+# --- summary -----------------------------------------------------------------
+printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
+[ "$FAILED" = 0 ]