forge-orkes 0.26.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.26.0",
+  "version": "0.29.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/discussing/SKILL.md

@@ -42,13 +42,23 @@ Never accumulate decisions in working memory. Never batch writes to convergence.
 
 ### Write Protocol
 
+`context.md` is **shared mutable** state per FORGE.md State Ownership — writes follow two structural rules:
+- **Scope to your milestone's block.** Different milestone blocks → git merges cleanly across worktrees.
+- **Append-only within a block.** When superseding an older decision, *strike through* (`~~old decision~~`) and append the new line below — never rewrite in place. Same-line concurrent edits become impossible by construction; reading the history of a decision becomes possible by inspection.
+
 **On first decision of the session:**
 - Check if `.forge/context.md` exists. If not → create it from `.forge/templates/context.md`
 - Add a milestone heading inside `## Locked Decisions`: `### M{id} — {name} (drafting)` (use "M?" if no milestone yet)
+- **Cross-tree liveness check (informational).** If editing an existing block for milestone `{id}`, run `git worktree list --porcelain | awk '/^branch / && $2 ~ /refs\/heads\/forge\/m-'"$id"'(-|$)/ {print}'`. Any hit means m{id} is **live in another worktree** — surface one line: *"m{id} is live in worktree at `{path}`. Edits land cleanly on main but won't be visible to that worktree until it rebases or pulls."* Proceed with the write — main is often the canonical author of `context.md`, this is a heads-up, not a block.
 
 **On each confirmed decision:**
 - Append under the milestone heading: `- **[Topic]**: [Decision]. Reason: [Why]`
 
+**On superseding a prior decision (in your own milestone's block):**
+- Find the original line. Wrap it in `~~ ~~` (markdown strikethrough). DO NOT delete it.
+- Append the new decision on a new line below it: `- **[Topic]**: [Decision]. Reason: [Why]. Supersedes ~~prior on {date}~~.`
+- Why: shared-mutable append-only rule (FORGE.md State Ownership). Decisions stay readable as history; concurrent writes from another worktree on a different bullet can't conflict with this one.
+
 **On deferred ideas** (user says "not now" / "later" / "skip"):
 - Append to `## Deferred Ideas` immediately: `- [Idea] — Deferred because: [reason]`
 

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

@@ -9,6 +9,33 @@ Entry point. Detect tier, route skills, manage transitions. New projects → ini
 
 ## Step 1: Read State
 
+**Preflight (multi-tree visibility) — run before everything in this section.**
+
+The presence of live Forge worktrees changes the meaning of "which milestone am I editing" — the operator needs to see the picture before any state edit. Cheap to compute, free if there's nothing to show.
+
+```bash
+# This session's checkout — main or a worktree? --git-dir == --git-common-dir → main; differ → linked worktree.
+this_dir=$(git rev-parse --git-dir 2>/dev/null) || exit 0
+common_dir=$(git rev-parse --git-common-dir)
+in_main_checkout=$([ "$this_dir" = "$common_dir" ] && echo true || echo false)
+
+# Forge worktrees = branch matches forge/m-*
+git worktree list --porcelain 2>/dev/null \
+  | awk '
+      /^worktree /  { path=$2 }
+      /^branch /    { br=$2; if (br ~ /refs\/heads\/forge\/m-/) print path " " br }
+    '
+```
+
+**If `in_main_checkout: true`** AND any Forge worktrees are reported:
+- Surface them at the top of the boot output, one line each: *"m{id} is live in worktree `{path}` on branch `{branch}`. Edits to its milestone state belong there; shared-doc edits here (`context.md`, `refactor-backlog.yml`) won't be visible to it until it rebases or pulls."*
+- This is informational — `forge` continues to Rollup + selection. The operator now knows. (See FORGE.md State Ownership for the full taxonomy.)
+
+**If `in_main_checkout: false`** (this session is itself a worktree) AND `forge.worktree_rebase_check: true` in `.forge/project.yml` (default `false` — opt-in):
+- Diff `.forge/` between this worktree's `HEAD` and `origin/main` (or `main` if no remote), restricted to the **shared-mutable** + **stable-shared** files per the FORGE.md taxonomy (`context.md`, `refactor-backlog.yml`, `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `requirements/m{N}.yml`).
+- Any differ → surface: *"`{file}` has changed on main since this worktree branched. Pull just this file (`git restore --source main -- {file}`), rebase, or skip?"* — operator decides.
+- Setting absent or `false` → no-op.
+
 ### 1.0 State Rollup (index.yml is derived)
 
 `index.yml` is a **derived registry** — regenerate it from the milestone files before reading, and after any milestone CRUD (promote/defer/resume/delete). **Never hand-edit `index.yml`.**

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

@@ -312,6 +312,12 @@ Deferred issues triage: If `.forge/deferred-issues.md` has `status: pending` ite
 
 ### Backlog
 
+`refactor-backlog.yml` is **shared mutable** state per FORGE.md State Ownership — many milestones append over time. Two rules apply:
+- **Items carry `milestone:` scoping** (already enforced by the schema below) — concurrent appends from different milestones touch different items, so git merges cleanly.
+- **Existing items are append-only** in spirit: change `status:` and add `completed:`/`deferred_at:` rather than rewriting the item's body. Compaction-on-write (below) handles physical relocation of terminal items.
+
+**Cross-tree liveness check (informational).** Before writing, run `git worktree list --porcelain | awk '/^branch / && $2 ~ /refs\/heads\/forge\/m-/ {print}'`. Any non-empty output means another milestone is live in a worktree — surface one line: *"{N} other Forge milestone(s) live in worktrees ({list}). Backlog appends here land cleanly on main but won't be visible to those worktrees until they rebase."* Proceed with the write — reviewing on main is the canonical author. (Two reviewing sessions writing in parallel from different worktrees rely on the milestone-scoped append rule above, not on this check.)
+
 Read `.forge/refactor-backlog.yml`. Next ID = max + 1. Append:
 
 ```yaml
@@ -350,7 +356,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 +406,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
 
@@ -160,9 +162,38 @@ State-sync commits are separate from per-task code commits (which stay atomic du
 
 ### State Ownership (multi-worktree safety)
 
-- `state/milestone-{id}.yml` is the **single source of truth**; exactly one agent owns it at a time.
+`.forge/` is **code-like**: it branches with the repo, syncs via git, atomic-commits with the work it describes. Worktrees get their own `.forge/` checkout by construction — that's not configuration, that's git. The framework's job is to specify how each *kind* of `.forge/` file behaves under that model.
+
+**Every `.forge/` artifact falls into one of five sharing classes.** The class determines the write rule across worktrees:
+
+| Class | Files | Write rule |
+|---|---|---|
+| **Single-owner mutable** | `state/milestone-{id}.yml`, `phases/milestone-{id}/`, `research/milestone-{id}.md` | Exactly one writer at a time — the worktree (or main session) currently driving that milestone. **Other worktrees never touch it**, not even to read-then-write — they pull from main if they need it. |
+| **Derived** | `state/index.yml` | Never hand-edited. Regenerated by Rollup 1.0 from `milestone-*.yml`. Only the main/orchestrator session runs rollup. |
+| **Append-only shared** | `releases.yml` (version reservations), `state/desire-paths/*` (one file per observation) | Many writers OK; structure prevents collision. `releases.yml` uses the Version Reservation Protocol (append + commit + push before depending on the slot); desire-paths use distinct filenames so two writers never touch the same file. |
+| **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` (ID space `FR-`/`DEF-`/`NFR-` is globally shared even though each milestone owns its file) | Two rules: **(a) Write only to YOUR milestone's block.** Different milestone blocks → git merges cleanly. **(b) Within a block, append-only.** Locked decisions get *struck through* (`~~old~~`) rather than rewritten in place; new sub-bullets appended below existing ones. Same-line concurrent edits become impossible by construction. |
+| **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md` | Rarely changes after init. Canonical on main. Worktrees lag and pull on rebase. No special protocol — git handles it because the conflict surface is tiny. |
+
+**Cross-tree write awareness.** When a session edits a shared-mutable file's block whose milestone is **live in a different worktree** (e.g. main writes to `context.md`'s `## M9` block while m9 is running in a worktree), the edit lands cleanly on main but is **invisible to the worktree until it pulls/rebases**. This is identical to how `src/foo.ts` works under branches — there's nothing pathological about it; it's branch divergence. The framework surfaces the situation so the operator can decide:
+
+- **`forge` Step 1** in main checks `git worktree list` and surfaces live Forge worktrees at boot — *"m9 is live in worktree X at e94b6bb. Edits to m9 state belong there; shared docs edited here need a sync."*
+- **`discussing`** (before writing to `context.md`'s milestone block) and **`reviewing`** (before writing to `refactor-backlog.yml`) emit a one-line warning when the target block's milestone is live elsewhere. The warning informs, never blocks — main is often the canonical author of these files.
+- **Worktree-side rebase check** (opt-in via `forge.worktree_rebase_check: true` in `project.yml`) — when `forge` boots inside a worktree, it diffs `.forge/` between the worktree's HEAD and `main`; if shared-mutable files have changed on main, it offers `git restore --source main -- <files>` or a rebase.
+
+**Why not global `.forge/`?** A common instinct is "make `.forge/` shared so context propagates automatically." It breaks four load-bearing invariants:
+1. **Decisions are contracts** — they're versioned with the code they govern; severing them from branches breaks the contract.
+2. **State survives machine loss** — the multi-laptop pull-from-any-clone story depends on `.forge/` being in git.
+3. **History time-travel** — `git checkout` an old commit and you see the plan/decisions as they were; global state makes that impossible.
+4. **Git is the concurrency detector** — without it, two sessions writing the same field becomes silent last-write-wins.
+
+Per-worktree `.forge/` with a sharing taxonomy is the model. See [ADR-011](../docs/decisions/ADR-011-shared-state-taxonomy.md) for the longer version.
+
+### State Ownership rules (quick reference)
+
+- `state/milestone-{id}.yml` is the **single source of truth**; exactly one agent owns it at a time. **Other worktrees never write it** — promoted from advice to explicit rule, because catching yourself before the first wrong edit is the part the framework can help with.
 - Worktree / parallel agents write **only** their own milestone file and **append** desire-path files. They **never** write `index.yml`.
 - `index.yml` is **regenerated by rollup** (read every `milestone-*.yml` → rewrite the registry) by the main/orchestrator session — on `forge` resume and at `orchestrating` teardown. The rollup is deterministic + idempotent, so it **is** the reconcile step — never a hand-merge.
+- For shared-mutable files: write only your milestone's block; within a block, append-only (strike through, don't rewrite).
 - Same-milestone parallel work is out of scope, guarded by the M10 claim layer.
 
 ### Version Reservation Protocol
@@ -211,6 +242,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/migrations/0.29.0-shared-state-taxonomy.md

@@ -0,0 +1,68 @@
+# Migration Guide: Shared-state taxonomy (Forge 0.29.0)
+
+Applies to any Forge project that uses git worktrees (M10 or hand-rolled). This is a **documentation + skill-behavior** change, not a state-file change — there is nothing in `.forge/` to migrate. Read this once, then the new skill behavior catches the situations.
+
+## What changed and why
+
+Forge's `State Ownership (multi-worktree safety)` section in `FORGE.md` previously documented two file classes — `state/milestone-{id}.yml` (single-owner) and `state/index.yml` (derived) — and was silent on every other file in `.forge/`. In practice three more classes exist, and the riskiest one (shared mutable — `context.md`, `refactor-backlog.yml`) had no rule.
+
+A worked example from canvaz on 2026-06-15: a main-session edit to `context.md`'s `## M9` block was invisible to the live m9 worktree, because the worktree was branched off main earlier and reads `.forge/` from its own checkout. The operator had to deduce the sync gap from first principles, and nearly committed `milestone-9.yml` edits from main on the first attempt before catching themselves.
+
+0.29.0 closes the gap with **taxonomy + visibility + structural rules**, not with a state migration. See [ADR-011](../decisions/ADR-011-shared-state-taxonomy.md) for the longer version (including why a "global `.forge/`" approach is wrong).
+
+## The 5-class taxonomy (read this once)
+
+| Class | Examples | Write rule |
+|---|---|---|
+| **Single-owner mutable** | `state/milestone-{id}.yml`, `phases/milestone-{id}/`, `research/milestone-{id}.md` | One writer at a time; other worktrees **never** touch it. Explicit rule. |
+| **Derived** | `state/index.yml` | Never hand-edited; regenerated by Rollup 1.0. Only main/orchestrator runs rollup. |
+| **Append-only shared** | `releases.yml`, `state/desire-paths/*` | Many writers OK; structure prevents collision. Append + commit + push before depending on the slot. |
+| **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` | (a) Write only to YOUR milestone's block. (b) Within a block, append-only — strike through (`~~old~~`) superseded decisions instead of rewriting in place. |
+| **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md` | Rarely changes after init; canonical on main; worktrees lag and pull on rebase. No protocol — git handles it. |
+
+The full canonical version lives in `FORGE.md` → `State Ownership`.
+
+## What the framework now does automatically
+
+After upgrading to 0.29.0:
+
+- **`forge` Step 1 preflight (main checkout):** before Rollup, surfaces any live Forge worktrees and their owning milestones — *"m9 is live in worktree X at e94b6bb. Edits to its milestone state belong there; shared docs edited here need a sync."* No prescription, just visibility.
+- **`discussing`** emits a one-line warning before writing to `context.md`'s milestone block if that milestone is live in another worktree.
+- **`reviewing`** emits the same warning before appending to `refactor-backlog.yml` if any milestone is live in a worktree.
+- **`discussing`** also documents the supersede protocol (strike-through old decisions, append new ones below) so concurrent edits across worktrees stay mergeable.
+
+## Optional: enable the worktree-side rebase check
+
+Opt-in; default off. When enabled, `forge` boot **inside a worktree** diffs `.forge/` against `main` and offers to pull individual shared-mutable / stable-shared files when they've moved.
+
+Add to `.forge/project.yml`:
+
+```yaml
+forge:
+  worktree_rebase_check: true
+```
+
+Trade-off: adds one git diff per `forge` boot inside worktrees. Worth it for projects that frequently update `context.md` / `constitution.md` on main while worktrees are mid-flight; overkill for projects where the main checkout is mostly read-only.
+
+## Existing decisions in context.md — do nothing
+
+The taxonomy is descriptive: every existing decision in `context.md` already fits the new rules (it lives under a milestone heading, was append-only in practice). No rewrite needed. **New** writes follow the protocol (use strike-through to supersede).
+
+If a past edit broke the rule (decision rewritten in place), don't go back and reconstruct strike-throughs — the history is in git. Just follow the rule going forward.
+
+## Detection (none needed)
+
+There's nothing to detect on disk. The framework changes are in skills and `FORGE.md`. Upgrade and you have them.
+
+## Validation
+
+After `npx forge-orkes upgrade`:
+
+- `grep "5-class\|sharing classes" .forge/FORGE.md` returns hits in the `State Ownership` section.
+- `grep "cross-tree liveness\|append-only" .claude/skills/discussing/SKILL.md` returns the Write Protocol additions.
+- `grep "worktree-liveness\|worktree_rebase_check" .claude/skills/forge/SKILL.md` returns the Step 1 preflight.
+
+Then, if you have a worktree active:
+
+- `forge` in the main checkout surfaces the live worktree at the top of its boot output.
+- Begin a discussion in main that touches a worktree-live milestone → `discussing` emits the cross-tree warning before its first write.

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: