forge-orkes 0.25.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.25.0",
+  "version": "0.28.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/skills/initializing/SKILL.md

@@ -355,7 +355,38 @@ User selects per stack.
    - `.forge/state/index.yml` — regenerate via the `forge` **Rollup** from the milestone file (do not hand-write the registry). It will derive `status: not_started` for milestone 1.
    - `.forge/state/desire-paths/` — create the (empty) directory for append-only observations.
 6. Templates as needed
-7. **State-sync commit**: `git add .forge/` then `git commit -m "chore(forge): initialize forge state"` (scoped; never `git add .`) — so the new project's state is in git from the start.
+7. **Track Forge product files in `.gitignore`.** Forge installs into `.claude/` (skills, agents, hooks, `settings.json`) — these are *product files*, not per-machine config, and **must be tracked in git** for two reasons: (a) `/forge` commands only exist in checkouts that have `.claude/skills/`, so a git worktree with `.claude/` fully ignored has no `/forge`; (b) M10 worktrees inherit hooks via tracked files (`.claude/hooks/*.sh`) — an ignored `.claude/` silently disables them (see ADR-007 + ADR-010 "related concerns").
+
+   Detect the failure mode + apply the carve-out:
+
+   ```bash
+   if grep -qE '^[[:space:]]*\.claude/?[[:space:]]*$' .gitignore 2>/dev/null && \
+      ! grep -qE '^![[:space:]]*\.claude/(skills|agents|hooks)' .gitignore; then
+     echo "[Forge] .gitignore ignores .claude/ wholesale — Forge worktrees won't have /forge."
+   fi
+   ```
+
+   Then **replace** any bare `.claude/` rule (or **append** if no `.gitignore` exists) with the recommended carve-out:
+
+   ```gitignore
+   # Claude Code — track Forge product files, ignore per-machine + scratch
+   .claude/*
+   .claude/.DS_Store
+   !.claude/settings.json
+   !.claude/skills/
+   !.claude/agents/
+   !.claude/hooks/
+   !.claude/commands/
+   .claude/settings.local.json
+   .claude/projects/
+   .claude/worktrees/
+   ```
+
+   `settings.local.json` (per-machine permission allowlists), `projects/` (Claude Code conversation transcripts), and `worktrees/` (app-managed scratch) **must stay ignored** — they're private/per-machine, not product.
+
+   **Confirm with the user first** in brownfield (this edits a user-owned file). In greenfield with no existing `.gitignore`, write it directly. Re-run is idempotent — the carve-out lines `grep` to themselves.
+
+8. **State-sync commit**: `git add .gitignore .claude/settings.json .claude/skills/ .claude/agents/ .claude/hooks/ .forge/` then `git commit -m "chore(forge): initialize forge state + track product files"` (scoped; never `git add .`) — so the new project's state and Forge product files are both in git from the start.
 
 *"Initialized. Ready?"*
 

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

@@ -79,6 +79,7 @@ Tag every finding:
 
 For independent topics, research simultaneously:
 - Spawn separate research agents per topic with focused scope
+- **Pass `model` param** from `project.yml` model routing (`models.skills.researching` → `models.default` → parent). Display: *"Spawning researchers with model: {model} (from {source})"*. Subagents don't inherit skill routing — without the param they run on the parent (often opus), defeating the cost intent.
 - Collect and synthesize results
 
 Never research sequentially when topics are independent.

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

@@ -350,7 +350,7 @@ Idempotent: a backlog with no terminal items and all-canonical statuses is left
 
 ### Route
 
-**HEALTHY/WARNINGS (accepted):** set `current.status: complete` in `milestone-{id}.yml`, then regenerate `index.yml` via the `forge` **Rollup** (do not hand-edit index). *"Milestone [{name}] complete. {N} backlog items."* Beads: `bd complete`.
+**HEALTHY/WARNINGS (accepted):** set `current.status: complete` in `milestone-{id}.yml` (only after the Human Verification Gate in Phase Handoff is satisfied), then regenerate `index.yml` via the `forge` **Rollup** (do not hand-edit index). *"Milestone [{name}] complete. {N} backlog items."* Beads: `bd complete`.
 
 **CRITICAL:** Don't complete. A) Fix->`planning` fix mode->re-verify->re-review. B) Accept risk->doc in report->complete.
 
@@ -400,8 +400,9 @@ If the milestone's phases produced `contract.md` files (planning Step 6.1 Tier 1
 ## Phase Handoff
 
 1. Confirm report + backlog
-2. **Run promoted-milestone completion hook** (above) if `milestone.origin` set
-3. **Run Contract Landing** (above) for any cross-layer phases — fold ratified contracts into their ADRs
-4. Set `current.status: complete` and `current.completed_at: "<ISO 8601 timestamp>"` in `milestone-{id}.yml`, then regenerate `index.yml` via the `forge` **Rollup**
-5. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after reviewing — m{N} complete"` (scoped; never `git add .`).
-6. *"Milestone [{name}] complete. Report: `.forge/audits/milestone-{id}-health-report.md`. {N} backlog items. `/forge` or backlog."*
+2. **Human Verification Gate (hard block)** — Read `current.human_verified` from `milestone-{id}.yml`. If **absent/null** → **do not complete the milestone.** Code-clean + review-clean is not enough to close (FORGE.md → Human Verification Gate). The milestone needs an explicit human sign-off, normally captured by `verifying`. Either route the user back to verify (then re-review) or capture the sign-off / recorded override here and write `current.human_verified` before proceeding. A recorded override (`method: override`) satisfies this check but **must** be surfaced in the health report. Never silently complete past an unset gate.
+3. **Run promoted-milestone completion hook** (above) if `milestone.origin` set
+4. **Run Contract Landing** (above) for any cross-layer phases — fold ratified contracts into their ADRs
+5. Set `current.status: complete` and `current.completed_at: "<ISO 8601 timestamp>"` in `milestone-{id}.yml`, then regenerate `index.yml` via the `forge` **Rollup**
+6. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after reviewing — m{N} complete"` (scoped; never `git add .`).
+7. *"Milestone [{name}] complete. Report: `.forge/audits/milestone-{id}-health-report.md`. {N} backlog items. `/forge` or backlog."*

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

@@ -42,6 +42,7 @@ Read: .github/workflows/* → CI config (ci-check mode, analyst CI sub-check)
 
 1. Spawn tester agent via Agent tool, mode = `analyst`:
    - Pass: milestone id + name, scope paths, stack summary from project.yml
+   - **Pass `model` param** from `project.yml` model routing (`models.skills.testing` → `models.default` → parent). Display: *"Spawning tester (analyst) with model: {model} (from {source})"*
    - Agent scans test files, runs suite with traces/retries, greps anti-patterns
 2. Agent writes `.forge/testing/suite-health.md`:
    - **Coverage Gaps** — untested surfaces, missing layers
@@ -106,6 +107,7 @@ Refusal message wording is contract (NFR-009 requires story ID + exact missing f
    - If project has existing test runner, match it. Don't introduce a second.
 3. Spawn tester agent via Agent tool, mode = `author`:
    - Pass: milestone id + name, layer, runner, scope paths, stack summary
+   - **Pass `model` param** from `project.yml` model routing (`models.skills.testing` → `models.default` → parent). Display: *"Spawning tester (author) with model: {model} (from {source})"*
    - Agent scaffolds tests following baked flake-resistant rules (see tester.md)
 4. Agent commits atomically per executor conventions.
 

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

@@ -266,6 +266,47 @@ No-op guarantee: detection exits clean (no prompt) when the backlog is absent, u
 
 `upgrading` never edits the backlog directly — migration runs via `quick-tasking`.
 
+### Pre-0.28.0 fully-ignored `.claude/`
+
+Run from project root:
+
+```bash
+F=.gitignore
+[ -f "$F" ] || exit 0
+# bare ".claude/" or ".claude" rule (no negation lines un-ignoring product files)
+if grep -qE '^[[:space:]]*\.claude/?[[:space:]]*$' "$F" \
+   && ! grep -qE '^![[:space:]]*\.claude/(skills|agents|hooks|settings\.json)' "$F"; then
+  echo "broad-ignore"
+fi
+```
+
+If the script prints `broad-ignore`, surface:
+
+```
+.claude/ fully ignored — Forge worktrees + hooks silently break (Forge 0.28.0)
+─────────────────────────────────────────────────────────────────────────────
+Your .gitignore ignores all of `.claude/` without a carve-out. That means:
+  • git worktrees (Forge or the app's) have no `.claude/skills/`, so `/forge`
+    is missing — typing `/forge` in a worktree prints "Unknown command".
+  • M10 worktrees come up with no hooks (forge-claim-check, branch-guard,
+    session-id) — coordination + ADR-008 protection are silently disabled.
+
+These are PRODUCT files, not per-machine config. The fix is a narrow
+carve-out: track skills/agents/hooks/settings.json; keep settings.local.json,
+projects/, worktrees/ ignored.
+
+A migration guide is available at: .forge/migrations/0.28.0-worktree-root.md
+(canonical: https://github.com/Attuned-Media/forge/blob/main/docs/migrations/0.28.0-worktree-root.md)
+
+Apply the carve-out now? (yes/no/show guide)
+```
+
+- **yes** → invoke `quick-tasking` skill with the migration guide as the task (edit `.gitignore` in place, `git rm -r --cached .claude/` to clear the ignore-cache, stage `.gitignore` + the four product trees, commit `chore(forge): track .claude/ product files`). The skill MUST confirm with the user before staging anything outside the four product trees.
+- **show guide** → read and display the file, then re-ask
+- **no** → note in upgrade report. The framework keeps working in the main checkout but worktree-mode sessions (M10 / Claude Desktop folder-open) will be missing `/forge` and Forge hooks until migrated.
+
+This is a Forge-product-tracking concern, not a state migration — `upgrading` never edits user `.gitignore` directly. Migration runs via `quick-tasking`.
+
 ### Future migrations
 
 Add new detection blocks here for each Forge version that changes file layout. Pattern:

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

@@ -236,6 +236,19 @@ Items that can't be verified automatically (visual appearance, real-time behavio
 3. [ ] External: Email sends correctly via SendGrid
 ```
 
+## Human Verification Gate (close precondition)
+
+Code-level PASS is necessary but **not sufficient** to close a milestone. Before handing off, capture an explicit human sign-off — this is the hard gate that `reviewing`-complete and `orchestrating`-teardown both check (see FORGE.md → Human Verification Gate). It is a precondition, not a peer option: never present milestone close / teardown as an alternative to running this.
+
+Run on a PASSED verdict (and after any **HUMAN VERIFICATION NEEDED** items are resolved):
+
+1. Surface what the human should confirm — the Observable Truths, any "Human Verification Items", and any milestone-specific manual check (device session, visual pass, real-device / e2e walk).
+2. Prompt explicitly: *"Code verification passed. Have you verified the work yourself (device session / visual / e2e walk)? This is required before the milestone can close. [verified | not yet | close without verifying]"*
+3. Record the response in `current.human_verified` in `.forge/state/milestone-{id}.yml`:
+   - **verified** → `{at: "<ISO 8601>", method: "<how they verified>", notes: "<optional>"}`
+   - **not yet** → leave `human_verified` unset. **Do NOT route to reviewing** — the milestone cannot close. Tell the human what's outstanding and stop. Re-run this gate after they've done it.
+   - **close without verifying** → recorded override: `{at: "<ISO 8601>", method: "override", override: true, reason: "<required free text>"}`. Note the override in the verification report. Satisfies the gate but is flagged downstream.
+
 ## Re-Verification Mode
 
 After gap closure:
@@ -289,9 +302,10 @@ Only suggest at 3+ occurrences. One-off issues are noise.
 
 After PASSED verdict:
 
-1. **Persist** — Confirm verification report documented, desire-path files written to `.forge/state/desire-paths/`
-2. **Update state** — Set `current.status` to `reviewing` in `.forge/state/milestone-{id}.yml`
-3. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after verifying — m{N} {phase-name}"` (scoped; never `git add .`).
-4. **Recommend clear:** *"State synced. `/clear` then `/forge` for reviewing."*
+1. **Human Verification Gate** — capture explicit sign-off and write `current.human_verified` (see "Human Verification Gate" above). If the human answers **not yet** → STOP here; do not advance to reviewing. The milestone stays open until sign-off (or a recorded override) exists.
+2. **Persist** — Confirm verification report documented, desire-path files written to `.forge/state/desire-paths/`
+3. **Update state** — Set `current.status` to `reviewing` in `.forge/state/milestone-{id}.yml`
+4. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after verifying — m{N} {phase-name}"` (scoped; never `git add .`).
+5. **Recommend clear:** *"State synced. `/clear` then `/forge` for reviewing."*
 
 If GAPS found, route back to planning in gap-closure mode. Context clear applies after re-verified PASSED verdict.

package/template/.forge/FORGE.md

@@ -51,8 +51,8 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | Architectural decisions | `architecting` | Full |
 | Break work into tasks with gates | `planning` | Standard, Full |
 | Build with deviation rules + atomic commits | `executing` | All |
-| Prove work delivers on goals (+ M9 e2e validation gate when `e2e:true` stories present) | `verifying` | Standard, Full |
-| Audit health + catalog refactoring (+ M9 e2e soft-cap, orphan-test, flake-rate audits) | `reviewing` | Standard, Full |
+| Prove work delivers on goals (+ M9 e2e validation gate when `e2e:true` stories present; captures the Human Verification Gate sign-off) | `verifying` | Standard, Full |
+| Audit health + catalog refactoring (+ M9 e2e soft-cap, orphan-test, flake-rate audits; hard-blocks completion on the Human Verification Gate) | `reviewing` | Standard, Full |
 | Small scoped fix | `quick-tasking` | Quick |
 | UI with design system | `designing` | When UI |
 | Security review | `securing` | When auth/data/API |
@@ -102,6 +102,8 @@ models:
 **Precedence:** `skills.X` → `default` → parent model.
 **All advisory** — forge displays expected model at each transition, suggests `/model` on mismatch. Review gate logs model used. Cannot auto-switch.
 
+**Subagent inheritance.** When a skill spawns subagents via the Agent tool (parallel research, fresh-context reviewers, executor fan-out, tester author/analyst, etc.), the skill MUST pass the resolved `model` param explicitly. Subagents do NOT inherit skill-level routing automatically — without the param they run on the parent session's model, defeating the routing intent. Resolve using the same precedence chain (`models.skills.{skill}` → `models.default` → parent) and surface it: *"Spawning {role} with model: {model} (from {source})"*.
+
 ## Agents
 
 | Agent | Role | Tools | When |
@@ -145,7 +147,7 @@ State lives in `.forge/`:
 **Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions. Can be deferred (frozen in place) or archive-deleted.
 `index.yml status` gates routing: `not_started | active | deferred | complete`.
 **Format**: YAML for machine state, Markdown for human content.
-**`current.status` is authoritative.** Complete only at `current.status == complete`. 100% tasks ≠ done — still needs verifying + reviewing.
+**`current.status` is authoritative.** Complete only at `current.status == complete`. 100% tasks ≠ done — still needs verifying + reviewing + a recorded human sign-off (`current.human_verified` — see Verification Gates → Human Verification Gate).
 
 ### State Commit Protocol
 
@@ -211,6 +213,16 @@ verification:
 - Empty commands = no gate (opt-out)
 - `verification.e2e_soft_cap` (default 10) — advisory cap on `e2e:true` stories per milestone surfaced by the `reviewing` skill. Soft — never blocks.
 
+### Human Verification Gate (close precondition)
+
+**No milestone reaches `complete` and no orchestration worktree is torn down until a human has explicitly signed off** — recorded as `current.human_verified` in `milestone-{id}.yml`. Code-level verification (tests, lint, type-check, the 3-level goal-backward pass) is necessary but **never sufficient** to close a milestone. A human must confirm the work in whatever form fits the milestone — device session, visual check, e2e walk, smoke test ("of some sorts").
+
+- **Captured** by `verifying` — after the verdict it prompts for explicit sign-off and writes `current.human_verified: {at, method, notes}`. If the human can't verify yet (e.g. a device session is still pending), the field stays unset and downstream close blocks.
+- **Enforced (hard block)** at both close points — `reviewing` refuses to set `current.status: complete`, and `orchestrating` Step 5 refuses teardown, unless `current.human_verified` is present.
+- **Recorded override** is the only bypass. A human may explicitly close without verifying, but the skill writes `human_verified: {method: override, override: true, reason}` and surfaces it in the report. Silent close is impossible — an agent must **never** present milestone close / orchestration teardown as a peer alternative to "do the verification". The verification is a precondition, not an option.
+
+Lazy migration: milestones with no `human_verified` field (pre-0.27.0) simply hit the prompt on their next close transition; already-`complete` milestones are never re-gated.
+
 ## Beads Integration (Optional)
 
 With Beads installed: `bd prime` (session context), `bd ready` (unblocked tasks), `bd complete` (update deps), `bd compact` (summarize old). Without Beads, `.forge/state/` + Session Memory suffice.

package/template/.forge/migrations/0.28.0-worktree-root.md

@@ -0,0 +1,168 @@
+# Migration Guide: Repo-scoped worktree root (Forge 0.28.0)
+
+Applies to projects using M10 orchestration (experimental). Two related concerns ship under one version:
+
+1. **Worktree dir default changes** from a shared `../forge-worktrees/` to a per-repo `../<repo>-worktrees/` (see [ADR-010](../decisions/ADR-010-repo-scoped-worktree-root.md)). Live worktrees keep working; only new ones use the new default.
+2. **`.gitignore` carve-out for Forge product files** — repos that ignore `.claude/` wholesale silently break worktree mode (`/forge` is "Unknown command" inside any worktree). 0.28.0 ships detection + a guided fix.
+
+If you don't use M10, the worktree-dir change has no effect. If your `.gitignore` is broadly ignoring `.claude/`, the second part still applies (the same gap also affects Claude Desktop's native worktree switcher).
+
+## Part 1 — Worktree dir default
+
+### What changed
+
+Before:
+
+```bash
+git worktree add ../forge-worktrees/${anchor} main          # shared, cwd-resolved
+```
+
+After:
+
+```bash
+# orchestration.worktree_root from .forge/project.yml, default ../<repo>-worktrees
+# Relative paths resolve against the REPO ROOT (not shell cwd). Absolute + leading ~ honored.
+git worktree add ${wt_root}/${anchor} main
+```
+
+The resolved absolute path is recorded in `lifecycle.worktree_path` and read verbatim by teardown + crash-recovery — so the config knob is forward-looking, not retroactive.
+
+### Detection
+
+```bash
+# Are any of your active milestones pointing at the old shared dir?
+grep -rE '^\s*worktree_path:.*forge-worktrees' .forge/state/ 2>/dev/null | head
+```
+
+Matches = pre-0.28.0 worktrees still in flight. **Leave them alone** — they keep working off their recorded path. Only **new** worktrees pick up the new default.
+
+### Migration
+
+**Do nothing.** This is a new-worktree-only change. Future orchestration runs in this repo will create their worktrees in `../<repo>-worktrees/<anchor>` instead of `../forge-worktrees/<anchor>`. Existing worktrees keep functioning; their `lifecycle.worktree_path` is honored.
+
+### Opting back into the old layout
+
+If you want the old behavior (shared dir, e.g. because you've already got tooling pointed at `../forge-worktrees/`), set in `.forge/project.yml`:
+
+```yaml
+orchestration:
+  worktree_root: "../forge-worktrees"   # relative to repo root
+```
+
+### Other layout choices the new key enables
+
+```yaml
+orchestration:
+  worktree_root: "~/.forge/worktrees/<this-repo>"     # central home dir
+  # or
+  worktree_root: "../wt/<this-repo>"                  # shared dir, repo-namespaced subfolder
+  # or
+  worktree_root: "/abs/path/to/somewhere"             # absolute
+```
+
+**Do not** point this inside the working tree (e.g. `.worktrees/`) — file watchers, language-server indexers, test discovery, and bundlers commonly recurse into the second checkout regardless of `.gitignore`. ADR-010 has the longer analysis.
+
+### Relocating a live worktree (only if you really need to)
+
+Use `git worktree move` — it updates the gitdir pointer. A bare `mv` leaves the pointer stale and the worktree unusable.
+
+```bash
+# from the repo root
+git worktree move ../forge-worktrees/m-9-abc12345 ../<repo>-worktrees/m-9-abc12345
+# then update the recorded path in milestone state:
+#   .forge/state/milestone-9.yml  →  lifecycle.worktree_path
+```
+
+Confirm the worktree opens cleanly (`cd <new-path> && git status`) before editing state. **Don't relocate a worktree that's an active orchestration run** without checking with the running session first — its claim state references that path.
+
+## Part 2 — `.gitignore` carve-out for Forge product files
+
+### Why this matters
+
+Forge installs into `.claude/` (skills, agents, hooks, `settings.json`). Many Claude Code starters add `.claude/` to `.gitignore` wholesale. Consequences:
+
+- **`/forge` is "Unknown command:" in any git worktree.** Worktrees only check out *tracked* files. With `.claude/` fully ignored, `.claude/skills/forge/` doesn't exist in worktrees, so the slash command isn't loaded. Same applies to Claude Desktop's native worktree switcher.
+- **M10 worktrees come up with no hooks.** `forge-claim-check.sh`, `forge-branch-guard.sh`, `forge-session-id.sh` all live in `.claude/hooks/` — ignored = absent = silently disabled. ADR-007 / ADR-008 protection are off.
+
+The fix: track product files, keep per-machine/scratch files ignored.
+
+### Detection
+
+`upgrading` runs this automatically; you can run it by hand too:
+
+```bash
+F=.gitignore
+[ -f "$F" ] || exit 0
+if grep -qE '^[[:space:]]*\.claude/?[[:space:]]*$' "$F" \
+   && ! grep -qE '^![[:space:]]*\.claude/(skills|agents|hooks|settings\.json)' "$F"; then
+  echo "broad-ignore — apply the carve-out below"
+fi
+```
+
+### Migration
+
+Replace any bare `.claude/` rule with this carve-out:
+
+```gitignore
+# Claude Code — track Forge product files, ignore per-machine + scratch
+.claude/*
+.claude/.DS_Store
+!.claude/settings.json
+!.claude/skills/
+!.claude/agents/
+!.claude/hooks/
+!.claude/commands/
+.claude/settings.local.json
+.claude/projects/
+.claude/worktrees/
+```
+
+Then refresh git's view of the directory:
+
+```bash
+git rm -r --cached .claude/ 2>/dev/null    # drop the wholesale-ignored cache
+git status .claude/                        # eyeball what's now untracked
+
+# Stage only the four product trees — explicitly, never `git add .claude/`
+git add .gitignore \
+        .claude/settings.json \
+        .claude/skills/ \
+        .claude/agents/ \
+        .claude/hooks/
+
+# Sanity check — no per-machine files snuck in
+git status                                 # settings.local.json, projects/, worktrees/ should still be untracked-and-ignored
+git diff --cached --stat | head
+
+git commit -m "chore(forge): track .claude/ product files (skills, agents, hooks, settings)"
+```
+
+After the commit lands on `main`, every **new** worktree (Forge's or the app's) inherits `/forge` and the hooks. Existing worktrees will see them on their next pull/rebase.
+
+### What stays ignored, and why
+
+| Path | Why it stays ignored |
+|---|---|
+| `.claude/settings.local.json` | Per-machine permission allowlists. Build-specific. |
+| `.claude/projects/` | Claude Code conversation transcripts — privacy + repo bloat. |
+| `.claude/worktrees/` | App-managed scratch worktrees — per-machine ephemera. |
+| `.claude/.DS_Store` | macOS metadata. |
+| (project-local) `.mcp.json` if you already ignore it | Per-machine MCP wiring. |
+
+### One-shot vs guided
+
+`upgrading` detects this pattern and offers a `quick-tasking` migration that applies the change above for you. Either path works — by-hand is fine if you want to eyeball each step. The migration is **never auto-applied**; `.gitignore` is user-owned.
+
+## Validation
+
+After the worktree-root change ships and you've reopened a session:
+
+- `cat .forge/project.yml` includes the `orchestration:` block (uncomment `worktree_root` only if you want a non-default value).
+- Run an M10 milestone — confirm the new worktree appears at `../<your-repo>-worktrees/m-{id}-{session_id}/`.
+- `cat .forge/state/milestone-{id}.yml | grep worktree_path` shows an **absolute** path, not the relative input.
+
+After the gitignore migration:
+
+- `git ls-files .claude/skills/forge/SKILL.md` returns the file.
+- Open or create a worktree, `cd` into it, run `/forge` — the command exists.
+- (If M10) Open a new orchestrating session in the worktree — `.session-id` is written, hooks fire.

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

@@ -91,6 +91,16 @@ models:
     debugging: sonnet                  # Investigation needs solid reasoning
     discussing: sonnet                 # Conversation needs natural fluency
 
+orchestration:                       # M10 multi-agent orchestration (experimental). Only consulted when M10 is installed.
+  # auto: true                         # false = never auto-route Standard/Full through orchestrating (install = consent; set false to opt out).
+  # worktree_root: "../<repo>-worktrees"  # Where Forge worktrees live. Default: ../<repo-basename>-worktrees (per-repo sibling — see ADR-010).
+                                          # Relative paths resolve against the REPO ROOT (not shell cwd). Absolute paths and a leading ~ are honored.
+                                          # Editing only affects newly created worktrees; live worktrees keep their recorded lifecycle.worktree_path.
+                                          # Common overrides:
+                                          #   ~/.forge/worktrees/<repo>    — central home dir, keeps the parent dir of the repo clutter-free
+                                          #   ../wt/<repo>                 — shared dir with per-repo subfolder
+                                          # Do NOT point this inside the repo working tree (file watchers + indexers will recurse into the worktree).
+
 risks:                              # What could go wrong?
   - risk: ""
     mitigation: ""

package/template/.forge/templates/state/milestone.yml

@@ -22,6 +22,21 @@ current:
   status: not_started                  # not_started | researching | discussing | planning | executing | verifying | reviewing | complete
   completed_at: null                    # ISO 8601 timestamp — set when status transitions to complete
   last_updated: null                    # ISO 8601 — set at each transition; rolled up into index.yml registry for resume ordering
+  human_verified: null                  # Human Verification Gate record — REQUIRED before status can become `complete`
+                                         # or an orchestration worktree can be torn down (FORGE.md → Human Verification Gate).
+                                         # Code-level PASS is necessary but never sufficient. Set by the `verifying` skill
+                                         # when a human signs off (device session, visual check, e2e walk — form is open).
+                                         # Shape when set:
+                                         #   human_verified:
+                                         #     at: "<ISO 8601>"           # when the human confirmed
+                                         #     method: "device-session"   # free text: how they verified
+                                         #     notes: ""                   # optional free text
+                                         # Recorded-override escape hatch (satisfies the gate, but flagged downstream):
+                                         #   human_verified:
+                                         #     at: "<ISO 8601>"
+                                         #     method: "override"
+                                         #     override: true
+                                         #     reason: "headless milestone — no human-observable surface"
 
 # NO stored progress block. Progress percent is DERIVED on read, never stored.
 # The forge skill computes it from genuinely-maintained signals: