forge-orkes 0.28.0 → 0.30.0

package/package.json

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

@@ -11,6 +11,7 @@ description: "Build to plan with atomic commits, deviation rules, and context en
 - [ ] Constitution.md gates satisfied
 - [ ] Milestone state updated to `status: executing`
 - [ ] Baseline snapshot captured (see below)
+- [ ] Plan anchors re-derived against HEAD (see below)
 
 ## Baseline Snapshot
 
@@ -23,6 +24,19 @@ Run **before the first task begins**. Makes failure causality mechanical — no
 
 Skip only if re-entering an in-progress execution and `deferred-issues.md` already documents all current failures.
 
+## Plan Anchor Re-Derivation
+
+Run **once, before the first task** (alongside the baseline snapshot). Plans snapshot concrete codebase literals — symbol names, `file:line` references, contract/type shapes, dependency versions — at planning time. Between planning and execution the codebase moves, and a stale literal silently misdirects the task ("plan said v5, HEAD is v6").
+
+Re-derive each anchor the plan names against current HEAD:
+
+1. Scan plan `<files>`, `<action>`, `must_haves`, and any `contract.md` for concrete literals: symbol/function names, `path:line` references, contract shapes, pinned versions.
+2. Resolve each against HEAD — grep the symbol, open the file, read the installed version.
+3. **Drifted** (symbol moved/renamed, line shifted, version bumped, shape changed) → reconcile the plan text to the live value *before* acting. Reconciled here, not discovered mid-task.
+4. **Gone** (symbol/file deleted, contract removed) → not a drift but a broken planning assumption → **STOP under Rule 4**; the slice may no longer hold.
+
+Cheap pass, high leverage. Skip only when re-entering an in-progress execution already past its first task.
+
 ## Deviation Rules
 
 **Full definitions:** `.claude/agents/executor.md`. Decision order: **Rule 4 first** (architectural → STOP, ask user), then Rule 1 (bugs), Rule 2 (critical gaps), Rule 3 (infra blockers). Uncertain → Rule 4.
@@ -265,6 +279,8 @@ Append **one file per observation** to `.forge/state/desire-paths/` — copy `.f
 - **User corrections**: Repeated correction matching a prior one → `type: user_correction`
 - **Agent struggles**: Multiple attempts or user guidance needed → `type: agent_struggle`
 
+**Set `scope` at capture** (see ADR-012): `framework` when the fix this signal implies targets Forge's own skills/templates (a skill's check, a plan/tier heuristic, a template); `project` when it targets user-owned files (`constitution.md`, `design-system.md`, `context.md`, project setup). Record `suggestion_target` when you know the file/skill it touches. `scope: framework` is what later lets `forge` review route the signal upstream instead of trapping it in this project.
+
 ## Cross-Layer Seam Check
 
 **Trigger:** the phase was split by planning Step 6.1 into a **Tier-2** producer plan-NNa + consumer plan-NNb (both carry a `contract:` frontmatter path pointing at the same `contract.md`). Single-plan / Tier-1 (`layer:` tag, no split, contract honored inline) → skip; no seam check needed.

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`.**
@@ -95,11 +122,35 @@ backlog pickup → effort: standard
 
 Downstream skills (researching, discussing, planning, executing, verifying, reviewing) see a normal milestone — no special branching.
 
-Check desire paths for 3+ occurrences: glob `.forge/state/desire-paths/*.yml`, group by `type` + normalized `note`, count each group.
-- 3+ in a group → *"Recurring: [{note}] ({N}x). Fix via [suggestion]?"*
-- Agree → apply; archive the group's files to `.forge/state/desire-paths/resolved/`. Decline → note, don't nag.
+**Desire-path review — `forge` boot is the SINGLE review owner** (verifying *captures* but does not surface; see ADR-012). Glob `.forge/state/desire-paths/*.yml`, group by `type` + normalized `note`, count each group. Read each file's `scope` (absent ⇒ `project`).
+
+**Skip declined groups first.** Glob `.forge/state/desire-paths/declined/*.yml`; skip any group whose key (`type` + normalized `note`) already has a decline file — it stays dismissed, no re-nag.
+
+**Surface at 3+.** For each remaining group with 3+ files, name a CONCRETE fix from this table (co-located here so the reader that acts carries the map):
+
+| Type | Suggested evolution |
+|------|---------------------|
+| `deviation_pattern` | Add a pre-check to planning, or a new constitutional article |
+| `tier_override` | Adjust tier-detection heuristics in the forge skill |
+| `skipped_step` | Make the step optional, or merge it into another |
+| `recurring_friction` | Add guidance to the relevant skill, or create a template |
+| `agent_struggle` | Add examples or anti-patterns to the relevant skill |
+| `user_correction` | Add a rule to constitution / context.md / the relevant skill |
+
+Prompt: *"Recurring: [{note}] ({N}x, scope:{scope}). Fix: [concrete suggestion from table]. Apply / decline?"*
+
+- **Agree** → apply the fix; archive the group's files to `.forge/state/desire-paths/resolved/`.
+- **Decline** → write ONE file `.forge/state/desire-paths/declined/{date}-{type}-{slug}.yml` with `{group_key, declined_at, reason}`, so it never re-prompts. (Replaces the old "note, don't nag" — which wrote nothing, so the 3+ files re-nagged every boot.)
 - (Occurrence count is derived from file count — there is no counter to reset.)
 
+**Upstream transport — for `scope: framework` groups only** (ADR-012). A framework-scope signal's fix targets Forge's own skills/templates, which live in the Forge repo, not this project. So in addition to the Apply/decline prompt above:
+
+1. **Always** write a portable, self-contained block to `.forge/state/desire-paths/upstream/{date}-{type}-{slug}.md` — pattern, occurrence count, the sibling observation filenames, the suggested evolution (from the table), and `suggestion_target`. Formatted to paste cleanly into a GH issue. This is the durable floor; it survives even with no network/tooling.
+2. **Resolve `forge.upstream_repo`** from `project.yml`; if absent, default to `https://github.com/zayneupton/forge`. If resolvable **and** `gh` is on PATH → offer (don't auto-run — it publishes externally): `gh issue create --repo {upstream_repo} --title "[desire-path] {note}" --body-file {block}`. **The GH issue is the real close** — tracked, central, survives machine loss.
+3. If `gh`/url unavailable → note the block is on disk and harvestable by `upgrading` (which runs from a local Forge clone) into `{source}/docs/desire-paths-inbox/`.
+
+`project`-scope groups keep the in-project flow above — no upstream. Applying a framework fix locally (when this *is* the Forge repo) and routing it upstream are not mutually exclusive: in a user project you route; in the Forge repo you apply.
+
 ### 1.3 Interface Check
 
 Check `interface` in `project.yml`:

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

@@ -156,7 +156,7 @@ Before decomposing, classify whether this phase crosses a layer boundary with a
 **Tier-2 ratify gate** (the ONLY interruption; frame as contract-correctness, not "parallelize y/n"):
 > *"This phase changes the {integration point} contract ({governing ADR}). Delta: [summary]. plan-NNa ({producer}) pins it; plan-NNb ({consumer}) builds against it in parallel. Is this contract shape correct?"*
 
-Block the split until confirmed. Override ("keep it one plan") -> append a `type: tier_override` file to `.forge/state/desire-paths/` (recurring overrides tune the threshold), fall back to Tier 1.
+Block the split until confirmed. Override ("keep it one plan") -> append a `type: tier_override` file to `.forge/state/desire-paths/` with `scope: framework` (the fix would tune Forge's own Tier-2 threshold/heuristics — see ADR-012; recurring overrides route upstream), fall back to Tier 1.
 
 **Integration (Tier 2):** layer plans build isolated (per-layer worktrees). The phase's final task is a **seam check** owned by the executing flow (NOT a standing agent): merge the layer branches, verify the shape the producer emits matches what the consumer built against, per `contract.md`.
 
@@ -196,6 +196,15 @@ Plan naming reflects the slice: `plan-01-user-signs-up.md`, not `plan-01-models.
 </task>
 ```
 
+#### Plan Anchors (drift-resistant references)
+
+Tasks reference concrete code — symbols, paths, line numbers, contract shapes, versions. These are **anchors**: snapshotted at planning time, relied on at execution time, *after* the codebase has moved. Make them re-derivable instead of fragile:
+
+- Reference by **symbol/intent** (`the signup handler in src/api/signup.ts`), not by bare line number (`src/api/signup.ts:42`). Line numbers drift on the next edit; symbols survive refactors.
+- For a version or contract shape that *must* be pinned, state the literal **and** its source (`react 18 — per package.json at plan time`) so executing can re-derive it against HEAD.
+
+Executing re-derives all anchors against HEAD before the first task (see executing → Plan Anchor Re-Derivation). Planning's job is to make that possible: name the symbol, cite the source.
+
 ### Task Sizing
 
 | Duration | Action |

package/template/.claude/skills/quick-tasking/SKILL.md

@@ -60,6 +60,8 @@ Example: `fix(docs): correct typo in API reference`
 ### 6. Done
 No verification ceremony. Move on.
 
+**Desire-path check (only when `.forge/state/desire-paths/` exists).** A Quick-tier streak (`quick-tasking → commit → done`) never boots `forge` or runs `verifying`, so recurring signals would pile up unreviewed. Cheap catch: glob `.forge/state/desire-paths/*.yml`, group by `type` + normalized `note`, and if any group hits 3+ (and has no decline file under `declined/`), surface it using **forge Step 1.2's review procedure** (the canonical table + Apply/decline + decline-ledger live there — do not duplicate them). One glob, surface if 3+, done. Standalone (no forge state) → skip.
+
 ## Milestone Context
 
 Quick-tasking handles two contexts. Existing workflow steps (Identify → Validate → Execute → Test → Commit → Done) apply in both — this section adds state management around them.

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

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

@@ -18,6 +18,16 @@ Check if `.forge/dev-source` exists in the project root.
 
 Template directory: `{source}/packages/create-forge/template/`.
 
+### Harvest upstream desire paths (advisory)
+
+`upgrading` is the one skill that bridges this project and a local Forge clone (`{source}`), so it harvests framework-scope desire paths the project has queued (ADR-012). After resolving `{source}`:
+
+1. Glob this project's `.forge/state/desire-paths/upstream/*.md`. None → skip silently.
+2. Any present → list them and offer to copy each into `{source}/docs/desire-paths-inbox/` (create the dir if missing) — a **tracked** location in the Forge repo where it won't be lost on machine swap.
+3. On copy → move the project-side block to `.forge/state/desire-paths/upstream/harvested/` so it isn't re-offered. Report counts like other steps.
+
+Advisory — never blocks the sync. This is the **convenience tier**: the primary close is the GH issue offered by `forge` review at capture time. Harvest just catches anything written when `gh`/the repo URL wasn't available.
+
 ### Downgrade guard
 
 Read the source version (`{source}/packages/create-forge/package.json` `version`) and the installed version (`.claude/settings.json` `forge.version`). **If source < installed, STOP** — do not sync. Report: *"Refusing to downgrade: installed v{installed} is newer than source v{source}. Point dev-source at a newer checkout, or confirm an intentional downgrade."* Only proceed on explicit user override. (Rolling backward overwrites newer framework files and deletes files newer versions added — and with `.claude/` often gitignored, it is unrecoverable.)

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

@@ -278,25 +278,11 @@ After verification completes (PASSED or GAPS FOUND), run a quick retrospective o
 
 **6. User corrections**: User correct the same thing multiple times? Implicit rules that should become explicit.
 
-### Surface Recommendations
+**Set `scope` on each observation** (see ADR-012): `framework` when the fix targets Forge's own skills/templates (tier heuristics, a skill's step, a template); `project` when it targets user-owned files (`constitution.md`, `design-system.md`, `context.md`). Record `suggestion_target` when known. This classifies the signal at write time so review can route `framework` signals upstream. Tier-override signals (#2) and the "constitution needs a new article" deviation case (#1) are usually `framework` and `project` respectively — judge by the file the fix touches, not the type.
 
-When any pattern reaches **3+ occurrences**, surface it:
+**Surfacing is owned by `forge` boot — not here** (single review owner, ADR-012). `verifying` only *records* observations; it does not surface recommendations, prompt for fixes, or archive. The 3+ aggregation, the type→evolution suggestion table, the decline-ledger, and upstream routing all live in `forge` Step 1.2. Write the observation files (with `scope`) and move on — the next `forge` boot reviews them.
 
-| Pattern Type | Suggested Evolution |
-|-------------|-------------------|
-| Repeated deviations | Add pre-check to planning, or new constitutional article |
-| Tier overrides | Adjust detection heuristics in forge skill |
-| Skipped steps | Make step optional, or merge into another step |
-| Recurring friction | Add guidance to relevant skill, or create a template |
-| Agent struggles | Add examples or anti-patterns to the relevant skill |
-| User corrections | Add rule to constitution, context.md, or relevant skill |
-
-Propose concrete actions:
-- *"Add 'always use Card component for content containers' to design-system.md?"*
-- *"Add null-check verification step to planning template?"*
-- *"Make research phase optional for Standard tier in this project?"*
-
-Only suggest at 3+ occurrences. One-off issues are noise.
+> Why retired: two surfacers (`forge` + `verifying`) disagreed, and `verifying` proposed without archiving, so its patterns re-surfaced forever. One owner fixes both.
 
 ## Phase Handoff
 

package/template/.forge/FORGE.md

@@ -135,7 +135,7 @@ State lives in `.forge/`:
 - `roadmap.yml` — Phases, milestones, dependencies
 - `state/index.yml` — DERIVED registry rolled up from milestone files (id, name, status, last_updated). Never hand-edited; never written by worktree agents.
 - `state/milestone-{id}.yml` — Per-milestone cursor (single source of truth): position, progress, decisions, blockers. One owner at a time.
-- `state/desire-paths/` — Append-only framework-usage observations, one file per observation. Occurrence counts derived by globbing (no mutable counter).
+- `state/desire-paths/` — Append-only framework-usage observations, one file per observation. Occurrence counts derived by globbing (no mutable counter). Each carries `scope: project | framework` (set at capture; absent ⇒ project). **`forge` boot is the single review owner**: at 3+ occurrences it surfaces a concrete fix from the co-located suggestion table, persists declines to `declined/` (no re-nag), and for `scope: framework` signals routes them upstream — a portable block to `upstream/` plus a `gh issue` offer against `forge.upstream_repo`. This closes Principle 7's capture→act loop; `verifying` captures but no longer surfaces. See [ADR-012](../docs/decisions/ADR-012-upstream-desire-path-feedback-channel.md).
 - `context.md` — Locked decisions + deferred ideas (discuss phase)
 - `research/milestone-{id}.md` — Research findings snapshot (dated, immutable)
 - `phases/milestone-{id}/{phase}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter (`{id}`=milestone, `{phase}`=phase# preserved verbatim, `{name}`=kebab, `{NN}`=seq)
@@ -162,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

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

@@ -101,6 +101,14 @@ orchestration:                       # M10 multi-agent orchestration (experiment
                                           #   ../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).
 
+forge:                               # Forge framework-level settings (all optional)
+  # upstream_repo: "https://github.com/zayneupton/forge"
+                                       # Where framework-scope desire paths (ADR-012) file issues when `gh`
+                                       # is available. Default if absent: the canonical Forge repo, so this
+                                       # works configless. Uncomment only to retarget a fork/mirror.
+  # worktree_rebase_check: true        # Opt-in: when forge boots inside a worktree, diff .forge/ vs main and
+                                       # offer to rebase/restore shared-mutable files (FORGE.md State Ownership).
+
 risks:                              # What could go wrong?
   - risk: ""
     mitigation: ""

package/template/.forge/templates/state/desire-path.yml

@@ -9,12 +9,27 @@
 # The date+type+milestone+slug make the name unique, so concurrent agents in
 # different worktrees only ever ADD files — git never has to merge content.
 #
-# Occurrence counts are DERIVED: the `forge` skill and the `verifying`
-# retrospective glob this directory and group by (type + normalized note).
-# A pattern appearing in 3+ files is a candidate for framework evolution.
+# Occurrence counts are DERIVED: the `forge` skill globs this directory and
+# groups by (type + normalized note). A pattern appearing in 3+ files is a
+# candidate for framework evolution, surfaced at `forge` boot — the single
+# review owner (see ADR-012).
+#
+# SCOPE decides where a 3+ pattern's fix lands:
+#   project   = fix targets user-owned files (constitution.md, design-system.md,
+#               context.md). Stays in-project.
+#   framework = fix targets Forge's own skills/templates. Eligible for UPSTREAM
+#               transport — forge review writes a portable block to
+#               state/desire-paths/upstream/ and (when gh + forge.upstream_repo
+#               are available) offers a GH issue against the Forge repo.
+# Lazy migration: a file with no `scope` is read as `project`.
 
 type: ""                 # deviation_pattern | tier_override | skipped_step |
                          # recurring_friction | agent_struggle | user_correction
+scope: ""                # project | framework — set AT CAPTURE by the writing
+                         # skill, from the file its suggested fix targets.
+                         # Absent ⇒ project (lazy migration).
+suggestion_target: ""    # optional: the skill/file the fix would touch
+                         # (e.g. "planning/executing skills", "constitution.md")
 milestone: ""            # e.g. "m7" (or "global" if not milestone-scoped)
 skill: ""                # skill that observed it (executing, planning, verifying, ...)
 first_seen: null         # ISO 8601 date this observation was recorded