forge-orkes 0.63.0 → 0.64.0

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

@@ -0,0 +1,176 @@
+#!/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)
+#
+# 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
+# environment — the runner loop is UNTOUCHED (the "no runner changes" boundary; the runner's
+# swappable seams are used exactly as designed).
+#
+# WHAT IT SETS (and nothing else):
+#   FORGE_SLICE_NOTIFY_LOG  → INTO the slice worktree (<worktree>/.forge/runner-work/notify.log),
+#                             never the invoker's cwd. The default would land the log in the
+#                             MAIN checkout (one shared file, invisible to the worktree glob,
+#                             dirtying step 0's clean-main invariant). This is the path the B4
+#                             relay derives per slice from its worktree glob. (acceptance #5)
+#   FORGE_SLICE_NOTIFY      → the LOG-ONLY channel (forge-jarvis-notify-logonly.sh), so the
+#                             default channel's per-ping headless `claude -p` push stays quiet
+#                             — under a live relay, delivery is the relay's job; a live default
+#                             channel would risk a double-buzz (B1 probe x). Explicit + portable
+#                             (FR-197): true regardless of the ambient auth shape.
+#
+# MODEL MAP — PASSED THROUGH UNTOUCHED (FR-198, boundary "No routing"): the runner reads
+# config.model_by_phase_type from its CONFIG (the step-5 seam — read, not routed). This helper
+# forwards every runner arg (incl. --config) VERBATIM and carries NO model-selection logic. If
+# 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.
+#
+#   --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.
+#
+# 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
+# .forge/phases/milestone-{id}/{phase}-{name}/plan-NN.md, and nothing bridged the two: the
+# observed failure was a clean dispatch whose runner refused instantly ('no slice.yml'), the
+# refusal visible only in dispatch.out — the operator's phone stayed silent. So before the
+# detach this helper MATERIALIZES the work order from the milestone's locked plans (slice.yml
+# in phase order + phases/<name>/plan.md concatenated from that phase's plan-NN.md files), and
+# REFUSES LOUDLY AND SYNCHRONOUSLY when it cannot — the failure surface is this exit code, not
+# a silent phone. An existing slice.yml is honored untouched (a hand-authored work order wins).
+#   --materialize-only   materialize (or refuse) and exit — no dispatch. Test hook + operator tool.
+set -u
+
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"                     # .forge/checks → repo root
+RUNNER="$REPO_ROOT/.claude/hooks/forge-slice-runner.sh"       # the slice runner (consumed, never edited)
+CHANNEL="$SELF_DIR/forge-jarvis-notify-logonly.sh"            # the log-only channel (sibling)
+
+# --- parse args: consume --dry-run; extract --slice; forward everything else verbatim -------
+# POSIX count-guard idiom: shift originals off the front, re-append forwarded args to the back;
+# when the original count hits 0, "$@" holds exactly the forwarded runner args (spaces safe).
+DRY_RUN=0
+MAT_ONLY=0
+WORKTREE=""
+argc=$#
+while [ "$argc" -gt 0 ]; do
+  arg="$1"; shift; argc=$((argc - 1))
+  case "$arg" in
+    --dry-run)
+      DRY_RUN=1 ;;                                   # ours — not forwarded
+    --materialize-only)
+      MAT_ONLY=1 ;;                                  # ours — not forwarded
+    --slice)
+      WORKTREE="${1:-}"; shift; argc=$((argc - 1))
+      set -- "$@" --slice "$WORKTREE" ;;             # forward it too (runner needs it)
+    *)
+      set -- "$@" "$arg" ;;                          # forward verbatim
+  esac
+done
+
+[ -n "$WORKTREE" ] || { printf 'forge-jarvis-dispatch: --slice <worktree> is required\n' >&2; exit 2; }
+[ -d "$WORKTREE" ] || { printf 'forge-jarvis-dispatch: slice worktree not found: %s\n' "$WORKTREE" >&2; exit 2; }
+WORKTREE="$(cd "$WORKTREE" && pwd)"                  # absolutize — the log path must be stable
+
+[ -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; }
+
+# --- 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.
+materialize_work_order() {
+  if [ -f "$WORKTREE/slice.yml" ]; then
+    printf 'forge-jarvis-dispatch: slice.yml present — using it as-is\n' >&2
+    return 0
+  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
+  # assumption. The Worktree Convention names the branch forge/{anchor} with anchor =
+  # {milestone-id}[-{session}]; derive the id and pick that milestone's dir.
+  _mdir=""
+  _branch="$(git -C "$WORKTREE" branch --show-current 2>/dev/null)"
+  case "$_branch" in
+    forge/m-*)
+      _anchor="${_branch#forge/m-}"                                   # 40 | 40-a1b2c3d4 | R61-002
+      [ -d "$WORKTREE/.forge/phases/milestone-$_anchor" ] && _mdir="$WORKTREE/.forge/phases/milestone-$_anchor"
+      if [ -z "$_mdir" ]; then
+        _short="${_anchor%-*}"                                        # strip one trailing -token (session suffix)
+        [ "$_short" != "$_anchor" ] && [ -d "$WORKTREE/.forge/phases/milestone-$_short" ] && _mdir="$WORKTREE/.forge/phases/milestone-$_short"
+      fi ;;
+  esac
+  # Fallback (non-git fixture dirs / unconventional branches): a SINGLE milestone dir is
+  # unambiguous; several without a branch-derived pick is a refusal, never a guess.
+  if [ -z "$_mdir" ]; then
+    _mdirs=0
+    for _d in "$WORKTREE"/.forge/phases/milestone-*; do
+      [ -d "$_d" ] || continue
+      _mdirs=$((_mdirs + 1)); _mdir="$_d"
+    done
+    if [ "$_mdirs" -eq 0 ]; then
+      printf 'forge-jarvis-dispatch: REFUSED — no slice.yml and no .forge/phases/milestone-*/ plans in %s; nothing to dispatch. Plan the slice first. RELAY this refusal to the operator.\n' "$WORKTREE" >&2
+      return 2
+    fi
+    if [ "$_mdirs" -gt 1 ]; then
+      printf 'forge-jarvis-dispatch: REFUSED — %s milestone plan dirs in %s and no forge/m-* branch to pick by; ambiguous work order. Write slice.yml explicitly. RELAY this refusal to the operator.\n' "$_mdirs" "$WORKTREE" >&2
+      return 2
+    fi
+  fi
+  _tmp="$WORKTREE/slice.yml.tmp"
+  printf '# Materialized by forge-jarvis-dispatch from %s (delete to re-materialize)\nphases:\n' "${_mdir#"$WORKTREE"/}" > "$_tmp"
+  _count=0
+  for _p in $(ls "$_mdir" 2>/dev/null | sort -n); do
+    [ -d "$_mdir/$_p" ] || continue
+    _plans="$(ls "$_mdir/$_p"/plan-*.md 2>/dev/null | sort)"
+    [ -n "$_plans" ] || continue
+    mkdir -p "$WORKTREE/phases/$_p"
+    # shellcheck disable=SC2086
+    cat $_plans > "$WORKTREE/phases/$_p/plan.md"
+    printf '  - %s\n' "$_p" >> "$_tmp"
+    _count=$((_count + 1))
+  done
+  if [ "$_count" -eq 0 ]; then
+    rm -f "$_tmp"
+    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
+  mv "$_tmp" "$WORKTREE/slice.yml"
+  printf 'forge-jarvis-dispatch: materialized slice.yml (%s phase(s)) from %s\n' "$_count" "${_mdir#"$WORKTREE"/}" >&2
+  return 0
+}
+
+# --- caller-side env (the two seams; nothing else) ------------------------------------------
+LOG="$WORKTREE/.forge/runner-work/notify.log"        # INTO the slice worktree (B4 derives this)
+
+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
+    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
+  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"
+  for a in "$@"; do printf ' %s' "$a"; done
+  printf ' >%s 2>&1 &\n' "$WORKTREE/.forge/runner-work/dispatch.out"
+  exit 0
+fi
+
+if [ "$MAT_ONLY" = "1" ]; then
+  materialize_work_order; exit $?
+fi
+
+materialize_work_order || exit 2
+
+# --- dispatch DETACHED (nohup-& — survives Jarvis's death, B1 probe viii) --------------------
+mkdir -p "$WORKTREE/.forge/runner-work" 2>/dev/null || true
+printf 'forge-jarvis-dispatch: dispatching runner for %s (detached)\n' "$WORKTREE" >&2
+nohup env FORGE_SLICE_NOTIFY_LOG="$LOG" FORGE_SLICE_NOTIFY="$CHANNEL" \
+  "$RUNNER" "$@" >"$WORKTREE/.forge/runner-work/dispatch.out" 2>&1 &
+
+printf 'forge-jarvis-dispatch: dispatched (pid %s); notify log → %s\n' "$!" "$LOG" >&2
+exit 0

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env sh
+# forge-jarvis-instruments.sh — the week's DIRECTION-TEST numbers, derived from what B4 already
+# wrote: the notify logs + relay markers. NO new store (m-37 B5 instruments; FR-205; NFR-036).
+#
+# Risk 1 (contract): did the front door REDUCE operator touches, or just RELOCATE them? These four
+# numbers are how we would tell, measured from existing artifacts ONLY (no instrumentation added):
+#   1. PINGS RELAYED BY TYPE  — how many buzzes, of what kind (ambiguity / fork / irreversible /
+#                               budget / done / halt). Only RELAYED pings count (a marker exists).
+#   2. RELAY LATENCY          — log-line emit-time → marker relay-time, per ping (mean + max secs).
+#   3. DISCREPANCY COUNT      — how often B4(c) host-verification caught a payload's state claim
+#                               disagreeing with the host (the standing lesson, counted).
+#   4. PRESENCE PROXY         — pings relayed LIVE vs pings that landed while the relay was down
+#                               (relayed late, on catch-up). Uptime here is a PROXY derived from
+#                               relay latency, NOT an uptime store: a ping whose relay lagged past
+#                               --live-window seconds is counted "landed while away". Labelled a
+#                               proxy in the output so it is never read as a measured SLA.
+#
+# SOURCES (read-only): each slice's <worktree>/.forge/runner-work/notify.log (TSV
+# emit-ts<TAB>type<TAB>payload) and its sibling relay-markers/<offset>.relayed
+# (relay-ts<TAB>offset=N<TAB>relay-text). A marker's offset (line number) joins it to its log line.
+# Nothing is written; the numbers are a pure function of the existing markers + logs.
+#
+#   forge-jarvis-instruments.sh [--log <notify.log> ...] [--marker-dir <dir>] \
+#                               [--live-window <sec>] [--since <ISO-Z>] [--worktree-root <dir>] [--dry-run]
+#     (no --log)     disk-glob live slice worktrees (git worktree list, forge/m-*) for their logs.
+#     --marker-dir   override the marker dir (default: sibling relay-markers/ of each log).
+#     --live-window  seconds under which a relay counts LIVE (default 120).
+#     --since        only count pings emitted at/after this ISO-Z timestamp (default: all).
+#     --worktree-root  glob this dir for slice worktrees instead of `git worktree list` (tests).
+#     --dry-run      print the resolved logs/markers and exit (plumbing check).
+# Portable date (BSD then GNU) so latency math works on macOS and Linux.
+set -u
+
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"
+
+LOGS=""
+MARKER_DIR_OVERRIDE=""
+LIVE_WINDOW=120
+SINCE=""
+WT_ROOT=""
+DRY_RUN=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --log)           LOGS="${LOGS}${LOGS:+
+}${2:-}"; shift 2 ;;
+    --marker-dir)    MARKER_DIR_OVERRIDE="${2:-}"; shift 2 ;;
+    --live-window)   LIVE_WINDOW="${2:-120}"; shift 2 ;;
+    --since)         SINCE="${2:-}"; shift 2 ;;
+    --worktree-root) WT_ROOT="${2:-}"; shift 2 ;;
+    --dry-run)       DRY_RUN=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+# ISO-8601 Z → epoch seconds; empty on failure (GNU `date -d` then BSD `date -j -f`).
+to_epoch() {  # to_epoch <iso-z>
+  _t="${1:-}"; [ -n "$_t" ] || return 1
+  date -u -d "$_t" +%s 2>/dev/null || date -u -j -f '%Y-%m-%dT%H:%M:%SZ' "$_t" +%s 2>/dev/null
+}
+
+# ── resolve the log set: explicit --log wins; else disk-glob live slice worktrees ────────────────
+if [ -z "$LOGS" ]; then
+  if [ -n "$WT_ROOT" ]; then
+    for _wt in "$WT_ROOT"/*/; do
+      [ -d "$_wt" ] || continue
+      _l="${_wt}.forge/runner-work/notify.log"
+      [ -f "$_l" ] && LOGS="${LOGS}${LOGS:+
+}$_l"
+    done
+  else
+    _globbed="$(git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | awk '
+      /^worktree / { p = $2 }
+      /^branch /   { if ($2 ~ /refs\/heads\/forge\/m-/) print p "/.forge/runner-work/notify.log" }')"
+    for _l in $_globbed; do
+      [ -f "$_l" ] && LOGS="${LOGS}${LOGS:+
+}$_l"
+    done
+  fi
+fi
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  printf 'forge-jarvis-instruments (--dry-run): resolved logs:\n'
+  if [ -n "$LOGS" ]; then printf '%s\n' "$LOGS" | sed 's/^/   /'; else printf '   (none)\n'; fi
+  exit 0
+fi
+
+# ── build one record per RELAYED ping: type, latency_sec, live(1/0), discrepancy(1/0) ────────────
+TMP="$(mktemp)"; trap 'rm -f "$TMP"' EXIT INT TERM
+_since_epoch=""; [ -n "$SINCE" ] && _since_epoch="$(to_epoch "$SINCE")"
+
+printf '%s\n' "$LOGS" | while IFS= read -r LOG; do
+  [ -n "$LOG" ] && [ -f "$LOG" ] || continue
+  MK="$MARKER_DIR_OVERRIDE"; [ -n "$MK" ] || MK="$(dirname "$LOG")/relay-markers"
+  _n=0
+  while IFS= read -r _line || [ -n "$_line" ]; do
+    _n=$((_n + 1))
+    _emit="$(printf '%s' "$_line" | cut -f1)"
+    _type="$(printf '%s' "$_line" | cut -f2)"
+    if [ -n "$_since_epoch" ]; then
+      _e="$(to_epoch "$_emit")"
+      { [ -n "$_e" ] && [ "$_e" -lt "$_since_epoch" ]; } && continue
+    fi
+    _marker="$MK/$_n.relayed"
+    [ -f "$_marker" ] || continue                      # only RELAYED pings carry instruments data
+    _relayts="$(cut -f1 "$_marker" 2>/dev/null)"
+    _text="$(cut -f3- "$_marker" 2>/dev/null)"
+    _ee="$(to_epoch "$_emit")"; _re="$(to_epoch "$_relayts")"
+    if [ -n "$_ee" ] && [ -n "$_re" ]; then _lat=$((_re - _ee)); else _lat=-1; fi
+    if [ "$_lat" -ge 0 ] && [ "$_lat" -le "$LIVE_WINDOW" ]; then _live=1; else _live=0; fi
+    case "$_text" in
+      *DISCREPANCY*|*"could NOT be verified"*) _disc=1 ;;
+      *) _disc=0 ;;
+    esac
+    printf '%s\t%s\t%s\t%s\n' "$_type" "$_lat" "$_live" "$_disc" >> "$TMP"
+  done < "$LOG"
+done
+
+# ── emit the four numbers ────────────────────────────────────────────────────────────────────────
+_total="$(wc -l < "$TMP" 2>/dev/null | tr -d ' ')"; [ -n "$_total" ] || _total=0
+
+printf '── Jarvis week-zero instruments  (from relay markers + notify logs) ──\n\n'
+
+printf '1. Pings relayed by type (%s total):\n' "$_total"
+if [ "$_total" -gt 0 ]; then
+  cut -f1 "$TMP" | sort | uniq -c | while read -r _c _t; do
+    printf '     %-14s %s\n' "$_t" "$_c"
+  done
+else
+  printf '     (no relayed pings in range)\n'
+fi
+
+awk -F'\t' -v total="$_total" -v win="$LIVE_WINDOW" '
+  { if ($2 + 0 >= 0) { s += $2; n++; if ($2 + 0 > mx) mx = $2 }
+    live += $3; disc += $4 }
+  END {
+    mean = (n > 0) ? s / n : 0
+    printf "2. Relay latency: mean %.1fs, max %ds (over %d timed ping(s); live window %ds)\n", mean, mx + 0, n + 0, win + 0
+    printf "3. Discrepancies caught (host-verification): %d\n", disc + 0
+    away = total - live
+    up = (total > 0) ? (live * 100.0 / total) : 0
+    printf "4. Presence proxy: %d/%d relayed live (%.0f%%); %d landed while away", live + 0, total + 0, up, away + 0
+    printf "  (proxy — derived from relay latency, not an uptime store)\n"
+  }' "$TMP"
+
+exit 0

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env sh
+# forge-jarvis-notify-logonly.sh <type> <payload> — a LOG-ONLY notify channel for
+# Jarvis-dispatched slices (m-37, Brief-R2 step 4 B3; contract handoff-step4-jarvis.md REV2).
+#
+# The default runner channel (.claude/hooks/forge-slice-notify.sh) does TWO things per
+# ping: (1) append it to the durable log, and (2) a best-effort headless `claude -p`
+# PushNotification micro-call. Under a live Jarvis relay (B4), delivery to the phone is the
+# RELAY's job — the Monitor `tail -F` on this log IS the delivery path. Running the default
+# channel's own push in parallel risks a double-buzz (B1 probe x). So a Jarvis dispatch
+# points FORGE_SLICE_NOTIFY at THIS channel, which does step (1) ONLY.
+#
+# Why an EXPLICIT channel and not just "the keychain box has no exported token so the
+# default is already quiet": that quiet is ambient (it depends on CLAUDE_CODE_OAUTH_TOKEN /
+# ANTHROPIC_API_KEY being unset). On a box where a token IS exported, the default WOULD
+# push and double-buzz. Pointing at this channel makes log-only EXPLICIT and PORTABLE
+# (FR-197) — the relay is the one delivery path regardless of the ambient auth shape.
+#
+# This is the runner's swappable channel seam used exactly as designed: the runner is
+# UNTOUCHED; the caller (forge-jarvis-dispatch.sh) owns the env. The log FORMAT is identical
+# to the default channel (same tab-separated timestamp/type/payload) so the log is uniform
+# whichever channel wrote a line — the relay parses one format.
+#
+# BEST-EFFORT by contract (same as the default channel): exit 0 even if the log write
+# fails — the runner treats a non-zero exit as a best-effort miss, never a slice failure.
+#
+# type/payload: the runner calls `$FORGE_SLICE_NOTIFY <type> <payload>`; the type is one of
+# the §8 surface (ambiguity | irreversible | fork | budget | done) plus `halt`.
+set -u
+
+TYPE="${1:-note}"
+PAYLOAD="${2:-}"
+
+# Durable local record — the ONLY thing this channel does. Default location travels with
+# the slice (FORGE_SLICE_WORK_DIR), but a Jarvis dispatch always sets FORGE_SLICE_NOTIFY_LOG
+# explicitly INTO the slice worktree.
+LOG="${FORGE_SLICE_NOTIFY_LOG:-${FORGE_SLICE_WORK_DIR:-.}/notify.log}"
+mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
+printf '%s\t%s\t%s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo now)" "$TYPE" "$PAYLOAD" >> "$LOG" 2>/dev/null || true
+
+exit 0

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

@@ -0,0 +1,103 @@
+#!/usr/bin/env sh
+# forge-jarvis-promote.sh — the promotion VOICE (m-37, Brief-R2 step 4 B6; contract
+# handoff-step4-jarvis.md REV2; FR-208; NFR-038; operator ruling 3 "trigger-not-approve").
+#
+# The operator says "promote <sha>". Jarvis does exactly two things, in order:
+#   1. SHOW what that SHA carries — recomputed from HOST truth (the board projection + the
+#      fold), never a session's word. The merged-but-not-yet-validated units are the ones a
+#      promotion covers, by CONTAINMENT: a unit becomes validated when its landed SHA is an
+#      ancestor of the signed promotion tag's commit (ADR-024) — verified offline, host-side.
+#   2. TRIGGER the step-2 seam:  gh workflow run promote.yml -f sha=<full-sha>
+#
+# That is ALL it does. It NEVER approves, waives, or lowers anything: the flow STOPS at
+# GitHub's Environment gates (both taps: deploy + mint) until the operator presses there.
+# Triggering is not approving — the approval is not Jarvis's to give (operator ruling 3).
+# There is deliberately NO Environment-approval call anywhere in this file; the neg-control in
+# the test suite greps this file to prove it (an approval path would fail the acceptance test).
+#
+#   forge-jarvis-promote.sh <full-sha> [--dry-run]
+#     <full-sha>   the full 40-hex deploy SHA. The promotion tag is promotion/<full-sha>
+#                  (FROZEN with the operator); a short sha is refused — containment needs the
+#                  full one, and Jarvis never invents or truncates a sha.
+#     --dry-run    SHOW host state, then PRINT the trigger command without running it.
+#
+# HOST-TRUTH commands (env-overridable so tests inject stubs and degradation is explicit):
+#   FORGE_JARVIS_BOARD  default .forge/checks/forge-board-render.sh   (the rollup projection)
+#   FORGE_JARVIS_FOLD   default .claude/hooks/forge-release-fold.sh   (per-unit release_state)
+#   FORGE_JARVIS_GH     default `gh`                                   (the trigger — never an approval)
+# BEST-EFFORT: a missing board/fold degrades to a stated '(unavailable)' — the show still
+# renders; a missing gh in a real (non-dry-run) trigger is a clear error, never a silent success.
+set -u
+
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"                 # .forge/checks → repo root
+BOARD="${FORGE_JARVIS_BOARD:-$REPO_ROOT/.forge/checks/forge-board-render.sh}"
+FOLD="${FORGE_JARVIS_FOLD:-$REPO_ROOT/.claude/hooks/forge-release-fold.sh}"
+GH="${FORGE_JARVIS_GH:-gh}"
+WORKFLOW="promote.yml"
+
+SHA=""
+DRY_RUN=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    --*)       shift ;;                          # tolerate/ignore unknown flags
+    *)         [ -z "$SHA" ] && SHA="$1"; shift ;;
+  esac
+done
+
+# ── refuse a missing or non-full sha (Jarvis never invents/truncates a sha) ─────────────────────
+case "$SHA" in
+  "") printf 'forge-jarvis-promote: need a full deploy SHA — usage: forge-jarvis-promote.sh <full-sha> [--dry-run]\n' >&2; exit 2 ;;
+esac
+if ! printf '%s' "$SHA" | grep -qE '^[0-9a-f]{40}$'; then
+  printf 'forge-jarvis-promote: %s is not a full 40-hex SHA. Promotion validates by containment against promotion/<full-sha> — pass the full deploy SHA, not a short one.\n' "$SHA" >&2
+  exit 2
+fi
+
+# ── 1. SHOW what this SHA carries — host truth, recomputed now (never a session's claim) ─────────
+printf '── Promote %s ────────────────────────────────────\n' "$SHA"
+printf '\n> What this promotion covers  (board projection — merged units validate by containment):\n'
+if [ -f "$BOARD" ]; then
+  _emit="$(sh "$BOARD" --emit 2>/dev/null)"
+  if [ -n "$_emit" ]; then
+    # release-relevant units: merged (candidate -> validated) + validated (already covered).
+    # line-oriented JSON -> grep/sed, no jq (Article X native-first) — same parse as awareness.
+    _rel="$(printf '%s\n' "$_emit" | grep '"forge_id"' | grep -E '"release_state":[[:space:]]*"(merged|validated)"')"
+    if [ -n "$_rel" ]; then
+      printf '%s\n' "$_rel" \
+        | sed -E 's/.*"forge_id":[[:space:]]*"([^"]+)".*"release_state":[[:space:]]*"([^"]+)".*/   \1  release_state=\2/' \
+        | head -60
+    else
+      printf '   (no merged units in the board projection — nothing waiting on a promotion)\n'
+    fi
+  else
+    printf '   (board projection unavailable — degraded, not fatal)\n'
+  fi
+else
+  printf '   (forge-board-render.sh not found — projection unavailable)\n'
+fi
+printf '\n  Validation is by CONTAINMENT: each merged unit becomes validated when its landed SHA is an\n'
+printf '  ancestor of the signed promotion/%s tag commit (ADR-024) — host-verified offline, not a claim.\n' "$SHA"
+
+# ── 2. TRIGGER the step-2 seam — and STOP. Jarvis triggers; the operator presses the gates. ──────
+CMD="$GH workflow run $WORKFLOW -f sha=$SHA"
+printf '\n> Trigger (step-2 seam — Jarvis triggers; the operator presses GitHub Environment gates):\n'
+if [ "$DRY_RUN" -eq 1 ]; then
+  printf '   [--dry-run] would run: %s\n' "$CMD"
+  exit 0
+fi
+if ! command -v "$GH" >/dev/null 2>&1; then
+  printf '   gh not found — cannot trigger the promotion. Run it from a host that has gh: %s\n' "$CMD" >&2
+  exit 3
+fi
+printf '   %s\n' "$CMD"
+# gh workflow run promote.yml -f sha=<full-sha> — the trigger, never an approval call.
+"$GH" workflow run "$WORKFLOW" -f sha="$SHA"
+_rc=$?
+if [ "$_rc" -eq 0 ]; then
+  printf '\n[ok] Triggered promote.yml for %s. It now STOPS at GitHub Environment gates — press them there; Jarvis does not.\n' "$SHA"
+else
+  printf '\n[!] gh workflow run exited %s — the promotion was NOT triggered. Check the workflow name / host auth.\n' "$_rc" >&2
+fi
+exit "$_rc"

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

@@ -0,0 +1,92 @@
+#!/usr/bin/env sh
+# forge-jarvis-prwatch.sh — the bounded "merged, on staging — come try" watch
+# (m-37, Brief-R2 step 4 B4(c); contract handoff-step4-jarvis.md REV2).
+#
+# The runner's `done` ping fires at PR-open; step-2 auto-merge + the staging deploy land minutes
+# LATER, so that flagship "come try it" moment never appears in the notify log. This watch is the
+# SECOND bounded source for it: on a `done`, poll `gh` for the PR's merge + staging-deploy state
+# with a HARD bound and, on merge+deploy, emit the come-try text once.
+#
+# STRICTLY BOUNDED + self-terminating (NFR-036 / Fork 3): it stops on merge+deploy, on a closed
+# PR, or when the iteration/wall bound is hit — it NEVER becomes a standing daemon and owns no
+# durable state beyond the at-most-once come-try marker (keyed by PR number).
+#
+# HOST TRUTH ONLY: merge + deploy state come from `gh`, never from a build session's words
+# (operator ruling 5). The gh binary is env-overridable (FORGE_JARVIS_GH) so fixtures drive tests.
+#
+#   --pr <num>             the PR to watch (required)
+#   --repo <owner/repo>    default: the current repo (gh resolves it)
+#   --staging-env <name>   deployment environment that means "on staging" (default: staging)
+#   --max-iterations <N>   hard poll bound (default 30)
+#   --interval <seconds>   sleep between polls (default 20; 0 = no sleep, for fixtures)
+#   --marker-dir <dir>     where the at-most-once come-try marker lives (default: cwd/.relay-markers)
+#   --dry-run              print the resolved plan (pr, repo, env, bound) and exit; no polling
+set -u
+
+PR=""; REPO=""; ENV_STAGING="staging"; MAX_ITER=30; INTERVAL=20; MARKER_DIR=""
+GH="${FORGE_JARVIS_GH:-gh}"
+DRY=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --pr)            PR="${2:-}"; shift 2 ;;
+    --repo)          REPO="${2:-}"; shift 2 ;;
+    --staging-env)   ENV_STAGING="${2:-staging}"; shift 2 ;;
+    --max-iterations) MAX_ITER="${2:-30}"; shift 2 ;;
+    --interval)      INTERVAL="${2:-20}"; shift 2 ;;
+    --marker-dir)    MARKER_DIR="${2:-}"; shift 2 ;;
+    --dry-run)       DRY=1; shift ;;
+    *) shift ;;
+  esac
+done
+[ -n "$PR" ] || { printf 'forge-jarvis-prwatch: --pr <num> is required\n' >&2; exit 2; }
+[ -n "$MARKER_DIR" ] || MARKER_DIR="./.relay-markers"
+REPO_ARG=""; [ -n "$REPO" ] && REPO_ARG="--repo $REPO"
+
+if [ "$DRY" = 1 ]; then
+  printf 'prwatch plan: pr=%s repo=%s env=%s bound=%s×%ss marker-dir=%s\n' \
+    "$PR" "${REPO:-<current>}" "$ENV_STAGING" "$MAX_ITER" "$INTERVAL" "$MARKER_DIR"
+  exit 0
+fi
+
+# --- host-truth probes (gh only) -------------------------------------------------------------
+# The two probes are literal gh queries (env-overridable via $GH for fixtures):
+#   merge state   → `gh pr view <num> --json state --jq .state`
+#   staging deploy → `gh api repos/{owner}/{repo}/deployments?environment=<env>` + its statuses
+# Both read host truth; neither consults anything a build session emitted.
+pr_merge_state() {   # → MERGED | CLOSED | OPEN (empty on gh error → treated as OPEN, keep polling)
+  # shellcheck disable=SC2086
+  "$GH" pr view "$PR" $REPO_ARG --json state --jq '.state' 2>/dev/null
+}
+deploy_succeeded() { # → exit 0 iff the latest staging deployment is in a success state
+  # shellcheck disable=SC2086
+  _st="$("$GH" api "repos/{owner}/{repo}/deployments?environment=$ENV_STAGING&per_page=1" \
+           --jq '.[0].statuses_url' 2>/dev/null)"
+  [ -n "$_st" ] || return 1
+  _s="$("$GH" api "$_st?per_page=1" --jq '.[0].state' 2>/dev/null)"
+  [ "$_s" = success ]
+}
+
+fire_come_try() {    # at-most-once, keyed by PR (the ONE owned state class)
+  mkdir -p "$MARKER_DIR" 2>/dev/null || true
+  _mk="$MARKER_DIR/pr-$PR-cometry.relayed"
+  [ -f "$_mk" ] && return 0                       # already fired — never re-buzz
+  _text="🚀 Merged, on staging — come try: PR #$PR is live on $ENV_STAGING."
+  printf '%s\toffset=pr-%s\t%s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo now)" "$PR" "$_text" > "$_mk" 2>/dev/null || true
+  printf '%s\n' "$_text"                           # the skill fires PushNotification with this
+}
+
+# --- the bounded poll loop -------------------------------------------------------------------
+i=0
+while [ "$i" -lt "$MAX_ITER" ]; do
+  case "$(pr_merge_state)" in
+    MERGED)
+      if deploy_succeeded; then fire_come_try; exit 0; fi ;;   # the come-try moment — fire + stop
+    CLOSED)
+      exit 0 ;;                                                # closed without a live deploy — stop, no fire
+    *) : ;;                                                    # OPEN (or gh hiccup) — keep polling
+  esac
+  i=$((i + 1))
+  [ "$i" -lt "$MAX_ITER" ] && [ "$INTERVAL" -gt 0 ] && sleep "$INTERVAL"
+done
+# bound reached without a merge+deploy — self-terminate cleanly, no fire (never a daemon).
+exit 0