forge-orkes 0.63.0 → 0.64.2

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 ]

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env sh
+# Fixture-repo test suite for .forge/checks/forge-jarvis.sh --dry-run (m-37, Brief-R2 step 4 B2).
+#
+# Contract under test (handoff-step4-jarvis.md REV2 B2 + operator ruling 6 +
+# runbook-B1-live-test-recon.md "After B1" bake-ins):
+#   --dry-run prints the fully resolved launch command and NEVER executes:
+#     caffeinate -s claude remote-control --name <sticky> --spawn worktree --capacity <N>
+#   Name: jarvis-<repo-basename> (from the git COMMON dir — stable across worktrees),
+#   + optional suffix from jarvis.name_suffix, overridden per machine by
+#   FORGE_JARVIS_NAME_SUFFIX (probe ii: the sticky name is the only discoverability
+#   anchor). Capacity: --capacity flag > jarvis.capacity > 4. NO token export ever
+#   (probe iv — asserted here as an env-name absence in the output). Refusals:
+#   jarvis.enabled: false, or not a git repo → non-zero exit, NO command on stdout.
+#
+# 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).
+#
+# Usage: ./.forge/checks/tests/forge-jarvis.test.sh
+# RED-phase friendly: a missing/non-executable script fails every case, exits non-zero.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+JARVIS="$SCRIPT_DIR/../forge-jarvis.sh"
+
+[ -f "$JARVIS" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$JARVIS" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null
+export GIT_CONFIG_GLOBAL GIT_CONFIG_SYSTEM
+unset FORGE_JARVIS_NAME_SUFFIX 2>/dev/null || true
+
+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 repo (basename "proj" → expected sticky base jarvis-proj) -------
+REPO="$ROOT/proj"
+mkdir -p "$REPO/.forge"
+git -C "$ROOT" init -q -b main "$REPO"
+
+# 1. default derivation — no jarvis: block → full default command
+out="$(cd "$REPO" && sh "$JARVIS" --dry-run 2>/dev/null)"; rc=$?
+want="caffeinate -s claude remote-control --name jarvis-proj --spawn worktree --capacity 4"
+if [ "$rc" = 0 ] && [ "$out" = "$want" ]; then
+  ok "default derivation: no config → jarvis-proj, capacity 4"
+else
+  bad "default derivation" "rc=$rc out=$out"
+fi
+
+# 2. caffeinate -s present (operator ruling 6 — asserted on its own so a future
+#    edit dropping the wrap fails a NAMED case, not just the exact-match above)
+case "$out" in
+  "caffeinate -s "*) ok "caffeinate -s wraps the resolved command (ruling 6 / probe iii)" ;;
+  *) bad "caffeinate -s wrap" "out=$out" ;;
+esac
+
+# 3. config override — jarvis: block with name_suffix + capacity
+cat > "$REPO/.forge/project.yml" <<'EOF'
+project:
+  name: "proj"
+jarvis:
+  enabled: true
+  name_suffix: "alpha"
+  capacity: 2
+EOF
+out="$(cd "$REPO" && sh "$JARVIS" --dry-run 2>/dev/null)"; rc=$?
+want="caffeinate -s claude remote-control --name jarvis-proj-alpha --spawn worktree --capacity 2"
+if [ "$rc" = 0 ] && [ "$out" = "$want" ]; then
+  ok "config override: name_suffix + capacity from jarvis: block"
+else
+  bad "config override" "rc=$rc out=$out"
+fi
+
+# 4. per-machine env seam — FORGE_JARVIS_NAME_SUFFIX beats jarvis.name_suffix
+out="$(cd "$REPO" && FORGE_JARVIS_NAME_SUFFIX=work sh "$JARVIS" --dry-run 2>/dev/null)"; rc=$?
+case "$out" in
+  *"--name jarvis-proj-work "*) ok "env FORGE_JARVIS_NAME_SUFFIX overrides config suffix (per-machine seam)" ;;
+  *) bad "env suffix override" "rc=$rc out=$out" ;;
+esac
+
+# 5. capacity flag override — --capacity beats jarvis.capacity
+out="$(cd "$REPO" && sh "$JARVIS" --dry-run --capacity 7 2>/dev/null)"; rc=$?
+case "$out" in
+  *"--capacity 7") ok "--capacity flag overrides config capacity" ;;
+  *) bad "capacity flag override" "rc=$rc out=$out" ;;
+esac
+
+# 6. no token export — the resolved command never carries an auth env assignment
+#    (probe iv: keychain authenticates; a token in the launch line would be the
+#    exact regression the B1 bake-in forbids)
+case "$out" in
+  *CLAUDE_CODE_OAUTH_TOKEN*|*ANTHROPIC_API_KEY*) bad "no token in resolved command" "out=$out" ;;
+  *) ok "no token export in the resolved command (probe iv)" ;;
+esac
+
+# 7. NEG: enabled: false → clean refusal (non-zero, no command on stdout)
+cat > "$REPO/.forge/project.yml" <<'EOF'
+jarvis:
+  enabled: false
+EOF
+out="$(cd "$REPO" && sh "$JARVIS" --dry-run 2>/dev/null)"; rc=$?
+if [ "$rc" != 0 ] && [ -z "$out" ]; then
+  ok "neg-control: jarvis.enabled false → refusal, no command emitted"
+else
+  bad "neg-control enabled:false" "rc=$rc out=$out"
+fi
+
+# 8. NEG: not a git repo → clean refusal (RC --spawn worktree needs one)
+NOREPO="$ROOT/norepo"
+mkdir -p "$NOREPO"
+out="$(cd "$NOREPO" && sh "$JARVIS" --dry-run 2>/dev/null)"; rc=$?
+if [ "$rc" != 0 ] && [ -z "$out" ]; then
+  ok "neg-control: outside a git repo → refusal, no command emitted"
+else
+  bad "neg-control non-repo" "rc=$rc out=$out"
+fi
+
+# --- summary -----------------------------------------------------------------
+printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
+[ "$FAILED" = 0 ]

package/template/.forge/templates/project.yml

@@ -138,6 +138,17 @@ models:
 #     backlog: true                  #   lane is PROJECT-LOCAL config composing these; the framework carries none.
 #     deferred: true                 #   status / backlog (explicit-intake, M21) / deferred view.
 
+# jarvis:                            # OPTIONAL front door (Brief-R2 step 4) — the repo's standing presence: a
+#                                    # named `claude remote-control` server whose pre-created session is Jarvis,
+#                                    # started by the operator via .forge/checks/forge-jarvis.sh. Unlike board:,
+#                                    # absence does NOT mean inert — the launcher is operator-invoked, never
+#                                    # ambient, and works with no block (defaults below). See docs/jarvis.md.
+#   enabled: true                    # explicit false = the launcher refuses (the door is switched off)
+#   name_suffix: ""                  # appended to the sticky name jarvis-<repo-basename>; on multi-machine
+#                                    #   repos each machine overrides via env FORGE_JARVIS_NAME_SUFFIX so two
+#                                    #   live presences never share one name
+#   capacity: 4                      # RC server session capacity (--capacity), default 4
+
 risks:                              # What could go wrong?
   - risk: ""
     mitigation: ""