forge-orkes 0.29.0 → 0.31.0

package/bin/create-forge.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const { execSync } = require('child_process');
 
 const templateDir = path.join(__dirname, '..', 'template');
 const targetDir = process.cwd();
@@ -349,144 +350,117 @@ async function install() {
 }
 
 /**
- * Detect pre-0.10.0 requirements layouts (single top-level file, suffixed top-level,
- * or per-phase files). Returns array of legacy paths found, relative to project root.
+ * Extract the first fenced ```bash block under a guide's `## Detection` heading.
+ * Returns the script string, or null if the guide has no such block (e.g. a
+ * non-conformant guide). State-machine parse — no markdown dependency.
  */
-function detectLegacyRequirementsLayout() {
-  const forgeDir = path.join(targetDir, '.forge');
-  if (!fs.existsSync(forgeDir)) return [];
-
-  const legacy = [];
-
-  for (const entry of fs.readdirSync(forgeDir, { withFileTypes: true })) {
-    if (!entry.isFile()) continue;
-    if (entry.name === 'requirements.yml') {
-      legacy.push(path.join('.forge', entry.name));
-    } else if (/^requirements-m\d+\.yml$/.test(entry.name)) {
-      legacy.push(path.join('.forge', entry.name));
+function extractDetectionBlock(guideContent) {
+  const lines = guideContent.split('\n');
+  let inDetection = false;
+  let inCode = false;
+  const code = [];
+  for (const line of lines) {
+    if (!inDetection) {
+      if (/^##\s+Detection\b/.test(line)) inDetection = true;
+      continue;
     }
-  }
-
-  const phasesDir = path.join(forgeDir, 'phases');
-  if (fs.existsSync(phasesDir)) {
-    for (const phase of fs.readdirSync(phasesDir, { withFileTypes: true })) {
-      if (!phase.isDirectory()) continue;
-      const reqPath = path.join(phasesDir, phase.name, 'requirements.yml');
-      if (fs.existsSync(reqPath)) {
-        legacy.push(path.join('.forge', 'phases', phase.name, 'requirements.yml'));
-      }
+    // Stop scanning if we hit the next top-level (## ...) heading before a block.
+    if (!inCode && /^##\s/.test(line) && !/^##\s+Detection\b/.test(line)) break;
+    if (!inCode) {
+      if (/^```bash\s*$/.test(line)) inCode = true;
+      continue;
     }
+    if (/^```/.test(line)) break; // closing fence
+    code.push(line);
   }
-
-  return legacy;
+  return code.length ? code.join('\n') : null;
 }
 
 /**
- * Detect a pre-0.17.0 project.yml that has no `layers:` field. Cross-layer
- * contract detection (planning Step 6.1) reads `layers:`; without it the planner
- * falls back to a coarse top-level-directory heuristic. Returns true if the field
- * is absent and no contract index has been seeded. False if project.yml is missing
- * (not yet initialized) or already migrated.
+ * Data-driven post-upgrade migration check. Loops over the migration guides
+ * synced into the project this run (.forge/migrations/{v}-*.md), runs each
+ * guide's `## Detection` block, and on a `MIGRATE` stdout hit prints a warning
+ * with the exact guide pointer. There are NO per-version code branches: a new
+ * guide that ships with a conformant Detection block is auto-covered.
+ *
+ * Range: installed < v <= source. `installedVersion` is the project's
+ * settings.json forge.version captured BEFORE the version stamp; `source` is
+ * pkgVersion (this package's package.json) — never the template settings.json
+ * literal, which is a placeholder the installer stamps at write time. Non-
+ * interactive: the bin only warns and points at the guide; it never applies.
  */
-function detectMissingLayersConfig() {
-  const projectYml = path.join(targetDir, '.forge', 'project.yml');
-  if (!fs.existsSync(projectYml)) return false;
-
-  let content;
-  try {
-    content = fs.readFileSync(projectYml, 'utf-8');
-  } catch {
-    return false;
-  }
-
-  // Already declared a layers: key (any value, including []) → migrated.
-  if (/^layers:/m.test(content)) return false;
-  // A seeded contract index implies layers were declared at init → migrated.
-  if (fs.existsSync(path.join(targetDir, '.forge', 'contracts', 'index.yml'))) return false;
+function runPostUpgradeMigrationChecks(installedVersion) {
+  const migrationsDir = path.join(targetDir, '.forge', 'migrations');
+  if (!fs.existsSync(migrationsDir)) return;
 
-  return true;
-}
+  const installed =
+    installedVersion && installedVersion !== 'unknown' ? installedVersion : '0.0.0';
+  const source = pkgVersion;
 
-/**
- * Detect a pre-0.19.0 state/index.yml: 0.19.0 makes index.yml a thin derived
- * registry (regenerated by rollup) and moves desire_paths to append-only files.
- * A legacy index.yml still carries desire_paths:/metrics:/embedded narrative, or
- * is large. Returns true if index.yml exists and looks legacy; false if missing
- * (not yet initialized) or already a slim registry.
- */
-function detectLegacyStateIndex() {
-  const indexYml = path.join(targetDir, '.forge', 'state', 'index.yml');
-  if (!fs.existsSync(indexYml)) return false;
-
-  let content;
+  // Select in-range guides: installed < v <= source. Parse {v} from the filename.
+  let guides;
   try {
-    content = fs.readFileSync(indexYml, 'utf-8');
+    guides = fs
+      .readdirSync(migrationsDir)
+      .map((name) => {
+        const m = name.match(/^(\d+\.\d+\.\d+)-.*\.md$/);
+        return m ? { name, version: m[1] } : null;
+      })
+      .filter(Boolean)
+      .filter(
+        (g) =>
+          compareVersions(installed, g.version) < 0 &&
+          compareVersions(g.version, source) <= 0
+      )
+      .sort((a, b) => compareVersions(a.version, b.version));
   } catch {
-    return false;
+    return;
   }
 
-  // Legacy markers: shared accumulators or per-milestone narrative drifted in.
-  if (/^\s*(desire_paths|metrics|current_status):/m.test(content)) return true;
-  // A slim registry is small; KBs of index.yml means narrative crept in.
-  if (Buffer.byteLength(content, 'utf-8') > 4096) return true;
+  for (const guide of guides) {
+    const guidePath = path.join(migrationsDir, guide.name);
+    let script;
+    try {
+      script = extractDetectionBlock(fs.readFileSync(guidePath, 'utf-8'));
+    } catch {
+      continue;
+    }
+    if (!script) continue; // no runnable Detection block → treat as no-op
+
+    let stdout = '';
+    try {
+      stdout = execSync(script, {
+        cwd: targetDir,
+        shell: '/bin/bash',
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+    } catch {
+      // A non-zero exit or detection error is a no-op, not a failure — keep going.
+      continue;
+    }
+
+    if (!/MIGRATE/.test(stdout)) continue; // no-op
 
-  return false;
-}
+    const reasonLine = stdout
+      .split('\n')
+      .find((l) => l.includes('MIGRATE'));
+    const reason = reasonLine
+      ? reasonLine.replace(/^.*MIGRATE\s*[—-]?\s*/, '').trim()
+      : '';
 
-/**
- * After upgrade, surface any detected legacy file layouts the new framework
- * version no longer writes, or new config fields older projects lack.
- * Non-interactive — prints a warning with a pointer to the migration guide.
- * Add new detection blocks here as future versions change layout.
- */
-function runPostUpgradeMigrationChecks() {
-  const legacyReqs = detectLegacyRequirementsLayout();
-  if (legacyReqs.length > 0) {
-    console.log('  ⚠  Pre-0.10.0 requirements layout detected');
-    console.log('  ─────────────────────────────────────────');
-    console.log('  Found:');
-    for (const p of legacyReqs) {
-      console.log(`    ${p}`);
-    }
-    console.log();
-    console.log('  Forge 0.10.0+ uses per-milestone files at .forge/requirements/m{N}.yml.');
-    console.log('  Migration guide: .forge/migrations/0.10.0-per-milestone-requirements.md');
+    console.log(`  ⚠  ${guide.version} migration available${reason ? ` — ${reason}` : ''}`);
+    console.log('  ─────────────────────────────────────────────────────────────');
+    console.log(`  Guide: .forge/migrations/${guide.name}`);
+    console.log(
+      `         (canonical: https://github.com/Attuned-Media/forge/blob/main/docs/migrations/${guide.name})`
+    );
     console.log();
-    console.log('  Run the migration before your next planning cycle. In Claude Code:');
+    console.log('  Migrations are never applied automatically. In Claude Code:');
     console.log('    /forge then hand the guide to quick-tasking, or invoke Skill(quick-tasking)');
     console.log('    with the guide path as the task definition.');
     console.log();
   }
-
-  if (detectMissingLayersConfig()) {
-    console.log('  ⚠  Cross-layer contracts: project.yml has no `layers:` field (Forge 0.17.0)');
-    console.log('  ──────────────────────────────────────────────────────────────────────');
-    console.log('  Forge 0.17.0 added cross-layer contract detection (planning Step 6.1),');
-    console.log('  which reads `layers:` from .forge/project.yml. Your project.yml predates');
-    console.log('  this field, so planning falls back to a coarse top-level-directory heuristic.');
-    console.log();
-    console.log('  Migration guide: .forge/migrations/0.17.0-cross-layer-contracts.md');
-    console.log();
-    console.log('  Quick fix: add a `layers:` list to .forge/project.yml — or `layers: []`');
-    console.log('  for a single-layer project to silence this notice. In Claude Code:');
-    console.log('    /forge then hand the guide to quick-tasking.');
-    console.log();
-  }
-
-  if (detectLegacyStateIndex()) {
-    console.log('  ⚠  Worktree-safe state: legacy state/index.yml detected (Forge 0.19.0)');
-    console.log('  ────────────────────────────────────────────────────────────────────');
-    console.log('  Forge 0.19.0 makes index.yml a derived registry (regenerated by rollup),');
-    console.log('  moves desire_paths to append-only files, and commits .forge/ state at every');
-    console.log('  phase handoff. Your index.yml predates this — it still carries desire_paths/');
-    console.log('  metrics or embedded narrative, which conflicts across git worktrees.');
-    console.log();
-    console.log('  Migration guide: .forge/migrations/0.19.0-worktree-safe-state.md');
-    console.log();
-    console.log('  This migration edits user-owned state, so it is guided — never automatic.');
-    console.log('  In Claude Code: /forge then hand the guide to quick-tasking.');
-    console.log();
-  }
 }
 
 async function upgrade() {
@@ -656,7 +630,9 @@ async function upgrade() {
 
   console.log(`  Upgraded to v${pkgVersion}\n`);
 
-  runPostUpgradeMigrationChecks();
+  // Pass the version captured BEFORE upgradeSettings() stamped the new one, so the
+  // migration range is (installed, source] against the freshly-synced guides.
+  runPostUpgradeMigrationChecks(installedVersion);
 }
 
 // --- Entry point ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.29.0",
+  "version": "0.31.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/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

@@ -122,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/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.)
@@ -102,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
-
-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.
-
-### Pre-0.10.0 requirements layout
-
-Run from project root:
-
-```bash
-find .forge -maxdepth 2 -type f \( -name "requirements.yml" -o -name "requirements-m*.yml" \) \
-  | grep -v "^.forge/templates/" \
-  | grep -v "^.forge/requirements/"
-
-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.
+## Step 7: Post-Upgrade Migration Checks (data-driven)
 
-A migration guide is available at: .forge/migrations/0.19.0-worktree-safe-state.md
+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.
 
-Migrate now? (yes/no/show guide)
-```
+For each guide that signals it applies, surface a migration prompt — **never auto-migrate**.
 
-- **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.
+### The loop
 
-`upgrading` never edits `.forge/state/` directly — migration runs via `quick-tasking`.
+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.
 
-### Pre-0.20.0 flat phase dirs
+### The prompt (uniform across guides)
 
-Run from project root:
+For each applying guide:
 
-```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:
-
-```
-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/.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)

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
 

package/template/.forge/templates/migration-guide.md

@@ -0,0 +1,110 @@
+# Migration Guide Template
+
+Copy to `.forge/migrations/{version}-{slug}.md` (e.g. `0.31.0-foo.md`) when a Forge
+version changes an on-disk layout, a config field, or a state shape that older
+projects need to migrate. Also mirror the file to `docs/migrations/{version}-{slug}.md`
+(canonical) — the two copies must be byte-identical.
+
+A guide written to this contract is **auto-covered** by the post-upgrade migration
+check in BOTH routes (`upgrading` SKILL Step 7 and `npx forge-orkes upgrade`) the
+moment it ships in the template. **You do not edit `upgrading/SKILL.md` or
+`create-forge.js`** — they loop over the guides, so a conformant new guide just works.
+
+---
+
+## The Detection-block contract (load-bearing — read before writing the guide)
+
+The data-driven migration loop in both routes finds each guide, decides whether it is
+in range, and runs its Detection block. For that to work, every guide MUST follow this
+contract:
+
+1. **Exactly one `## Detection` heading per guide.** Not `### Detection`, not two of
+   them. If a guide has informational sub-checks (e.g. an inventory the user should see
+   but that does NOT trigger a migration), give them a different heading — only the one
+   `## Detection` block is run.
+2. **Under it, exactly one fenced ` ```bash ` block.** It is run from the project root,
+   must tolerate absent files (`[ -f … ] || exit 0`, `2>/dev/null`), and must not depend
+   on the user's shell config. The loop runs it under `bash` explicitly — do not rely on
+   zsh-only or interactive features. (The Bash tool runs zsh; `$BASH_REMATCH` / `=~`
+   capture groups silently fail — avoid them.)
+3. **Sentinel = `MIGRATE`.** The block echoes the literal token `MIGRATE` on stdout when
+   the migration applies. A trailing `— reason` after it is encouraged — it surfaces in
+   the prompt the user sees. When there is nothing to migrate (no-op guides included),
+   the block prints **no** `MIGRATE` token and exits 0.
+4. **No-op guides still get the heading.** A documentation/skill-behavior-only change
+   (nothing on disk to migrate) keeps a `## Detection` heading with a bash block that
+   simply `exit 0`s, so the loop's heading-find stays uniform across all guides.
+
+### Range gating (why you never touch the loop code)
+
+The loop reads the project's **installed** version (`settings.json forge.version`, captured
+BEFORE the upgrade stamps the new value) and the **source** version
+(`packages/create-forge/package.json`). It runs only the guides where
+`installed < {guide version} <= source`. So a guide ships, the next upgrade that crosses
+its version runs it once, and after the version is stamped it falls out of range — no
+ledger, no per-version code, no staleness. (It also closes the install-run blind spot:
+detection keys off the freshly-synced guides on disk, not the skill's own pre-sync code.)
+
+### Detection block skeleton (applies)
+
+```bash
+# Detect the legacy shape; tolerate absent files; emit MIGRATE iff it applies.
+F=.forge/some-file.yml
+[ -f "$F" ] || exit 0
+if grep -q 'legacy-marker' "$F"; then
+  echo "MIGRATE — <one-line reason the user will see>"
+fi
+```
+
+### Detection block skeleton (no-op guide)
+
+```bash
+# Documentation / skill-behavior change only — nothing on disk to migrate.
+exit 0
+```
+
+---
+
+## Guide skeleton
+
+```markdown
+# Migration Guide: <Title> (Forge <version>)
+
+Applies to <which projects>. <One-paragraph what-changed-and-why.>
+
+## Prerequisites
+
+1. <e.g. on the new version's framework files (run `npx forge-orkes upgrade` first)>
+2. <e.g. working tree clean or changes committed — migration touches N files>
+
+## Detection
+
+<One sentence: prints `MIGRATE` when it applies; silent + exit 0 otherwise.>
+
+​```bash
+<the single detection block per the contract above>
+​```
+
+## Migration steps
+
+### 1. <step>
+### 2. <step>
+...
+<The migration is NEVER auto-applied. In Claude Code it runs via the `quick-tasking`
+skill, which the `upgrading` Step-7 prompt hands the guide to on "yes". Lossy steps
+must be confirmed with the user.>
+
+## Validation
+
+<How to confirm the migration succeeded — greps, counts, conservation checks.>
+```
+
+---
+
+## Acceptance self-check before you ship the guide
+
+- [ ] Exactly one `## Detection` heading; exactly one ` ```bash ` block under it.
+- [ ] Block emits `MIGRATE` on stdout iff the migration applies; silent + exit 0 otherwise.
+- [ ] Block is safe on a clean/empty project (no errors, exit 0).
+- [ ] Mirrored byte-identical to `docs/migrations/{same-name}.md`.
+- [ ] No edit to `upgrading/SKILL.md` or `create-forge.js` was needed (the loop covers it).

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