forge-orkes 0.30.0 → 0.32.0

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

@@ -112,215 +112,38 @@ Unchanged: {N} files
 
 The `Migrated:` line appears only when a legacy marker/`# Forge` section was extracted this run; `Restored:` only when a missing import line was re-appended. A steady-state upgrade lists `CLAUDE.md` under Unchanged.
 
-## Step 7: Post-Upgrade Migration Checks
+## Step 7: Post-Upgrade Migration Checks (data-driven)
 
-After sync completes, detect legacy file layouts that the new framework version no longer writes but may still read in compatibility mode. For each match, surface a migration prompt — do not auto-migrate.
+After sync completes, detect legacy file layouts the new framework version no longer writes but may still read in compatibility mode. This is **data-driven** — it loops over the migration guides synced in Step 4 and runs each guide's `## Detection` block. There are **no per-version blocks here**: a new guide that ships in the template (with a conformant Detection block — see `.forge/templates/migration-guide.md`) is auto-covered on the next upgrade with no edit to this skill.
 
-### Pre-0.10.0 requirements layout
+For each guide that signals it applies, surface a migration prompt — **never auto-migrate**.
 
-Run from project root:
+### The loop
 
-```bash
-find .forge -maxdepth 2 -type f \( -name "requirements.yml" -o -name "requirements-m*.yml" \) \
-  | grep -v "^.forge/templates/" \
-  | grep -v "^.forge/requirements/"
+1. **`installed`** = the project's `.claude/settings.json` `forge.version`, **captured at the START of this upgrade run, BEFORE Step 5 stamps the new version**. If absent/unknown, treat `installed` as `0.0.0` (all guides in range). Do **not** read the *source template's* `settings.json` literal — it carries a placeholder the installer stamps at write time, not the real version.
+2. **`source`** = `{source}/packages/create-forge/package.json` `version`. This is the authoritative new version. (Again: never the template `settings.json` literal.)
+3. Glob the just-synced guides: `.forge/migrations/{v}-*.md`. Parse `{v}` (the leading `MAJOR.MINOR.PATCH`) from each filename. Select guides where **`installed < v <= source`** (semver compare on dotted numerics).
+4. For each selected guide, ascending by version: run its `## Detection` fenced bash block from the project root (via the Bash tool, under `bash`). 
+   - stdout contains **`MIGRATE`** → the migration applies; surface the prompt (below). The text after `MIGRATE —` is the reason; show it.
+   - prints nothing / no `MIGRATE` → **no-op**; report `{v}: no action` and move on.
+   - the block errors → report `{v}: detection error (skipped)`; do **not** abort the loop.
 
-find .forge/phases -type f -name "requirements.yml" 2>/dev/null
-```
-
-If either command returns matches, surface:
-
-```
-Pre-0.10.0 requirements layout detected
-───────────────────────────────────────
-Found: {list of legacy paths}
-
-Forge 0.10.0 uses per-milestone files at .forge/requirements/m{N}.yml.
-A migration guide is available at: .forge/migrations/0.10.0-per-milestone-requirements.md
-(installed alongside Forge; canonical copy at
- https://github.com/Attuned-Media/forge/blob/main/docs/migrations/0.10.0-per-milestone-requirements.md)
-
-Run the migration now? (yes/no/show guide)
-```
-
-- **yes** → invoke `quick-tasking` skill, hand it the migration guide as the task definition
-- **show guide** → read and display the file, then re-ask
-- **no** → note in upgrade report. Skills will continue reading the legacy path as deprecated; new writes still go to the new path, causing split-brain state. Recommend running migration before next planning cycle.
-
-### Pre-0.17.0 missing `layers:` field
-
-Run from project root:
-
-```bash
-grep -q '^layers:' .forge/project.yml || echo "no layers field"
-ls .forge/contracts/index.yml 2>/dev/null
-```
-
-If `project.yml` has no `layers:` key AND `.forge/contracts/index.yml` is absent, surface:
-
-```
-Cross-layer contracts: project.yml predates the `layers:` field (Forge 0.17.0)
-─────────────────────────────────────────────────────────────────────────────
-Forge 0.17.0 added cross-layer contract detection (planning Step 6.1), which
-reads `layers:` from .forge/project.yml. Without it, planning falls back to a
-coarse top-level-directory heuristic.
-
-A migration guide is available at: .forge/migrations/0.17.0-cross-layer-contracts.md
-
-Add the layers field now? (yes/no/show guide)
-```
-
-- **yes** → invoke `quick-tasking` skill, hand it the migration guide as the task definition (identify layers, write `layers:` to project.yml, seed `.forge/contracts/index.yml` for multi-layer projects)
-- **show guide** → read and display the file, then re-ask
-- **no** → note in upgrade report. Planning still works on the fallback heuristic; cross-layer detection is just imprecise until `layers:` is declared. A single-layer project can set `layers: []` to opt out and clear the notice.
-
-`upgrading` never edits `.forge/project.yml` directly — this is the only path that adds the field, via `quick-tasking`.
-
-### Pre-0.19.0 legacy `state/index.yml`
-
-Run from project root:
-
-```bash
-grep -qE '^[[:space:]]*(desire_paths|metrics|current_status):' .forge/state/index.yml && echo "legacy index"
-wc -c .forge/state/index.yml   # slim registry is a few hundred bytes; KBs = narrative drifted in
-```
-
-If `state/index.yml` carries `desire_paths:`/`metrics:`/embedded narrative or is large, surface:
-
-```
-Worktree-safe state: state/index.yml predates the derived registry (Forge 0.19.0)
-─────────────────────────────────────────────────────────────────────────────────
-Forge 0.19.0 makes index.yml a derived registry (regenerated by rollup), moves
-desire_paths to append-only files, and commits .forge/ at every phase handoff.
-A legacy index.yml conflicts across git worktrees.
-
-A migration guide is available at: .forge/migrations/0.19.0-worktree-safe-state.md
-
-Migrate now? (yes/no/show guide)
-```
+### The prompt (uniform across guides)
 
-- **yes** → invoke `quick-tasking` skill, hand it the migration guide as the task definition (secure state, slim index.yml, split desire_paths into files, drop metrics, regenerate via rollup). This edits user-owned state — confirm each lossy step (the narrative extraction) with the user.
-- **show guide** → read and display the file, then re-ask
-- **no** → note in upgrade report. Skills still run against a legacy index.yml; it just won't gain worktree conflict-safety until migrated.
-
-`upgrading` never edits `.forge/state/` directly — migration runs via `quick-tasking`.
-
-### Pre-0.20.0 flat phase dirs
-
-Run from project root:
-
-```bash
-ls .forge/phases/ | grep -E '^m[0-9]+-[0-9]+-' && echo "flat layout"
-```
-
-If any dir matching `m{id}-{phase}-{name}` sits directly under `.forge/phases/`, surface:
+For each applying guide:
 
 ```
-Nested phase layout: phase dirs are flat under .forge/phases/ (Forge 0.20.0)
-──────────────────────────────────────────────────────────────────────────
-Forge 0.20.0 nests phase dirs one level per milestone:
-  m{id}-{phase}-{name}/  →  milestone-{id}/{phase}-{name}/
-This keeps `ls .forge/phases/` scoped per-milestone instead of dumping every
-phase across all milestones into context. Phase numbers are preserved verbatim
-(nothing is renumbered); the state cursor stays valid.
-
-{N} flat phase dir(s) detected.
-A migration guide is available at: .forge/migrations/0.20.0-nested-phase-layout.md
-(canonical: https://github.com/Attuned-Media/forge/blob/main/docs/migrations/0.20.0-nested-phase-layout.md)
+{v} migration available — {reason from the MIGRATE line, or the guide title}
+Guide: .forge/migrations/{v}-{slug}.md
+       (canonical: https://github.com/Attuned-Media/forge/blob/main/docs/migrations/{v}-{slug}.md)
 
 Migrate now? (yes/no/show guide)
 ```
 
-- **yes** → invoke `quick-tasking` skill, hand it the migration guide as the task definition (`git mv` each flat dir to `milestone-{id}/{phase}-{name}/`, preserving phase numbers; rewrite any `milestone_dir:` in roadmap.yml; verify plan-file count unchanged).
-- **show guide** → read and display the file, then re-ask
-- **no** → note in upgrade report. Skills compose the new nested path on write while flat dirs still exist on disk, so new and old plans split across two layouts (split-brain) until migrated. Recommend running migration before the next planning cycle.
-
-`upgrading` never moves phase dirs directly — migration runs via `quick-tasking`.
-
-### Pre-0.22.0 unbounded refactor-backlog
-
-Run from project root (backlog present only):
-
-```bash
-F=.forge/refactor-backlog.yml
-[ -f "$F" ] || exit 0
-kb=$(( $(wc -c < "$F") / 1024 ))
-terminal=$(grep -cE 'status:[[:space:]]*(done|dismissed|completed|complete|closed|wont_fix|stale)' "$F")
-noncanon=$(grep -oE 'status:[[:space:]]*[A-Za-z_]+' "$F" \
-  | grep -vE 'status:[[:space:]]*(pending|in_progress|done|dismissed|deferred)$' | wc -l)
-# bloat if: kb > 150  OR  terminal > 0  OR  noncanon > 0
-```
-
-Surface the prompt when `kb > 150` OR `terminal > 0` OR `noncanon > 0`, printing the three detected numbers:
-
-```
-Refactor-backlog compaction available (Forge 0.22.0)
-────────────────────────────────────────────────────
-Pre-0.22.0 the refactor backlog was append-only — resolved items were never
-pruned and statuses drifted (completed/complete/closed/wont_fix/stale + junk).
-0.22.0 archives terminal items to .forge/refactor-backlog-archive.yml and
-enforces the canonical vocab (pending|in_progress|done|dismissed|deferred).
-
-Detected: {kb} KB · {terminal} terminal item(s) · {noncanon} non-canonical status(es).
-A migration guide is available at: .forge/migrations/0.22.0-backlog-compaction.md
-(canonical: https://github.com/Attuned-Media/forge/blob/main/docs/migrations/0.22.0-backlog-compaction.md)
-
-Migrate now? (yes/no/show guide)
-```
-
-- **yes** → invoke `quick-tasking` skill, hand it the migration guide as the task definition (snapshot item count, normalize statuses, split actionable/terminal/triage, archive terminal items to `.forge/refactor-backlog-archive.yml`, rewrite the working file, verify item-count conservation before committing).
-- **show guide** → read and display the file, then re-ask
-- **no** → note in upgrade report. The backlog keeps growing and statuses stay drifted until migrated; reviewing/quick-tasking will compact on their next write regardless, but a bloated file lingers until then. Recommend running before the next review cycle.
-
-No-op guarantee: detection exits clean (no prompt) when the backlog is absent, under the gate, has zero terminal items, and all statuses are canonical. (Pending-item count is **not** a trigger — a busy-but-clean backlog is left alone.)
-
-`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`.
+- **yes** → invoke the `quick-tasking` skill, handing it the guide path as the task definition. `upgrading` never edits user state / project files / `.gitignore` directly — every migration runs via `quick-tasking`, and any lossy step (e.g. narrative extraction, staging files) is confirmed with the user first.
+- **show guide** → read and display the guide file, then re-ask.
+- **no** → note in the upgrade report. The new skills compose new-shape paths on write while legacy files persist on disk (split-brain) until migrated; recommend running it before the next planning/review cycle.
 
-### Future migrations
+### Why there is no bookkeeping
 
-Add new detection blocks here for each Forge version that changes file layout. Pattern:
-1. Detection command(s)
-2. Single-line description of the drift
-3. Pointer to `.forge/migrations/{version}-{slug}.md` (installed copy; canonical at `docs/migrations/...` in the Forge source repo)
-4. Three-way prompt (yes/no/show guide)
+Recording "crossed" guides is implicit in the range. Once Step 5 stamps `forge.version` to `source`, a later run's range `(new installed, source]` excludes every guide already crossed — so nothing re-detects, with **no ledger or marker file**. The range also closes the install-run blind spot: detection keys off the guides **freshly synced this run** (Step 4) plus the **pre-stamp installed version**, so the run that installs new detection behavior uses the new guides, not this skill's own pre-sync prose.

package/template/.forge/FORGE.md

@@ -1,6 +1,6 @@
 # Forge
 
-Lean meta-prompting framework for Claude Code. Context engineering + constitutional governance on native primitives.
+Lean meta-prompting framework. Context engineering + constitutional governance on agent-native primitives.
 
 ## Critical: No Native Plan Mode
 
@@ -11,7 +11,7 @@ All phases: **invoke via `Skill` tool**, never native behavior. `planning` → `
 ## Core Principles
 
 1. **Lean default, powerful when needed.** Quick → skip ceremony. Complex → full governance.
-2. **Native-first.** Claude Code built-ins only. No custom JS. Deprecate Forge when native catches up.
+2. **Adapter-native.** Use each platform's built-ins through adapters. Avoid custom runtime unless the substrate truly needs it.
 3. **Context is sacred.** Size-gate artifacts, lazy-load skills, fresh agents for isolated work.
 4. **Decisions are contracts.** Lock before building. Honor or flag — never silently override.
 5. **Verify goals, not tasks.** "Does it work?" > "Did we finish checklist?"
@@ -19,6 +19,24 @@ All phases: **invoke via `Skill` tool**, never native behavior. `planning` → `
 7. **Pave desire paths.** Repeated deviations/corrections = signal → evolve framework.
 8. **Disconfirm before commit.** Before locking a diagnosis, a solution, or a foundational choice, run the cheap pass that could break it. A conclusion reached without an attempt to refute it is a hypothesis, not a finding. Enforced at the three commit points: `debugging` (Confirmation Gate), `discussing`/`architecting` (option-space framing), `architecting` (Platform & Goal Validation).
 
+## Core Protocol And Adapters
+
+**Core protocol** lives in `.forge/`: project/constitution state, milestones, requirements, roadmap, context, streams, work packages, plans, verification, audits, and state ownership rules. The core protocol describes durable behavior, not one platform's tool names.
+
+**Platform adapters** translate the protocol into a runtime. Each platform adapter maps core behavior to its tools: Claude Code skills/hooks, Codex/AGENTS behavior, manual multi-session handoffs, or future agent surfaces. Adapter mechanics stay in adapter files and skills; they should not become core requirements.
+
+## Project Streams
+
+Forge has three runtime coordination layers: Project, Stream, and Work Package.
+
+| Layer | Purpose | Default Context |
+|---|---|---|
+| **Project** | Repo-wide traffic map: active streams, ownership, risks, merge order | `.forge/streams/active.yml` |
+| **Stream** | One active line of work: goal, branch/worktree, state, blockers, next action | `.forge/streams/{stream}.yml` + `brief.md` |
+| **Work Package** | Delegated bounded task inside a stream | `.forge/streams/{stream}/packages/{id}.yml` |
+
+Use ordinary Quick/Standard/Full tiers inside a stream. Use Project Chief / Chief of Staff when coordinating multiple active streams or pivoting without dropping context. Workers never coordinate laterally; they report to the stream or project chief. M10 worktrees remain an optional backend for isolation/merge discipline, not the primary UX.
+
 ## Workflow Tiers
 
 Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
@@ -60,7 +78,7 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | Systematic debugging | `debugging` | When stuck |
 | Upgrade Forge files | `upgrading` | On-demand |
 | Cross-session memory | `beads-integration` | When Beads installed |
-| Multi-agent orchestration (experimental) | `orchestrating` | Full (opt-in) |
+| Multi-agent backend (experimental) | `orchestrating` | Optional, usually selected by Chief/Streams |
 
 > Experimental skills require opt-in install — see `packages/create-forge/experimental/m10/README.md`.
 
@@ -73,7 +91,25 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | `requirements/m{N}.yml` | 50 KB/file | Prevents scope creep |
 | `plan.md` | 30 KB | Keeps executor context <50% |
 | `constitution.md` | 10 KB | Gates must be scannable |
+| `context.md` | 12 KB | Active decisions only; history archives to `context-archive.md` |
 | `refactor-backlog.yml` | 150 KB | Working backlog stays scannable; terminal items archive to `refactor-backlog-archive.yml` (advisory — flags, never blocks) |
+| `streams/active.yml` | 20 KB | Project Chief traffic map must stay cheap to load |
+| `streams/{stream}.yml` | 15 KB | Stream state stays resumable without becoming history |
+| `streams/{stream}/brief.md` | 8 KB | Stream context packet must fit into active session context |
+| `streams/{stream}/packages/{id}.yml` | 10 KB | Delegated work contract stays bounded |
+
+### Accumulating Artifacts
+
+Every new accumulating artifact needs: owner, size gate, archive/compaction rule,
+`derived` vs source-of-truth status, and migration behavior. Defaults:
+
+- `roadmap.yml`, `requirements/*.yml`, `releases.yml` are source-of-truth; load
+  scoped slices, not whole history.
+- `phases/`, `audits/`, `research/`, `archive/`, and `context-archive.md` are
+  historical; load only by milestone/stream/package/version.
+- Runtime/generated files (`.mcp-server/*.db*`, logs, spike DBs) are excluded
+  from framework context and packages unless debugging them.
+- Template copies sync mechanically; do not treat them as separate concepts.
 
 ### Fresh Agent Pattern
 Task touches 20+ files or complex subsystem → spawn fresh executor with isolated context. Prevents context rot.
@@ -82,7 +118,9 @@ Task touches 20+ files or complex subsystem → spawn fresh executor with isolat
 Each phase writes outputs to `.forge/` before completing. At phase boundaries, recommend `/clear`. Next phase loads from disk. Advisory — skip for short phases under 40% context.
 
 ### Lazy Loading
-Skills load only when invoked. CLAUDE.md stays in context; skill details on demand. Base context ~300 lines.
+Skills load only when invoked. Active context is `.forge/context.md`; consult
+`.forge/context-archive.md` only when older decisions matter. Skill details stay
+on demand. Base context ~300 lines.
 
 ## Model Routing
 
@@ -136,7 +174,12 @@ State lives in `.forge/`:
 - `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). 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)
+- `context.md` — Active locked decisions + deferred ideas (target <=12KB)
+- `context-archive.md` — Historical locked decisions; load only when relevant
+- `streams/active.yml` — Compact Project Chief traffic map: active stream summaries only.
+- `streams/{stream}.yml` — Per-stream state: lifecycle, ownership, shared surfaces, blockers, merge readiness.
+- `streams/{stream}/brief.md` — Human-readable stream context packet loaded when resuming that stream.
+- `streams/{stream}/packages/{id}.yml` — Work package contract for delegated workers or manual sessions.
 - `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)
 - `refactor-backlog.yml` — Refactoring catalog (actionable items only), worked via quick-tasking. Canonical status vocab: `pending | in_progress | done | dismissed | deferred`. Terminal items auto-archive on the next reviewing/quick-tasking write (compaction-on-write).
@@ -162,31 +205,22 @@ State-sync commits are separate from per-task code commits (which stay atomic du
 
 ### State Ownership (multi-worktree safety)
 
-`.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:
+`.forge/` is code-like: it branches with the repo, syncs via git, and commits
+with the work it describes. Every artifact has a sharing class:
 
 | 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. |
+| **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) | Write only to your milestone/stream block. Within a block, append-only; strike through instead of rewriting. |
 | **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.
+Cross-tree edits land on the current branch and are invisible to other worktrees
+until they pull/rebase. `forge` surfaces live worktrees at boot; `discussing`
+and `reviewing` warn before touching shared-mutable blocks; optional
+`forge.worktree_rebase_check` detects stale shared files inside worktrees. See
+[ADR-011](../docs/decisions/ADR-011-shared-state-taxonomy.md) for rationale.
 
 ### State Ownership rules (quick reference)
 
@@ -194,7 +228,7 @@ Per-worktree `.forge/` with a sharing taxonomy is the model. See [ADR-011](../do
 - 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.
+- Same-milestone parallel work needs Chief/Streams contracts; M10 file claims are optional defense-in-depth.
 
 ### Version Reservation Protocol
 

package/template/.forge/migrations/0.10.0-per-milestone-requirements.md

@@ -15,16 +15,20 @@ The pre-0.10.0 spec had a single top-level `.forge/requirements.yml` "refreshed
 
 ## Detection
 
-Run from project root. Any match below means migration is needed:
+Run from project root. Prints `MIGRATE` on stdout if a legacy requirements layout is present; silent + exit 0 when already on the per-milestone layout (the data-driven `upgrading` loop keys off the `MIGRATE` sentinel).
 
 ```bash
-# Off-spec layout signals
-ls .forge/requirements.yml 2>/dev/null                    # legacy single file
-ls .forge/requirements-m*.yml 2>/dev/null                 # suffixed top-level
-find .forge/phases -name "requirements.yml" 2>/dev/null   # per-phase files
+legacy=$(
+  ls .forge/requirements.yml 2>/dev/null                    # legacy single file
+  ls .forge/requirements-m*.yml 2>/dev/null                 # suffixed top-level
+  find .forge/phases -name "requirements.yml" 2>/dev/null   # per-phase files
+)
+if [ -n "$legacy" ]; then
+  echo "MIGRATE — legacy requirements layout: $(echo "$legacy" | tr '\n' ' ')"
+fi
 ```
 
-If `.forge/requirements/` already exists as a directory and the legacy paths above are absent, migration is complete — stop here.
+If `.forge/requirements/` already exists as a directory and the legacy paths above are absent, migration is complete — the block prints nothing and exits 0.
 
 ## Migration steps
 

package/template/.forge/migrations/0.17.0-cross-layer-contracts.md

@@ -17,17 +17,17 @@ Adding `layers:` once makes the detection deterministic. A single-layer project
 
 ## Detection
 
-Run from project root. Migration is suggested if `layers:` is absent:
+Run from project root. Prints `MIGRATE` if `project.yml` predates the `layers:` field and no contract index has been seeded; silent + exit 0 once `layers:` is declared (the data-driven `upgrading` loop keys off the `MIGRATE` sentinel).
 
 ```bash
-# No `layers:` key in project.yml → migration applies
-grep -q '^layers:' .forge/project.yml || echo "no layers field — migrate"
-
-# Already has a contract index? Then layers were declared at init — likely done.
-ls .forge/contracts/index.yml 2>/dev/null
+if [ -f .forge/project.yml ] \
+   && ! grep -q '^layers:' .forge/project.yml \
+   && [ ! -f .forge/contracts/index.yml ]; then
+  echo "MIGRATE — project.yml has no layers: field"
+fi
 ```
 
-If `project.yml` already contains a `layers:` key (any value, including `[]`), migration is complete — stop here.
+If `project.yml` already contains a `layers:` key (any value, including `[]`), or a `.forge/contracts/index.yml` exists (layers were declared at init), migration is complete — the block prints nothing and exits 0.
 
 ## Migration steps
 

package/template/.forge/migrations/0.19.0-worktree-safe-state.md

@@ -19,14 +19,19 @@ Two problems this release fixes:
 
 ## Detection
 
+Run from project root. Prints `MIGRATE` if `state/index.yml` is a legacy file — still carrying the metrics/desire-paths/narrative blocks, or grown to KBs; silent + exit 0 once it is the slim derived registry (the data-driven `upgrading` loop keys off the `MIGRATE` sentinel).
+
 ```bash
-# Bloated/legacy index.yml — large, or still carrying the metrics/desire-paths/narrative blocks
-wc -c .forge/state/index.yml                 # » a few hundred bytes once migrated; KBs means legacy
+F=.forge/state/index.yml
+[ -f "$F" ] || exit 0
 # Anchored so the file's own explanatory comments don't false-positive:
-grep -nE '^[[:space:]]*(desire_paths|metrics|current_status):' .forge/state/index.yml   # any hit → migrate
+if grep -qE '^[[:space:]]*(desire_paths|metrics|current_status):' "$F" \
+   || [ "$(wc -c < "$F")" -gt 4096 ]; then
+  echo "MIGRATE — legacy state/index.yml ($(wc -c < "$F") bytes)"
+fi
 ```
 
-The installer also prints a notice after `upgrade` when it detects a legacy `index.yml`.
+A slim derived registry is a few hundred bytes and carries none of those keys → the block prints nothing and exits 0. The installer (`npx forge-orkes upgrade`) runs the same check after sync.
 
 ## Migration steps
 

package/template/.forge/migrations/0.20.0-nested-phase-layout.md

@@ -55,14 +55,18 @@ Now `ls .forge/phases/milestone-9/` shows only milestone 9's phases.
 ## Detection
 
 A flat (un-migrated) layout has directories matching `m{id}-{phase}-{name}`
-**directly** under `.forge/phases/`:
+**directly** under `.forge/phases/`. Run from project root — prints `MIGRATE`
+if any flat phase dir is present; silent + exit 0 when already nested (the
+data-driven `upgrading` loop keys off the `MIGRATE` sentinel):
 
 ```bash
-ls .forge/phases/ | grep -E '^m[0-9]+-[0-9]+-' && echo "FLAT — migrate" || echo "nested — no-op"
+if ls .forge/phases/ 2>/dev/null | grep -qE '^m[0-9]+-[0-9]+-'; then
+  echo "MIGRATE — flat phase layout under .forge/phases/"
+fi
 ```
 
-Already-nested projects have only `milestone-{id}/` dirs at that level and the
-check prints `nested — no-op`.
+Already-nested projects have only `milestone-{id}/` dirs at that level → the
+block prints nothing and exits 0.
 
 ## Defensive parse
 

package/template/.forge/migrations/0.22.0-backlog-compaction.md

@@ -59,23 +59,27 @@ triage."* Silently dropping or guessing is forbidden.
 ## Detection
 
 Bloat/drift exists if the file is over the 150 KB size gate, OR any terminal
-item is present, OR any non-canonical status appears:
+item is present, OR any non-canonical status appears. Run from project root —
+prints `MIGRATE` when bloat is detected; silent + exit 0 when the backlog is
+absent or clean (the data-driven `upgrading` loop keys off the `MIGRATE`
+sentinel):
 
 ```bash
 F=.forge/refactor-backlog.yml
-[ -f "$F" ] || { echo "no backlog — no-op"; exit 0; }
+[ -f "$F" ] || exit 0
 kb=$(( $(wc -c < "$F") / 1024 ))
 terminal=$(grep -cE 'status:[[:space:]]*(done|dismissed|completed|complete|closed|wont_fix|stale)' "$F")
 noncanon=$(grep -oE 'status:[[:space:]]*[A-Za-z_]+' "$F" \
   | grep -vE 'status:[[:space:]]*(pending|in_progress|done|dismissed|deferred)$' | wc -l)
-echo "size=${kb}KB terminal=$terminal noncanon=$noncanon"
-# bloat if: kb > 150  OR  terminal > 0  OR  noncanon > 0
+if [ "$kb" -gt 150 ] || [ "$terminal" -gt 0 ] || [ "$noncanon" -gt 0 ]; then
+  echo "MIGRATE — backlog bloat: size=${kb}KB terminal=$terminal noncanon=$noncanon"
+fi
 ```
 
-A clean backlog (under the gate, zero terminal, all-canonical) prints
-`size=… terminal=0 noncanon=0` → **no-op**. The detector keys off bloat that
-compaction actually fixes, **not** the count of pending items — a busy-but-clean
-backlog is left alone.
+A clean backlog (under the gate, zero terminal, all-canonical) prints nothing
+and exits 0 → **no-op**. The detector keys off bloat that compaction actually
+fixes, **not** the count of pending items — a busy-but-clean backlog is left
+alone.
 
 ## ⚠️ Environment gotcha (read before scripting)
 

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

@@ -27,14 +27,14 @@ 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
+### Inventory (informational — not a migration trigger)
 
 ```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.
+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. This is informational: it does **not** trigger a migration (the actionable trigger for this guide is the `.gitignore` carve-out — see `## Detection` below).
 
 ### Migration
 
@@ -86,16 +86,16 @@ Forge installs into `.claude/` (skills, agents, hooks, `settings.json`). Many Cl
 
 The fix: track product files, keep per-machine/scratch files ignored.
 
-### Detection
+## Detection
 
-`upgrading` runs this automatically; you can run it by hand too:
+This is the guide's single migration trigger — the `.gitignore` carve-out. (Part 1's worktree-path inventory above is informational only.) `upgrading` runs this automatically; you can run it by hand too. Prints `MIGRATE` when `.claude/` is broadly ignored with no product-file carve-out; silent + exit 0 otherwise (the data-driven `upgrading` loop keys off the `MIGRATE` sentinel):
 
 ```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"
+  echo "MIGRATE — .claude/ broadly ignored with no product-file carve-out"
 fi
 ```
 

package/template/.forge/migrations/0.29.0-shared-state-taxonomy.md

@@ -50,9 +50,14 @@ The taxonomy is descriptive: every existing decision in `context.md` already fit
 
 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)
+## Detection
 
-There's nothing to detect on disk. The framework changes are in skills and `FORGE.md`. Upgrade and you have them.
+Intentional no-op. There's nothing to detect on disk — the 0.29.0 changes are in skills and `FORGE.md`, so upgrading the framework files is the whole migration. The block below is the uniform-contract placeholder: it prints no `MIGRATE` sentinel and exits 0, so the data-driven `upgrading` loop correctly treats this in-range guide as "no action".
+
+```bash
+# 0.29.0 is documentation + skill-behavior only — nothing on disk to migrate.
+exit 0
+```
 
 ## Validation