forge-orkes 0.62.0 → 0.64.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/migrations/0.63.0-origin-first-upgrading.md

@@ -0,0 +1,49 @@
+# Migration Guide: Origin-First Upgrading (Forge 0.63.0)
+
+Applies to projects whose installed `upgrading` skill predates 0.63.0. The default `/upgrading` path changed from "sync from a local Forge clone at `.forge/dev-source`" to "wrap the npm registry bin": `/upgrading` now runs `npx forge-orkes@latest upgrade --yes --json` as the one sync engine and layers the agent-only steps (migration prompts, experimental re-sync, Codex offer, worktree propagation) on the bin's JSON report. Local-clone sync survives only as explicit **Dev Mode** (`/upgrading dev`) — presence of `.forge/dev-source` never selects it (ADR-026).
+
+## Prerequisites
+
+1. Network access to the npm registry (the new default path runs `npx forge-orkes`).
+2. Nothing else — the migration IS the upgrade run; no files need hand-editing.
+
+## Detection
+
+Prints `MIGRATE` when the installed upgrading skill is old-shape (it lacks the registry engine invocation the 0.63.0 skill always carries); silent + exit 0 otherwise.
+
+```bash
+# Old-shape upgrading skill: exists but lacks the registry engine invocation.
+S=.claude/skills/upgrading/SKILL.md
+[ -f "$S" ] || exit 0                        # skill not installed → nothing to do
+if ! grep -q 'forge-orkes@latest upgrade --yes --json' "$S" 2>/dev/null; then
+  echo "MIGRATE — installed upgrading skill predates the origin-first default (registry engine); re-running the upgrade replaces it"
+fi
+```
+
+## Migration steps
+
+### 1. Re-run the upgrade
+
+The sync itself replaces the skill — that is the whole migration. Either route works:
+
+- `npx forge-orkes@latest upgrade` (any machine, no clone needed), or
+- `/upgrading` in a Claude Code session **on 0.63.0+ framework files** (the run that installs this guide already synced the new skill; this Detection then stops firing).
+
+### 2. Understand what changed in daily use
+
+- **`/upgrading`** now upgrades from the npm registry. If `.forge/dev-source` exists you will see exactly one notice line — *"dev mode available — `/upgrading dev`"* — and the registry upgrade proceeds anyway.
+- **`/upgrading X.Y.Z`** pins the engine to that release (`npx forge-orkes@X.Y.Z upgrade --yes --json`).
+- **`/upgrading dev`** is the only way to sync from a local clone (framework development). Its flow — source resolution, downgrade guard, upstream desire-path harvest — is unchanged, just explicit.
+- Experimental skills now re-sync from the release tarball itself (`experimental/` ships in the package since 0.63.0), so registry-only machines get staleness detection + consent-gated re-sync too (closes issue #5).
+
+### 3. Optional: drop `.forge/dev-source` on non-dev machines
+
+On machines that never develop Forge itself, the file now only produces the notice line. Removing it is safe and silences the notice. Keep it on your framework-dev machine(s) for `/upgrading dev`.
+
+## Validation
+
+```bash
+grep -q 'forge-orkes@latest upgrade --yes --json' .claude/skills/upgrading/SKILL.md \
+  && echo "upgrading skill is origin-first (0.63.0+)" \
+  || echo "still old-shape — re-run the upgrade"
+```

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: ""