forge-orkes 0.73.1 → 0.75.0

package/experimental/m10/source/skills/orchestrating/SKILL.md

@@ -80,16 +80,45 @@ mkdir -p "$wt_root"
 git worktree prune
 git worktree add -b forge/${anchor} --lock --reason "forge session m-${milestone_id}" "$wt_root/${anchor}" main
 wt="$wt_root/${anchor}"
-# Submodules don't auto-populate in a new worktree — init them if present. Reuses the
+
+# --- Hydrate the worktree ---
+# A git worktree is a clean checkout of *tracked* files only. Everything required but
+# untracked — submodule working trees, gitignored config/secrets — is absent until we
+# put it there. Hydration is that ordered step; submodule init is one instance of it.
+
+# (1) Submodules don't auto-populate in a new worktree — init them if present. Reuses the
 # superproject's shared .git/modules object store (no re-clone, just a working-tree
 # checkout); ccache absorbs the subsequent rebuild cost across worktrees.
 if [ -n "$(git -C "$wt" submodule status 2>/dev/null)" ]; then
   ( cd "$wt" && git submodule update --init --recursive )
 fi
+
+# (2) Required-but-gitignored artifacts (e.g. .mcp.json — MCP config, often secret-bearing;
+# .env.local; experimental hook configs) named in orchestration.worktree_hydrate. A clean
+# checkout lacks them, and the failure is SILENT: MCP servers that never appear, an env-
+# dependent command that misbehaves. Copy each from the superproject, guarded source-exists
+# && dest-absent → never overwrites, and we NEVER `git add` a hydrated path: it stays
+# gitignored/untracked in both trees, so a secret like .mcp.json never enters git history.
+sed -n '/^orchestration:/,/^[^[:space:]#]/p' "$repo_root/.forge/project.yml" 2>/dev/null \
+  | sed -n '/^[[:space:]]*worktree_hydrate:/,/^[[:space:]]*[a-z_]*:/p' \
+  | sed -n 's/^[[:space:]]*-[[:space:]]*//p' | tr -d "\"'" \
+  | while IFS= read -r rel; do                   # line-based: a path may contain spaces; robust across sh/bash/zsh
+      [ -n "$rel" ] || continue
+      [ -e "$repo_root/$rel" ] || continue        # source-exists guard (no-op when nothing applies)
+      [ -e "$wt/$rel" ] && continue               # dest-absent guard (idempotent — never clobbers)
+      mkdir -p "$(dirname "$wt/$rel")"
+      cp -p "$repo_root/$rel" "$wt/$rel"
+    done
+
+# (3) Dependency install (node_modules etc.) is DEFERRED to the executing/verifying preflight
+# on purpose — Forge core owns no package-manager concept, and the node_modules desire path is
+# already handled there. That is where the false-green `tsc` class (a no-op tsc against a missing
+# node_modules reporting green) is closed — not here.
+
 ( cd "$wt" && git hook run pre-commit || true )
 ```
 
-Verify worktree dir exists, branch locked, and (if applicable) submodule dirs are non-empty. On failure → cleanup partial state, refuse mode.
+Verify worktree dir exists, branch locked, and (if applicable) submodule dirs are non-empty and each configured `worktree_hydrate` artifact that exists in the superproject is present in the worktree. On failure → cleanup partial state, refuse mode.
 
 `anchor` (= `m-{milestone_id}-{session_id}`) names the worktree dir **and** branch from here on; every reference below that used to be `{session_id}` is now `{anchor}`. `session_id` (the bare uuid) is retained only as the collision key + audit id in state.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.73.1",
+  "version": "0.75.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/hooks/forge-reserve.sh

@@ -249,10 +249,27 @@ compute_id() {
   # Hyphen is OPTIONAL in the token ([A-Z]+-?[0-9]+): refactor ids (R100) carry none
   # (ADR-023), so requiring a hyphen would hide them and drop the floor to 0. Split the
   # alpha prefix from the digits in awk so R does not match e.g. FR (anchor ^prefix$).
-  main_max="$(git show main:.forge/reservations.yml 2>/dev/null \
-    | grep -oE '[A-Z]+-?[0-9]+' \
-    | awk -v p="$prefix" '{ a=$0; sub(/[-0-9].*$/,"",a); d=$0; gsub(/[^0-9]/,"",d);
-                            if(a==p){ n=d+0; if(n>m)m=n } } END{print m+0}')"
+  #
+  # READ BOTH main AND origin/main (#26): in the local-main-first workflow (ADR-010 —
+  # primary checkout parked on main, all work in worktrees reaching main via PRs), local
+  # `main` routinely lags origin/main by whatever merged since the last fast-forward, so a
+  # local-only floor hands out ids origin/main already claimed — #19's collision class,
+  # relocated to the one input that still isn't machine-shared. Best-effort-fetch origin
+  # first, then take the max across whichever of {main, origin/main} resolve. Every leg
+  # degrades to nothing offline / with no remote (the same posture the rest of the script
+  # takes) — a fetch failure or a missing ref is never fatal, it just contributes 0.
+  # FORGE_RESERVE_NO_FETCH=1 skips the fetch (fixtures with a local file:// origin want the
+  # deterministic ref state they set up, not a network round-trip).
+  ref_reservations_max() {  # $1 = git ref → max reserved id for $prefix on that ref (0 if absent)
+    git show "$1:.forge/reservations.yml" 2>/dev/null \
+      | grep -oE '[A-Z]+-?[0-9]+' \
+      | awk -v p="$prefix" '{ a=$0; sub(/[-0-9].*$/,"",a); d=$0; gsub(/[^0-9]/,"",d);
+                              if(a==p){ n=d+0; if(n>m)m=n } } END{print m+0}'
+  }
+  [ "${FORGE_RESERVE_NO_FETCH:-0}" = 1 ] || git fetch --quiet origin main 2>/dev/null || true
+  main_local_max="$(ref_reservations_max main)";        [ -n "$main_local_max" ]  || main_local_max=0
+  main_origin_max="$(ref_reservations_max origin/main)"; [ -n "$main_origin_max" ] || main_origin_max=0
+  main_max="$(awk -v a="$main_local_max" -v b="$main_origin_max" 'BEGIN{print (a>b)?a:b}')"
   [ -n "$main_max" ] || main_max=0
 
   next="$(awk -v a="$ledger_max" -v b="$intree_max" -v c="$main_max" \

package/template/.claude/hooks/tests/forge-reserve.test.sh

@@ -285,6 +285,98 @@ else
   fail "case10b --days 1 dropped the kind's max row"
 fi
 
+# --- Case 11: origin/main floor beats a lagging local main (#26) -------------
+# The local-main-first collision: origin/main carries a MERGED higher claim
+# (FR-300) that local main has not fast-forwarded to (local main still at FR-200).
+# A local-main-only floor would hand out FR-201 — an id origin/main already used.
+# The fix reads across {main, origin/main}, so the floor is FR-300 → next FR-301.
+origin_repo="$(new_repo case11-origin)"
+( cd "$origin_repo"
+  mkdir -p .forge
+  cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-300
+    milestone: m-sibling
+    reserved_at: "2026-02-01"
+    summary: "merged on origin/main, ahead of local main"
+YML
+  git add -A && git commit -qm "origin has FR-300" )
+# Clone it (clone's origin → the seed repo), then rewind the clone's LOCAL main to
+# an earlier commit carrying only FR-200 — simulating a primary checkout parked on a
+# stale main while sibling work merged FR-300 to origin.
+clone="$ROOT/repo.case11-clone"
+git clone -q "$origin_repo" "$clone"
+cd "$clone"
+git config user.email t@example.com; git config user.name tester
+# Build a divergent local main: reset to an orphan-free earlier state with FR-200.
+cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-200
+    milestone: m-x
+    reserved_at: "2026-01-01"
+    summary: "local main lags"
+YML
+git add -A && git commit -qm "local main at FR-200 (behind origin/main FR-300)"
+# origin/main (remote-tracking) still points at FR-300; local main is now at FR-200.
+# Allow the helper to fetch the local file:// origin (deterministic, no network).
+got="$(FORGE_RESERVE_NO_FETCH=1 "$HELPER" fr --milestone m-x)"
+check "case11 origin/main floor (FR-300) beats lagging local main (FR-200) -> FR-301" "$got" "FR-301"
+# Negative control: with the origin arm blind (simulate no remote-tracking ref by
+# reading a repo that has NO origin at all), the floor falls back to local main only.
+d="$(new_repo case11-noorigin)"; cd "$d"
+mkdir -p .forge
+cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-200
+    milestone: m-x
+    reserved_at: "2026-01-01"
+    summary: "no origin — local main is the only floor"
+YML
+git add -A && git commit -qm init
+rm .forge/reservations.yml
+got="$(FORGE_RESERVE_NO_FETCH=1 "$HELPER" fr --milestone m-x)"
+check "case11 no-origin repo still floors on local main (FR-200) -> FR-201" "$got" "FR-201"
+
+# --- Case 12: the fetch refreshes a STALE origin/main tracking ref (#26) ------
+# The end-to-end proof: a sibling merges a higher claim to origin AFTER this clone
+# was made, so the clone's origin/main remote-tracking ref is stale. Without the
+# best-effort fetch the floor would miss it; with the fetch (default, NOT skipped)
+# the helper refreshes origin/main and floors correctly. Uses a local file:// origin
+# so the "fetch" is a deterministic local operation, no network.
+seed="$(new_repo case12-seed)"
+( cd "$seed"
+  mkdir -p .forge
+  cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-200
+    milestone: m-x
+    reserved_at: "2026-01-01"
+    summary: "seed FR-200"
+YML
+  git add -A && git commit -qm "seed FR-200" )
+clone2="$ROOT/repo.case12-clone"
+git clone -q "$seed" "$clone2"
+# Sibling advances origin to FR-400 AFTER the clone → clone's origin/main is now stale.
+( cd "$seed"
+  cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-400
+    milestone: m-sibling
+    reserved_at: "2026-03-01"
+    summary: "merged to origin after the clone"
+YML
+  git add -A && git commit -qm "origin advances to FR-400" )
+cd "$clone2"
+git config user.email t@example.com; git config user.name tester
+# Do NOT set FORGE_RESERVE_NO_FETCH — the fetch is exactly what we are testing.
+got="$("$HELPER" fr --milestone m-x)"
+check "case12 fetch refreshes stale origin/main (FR-400) -> FR-401" "$got" "FR-401"
+
 # --- Report -----------------------------------------------------------------
 printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
 [ "$FAILED" -eq 0 ]

package/template/.claude/skills/executing/SKILL.md

@@ -36,6 +36,29 @@ fi
 
 Surface the init if it ran (*"populated N uninitialised submodule(s) before baseline"*). A `+`/`U` line (divergent/conflicted submodule) is **not** an init case — STOP under Rule 4; it signals real submodule movement. (Desire-path: canvaz m-TIDES01 — empty `external/JUCE` failed the first CMake configure mid-task.)
 
+**Gitignored artifacts.** A fresh worktree is a clean checkout of *tracked* files only. Anything gitignored but required — `.mcp.json` (MCP server config, often secret-bearing so it MUST stay gitignored), `.env.local`, experimental hook configs — is simply **absent**, and the failure is silent: MCP servers that never appear, an env-dependent command that misbehaves — no clear "missing config" error. `orchestrating` hydrates these when *it* creates the worktree, but a worktree from any other origin (a manual `git worktree add`, a `chief-of-staff` stream, a fresh clone) does not. So assert it here, regardless of how the workspace was created. Advisory and guarded — a clean no-op when `orchestration.worktree_hydrate` is unset or nothing applies, so existing installs are unaffected:
+
+```bash
+# Copy required-but-gitignored artifacts named in orchestration.worktree_hydrate from the
+# superproject (the MAIN checkout, resolved from the shared git common dir — this assertion
+# runs INSIDE the worktree), guarded source-exists && dest-absent. Never overwrites, never
+# git-adds — the file stays gitignored/untracked in both trees (a secret like .mcp.json never
+# enters git history). No-op when the key is absent or nothing applies.
+repo_root=$(git rev-parse --show-toplevel)
+super=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null | sed 's#/\.git/modules/.*##;s#/\.git/worktrees/.*##;s#/\.git$##')
+sed -n '/^orchestration:/,/^[^[:space:]#]/p' "$repo_root/.forge/project.yml" 2>/dev/null \
+  | sed -n '/^[[:space:]]*worktree_hydrate:/,/^[[:space:]]*[a-z_]*:/p' \
+  | sed -n 's/^[[:space:]]*-[[:space:]]*//p' | tr -d "\"'" \
+  | while IFS= read -r rel; do                   # line-based: robust across sh/bash/zsh; a path may contain spaces
+      [ -n "$rel" ] && [ -n "$super" ] && [ "$super" != "$repo_root" ] || continue  # no key / main checkout → no-op
+      [ -e "$super/$rel" ] && [ ! -e "$repo_root/$rel" ] || continue                # source-exists && dest-absent
+      mkdir -p "$(dirname "$repo_root/$rel")"; cp -p "$super/$rel" "$repo_root/$rel"
+      echo "hydrated: $rel"
+    done
+```
+
+The loop prints one `hydrated: {path}` line per artifact it copied — surface those before the baseline (*"hydrated N gitignored artifact(s) before baseline"*), mirroring the submodule surface line; no output means nothing needed hydrating. The `$super != $repo_root` guard makes this a natural no-op in a non-worktree (main) checkout — where superproject and checkout are the same tree and there is nothing to hydrate from.
+
 ## Baseline Snapshot
 
 Run **before the first task begins**. Makes failure causality mechanical — no self-assessment.

package/template/.claude/skills/jarvis/SKILL.md

@@ -15,6 +15,7 @@ Read these before acting on any intake. Jarvis **relays and triggers — it neve
 
 - **No routing.** Dispatch passes the model map (`model_by_phase_type`) through **untouched** — per-phase model selection is step 5. If intake starts *choosing models*, STOP: that is not this door's job.
 - **No approval, ever.** Jarvis never approves, waives, lowers, or carries an approval. Promotions are approved on GitHub's Environment surface (step 2); holds are waived by your recorded host acts. Jarvis *tells* you an approval is waiting and *where* — the act happens there.
+- **UAT is the human's act — Jarvis never stands in for it.** UAT = the **operator** tests the work locally, with their own eyes and hands. An agent's browser/Playwright run, an e2e suite, or green CI is *automated verification* — necessary, **never sufficient, and never called UAT**. Agents are not users of the system, so "the agent tested it" can never satisfy UAT. The invariant this door holds: **a PR exists only after the operator's explicit in-session UAT confirmation** — there is **no agent-attestation path to PR-open**. This is Forge's Human Verification Gate (`in_session_signoff`) applied at the **merge boundary** instead of milestone-close. The failure mode it refuses: a session self-attesting "Real browser UAT" in a PR body and auto-merging on green CI — the agent's own run is not the human's acceptance. If you catch yourself about to open a PR because *you* checked the work, STOP: that is the gate this door exists to hold.
 - **No status memory.** "What's in play?" is **computed** from board / disk-glob / fold every time (B5), never remembered. If a question seems to need a Jarvis-owned status store, that is the drift class (pain 4): compute it or route out. The ONLY durable Jarvis state is the B4 relay markers.
 - **No new notification infrastructure.** PushNotification + the Monitor `tail -F` + the runner's existing log. No queue, no broker, no third-party service.
 - **No runner changes.** Jarvis consumes the runner's seams (env vars, the notify log, the m-35 answer-file convention) and never edits the loop. Runner work lives in its own milestone.
@@ -89,24 +90,56 @@ When a watched log grows, pipe it back through the relay core — do **not** buz
 `--scan` relays every **unmarked** line and prints the relay text (one line per new ping); fire **PushNotification** with each. Inside, the helper recomputes host truth (the fold / `gh` / board) before building any state claim, so:
 
 - an **ambiguity** reaches the phone as the question verbatim (it is a question, not a claim);
-- a **done/halt** is phrased from the host's `release_state`, and a payload that claims a merge the host does not show is relayed as a **loud discrepancy** (the standing lesson — host truth wins);
+- a **`done`** means **"ready for the operator's local UAT"** — the slice's work is built in its worktree and **no PR exists yet**. It is a *cue to UAT*, not a merge claim; relay it as such and hand off to the UAT gate (below). A payload that claims a merge or a PR at `done` contradicts the flow and is relayed as a **loud discrepancy** (host truth wins — and under this flow the host shows no PR at `done`);
+- a **halt** is phrased from the host's `release_state`, named as a halt;
 - **fork / irreversible / budget** relay verbatim, named.
 
 The `--milestone` is derived per slice from its worktree branch (`forge/m-<id>`); it is what the fold recomputes against. Jarvis holds no status of its own — if a buzz would need a remembered fact, that is the drift class: recompute it or route out.
 
+### The UAT gate (post-`done`) — no PR until the operator accepts
+
+A `done` ping is the cue that the work is ready for the operator's **local UAT**, not that it shipped. There is no PR yet, and Jarvis opens one **only** after the operator's explicit in-session confirmation (the hard boundary in "What Jarvis is NOT"). On a relayed `done`, run this sequence **in order** — never skip ahead to a PR:
+
+1. **Spin up the slice's local dev server** so the operator can actually try it. Read the project's dev-lane command from `project.yml`:
+
+   ```sh
+   # jarvis.dev_lane_cmd — the stack-specific command that starts THIS slice's local dev server.
+   # Run it in the slice worktree (the work under test lives there), detached like the runner.
+   ```
+
+   If `jarvis.dev_lane_cmd` is **set**, run it in the slice worktree and tell the operator where it's up. If it is **absent**, do not fail — tell the operator to start their dev lane manually for this worktree (Forge owns no dev-server concept; the "how" is the project's, per FR-248). Either way, name the worktree so the operator knows what they're testing.
+2. **Relay "ready for your UAT."** Buzz the operator: the work is built and the local server is up (or ask them to start it) — *"ready for your UAT on the local server."* This is a cue to the human, phrased as such.
+3. **Wait for the operator's explicit confirmation.** Do nothing irreversible until the operator says, in session, that they've tested it and it's good (a plain "looks good" / "ship it" / "approved"). **Your own browser run, a passing e2e suite, or green CI never substitutes** — see the UAT boundary. No confirmation → the slice sits; you do not open a PR.
+4. **On explicit confirmation only — open the PR and arm the merge.** This is a **trigger on the operator's word**, not an approval Jarvis grants (the "relays and triggers, never decides" boundary):
+
+   ```sh
+   gh pr create --fill --head <slice-branch>        # open the PR now that the human has accepted
+   gh pr merge <num> --auto --squash                # arm auto-merge; CI + branch protection gate the actual merge
+   ```
+
+   Then, and only then, arm the come-try watch on that PR number (below). The order is load-bearing: dev lane → ready-for-UAT → **explicit confirmation** → PR-open + arm merge → come-try. A PR that exists before step 3 is the failure this gate refuses.
+
+**On UAT failure — findings become an answer, and the slice re-dispatches.** If the operator says UAT failed, their findings are the fix instructions: land them as the runner's answer for the slice's `done` phase and re-dispatch, exactly like a parked-ambiguity answer (below) — no PR is opened, no new machinery:
+
+```sh
+.forge/checks/forge-jarvis-answer.sh --work-dir <dir> --phase <N> --slice <worktree> --answer "<operator's UAT findings>"
+```
+
+The runner resumes the slice with the findings in hand and fixes them; the next `done` re-enters this same UAT gate. (`<N>` is the slice's final/`done` phase — the one the operator just tested.)
+
 ### The come-try tap and the answer round-trip
 
 Two moments need a second source beyond the log line:
 
-- **"Merged, on staging — come try."** The runner's `done` ping fires at PR-open, but the step-2 auto-merge and the staging deploy land minutes later — that moment is never in the log. So when the handler relays a `done` that carries a PR, arm the bounded watch:
+- **"Merged, on staging — come try."** After the operator has accepted the work and Jarvis has opened + armed the PR (the UAT gate, above), the step-2 auto-merge and the staging deploy land minutes later — that moment is never in the log. So **once the PR is open (post-UAT), never at `done`**, arm the bounded watch on that PR number:
 
   ```sh
   .forge/checks/forge-jarvis-prwatch.sh --pr <num> [--staging-env <name>]
   ```
 
-  It polls `gh` (merge + staging-deploy) under a hard iteration/wall bound and self-terminates on merge+deploy (firing the come-try tap once, at-most-once by a PR-keyed marker), on a closed PR, or on the bound — never a standing daemon. It reads host truth only.
+  It polls `gh` (merge + staging-deploy) under a hard iteration/wall bound and self-terminates on merge+deploy (firing the come-try tap once, at-most-once by a PR-keyed marker), on a closed PR, or on the bound — never a standing daemon. It reads host truth only. The come-try moment therefore lands *after* the operator's own acceptance, so nothing reaches staging unverified.
 
-- **Park → answer → resume.** When the operator answers a parked ambiguity (typed or from the phone), close the loop through the runner's own convention:
+- **Park → answer → resume.** When the operator answers a parked ambiguity (typed or from the phone) — or supplies UAT-failure findings (the UAT gate, above) — close the loop through the runner's own convention:
 
   ```sh
   .forge/checks/forge-jarvis-answer.sh --work-dir <dir> --phase <N> --slice <worktree> --answer "<reply>"
@@ -205,3 +238,5 @@ B3 delivered intake → spec → detached dispatch; B4 added the callback relay;
 - **B6 — promotion voice** ✅ (this phase): on explicit `promote <sha>`, show what the SHA carries and trigger the step-2 seam — **trigger, never approve** (Promotion voice, above).
 
 The front door is now whole: intake, spec, detached dispatch, the callback relay, awareness + instruments, and the promotion voice — every state claim host-recomputed, no owned state beyond the B4 relay markers.
+
+**m-48 — UAT-gated dispatch** (later refinement, 0.74.0): the callback relay's back-half was re-sequenced so a `done` ping means "ready for the operator's local UAT" (no PR yet), Jarvis spins up the slice's local dev server (`jarvis.dev_lane_cmd`), waits for the operator's **explicit in-session UAT confirmation**, and only then triggers PR-open + arm merge — with the come-try PR watch re-armed *after* that operator-confirmed PR-open, and UAT failures routed back through the answer-file re-dispatch. The hard boundary — UAT is the human's act, no agent-attestation path to PR-open — lives in "What Jarvis is NOT". Nothing reaches staging unverified.

package/template/.forge/FORGE.md

@@ -59,6 +59,8 @@ Where worktrees live and what they're named — single source of truth, base con
 
 **Recorded path is authoritative once set** — `lifecycle.worktree_path` (milestone) / `runtime.worktree` (stream) is read verbatim, never re-derived; changing `worktree_root` affects only new worktrees; move a live worktree only with `git worktree move` + update the record. No recorded path → resolve from the convention. `forge` boot and `chief-of-staff` adoption **validate advisorily**: recorded path outside the resolved root → warn (never block, never move); an explicit `worktree_root` is honored.
 
+**`orchestration.worktree_hydrate`** (optional, `project.yml`; forge#18) lists superproject-relative paths to required-but-gitignored artifacts (e.g. `.mcp.json`) a fresh worktree's tracked-only checkout lacks. Copy is guarded `source-exists && dest-absent` — never overwrites, never `git add`s, so the secret stays untracked in both trees. Applied by `orchestrating` at creation and re-asserted idempotently in `executing`'s Workspace Prerequisites, covering worktrees of any origin. Omit ⇒ no propagation. The per-worktree runtime counterpart of the install-time carve-out propagation below (State Ownership § Stable shared).
+
 ## Workflow Tiers
 
 Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
@@ -188,7 +190,7 @@ Quick tier skips init.
 
 State lives in `.forge/`. One line per artifact; protocol detail lives in the named ADRs and skills:
 
-- `project.yml` — vision, stack, design system, verification, constraints (<5 KB)
+- `project.yml` — vision, stack, design system, verification, constraints (<5 KB). Optional `jarvis.dev_lane_cmd` (m-48) is the stack-agnostic seam Jarvis runs to spin up a slice's local dev server for operator UAT before a PR opens; absent ⇒ manual lane start. See `docs/jarvis.md`.
 - `constitution.md` — active architectural gates
 - `design-system.md` — component mapping table
 - `requirements/m{N}.yml` — per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. **FR/DEF/NFR ids are globally unique across all milestone files** — reserve via the ID Reservation Protocol before writing. M9 e2e gate fields (`e2e`, `observable_outcome`, `validated`, hash) lazy-migrate; absent ⇒ `false`.

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

@@ -1,11 +1,14 @@
 #!/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).
+# (m-37, Brief-R2 step 4 B4(c); contract handoff-step4-jarvis.md REV2; re-sequenced m-48).
 #
-# 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.
+# Under UAT-gated dispatch (m-48) a PR is opened by Jarvis ONLY after the operator's explicit
+# in-session UAT confirmation — never at the runner's `done` (which now means "ready for the
+# operator's local UAT", no PR yet). This watch is armed on THAT post-UAT PR: step-2 auto-merge +
+# the staging deploy land minutes LATER, so the flagship "come try it" moment never appears in the
+# notify log. On the opened PR, poll `gh` for its merge + staging-deploy state with a HARD bound
+# and, on merge+deploy, emit the come-try text once. Because it arms only after the operator has
+# accepted the work, nothing reaches staging unverified.
 #
 # 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

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

@@ -99,6 +99,20 @@ verification:
 #                                    # only — the private key lives host-side, in the deploy Environment).
 #                                    # Empty ⇒ git config gpg.ssh.allowedSignersFile.
 
+# orchestration:                     # OPTIONAL — worktree behavior (M10 / streams). Absent → defaults.
+#   worktree_root: ""                # Where Forge worktrees live. Default ../<repo-basename>-worktrees.
+#                                    #   Relative → resolves against repo root; absolute / ~ honored verbatim.
+#   worktree_hydrate: []             # OPTIONAL list of superproject-relative paths — required-but-gitignored
+#                                    #   artifacts copied into a fresh worktree so it can build and reach its
+#                                    #   tools (a clean worktree checks out TRACKED files only). Guarded
+#                                    #   source-exists && dest-absent: never overwrites, never git-adds, so a
+#                                    #   secret-bearing file stays gitignored/untracked in both trees and never
+#                                    #   enters git history (.mcp.json the canonical case). Applied by
+#                                    #   orchestrating at creation AND asserted in executing's Workspace
+#                                    #   Prerequisites → worktrees of ANY origin covered. Omit → no propagation.
+#                                    #   e.g. [".mcp.json", ".env.local"]. Dependency install stays with the
+#                                    #   executing/verifying preflight, not this key.
+
 success_criteria:                   # How do we know we're done?
   - ""                              # e.g., "User can create and edit posts"
   - ""                              # e.g., "All tests pass with >80% coverage"
@@ -154,6 +168,12 @@ models:
 #                                    #   no flag (platform default). TRUST WARNING: bypassPermissions means
 #                                    #   phone-spawned sessions act without prompts — opt in only where the
 #                                    #   phone lane carries the same trust as an attended terminal.
+#   dev_lane_cmd: ""                 # OPTIONAL. Shell command Jarvis runs (in the slice worktree) to spin up
+#                                    #   the LOCAL dev server for the operator's UAT after a `done` ping — the
+#                                    #   UAT-gated dispatch seam (m-48). Stack-specific: Forge owns no dev-server
+#                                    #   concept, so the project supplies the "how" (e.g. its `dev:all` lane).
+#                                    #   Absent → Jarvis tells the operator to start the lane manually (no failure).
+#                                    #   The PR opens only AFTER the operator's explicit in-session UAT — never here.
 
 # attribution:                       # OPT-IN Driven-by attribution (hold-waiver patch) — default OFF.
 #   driven_by: true                  # When true, the merge-floor check-quality lint