forge-orkes 0.30.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.30.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/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/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).