forge-orkes 0.62.0 → 0.64.0

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

@@ -0,0 +1,223 @@
+---
+name: orchestrating
+description: "[Experimental — M10] Optional backend for Forge stream isolation. Bootstrap worktrees, coordinate merge queue, and optionally use MCP file claims. Prefer Chief/Streams as the user-facing orchestration model."
+---
+
+# Orchestrating
+
+Multi-agent session lifecycle substrate. Worktree isolation + merge queue remain
+useful backend mechanics for Forge Streams. MCP/SQLite file claims are optional
+and experimental defense-in-depth, not the primary coordination model.
+
+## M16 Positioning
+
+Chief/Streams is the preferred user-facing orchestration model. The Project
+Chief decides when a stream needs M10 mechanics such as worktree isolation,
+branch anchoring, merge queue discipline, or claim checks. Users should normally
+ask to start, pause, delegate, conflict-check, merge, or close streams; they
+should not have to invoke M10 directly.
+
+M10 still matters when concurrent streams need hard workspace separation or a
+controlled merge path. It is a backend/substrate, not the project manager.
+
+## When to use
+
+- The Project Chief selects M10 for a stream that needs worktree isolation,
+  merge-queue support, or optional file-claim checks.
+- User explicitly invokes multi-agent mode (`/forge` argument selects multi-agent, or direct skill invocation).
+- Legacy installs may route Full tier work through this skill when
+  `orchestration.auto` remains enabled.
+
+Skip on Quick tier, single-phase work, or when bootstrap checks fail.
+
+## Enforcement scope — what claims actually protect
+
+Claim coordination (`forge_claim_files` + the PreToolUse gate) works for **one** mode only: a **single parent session** operating across a Forge-managed sibling worktree dir (default `../<repo>-worktrees/{anchor}`, configurable via `orchestration.worktree_root`), where main's hooks + `.session-id` apply. **It does NOT reach `Agent isolation:"worktree"` sub-agents** — those run in `.claude/worktrees/agent-*` with no hook config (`.claude` is gitignored), so they fire no SessionStart, claim under nothing, and their edits are **not gated**. For within-milestone fan-out, **worktree isolation + disjoint files behind a frozen contract is the safety — not claims.** Never assume a fan-out sub-agent is claim-protected; it is not. (See ADR-007.)
+
+## Step 1: Bootstrap
+
+Run all checks in `bootstrap-checks.md`:
+
+1. Git version ≥ 2.48
+2. LFS version ≥ 3.6 (skip if not installed)
+3. No divergent submodules — clean pinned submodules pass (auto-inited per worktree in Step 2); refuse only on `-`/`+`/`U` entries (see `bootstrap-checks.md` "Submodule handling")
+4. `core.hooksPath` empty or resolves inside worktree
+5. `git hook run pre-commit` smoke test in fresh worktree
+6. **Enforcement canary (advisory)** — `bash .claude/hooks/forge-claim-check-doctor.sh` reports `gate enforces`. On `GATE IS INERT`, warn loudly that claims provide no protection this session (worktree isolation still applies); do **not** refuse on this one — it never blocks, only surfaces.
+
+**Any check 1–5 fails** → log reason, write `lifecycle.worktree_mode: refused` + `lifecycle.refused_reason` into active milestone state, emit fallback message (see `bootstrap-checks.md`), return to caller. Caller continues single-agent. Check 6 is advisory — it warns, never refuses.
+
+## Step 2: Session ID + worktree
+
+```bash
+session_id=$(uuidgen | cut -c1-8)
+# Anchor the worktree name to the milestone id so the branch is self-describing:
+# the `m-{id}` token lets `forge` resume re-derive the milestone from the branch
+# name alone (its id-token fallback), not only from lifecycle.worktree_branch
+# state — which a moved/redone worktree can leave stale. The uuid suffix keeps the
+# name collision-resistant and unique per session; the `forge/` prefix keeps the GC
+# sweep simple. Milestone ids are dash-free, so `m-{id}` tokenizes cleanly.
+anchor="m-${milestone_id}-${session_id}"
+
+# Worktree root — configurable, repo-scoped by default (ADR-010).
+# Read `orchestration.worktree_root` from .forge/project.yml; if unset, default
+# to a per-repo sibling `../<repo-basename>-worktrees`. Per-repo siblings keep
+# each repo's worktrees in their own dir (no cross-repo mixing when multiple
+# repos share a parent), and resolve deterministically against the repo root
+# rather than the shell cwd. Relative roots resolve against repo root;
+# absolute roots and a leading `~` are honored as-is.
+repo_root=$(git rev-parse --show-toplevel)
+wt_root=$(sed -n '/^orchestration:/,/^[^[:space:]#]/p' "$repo_root/.forge/project.yml" 2>/dev/null \
+          | sed -n 's/^[[:space:]]*worktree_root:[[:space:]]*//p' | tr -d "\"'" | head -1)
+wt_root="${wt_root:-../$(basename "$repo_root")-worktrees}"
+case "$wt_root" in
+  /*)   : ;;                                  # absolute — use as-is
+  "~"*) wt_root="$HOME${wt_root#\~}" ;;       # expand leading ~
+  *)    wt_root="$repo_root/$wt_root" ;;      # relative → resolve against repo root
+esac
+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
+# 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
+( 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.
+
+`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.
+
+The **absolute** path Forge resolved (`$wt_root/${anchor}`) is recorded in `lifecycle.worktree_path` (Step 3). Every later operation — Step 4 handback, Step 5 teardown, Step 6 crash-recovery re-attach — uses that recorded path verbatim, never re-deriving it. This decouples in-flight worktrees from the config: changing `orchestration.worktree_root` later (or moving a worktree on disk) does not invalidate them.
+
+## Step 3: State update
+
+Write into `.forge/state/milestone-{id}.yml`:
+
+```yaml
+lifecycle:
+  session_id: "{session_id}"                 # short uuid — collision key + audit id only (not a name, not a claim id)
+  worktree_anchor: "m-{id}-{session_id}"     # milestone-anchored name of the worktree dir + branch
+  claim_session_id: "{claim_session_id}"     # Claude session id — owner of all file claims (see Identity)
+  worktree_path: "{absolute path Forge resolved in Step 2 — $wt_root/m-{id}-{session_id}}"
+  worktree_branch: "forge/m-{id}-{session_id}"
+  worktree_mode: "active"
+  started_at: "{ISO8601}"
+```
+
+Set `current.last_updated` in the milestone file. Do **not** write `state/index.yml` directly — it is a derived registry, regenerated by the `forge` rollup. (The orchestrator owns index.yml; worktree agents never touch it.)
+
+## Step 4: Hand back
+
+Relocate the session into the worktree, then return control to caller (typically `executing`) — instead of only *assuming* the caller is already inside `lifecycle.worktree_path`. Apply the canonical **Native Worktree Entry** contract (identical to the forge ownership-gate option 1):
+
+- **If the `EnterWorktree` tool is available**, call `EnterWorktree({path: {lifecycle.worktree_path}})` to relocate the session into the worktree before returning control, then log `Relocated into worktree {lifecycle.worktree_path} ({lifecycle.worktree_branch})` (independent of any prompt, so the cwd move is visible).
+- **If `EnterWorktree` is unavailable** (older Claude Code CLI, or a non-Claude-Code adapter), fall back to instructing the caller to `cd {path}` (here `cd {lifecycle.worktree_path}`) before continuing — today's implicit assumption stated explicitly.
+- Exit stays `ExitWorktree({action: "keep"})`; teardown remains Step 5 / `git worktree remove` — the native tool never removes the worktree.
+
+All subsequent work runs inside `lifecycle.worktree_path`. Caller honors claim convention.
+
+### Claim convention (executing-skill contract)
+
+State-file ownership: each session writes **only** its own `.forge/state/milestone-{own_id}.yml` and **appends** to `.forge/state/desire-paths/` (new files, never edited). It never writes `state/index.yml` — the registry is regenerated by rollup at teardown. Different milestones = different files, so these writes need no claim and never conflict across worktrees. Same-milestone parallelism is out of scope (one session per milestone — see the concurrent-invocation refusal in Edge Cases).
+
+**Identity (critical — see ADR-007).** File claims are owned by the **Claude session id**, NOT the worktree uuid. The worktree uuid (`session_id` above) only feeds the worktree name (via `anchor`) and serves as the collision/audit key. Read the claim identity from the file the `forge-session-id.sh` SessionStart hook writes:
+
+```bash
+claim_session_id=$(cat "${CLAUDE_PROJECT_DIR:-.}/.forge/.mcp-server/.session-id" 2>/dev/null)
+```
+
+This is the same id the `forge-claim-check.sh` enforcement hook reads from PreToolUse stdin, so a session's own claims are recognized and other sessions' claims block. If the file is missing/empty the hook fail-opens (no enforcement) — surface that rather than proceeding silently in genuine multi-agent work.
+
+Before any `Edit`, `Write`, `MultiEdit`, or `NotebookEdit` on a file outside `.forge/state/milestone-{own_id}.yml`:
+
+1. Call `forge_claim_files` with `{ session_id: claim_session_id, files: [...], ttl_seconds: 900 }`.
+2. On `granted` → proceed with edit.
+3. On `conflict: { holder_session, files: [...] }` → surface holder + files to user. Options:
+   - **wait** → poll `forge_claim_status` until released or TTL expiry.
+   - **skip** → drop the conflicted file from the task scope, continue with rest.
+   - **steal** → only if holder session is provably dead (PreToolUse hook validates). Otherwise refused.
+4. After edit batch → claim auto-extends on continued use; explicit `forge_release_claims` on plan-complete.
+
+PreToolUse hook (installed by plan-03) enforces this — uncaught violations block at hook level, not skill level.
+
+## Step 5: Teardown
+
+Triggered when caller signals work complete OR user requests teardown.
+
+### Step 5.0: Human Verification Gate (hard block — runs first)
+
+Before any merge or worktree removal, read `current.human_verified` from `.forge/state/milestone-{id}.yml`.
+
+- **Present** (`{at, method, ...}`, including a recorded `override`) → gate satisfied, proceed to the merge below.
+- **Absent / null** → **REFUSE teardown.** Code-clean + FF-clean is **not** enough to close a milestone (FORGE.md → Human Verification Gate). Do **not** present teardown as an option, and never offer it as a peer alternative to the outstanding verification. Respond with what's still unverified and offer exactly two paths:
+  1. **Verify now** → run the human verification (device session / visual / e2e walk). Have `verifying` (or this step) record `current.human_verified`, then re-invoke teardown.
+  2. **Record override** → only on an explicit human instruction to close without verifying: write `current.human_verified: {at: "<ISO 8601>", method: "override", override: true, reason}` to the milestone file, surface it, then proceed.
+
+Never merge + remove a worktree while `human_verified` is unset.
+
+```
+forge_queue_commit(branch=forge/m-{id}-{session_id}, base_sha={merge_base})
+```
+
+Branch on response status:
+
+- **`merged`** (response has `new_main_sha`) → **reconcile the working tree first** — `forge_queue_commit` merges *ref-only* (`update-ref`), so the main checkout is now behind HEAD: `git checkout HEAD -- $(git diff --name-only {base_sha} {new_main_sha})` — surgical, merged files only; **never** `git checkout HEAD -- .` (would clobber unrelated WIP) → `forge_release_claims(claim_session_id)` (the Claude session id, not the worktree uuid) → `git worktree remove --force --force "$(yq '.lifecycle.worktree_path' .forge/state/milestone-{id}.yml)"` (double `--force`: Step 2 created the worktree `--lock`ed, and a single `--force` refuses to remove a locked worktree; read the path from state rather than re-deriving it so a moved/non-default worktree still removes cleanly) → `git branch -d forge/m-{id}-{session_id}` → clear `lifecycle.*` (set `worktree_mode: complete`, retain `session_id` for audit) → **State reconcile = Rollup:** regenerate `state/index.yml` from the now-merged `milestone-*.yml` files (`forge` Rollup 1.0) and commit it (`chore(forge): rollup state after teardown — {session_id}`). The merged milestone files are the source of truth; index.yml is never hand-merged.
+- **`conflict`** → invoke `Skill(debugging)` with payload `{ conflicted_files, base_sha, messages, branch }`. Teardown blocks until debugging signals resolution (re-invoke teardown after fix).
+- **`stale_base`** → caller rebases worktree branch onto `current_target_sha` from response, retries `forge_queue_commit`. Max 3 retries → escalate to conflict path.
+
+## Step 6: Crash recovery (next session start)
+
+If no clean teardown happened previously:
+
+1. `git worktree prune` — drops stale admin dirs.
+2. `git branch --list 'forge/*'` — for each branch with no live worktree, prompt user. The branch suffix is the `anchor` (`m-{id}-{session_id}`); the milestone id is the `m-…` token, recoverable from the name alone even if state is stale:
+   - **resume** → re-attach at the path recorded in `lifecycle.worktree_path` (read from `state/milestone-{id}.yml` — the recorded absolute path survives a `worktree_root` config change after the fact). State missing the path → fall back to the current default (`<repo_root>/../<repo-basename>-worktrees/{anchor}`) and warn. `git worktree add <path> forge/{anchor}` and restore lifecycle state.
+   - **delete** → `git branch -D forge/{anchor}`.
+3. MCP server startup handles pidfile takeover + claim TTL expiry independently (see ADR-003).
+
+## Failure modes & operator notes
+
+- **MCP server absent** — bootstrap check 5 (hook smoke) will not detect this. Skill detects on first `forge_claim_files` call: error `MCP_SERVER_UNAVAILABLE` → write `lifecycle.worktree_mode: degraded`, warn user, continue without claim coordination. Hard isolation (worktree) still active; coordination is downgraded to best-effort.
+- **Disk full during worktree add** — `git worktree add` will error. Cleanup any partial `$wt_root/m-{id}-{session_id}/` dir, refuse mode, fall back.
+- **Concurrent orchestrating invocations** — second invocation reads first's `lifecycle.session_id` in state. If present and `worktree_mode: active` → refuse (one orchestration per milestone). Use a separate milestone for parallel orchestrated work.
+- **Worktree path collision** — UUIDv4 short (8 chars) collision negligible at <100 concurrent sessions. If `$wt_root/m-{id}-{session_id}/` already exists → regenerate session_id (the `anchor` recomputes with it), retry up to 3 times.
+- **`worktree_root` changed mid-flight** — Step 3 records the resolved absolute `lifecycle.worktree_path`; teardown + crash-recovery read it from state, never re-derive. Editing `orchestration.worktree_root` in `project.yml` only affects newly created worktrees. Do not relocate live worktrees on disk by hand — `git worktree move` is the supported way; bare `mv` leaves the gitdir pointer stale.
+
+## Example: clean session
+
+```
+user: /forge multi-agent
+forge → orchestrating
+orchestrating: bootstrap OK → session_id=a1b2c3d4 → anchor=m-9-a1b2c3d4 → worktree created at ../<repo>-worktrees/m-9-a1b2c3d4 → state written
+orchestrating → executing (working dir: ../<repo>-worktrees/m-9-a1b2c3d4, branch: forge/m-9-a1b2c3d4)
+executing: claim files → edit → commit (× N tasks)
+executing → verifying (captures current.human_verified on human sign-off) → reviewing (all inside worktree)
+reviewing → orchestrating (teardown)
+orchestrating: Step 5.0 gate — current.human_verified present → forge_queue_commit → merged → release claims → remove worktree → delete branch
+done.
+```
+
+## Example: conflict path
+
+```
+orchestrating: forge_queue_commit → conflict { files: [src/auth.ts] }
+orchestrating → debugging { conflicted_files, base_sha, branch }
+debugging: user resolves → signal resolved
+orchestrating: retry forge_queue_commit → merged → cleanup
+```
+
+## References
+
+- ADR-001 — experimental track / opt-in carve-out
+- ADR-002 — worktrees as isolation substrate
+- ADR-003 — MCP server + per-repo SQLite
+- ADR-004 — merge queue (forge_queue_commit status semantics)
+- ADR-005 — session lifecycle (this skill realizes it)
+- `.forge/research/milestone-10.md` — spike findings
+- `bootstrap-checks.md` — bootstrap check matrix + fallback

package/experimental/m10/source/skills/orchestrating/bootstrap-checks.md

@@ -0,0 +1,70 @@
+# Bootstrap Checks
+
+Run before worktree creation. Any failure → refuse worktree mode, fall back to single-agent.
+
+| Check | Command | Pass criterion | Fail action | Reason |
+|-------|---------|----------------|-------------|--------|
+| Git version | `git --version` | major.minor ≥ 2.48 | refuse worktree mode | Known worktree bugs < 2.48 (admin-dir leaks, prune races) |
+| LFS version | `git lfs version` (skip if not installed) | ≥ 3.6 OR not installed | refuse worktree mode | Known worktree-locking bugs < 3.6 |
+| Submodule scan | `git submodule status` | empty OR every entry clean (` ` prefix, in-sync with recorded pin) | refuse only on divergent (`+`) / conflicted (`U`) entries — see "Submodule handling" below | Clean pins are safe: every worktree wants the same SHA, so the shared `.git/modules` HEAD never contends. Divergent working state is the real hazard. New worktrees auto-init submodules (SKILL Step 2) |
+| `core.hooksPath` | `git config core.hooksPath` | empty OR path resolves inside worktree | refuse worktree mode | Husky/lefthook silent-skip risk when path points outside worktree |
+| Hook smoke test | `git hook run pre-commit` in fresh worktree | exit 0 OR matches main-repo exit code | refuse worktree mode | Confirms hook plumbing actually fires inside worktree |
+| Enforcement canary (advisory) | `bash .claude/hooks/forge-claim-check-doctor.sh` | canary line reports `gate enforces` | **warn, do not refuse** | Proves the claim gate actually denies a foreign claim — catches the inert-gate class (identity read from wrong source / hook unwired) that prereqs can't see |
+
+## Fallback message
+
+On any check failure, emit verbatim to user:
+
+```
+M10 worktree mode unavailable: <reason>. Continuing in single-agent mode. See ADR-005 for compatibility matrix.
+```
+
+Replace `<reason>` with the failing check name + observed value (e.g., "Git version 2.45.1 < required 2.48").
+
+## Submodule handling (conditional)
+
+Submodules do **not** auto-populate in a fresh worktree — `git worktree add` carries the gitlinks but leaves the directories empty until `git submodule update --init` runs (SKILL Step 2 does this). The historic blanket refusal was over-conservative; the real hazard is two worktrees fighting over the shared `.git/modules` HEAD/index when they point a submodule at *different* SHAs. Pinned third-party deps (e.g. JUCE, nanovg) never trigger that — every worktree converges on the one recorded SHA.
+
+Classify `git submodule status` output:
+
+| Observed | Meaning | Action |
+|----------|---------|--------|
+| empty | no submodules | pass |
+| every line ` ` (space) prefix | all clean, in-sync with recorded pin | **warn + proceed** — Step 2 will `submodule update --init --recursive` |
+| any line `-` (uninitialized) in main repo | superproject itself hasn't inited | refuse — init in the main checkout first (`git submodule update --init`) |
+| any line `+` (divergent SHA) | working tree ahead/behind recorded pin | refuse — uncommitted submodule movement is the shared-`.git/modules` hazard |
+| any line `U` (merge conflict) | unresolved submodule conflict | refuse |
+
+Warn-and-proceed message:
+
+```
+M10: <N> submodule(s) present and clean — proceeding. Each worktree auto-inits them
+(shared .git/modules object store, no re-clone). Ensure builds tolerate the one-time init.
+```
+
+## State write on refusal
+
+```yaml
+lifecycle:
+  worktree_mode: refused
+  refused_reason: "<check name>: <observed>"
+  refused_at: "{ISO8601}"
+```
+
+## Check execution order
+
+Run checks 1→5 in order. First failure halts the sequence — no point running hook smoke if Git itself is too old. Record the failing check name + observed value as `refused_reason` so the user knows exactly what to fix.
+
+## Remediation hints
+
+| Failing check | User remediation |
+|---------------|------------------|
+| Git version | Upgrade Git to ≥ 2.48 (Homebrew: `brew upgrade git`; apt: backports or PPA) |
+| LFS version | Upgrade Git LFS to ≥ 3.6 OR uninstall if not actually used |
+| Submodule scan | Only fails on uninitialized (`-`), divergent (`+`), or conflicted (`U`) submodules. Run `git submodule update --init --recursive` in the main checkout so every submodule sits at its recorded pin, then retry. Clean pinned submodules are supported |
+| `core.hooksPath` | Either unset (`git config --unset core.hooksPath`) or move hook dir inside repo tree so it resolves under each worktree |
+| Hook smoke test | Inspect failing hook output; common cause is hook script assuming `$PWD` is main repo root — fix to use `git rev-parse --show-toplevel` |
+
+## Re-running checks
+
+Bootstrap is idempotent and cheap (~200ms total). Skill re-runs on every session start; users do not invoke directly. If a check transiently fails (e.g., LFS not yet installed during initial setup), simply restart the orchestration entry.

package/experimental/m10/uninstall.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Forge M10 experimental uninstaller.
+# Preserves claims.db by default. Pass --purge to remove it.
+# Usage: bash uninstall.sh [--purge] /path/to/forge-repo
+
+set -euo pipefail
+
+PURGE=0
+TARGET=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --purge) PURGE=1; shift ;;
+    -h|--help) echo "Usage: $0 [--purge] /path/to/forge-repo"; exit 0 ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+[[ -z "$TARGET" ]] && { echo "ERROR: target repo path required" >&2; exit 2; }
+[[ -d "$TARGET" ]] || { echo "ERROR: target '$TARGET' does not exist" >&2; exit 2; }
+
+say() { echo "  $*"; }
+
+echo "==> M10 experimental uninstaller"
+echo "    target: $TARGET"
+[[ $PURGE -eq 1 ]] && echo "    mode:   --purge (claims.db will be removed)"
+echo
+
+# Remove MCP server dir
+if [[ -d "$TARGET/.forge/.mcp-server" ]]; then
+  if [[ $PURGE -eq 0 && -f "$TARGET/.forge/.mcp-server/claims.db" ]]; then
+    say "preserving claims.db; removing rest of .mcp-server/"
+    find "$TARGET/.forge/.mcp-server" -mindepth 1 -not -name claims.db -delete
+  else
+    rm -rf "$TARGET/.forge/.mcp-server"
+    say "removed .forge/.mcp-server/"
+  fi
+fi
+
+# Remove hooks
+for h in forge-claim-check.sh forge-claim-check-doctor.sh; do
+  [[ -f "$TARGET/.claude/hooks/$h" ]] && { rm -f "$TARGET/.claude/hooks/$h"; say "removed hook $h"; }
+done
+
+# Remove orchestrating skill
+[[ -d "$TARGET/.claude/skills/orchestrating" ]] && {
+  rm -rf "$TARGET/.claude/skills/orchestrating"
+  say "removed orchestrating skill"
+}
+
+# Strip .mcp.json entry
+if [[ -f "$TARGET/.mcp.json" ]] && jq -e '.mcpServers["forge-orchestrator"]' "$TARGET/.mcp.json" >/dev/null 2>&1; then
+  tmp=$(mktemp)
+  jq 'del(.mcpServers["forge-orchestrator"])' "$TARGET/.mcp.json" > "$tmp"
+  mv "$tmp" "$TARGET/.mcp.json"
+  say "removed forge-orchestrator from .mcp.json"
+fi
+
+# Strip settings.json hook entry
+if [[ -f "$TARGET/.claude/settings.json" ]]; then
+  tmp=$(mktemp)
+  jq '.hooks.PreToolUse = ((.hooks.PreToolUse // []) | map(select((.hooks // []) | all(.command != ".claude/hooks/forge-claim-check.sh"))))' \
+    "$TARGET/.claude/settings.json" > "$tmp"
+  mv "$tmp" "$TARGET/.claude/settings.json"
+  say "removed claim-check hook from settings.json"
+fi
+
+echo
+echo "==> Done."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.62.0",
+  "version": "0.64.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"
@@ -11,7 +11,8 @@
   },
   "files": [
     "bin/",
-    "template/"
+    "template/",
+    "experimental/"
   ],
   "keywords": [
     "claude",

package/template/.claude/hooks/forge-release-fold.sh

@@ -200,8 +200,10 @@ case "$unit" in
   *) printf 'forge-release-fold: unit-id must be m-<N>, got: %s\n' "$unit" >&2; usage ;;
 esac
 num="${unit#m-}"
+# Numeric (m-8) and labeled (m-AUTO01, incl. letter sub-phases like m-3-1a) id
+# schemes are both valid; reject only empty ids and ids with unsafe characters.
 case "$num" in
-  ''|*[!0-9]*) printf 'forge-release-fold: unit-id must be m-<N>, got: %s\n' "$unit" >&2; usage ;;
+  ''|*[!A-Za-z0-9_-]*) printf 'forge-release-fold: unit-id must be m-<N> or m-<LABEL>, got: %s\n' "$unit" >&2; usage ;;
 esac
 
 # --- repo + main ref -------------------------------------------------------
@@ -217,6 +219,12 @@ if ! git -C "$root" rev-parse -q --verify "$main_ref^{commit}" >/dev/null 2>&1;
 fi
 
 state_path=".forge/state/milestone-$num.yml"
+# Labeled-id convention keeps the m- prefix in the filename (milestone-m-LABEL.yml);
+# prefer whichever spelling is tracked in the main tree.
+if ! git -C "$root" cat-file -e "$main_ref:$state_path" 2>/dev/null \
+   && git -C "$root" cat-file -e "$main_ref:.forge/state/milestone-$unit.yml" 2>/dev/null; then
+  state_path=".forge/state/milestone-$unit.yml"
+fi
 stream_path=".forge/streams/$unit.yml"
 
 # MAIN-TREE state read — never the working tree. Empty when not tracked.

package/template/.claude/settings.json

@@ -47,13 +47,7 @@
       "Edit(**/secrets/**)",
       "Edit(**/.secrets/**)",
       "Edit(**/*.pem)",
-      "Edit(**/*.key)",
-      "Write(**/.env)",
-      "Write(**/.env.*)",
-      "Write(**/secrets/**)",
-      "Write(**/.secrets/**)",
-      "Write(**/*.pem)",
-      "Write(**/*.key)"
+      "Edit(**/*.key)"
     ]
   },
   "hooks": {

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

@@ -0,0 +1,204 @@
+---
+name: jarvis
+description: "The per-repo front door (Brief-R2 step 4, kills P15). Conversational intake → spec → detached dispatch → callback relay → awareness → promotion voice, running in the standing Jarvis remote-control session. Triggers: /jarvis at conversation start (the reliable binding — invoke it in every RC conversation), intake from laptop or phone, 'go' to dispatch a specced slice, 'what's in play?', 'promote <sha>'. On 'go' the session dispatches detached via forge-jarvis-dispatch.sh — it never runs executing inline. Consumes existing primitives (slice runner, board, fold, promotion seam) — wiring, not machinery."
+---
+
+# Jarvis — the per-repo front door
+
+**The shape (state it exactly this simply):** Jarvis is the single door and comms interface for this repo. You design and spec work by talking to it — from the laptop or the phone; it hands the build off to detached agents, tells you when work is done or when your input is needed, and losing the session loses no work. Every state it speaks is recomputed from the host (fold / `gh` / board), never a session's claim.
+
+Jarvis is the **pre-created session** of the `claude remote-control` server that `.forge/checks/forge-jarvis.sh` starts. It is not a daemon and owns almost nothing: kill it and only the live connection + armed watches are lost, both re-established at restart from files (Amendment 2). The one exception is the relay-marker class (B4) — delivery bookkeeping, never authority over work state.
+
+## What Jarvis is NOT (boundaries — binding; the contract's "Not this step")
+
+Read these before acting on any intake. Jarvis **relays and triggers — it never decides or approves.**
+
+- **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.
+- **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.
+- **One presence per repo per machine.** No multi-repo hub (monitored, not built — DEF-193). On a multi-machine repo the awareness is per-machine by construction; say so, don't pretend.
+
+If intake ever wants to grow a routing brain, an approval, or a memory — **STOP and route out.** That is the concierge failure mode this door is built to refuse.
+
+## Session binding (start here)
+
+Skill loading is description-matched — nothing *forces* an RC conversation to load this skill, and an unbound session silently degrades to plain Forge: it specs beautifully, then builds inline on "go" — no dispatch, no notify log, nothing for the relay to watch, the operator's phone silent for the whole build (observed live, m-39 walk, 2026-07-22). Two rules close that hole:
+
+- **Operator side:** open each Jarvis conversation by invoking **`/jarvis`** (or naming the skill). The launcher's sticky `--name` makes the presence findable; `/jarvis` makes the session *be* Jarvis.
+- **Session side:** once this skill loads, you ARE the front door for the rest of the conversation. Driving other skills (`forge`, `discussing`, `planning`) during intake is exactly right — but every later step (dispatch, relay, awareness, promotion) stays under these rules, and the Dispatch section's "go means dispatch — never build" override outranks any other skill's routing.
+- **Binding is a restart moment — act on it immediately:** the instant this skill loads, (1) arm the watches (Callback relay → Arm the watches) and (2) run the **while-you-were-away catchup** (Callback relay → While you were away) across every live slice log. Any pending ping is the FIRST thing you tell the operator — before greeting, before asking what they want. WHY hard-anchored: in the live walk (run 6, 2026-07-22) a completed slice's `done` ping sat unmarked through a `/jarvis` bind AND a "what's happening?" — the section existed but no trigger invoked it; the operator learned of the finished work only from the host-side verifier.
+
+## Intake → spec (run the EXISTING act — do not rebuild it)
+
+Intake collaboration is already validated (Brief-R2 §1). Jarvis does **not** reimplement it — it drives the existing Forge skills from the conversation:
+
+1. **Listen.** The operator describes a small real slice conversationally — from the laptop or the phone (identical either way; see Phone parity).
+2. **Spec it together.** Route into the normal Forge flow: `Skill(forge)` for a new slice (which does the worktree entry + milestone declaration on main — the step-0 B3′ declaration split, ff-pushed so the work is sighted on main), then `Skill(discussing)` / `Skill(planning)` **in the work's own worktree**. The spec conversation *is* the value; Jarvis is the front door to it, not a second copy of it.
+3. **Confirm the spec back** to the operator before any build. A declaration lands on main; the plan lands in the worktree. Nothing has been dispatched yet.
+
+Jarvis owns none of this logic — it owns the *doorway*. The declaration/spec artifacts are written by the existing skills, in the worktree, exactly as they are today.
+
+## Dispatch (on the operator's "go")
+
+**"Go" means dispatch — never build.** In the front-door session, `Skill(executing)` is NEVER invoked for a specced slice, and no slice file is ever edited here after "go". Forge's own routing (`planning → executing`) still holds — but it is the **detached runner's** path, executed headless in the slice worktree; it is not this session's. This override outranks the forge routing table: when routing says "executing" for a dispatched slice, the front door's move is the dispatch helper, nothing else. If you notice yourself editing slice files or invoking executing after a "go" — STOP; that is the observed failure mode (m-39: built inline, no notify log, no pings, the entire relay dark).
+
+When the operator says **go** on a specced slice, dispatch the runner **detached** so it survives Jarvis's death (B1 probe viii). Do not run the runner in the foreground and do not reach into its loop — call the helper:
+
+```sh
+.forge/checks/forge-jarvis-dispatch.sh --slice <worktree-path>
+```
+
+The helper (see its header for the full contract) owns the caller-side environment and nothing else:
+
+- **`FORGE_SLICE_NOTIFY_LOG` points INTO the slice's worktree** — never the invoker's cwd (the main checkout), which would drop a shared `notify.log` invisible to the worktree glob and dirty the clean-main invariant (step 0; acceptance #5).
+- **`FORGE_SLICE_NOTIFY` points at a log-only channel** (`forge-jarvis-notify-logonly.sh`) so the default channel's per-ping headless `claude -p` micro-call stays quiet — the B4 relay is the single delivery path; a live default channel would risk a double-buzz (B1 probe x). This is the swappable channel seam used exactly as designed: the runner is untouched, the caller owns the env.
+- **The model map is forwarded verbatim.** The helper carries no model-selection logic (see Boundaries — routing is step 5).
+- **The work order is materialized at dispatch** (FR-197): the runner's contract is `<worktree>/slice.yml` + `phases/<name>/plan.md`; when `slice.yml` is absent the helper builds both from the milestone's locked `.forge/phases/milestone-{id}/` plans (an existing `slice.yml` is honored untouched). When it cannot, it **refuses synchronously, before the detach** — relay that refusal to the operator immediately. And shortly after any real dispatch, read `<worktree>/.forge/runner-work/dispatch.out` once: a runner refusal lands there and must be relayed — **a silent phone is never success** (walk run 4's failure mode: the runner declined instantly and nothing ever buzzed).
+
+After dispatch, the slice runs headless in its worktree, writing every ping to its notify log. That log is the event bus the callback relay watches (B4).
+
+`--dry-run` on the helper prints the exact command + env it would run, without running it — use it to show the operator what "go" will do.
+
+## Callback relay (B4) — the load-bearing half
+
+This is what makes Jarvis a front door and not just a launcher: a runner ping in a slice's notify log becomes a typed buzz on the operator's phone, and **every state it speaks is recomputed from the host, never from the session's own words.** The notify log is the event bus; `forge-jarvis-relay.sh` is the decision core; PushNotification (over the live RC connection — B1 probe v) is the delivery. No queue, no broker, no daemon (NFR-038).
+
+### Arm the watches (boot, and after every dispatch)
+
+The set of logs to tail is **recomputed from disk every time, never held in memory** (Amendment 2). Ask the relay helper for the current set and arm a Monitor `tail -F` on each:
+
+```sh
+.forge/checks/forge-jarvis-relay.sh --list-logs        # one notify-log path per live slice worktree
+```
+
+For each path, arm a **Monitor `tail -F`** (capital F — the log may not exist until the slice's first ping; `tail -f` on a missing file would kill the watch, F8). Re-run `--list-logs` and re-arm on boot and after each `go` dispatch — the watch set is a pure function of what's on disk, so it always reflects the live slices without a remembered list. Kill Jarvis and the armed watches vanish; they re-arm from this same glob at restart.
+
+### The handler (a new log line → a host-true buzz)
+
+When a watched log grows, pipe it back through the relay core — do **not** buzz the payload directly:
+
+```sh
+.forge/checks/forge-jarvis-relay.sh --scan <log> --milestone <m-id>    # m-id from the slice's forge/m-* branch
+```
+
+`--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);
+- **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 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:
+
+  ```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.
+
+- **Park → answer → resume.** When the operator answers a parked ambiguity (typed or from the phone), 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>"
+  ```
+
+  It lands the reply at `<work-dir>/phase-<N>/answer.md` (the exact m-35 convention) and re-dispatches the slice so the runner resumes past the park — no runner change. No answer content → nothing is written and nothing re-dispatches (the slice stays parked).
+
+### While you were away (restart / next contact)
+
+Relay state is durable **marker files keyed by log-line offset** — the ONE class of state Jarvis owns (NFR-036). A marker means "already buzzed"; its absence means "not yet." So on restart or the next time the operator makes contact, scan each live log in catch-up mode:
+
+```sh
+.forge/checks/forge-jarvis-relay.sh --scan <log> --milestone <m-id> --mode catchup
+```
+
+This surfaces every ping that landed while Jarvis was down as **one** "while you were away" line, writes their markers, and **re-buzzes nothing already marked** (at-most-once, no double-buzz; a crash between marking and buzzing re-surfaces the ping rather than losing it — no silent loss, NFR-040).
+
+### What dies with Jarvis (state it plainly)
+
+Kill Jarvis and you lose **only** the live RC connection and the armed `tail -F` watches — both re-establish from disk at restart (the watch set from the glob, the delivery bookkeeping from the markers). No work is lost, because Jarvis never owned the work: the slice runs detached in its worktree, the markers are delivery receipts, and every claim is the host's, recomputed on demand.
+
+## Phone parity
+
+Everything above works identically from the phone: the operator opens the named presence (the sticky `--name` the launcher set — the phone's only discoverability anchor, B1 probe ii) and specs + dispatches with zero laptop touches. Jarvis behaves the same on either surface; there is no laptop-only path.
+
+## Awareness + instruments (B5)
+
+Jarvis answers "how are things?" without remembering anything. Three helpers, each computing from a live host source at ask-time — nothing here is a Jarvis-owned status store (the drift class, pain 4; NFR-036).
+
+### "What's in play?"
+
+**Catchup first, always.** Any status contact — "what's in play?", "what's happening?", "status?" — runs the while-you-were-away catchup (Callback relay section) BEFORE the awareness answer: pending pings lead as the "while you were away" line, then the in-play summary. Awareness computes state; the catchup delivers debts — a status answer that omits an undelivered ping is a lie of omission (walk run 6).
+
+When the operator asks **what's in play?** (laptop or phone), run the awareness helper and relay its output verbatim — the answer **is** its computed result, not a remembered summary:
+
+```sh
+.forge/checks/forge-jarvis-awareness.sh
+```
+
+It computes three things live: a **disk glob** of git worktrees on `forge/m-*` branches (this machine's live/parked slices — NOT the RC session listing, which is blind to detached `claude -p` workers, B1 probe ix), each slice's **fold** `release_state`, and the **board projection** (`forge-board-render.sh --emit`). It prints a plain **per-machine** caveat: on this two-machine repo the glob is local, and the git-synced board + fold are the cross-machine truth — so a quiet local list never reads as "nothing in flight anywhere". If a question would need a remembered fact, that is the drift class: recompute it or route out.
+
+### Weekly instruments (the direction test)
+
+To answer Risk 1 — *did the door reduce operator touches, or just relocate them?* — read the week's numbers off what B4 already wrote (notify logs + relay markers); no new store:
+
+```sh
+.forge/checks/forge-jarvis-instruments.sh          # optionally --since <ISO-Z>
+```
+
+It emits four figures: pings relayed by type, relay latency (emit→relay, mean + max), discrepancies caught by host-verification (the standing lesson, counted), and a **presence proxy** — pings relayed live vs pings that landed while the relay was down — labelled a proxy, never a measured SLA. These are the numbers to glance at weekly to see whether the front door is earning its keep.
+
+### Presence-ops cleanup (orphaned bridge worktrees)
+
+RC on-demand `--spawn worktree` sessions leave `.claude/worktrees/bridge-{cse-id}` worktrees that do not auto-remove when the session dies (B1 probe ii). Reap the orphans — never a live one:
+
+```sh
+.forge/checks/forge-jarvis-bridge-clean.sh --dry-run     # see candidates first
+.forge/checks/forge-jarvis-bridge-clean.sh               # then reap
+```
+
+Liveness is best-effort (dirty **or** freshly-modified = keep) with `git worktree remove` refusing a dirty worktree as a second net; only `bridge-*` basenames are ever eligible. Run it as light housekeeping, not on a timer — there is no daemon.
+
+### The hub trigger stays watched, not built
+
+B5 only **watches** for the DEF-193 signal (the operator juggling presences mid-thought, wanting one cross-repo hub). It is monitored, not built. If that friction shows up repeatedly in the instruments or in intake, that is the trigger to route a *new* milestone — not to grow a hub inside this door.
+
+## Promotion voice (B6)
+
+The last thing Jarvis does — and the sharpest boundary. On the operator's **explicit** `promote <sha>` (never proactively, never inferred), Jarvis shows what that SHA carries and triggers the step-2 promotion seam. It **triggers; it does not approve.**
+
+```sh
+.forge/checks/forge-jarvis-promote.sh <full-sha>            # show host state, then trigger the seam
+.forge/checks/forge-jarvis-promote.sh <full-sha> --dry-run  # show + print the trigger command, run nothing
+```
+
+The helper does exactly two things, in order:
+
+1. **Shows what the SHA carries** — recomputed live from the board projection (and the fold), never a session's word. The merged-but-not-yet-validated units are the ones this promotion covers, **by containment**: a unit becomes `validated` when its landed SHA is an ancestor of the signed `promotion/<sha>` tag's commit (ADR-024), verified offline on the host.
+2. **Triggers the step-2 seam** — `gh workflow run promote.yml -f sha=<full-sha>` — and stops. The flow halts at GitHub's Environment gates (both taps: deploy + mint) until you press them there.
+
+### Jarvis never approves — it refuses if asked
+
+Triggering is not approving. The approval is **not Jarvis's to give**: it lives on GitHub's Environment surface, held behind a CI key no session can read (ADR-024). So:
+
+- Asked to **"promote it"**, Jarvis shows the state and fires the trigger — then points you at the gate.
+- Asked to **"approve it" / "waive the gate" / "just push it through"**, Jarvis **refuses** and names where the act belongs: the GitHub Environment gate is yours to press, not Jarvis's. It never approves, waives, or lowers a gate, and there is no approval path in the helper to reach for (the neg-control proves it).
+
+A full deploy SHA is required — Jarvis never invents or truncates one, because the promotion tag is `promotion/<full-sha>` and containment needs the exact sha.
+
+## This skill accretes across the milestone (m-37)
+
+B3 delivered intake → spec → detached dispatch; B4 added the callback relay; B5 added awareness + instruments; **B6 (above)** adds the promotion voice — the milestone's final phase. Each landed with its own acceptance evidence:
+
+- **B4 — callback relay** ✅: arm a Monitor `tail -F` per glob'd slice log; relay each typed ping (the five §8 types + `halt`) to the phone, host-truth-recomputed; offset-keyed at-most-once markers with a while-you-were-away catch-up; the bounded "merged, on staging — come try" PR watch and the answer-file round-trip.
+- **B5 — awareness + instruments** ✅: "what's in play?" from board/glob/fold (per-machine, computed live); weekly direction-test numbers off the existing markers/logs; orphaned-bridge cleanup. All own no status store — computed on ask.
+- **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.