forge-orkes 0.19.0 → 0.21.0

package/bin/create-forge.js

@@ -8,8 +8,23 @@ const templateDir = path.join(__dirname, '..', 'template');
 const targetDir = process.cwd();
 const pkgVersion = require('../package.json').version;
 
-// --- Section markers for CLAUDE.md ---
-
+// --- CLAUDE.md import management ---
+
+// The framework prose lives in .forge/FORGE.md (a framework-owned file). CLAUDE.md
+// itself only carries a single native Claude Code memory import line pointing at it,
+// so CLAUDE.md belongs entirely to the user and upgrades never rewrite their content.
+const FORGE_IMPORT_LINE = '@.forge/FORGE.md';
+// Tolerate trailing whitespace / CRLF on the import line so we never duplicate it.
+const FORGE_IMPORT_RE = /^@\.forge\/FORGE\.md\s*$/m;
+// Stub written when no CLAUDE.md exists yet: one explanatory comment + the import line.
+const CLAUDE_STUB =
+  '<!-- Forge loads its workflow context from the import below. ' +
+  'The rest of this file is yours — add project instructions freely. -->\n' +
+  FORGE_IMPORT_LINE + '\n';
+
+// Legacy section markers. These survive SOLELY as migration detection for pre-0.20
+// installs whose CLAUDE.md still embeds the framework prose between these markers.
+// Forge no longer writes markers — new installs get the @import line instead.
 const FORGE_START = '<!-- forge:start -->';
 const FORGE_END = '<!-- forge:end -->';
 
@@ -18,6 +33,29 @@ const FORGE_END = '<!-- forge:end -->';
 // Framework-owned: Forge controls these entirely
 const FRAMEWORK_OWNED_DIRS = ['.claude/agents', '.claude/skills'];
 
+// Experimental / opt-in skills installed separately (e.g. from experimental/m10).
+// They are NOT in the shipped base template, so the framework-owned auto-clean
+// would otherwise delete them on upgrade. Preserve them instead.
+const EXPERIMENTAL_SKILL_PATHS = ['.claude/skills/orchestrating'];
+
+function isExperimentalSkillPath(displayPath) {
+  const norm = displayPath.split(path.sep).join('/');
+  return EXPERIMENTAL_SKILL_PATHS.some(
+    (p) => norm === p || norm.startsWith(p + '/')
+  );
+}
+
+// Compare dotted numeric versions (e.g. "0.19.1"). Returns 1 if a>b, -1 if a<b, 0 if equal.
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
 // Template-only: reference templates Forge controls
 const TEMPLATE_ONLY_DIRS = ['.forge/templates', '.forge/migrations'];
 
@@ -106,7 +144,7 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
   const srcDir = path.join(templateDir, relDir);
   const destDir = path.join(targetDir, relDir);
 
-  const result = { updated: [], added: [], unchanged: [], removed: [] };
+  const result = { updated: [], added: [], unchanged: [], removed: [], preserved: [] };
 
   if (!fs.existsSync(srcDir)) return result;
 
@@ -138,6 +176,12 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
   for (const rel of destFiles) {
     const srcPath = path.join(srcDir, rel);
     if (!fs.existsSync(srcPath)) {
+      const displayPath = path.join(relDir, rel);
+      // Never auto-clean opt-in experimental skills — they live outside the base template.
+      if (autoClean && isExperimentalSkillPath(displayPath)) {
+        result.preserved.push(displayPath);
+        continue;
+      }
       const destPath = path.join(destDir, rel);
       if (autoClean) {
         fs.unlinkSync(destPath);
@@ -156,60 +200,61 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
 }
 
 /**
- * Smart-merge CLAUDE.md using section markers.
- * - If markers exist: replace the forge section, preserve everything else
- * - If no markers but forge content exists: replace it and add markers
- * - If no forge content: append with markers
- * Returns 'replaced' | 'appended' | 'unchanged' | 'created'
+ * Guarantee CLAUDE.md carries the single `@.forge/FORGE.md` import line, migrating
+ * any legacy embedded forge section out in one pass. The framework prose itself lives
+ * in .forge/FORGE.md (synced separately) — this function never writes prose into
+ * CLAUDE.md and never touches user content outside the legacy forge section.
+ *
+ *   no CLAUDE.md                         → write the stub (comment + import) → 'created'
+ *   marker section present               → replace section in place with the import line → 'migrated'
+ *   legacy `# Forge` header (no markers) → strip header-to-EOF, append import line → 'migrated'
+ *   import line already present          → 'unchanged'
+ *   none of the above                    → append comment + import line at EOF → 'appended'
+ *
+ * Newline cleanup is confined to the seam of the replaced region only — a global
+ * collapse would mutate user content, which upgrades must never do.
  */
-function mergeClaudeMd() {
-  const srcPath = path.join(templateDir, 'CLAUDE.md');
+function ensureClaudeMdImport() {
   const destPath = path.join(targetDir, 'CLAUDE.md');
 
-  if (!fs.existsSync(srcPath)) return null;
-
-  const forgeContent = fs.readFileSync(srcPath, 'utf-8');
-
-  // No existing CLAUDE.md — just copy
+  // No existing CLAUDE.md — write the stub.
   if (!fs.existsSync(destPath)) {
-    fs.writeFileSync(destPath, forgeContent);
+    fs.writeFileSync(destPath, CLAUDE_STUB);
     return 'created';
   }
 
   const existing = fs.readFileSync(destPath, 'utf-8');
 
-  // Check if content is already identical
-  if (existing === forgeContent) return 'unchanged';
-
   const startIdx = existing.indexOf(FORGE_START);
   const endIdx = existing.indexOf(FORGE_END);
 
   if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    // Markers found — replace the section between them (inclusive)
+    // Legacy marker section — replace it in place with the import line (position preserved).
     const before = existing.substring(0, startIdx);
     const after = existing.substring(endIdx + FORGE_END.length);
-    const merged = before + forgeContent + after;
-
-    // Clean up any double newlines at the seams
-    const cleaned = merged.replace(/\n{3,}/g, '\n\n');
-    fs.writeFileSync(destPath, cleaned);
-    return 'replaced';
+    // Collapse blank-line runs only at the two seams we just created, never globally.
+    const merged = (before + FORGE_IMPORT_LINE + after)
+      .replace(/\n{3,}(@\.forge\/FORGE\.md)/, '\n\n$1')
+      .replace(/(@\.forge\/FORGE\.md)\n{3,}/, '$1\n\n');
+    fs.writeFileSync(destPath, merged);
+    return 'migrated';
   }
 
-  // No markers — check if there's an old forge section (starts with "# Forge")
+  // No markers, but a legacy `# Forge` header — old installs appended prose to EOF.
   const forgeHeaderIdx = existing.indexOf('# Forge\n');
   if (forgeHeaderIdx !== -1) {
-    // Old install without markers — replace from "# Forge" to end of file
-    // (Forge content is always appended at the end in old installs)
-    const before = existing.substring(0, forgeHeaderIdx);
-    const merged = before + forgeContent;
-    const cleaned = merged.replace(/\n{3,}/g, '\n\n');
-    fs.writeFileSync(destPath, cleaned);
-    return 'replaced';
+    const before = existing.substring(0, forgeHeaderIdx).trimEnd();
+    const merged = (before ? before + '\n\n' : '') + FORGE_IMPORT_LINE + '\n';
+    fs.writeFileSync(destPath, merged);
+    return 'migrated';
   }
 
-  // No forge content at all — append with markers
-  const merged = existing.trimEnd() + '\n\n' + forgeContent + '\n';
+  // Import line already present (tolerating trailing whitespace/CRLF) — nothing to do.
+  if (FORGE_IMPORT_RE.test(existing)) return 'unchanged';
+
+  // User-authored CLAUDE.md with no forge content and no import line — append it.
+  const merged =
+    existing.trimEnd() + '\n\n' + CLAUDE_STUB;
   fs.writeFileSync(destPath, merged);
   return 'appended';
 }
@@ -261,23 +306,6 @@ function isForgeInstalled() {
 async function install() {
   console.log('\n  Forge - Meta-prompting framework for Claude Code\n');
 
-  // Handle CLAUDE.md — use smart merge
-  const claudeStatus = mergeClaudeMd();
-  switch (claudeStatus) {
-    case 'created':
-      console.log('  Created CLAUDE.md');
-      break;
-    case 'replaced':
-      console.log('  Updated Forge section in CLAUDE.md (user content preserved)');
-      break;
-    case 'appended':
-      console.log('  Appended Forge config to existing CLAUDE.md');
-      break;
-    case 'unchanged':
-      console.log('  CLAUDE.md already up to date');
-      break;
-  }
-
   // Copy .claude/ directory
   const srcClaude = path.join(templateDir, '.claude');
   const destClaude = path.join(targetDir, '.claude');
@@ -294,6 +322,23 @@ async function install() {
   // the template ships it as `gitignore`. Materialize the real dotfile here.
   materializeForgeGitignore(destForge);
 
+  // Guarantee CLAUDE.md imports the framework prose (now on disk at .forge/FORGE.md).
+  const claudeStatus = ensureClaudeMdImport();
+  switch (claudeStatus) {
+    case 'created':
+      console.log('  Created CLAUDE.md (@.forge/FORGE.md import stub)');
+      break;
+    case 'migrated':
+      console.log('  Migrated CLAUDE.md: forge section extracted to .forge/FORGE.md (@import)');
+      break;
+    case 'appended':
+      console.log('  Added @.forge/FORGE.md import line to existing CLAUDE.md');
+      break;
+    case 'unchanged':
+      console.log('  CLAUDE.md import line already present');
+      break;
+  }
+
   // Stamp version from package.json into settings.json
   const settingsPath = path.join(targetDir, SETTINGS_FILE);
   if (fs.existsSync(settingsPath)) {
@@ -381,7 +426,7 @@ function detectLegacyStateIndex() {
   }
 
   // Legacy markers: shared accumulators or per-milestone narrative drifted in.
-  if (/^\s*desire_paths:|^\s*metrics:|current_status:/m.test(content)) return true;
+  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;
 
@@ -468,11 +513,28 @@ async function upgrade() {
   console.log(`  Installed: v${installedVersion}`);
   console.log(`  Available: v${pkgVersion}\n`);
 
+  // Downgrade guard: refuse to roll backward (overwrites newer framework files
+  // with older ones and deletes files newer versions added). Almost always a
+  // stale npx cache serving an old forge-orkes. Override with --force.
+  const force = process.argv.includes('--force');
+  if (
+    installedVersion !== 'unknown' &&
+    compareVersions(pkgVersion, installedVersion) < 0 &&
+    !force
+  ) {
+    console.error(`  ✖ Refusing to downgrade: installed v${installedVersion} is newer than available v${pkgVersion}.`);
+    console.error(`    This usually means a stale npx cache served an old forge-orkes.`);
+    console.error(`    Fix:  npx forge-orkes@latest upgrade   (or clear the cache: rm -rf ~/.npm/_npx)`);
+    console.error(`    To downgrade intentionally: forge-orkes upgrade --force\n`);
+    process.exit(1);
+  }
+
   const results = {
     updated: [],
     added: [],
     unchanged: [],
     removed: [],
+    preserved: [],
   };
 
   // 1. Process framework-owned directories (auto-clean stale files)
@@ -482,6 +544,7 @@ async function upgrade() {
     results.added.push(...dirResult.added);
     results.unchanged.push(...dirResult.unchanged);
     results.removed.push(...dirResult.removed);
+    results.preserved.push(...dirResult.preserved);
   }
 
   // 2. Process template-only directories
@@ -491,6 +554,7 @@ async function upgrade() {
     results.added.push(...dirResult.added);
     results.unchanged.push(...dirResult.unchanged);
     results.removed.push(...dirResult.removed);
+    results.preserved.push(...dirResult.preserved);
   }
 
   // 2b. Sync the forge .gitignore. Shipped as `gitignore` (npm strips dotfiles
@@ -510,10 +574,32 @@ async function upgrade() {
     }
   }
 
-  // 3. Smart-merge CLAUDE.md using section markers
-  const claudeStatus = mergeClaudeMd();
-  if (claudeStatus === 'replaced' || claudeStatus === 'appended') {
+  // 2c. Sync the framework prose file .forge/FORGE.md (framework-owned single file,
+  // same overwrite-when-different pattern as 2b). MUST run before the CLAUDE.md pass
+  // so a migrated project's import line never points at a missing file.
+  const fmSrc = path.join(templateDir, '.forge', 'FORGE.md');
+  const fmDest = path.join(targetDir, '.forge', 'FORGE.md');
+  if (fs.existsSync(fmSrc)) {
+    const newContent = fs.readFileSync(fmSrc, 'utf-8');
+    const existed = fs.existsSync(fmDest);
+    const oldContent = existed ? fs.readFileSync(fmDest, 'utf-8') : null;
+    if (oldContent !== newContent) {
+      fs.mkdirSync(path.dirname(fmDest), { recursive: true });
+      fs.writeFileSync(fmDest, newContent);
+      results[existed ? 'updated' : 'added'].push('.forge/FORGE.md');
+    } else {
+      results.unchanged.push('.forge/FORGE.md');
+    }
+  }
+
+  // 3. Guarantee the CLAUDE.md import line; auto-migrate any legacy embedded section.
+  const claudeStatus = ensureClaudeMdImport();
+  if (claudeStatus === 'migrated') {
     results.updated.push('CLAUDE.md');
+    console.log('  CLAUDE.md migrated: forge section extracted to .forge/FORGE.md (@import)');
+  } else if (claudeStatus === 'appended') {
+    results.updated.push('CLAUDE.md');
+    console.log('  CLAUDE.md: @.forge/FORGE.md import line restored');
   } else if (claudeStatus === 'unchanged') {
     results.unchanged.push('CLAUDE.md');
   } else if (claudeStatus === 'created') {
@@ -560,6 +646,14 @@ async function upgrade() {
     console.log();
   }
 
+  if (results.preserved.length > 0) {
+    console.log(`  Preserved (${results.preserved.length}):`);
+    for (const f of results.preserved) {
+      console.log(`    ${f} (kept — opt-in experimental skill)`);
+    }
+    console.log();
+  }
+
   console.log(`  Upgraded to v${pkgVersion}\n`);
 
   runPostUpgradeMigrationChecks();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.19.0",
+  "version": "0.21.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/agents/executor.md

@@ -15,7 +15,7 @@ Execute plan tasks. Full dev tools, strict deviation rules. Plan says X, build X
 | Task (sub-executors) | `git add .` or `git add -A` |
 
 ## Input
-Plan: `.forge/phases/m{M}-{N}-{name}/plan.md`, context: `.forge/context.md`, state: `.forge/state/milestone-{id}.yml`.
+Plan: `.forge/phases/milestone-{id}/{phase}-{name}/plan.md`, context: `.forge/context.md`, state: `.forge/state/milestone-{id}.yml`.
 
 ## Output
 Committed code, updated `milestone-{id}.yml` (progress/deviations), execution summary. **Never write `index.yml`** — it is a derived registry; `milestone-{id}.yml` is the single source of truth, regenerated into the registry by the `forge` rollup. The phase-boundary state-sync commit (State Commit Protocol, CLAUDE.md) is run by the `executing` skill at handoff — you do per-task code commits and update the milestone file.
@@ -41,7 +41,7 @@ Need to deviate from plan?
 
 ### 1. Read Plan
 ```
-Read: .forge/phases/m{M}-{N}-{name}/plan.md
+Read: .forge/phases/milestone-{id}/{phase}-{name}/plan.md
 Read: .forge/context.md
 Read: .forge/state/milestone-{id}.yml
 ```

package/template/.claude/agents/planner.md

@@ -18,7 +18,7 @@ Research -> actionable plans. Every plan passes constitutional gates with verifi
 Research findings, `.forge/templates/project.yml`, `constitution.md`, `context.md`, `state/milestone-{id}.yml` (if resuming).
 
 ## Output
-`.forge/` files: `phases/m{M}-{N}-{name}/plan.md` (XML tasks), `specs/`, `requirements/m{N}.yml`, `context.md`, `state/milestone-{id}.yml`. **Never write `index.yml`** — it is a derived registry; `milestone-{id}.yml` is the single source of truth. The `planning` skill runs the state-sync commit at handoff (State Commit Protocol, CLAUDE.md).
+`.forge/` files: `phases/milestone-{id}/{phase}-{name}/plan.md` (XML tasks), `specs/`, `requirements/m{N}.yml`, `context.md`, `state/milestone-{id}.yml`. **Never write `index.yml`** — it is a derived registry; `milestone-{id}.yml` is the single source of truth. The `planning` skill runs the state-sync commit at handoff (State Commit Protocol, CLAUDE.md).
 
 ## Process
 

package/template/.claude/agents/verifier.md

@@ -14,7 +14,7 @@ Goal-backward: start from must_haves, confirm existence, substance, wiring. Repo
 | Task (parallel sub-verifiers) | Fixing code (report — Executor fixes) |
 
 ## Input
-Plan+must_haves (`.forge/phases/m{M}-{N}-{name}/plan.md`), execution summary, source (read-only), milestone state.
+Plan+must_haves (`.forge/phases/milestone-{id}/{phase}-{name}/plan.md`), execution summary, source (read-only), milestone state.
 
 ## Output
 
@@ -57,7 +57,7 @@ Run: {n} | Passed: {n} | Failed: {n} | Coverage: {if available}
 
 ### 1. Load Criteria
 ```
-Read: .forge/phases/m{M}-{N}-{name}/plan.md → extract must_haves
+Read: .forge/phases/milestone-{id}/{phase}-{name}/plan.md → extract must_haves
 Read: .forge/state/milestone-{id}.yml → reported progress (the source of truth; index.yml is a derived registry — read the milestone file, not index)
 Read: .forge/context.md → locked decisions
 Read: .forge/deferred-issues.md → known pre-existing failures (if exists; treat as advisory)

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

@@ -101,7 +101,7 @@ Common conflicts:
 4. Consider indexing for frequent queries
 5. Plan for evolution — prefer nullable fields over rigid schemas
 
-Document in `.forge/phases/m{M}-{N}-{name}/data-model.md`.
+Document in `.forge/phases/milestone-{id}/{phase}-{name}/data-model.md`.
 
 ## API Contract Design
 
@@ -111,7 +111,7 @@ Document in `.forge/phases/m{M}-{N}-{name}/data-model.md`.
 4. Add pagination for list endpoints
 5. Plan per-endpoint auth requirements
 
-Document in `.forge/phases/m{M}-{N}-{name}/contracts/`.
+Document in `.forge/phases/milestone-{id}/{phase}-{name}/contracts/`.
 
 ## Output
 
@@ -123,7 +123,7 @@ Document in `.forge/phases/m{M}-{N}-{name}/contracts/`.
 
 ## Phase Handoff
 
-1. **Persist** — Confirm ADRs in `.forge/decisions/`, models and contracts in `.forge/phases/m{M}-{N}-{name}/`
+1. **Persist** — Confirm ADRs in `.forge/decisions/`, models and contracts in `.forge/phases/milestone-{id}/{phase}-{name}/`
 2. **Update state** — Set `current.status` to `planning` in `.forge/state/milestone-{id}.yml`
 3. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after architecting — m{N} {phase-name}"` (scoped; never `git add .`).
 4. **Recommend context clear:**

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

@@ -198,7 +198,7 @@ options:
 ### Step 1: Load Context
 
 ```
-Read: .forge/phases/m{M}-{N}-{name}/plan-{NN}.md → the plan
+Read: .forge/phases/milestone-{id}/{phase}-{name}/plan-{NN}.md → the plan
 Read: .forge/requirements/m{N}.yml → source requirements (current milestone)
 Read: .forge/context.md → locked decisions
 Read: .forge/constitution.md → active gates

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

@@ -6,7 +6,7 @@ description: "Build to plan with atomic commits, deviation rules, and context en
 # Executing
 
 ## Pre-Execution Checklist
-- [ ] Plan exists (`.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`)
+- [ ] Plan exists (`.forge/phases/milestone-{id}/{phase}-{name}/plan-{NN}.md`)
 - [ ] Context.md locked decisions noted
 - [ ] Constitution.md gates satisfied
 - [ ] Milestone state updated to `status: executing`
@@ -78,7 +78,7 @@ For each task in the plan:
 ## TDD Flow (task type="tdd")
 
 **With Test Spec:**
-1. Copy spec from `.forge/phases/m{M}-{N}-{name}/specs/` to test directory
+1. Copy spec from `.forge/phases/milestone-{id}/{phase}-{name}/specs/` to test directory
 2. **RED:** Remove `skip` markers. Confirm failure. Commit: `test({scope}): activate spec tests for {feature}`
 3. **GREEN:** Minimal code to pass. Repeat per test.
 4. **REFACTOR:** Clean up. Commit: `feat({scope}): implement {feature}`
@@ -116,7 +116,7 @@ forge_claim_files {
   session_id: lifecycle.session_id,
   files: [<absolute paths from task <files> manifest>],
   ttl_seconds: 1800,
-  reason: "executing m{M}-{N} task <name>"
+  reason: "executing m{id} phase {phase} task <name>"
 }
 ```
 
@@ -221,7 +221,7 @@ Run all non-advisory verification commands once after commit. 1 retry max.
 After completing all tasks in a plan:
 
 ```markdown
-# Execution Summary: m{M}-{N}-{name}, Plan {NN}
+# Execution Summary: milestone-{id}/{phase}-{name}, Plan {NN}
 
 ## Completed Tasks
 1. [Task name] — [one-line result]

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

@@ -15,13 +15,13 @@ Entry point. Detect tier, route skills, manage transitions. New projects → ini
 
 Rollup procedure (deterministic + idempotent):
 1. Glob `.forge/state/milestone-*.yml`.
-2. For each, read `milestone.id`, `milestone.name`, `current.status`, `lifecycle.{deferred_at, resumed_at}`, `current.last_updated`.
+2. For each, read `milestone.id`, `milestone.name`, `current.status`, `lifecycle.{deferred_at, resumed_at}`, and the last-touched date as `current.last_updated` → else legacy `progress.last_update` → else null. (The fallback keeps pre-0.19.0 milestone files self-sourcing without editing them; active milestones gain `current.last_updated` on their next transition.)
 3. Derive the registry `status`:
    - **deferred** — `lifecycle.deferred_at` set and not superseded by a later `resumed_at`
    - **complete** — `current.status == complete`
    - **not_started** — `current.status == not_started`
    - **active** — otherwise
-4. Rewrite `index.yml` `milestones:` (sorted by id) as `{id, name, status, last_updated: current.last_updated}`. No other keys.
+4. Rewrite `index.yml` `milestones:` (sorted by id) as `{id, name, status, last_updated}` (date from step 2's fallback). No other keys.
 
 Output is a pure function of the milestone files, so two sessions regenerating it produce identical bytes — it never needs a hand-merge. **Only the main/orchestrator session runs rollup; worktree agents never write `index.yml`** (they edit only their own `milestone-{id}.yml`).
 
@@ -144,7 +144,7 @@ No match → fall through to Step 2B (tier detection).
 1. Validate: milestone in `index.yml` (any status — active, deferred, complete, not_started)
 2. Build manifest — scan for associated files:
    - `.forge/state/milestone-{id}.yml`
-   - `.forge/phases/m{id}-*/` (glob all phase dirs)
+   - `.forge/phases/milestone-{id}/` (the milestone's phase dir — holds all `{phase}-{name}/` subdirs)
    - `.forge/research/milestone-{id}.md` (if exists)
    - `.forge/audits/milestone-{id}-*` (if exists)
    - Note: `.forge/context.md` is shared — do NOT archive or modify. M{id} decisions stay as history.
@@ -306,7 +306,7 @@ Phase transitions = clear boundaries. **Recommend `/clear`** after writing state
 | researching | `.forge/research/milestone-{id}.md` | discussing |
 | discussing | `.forge/context.md` (locked decisions, deferrals, discretion) | planning |
 | architecting | ADRs, data models, API contracts | planning |
-| planning | `.forge/phases/m{M}-{N}-{name}/`, `.forge/requirements/m{N}.yml`, roadmap.yml | executing |
+| planning | `.forge/phases/milestone-{id}/{phase}-{name}/`, `.forge/requirements/m{N}.yml`, roadmap.yml | executing |
 | executing | Committed code, execution summary, state | verifying |
 | verifying | Verification report, desire-path files (`state/desire-paths/`) | reviewing |
 

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

@@ -141,7 +141,7 @@ Before decomposing, classify whether this phase crosses a layer boundary with a
 
 **Two contract tiers:**
 - **Durable** = the standing layer API. Lives in ADRs (`.forge/decisions/`) + constitution, indexed in `.forge/contracts/index.yml` (integration-point -> governing ADR). Stable + unchanged -> agents read the ADR; no per-phase artifact.
-- **Per-phase delta** = the specific new/changed shape THIS phase introduces. Pinned in `.forge/phases/m{M}-{N}-{name}/contract.md` (from `.forge/templates/contract.md`); references its governing ADR; folded back into that ADR on landing.
+- **Per-phase delta** = the specific new/changed shape THIS phase introduces. Pinned in `.forge/phases/milestone-{id}/{phase}-{name}/contract.md` (from `.forge/templates/contract.md`); references its governing ADR; folded back into that ADR on landing.
 
 **Classify:**
 
@@ -176,9 +176,9 @@ Plan naming reflects the slice: `plan-01-user-signs-up.md`, not `plan-01-models.
 
 #### File Layout
 
-1. `.forge/templates/plan.md` -> `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`
-   - `{M}`=milestone, `{N}`=phase#, `{name}`=kebab, `{NN}`=seq
-   - Ex: `.forge/phases/m3-2-providers/plan-01.md`
+1. `.forge/templates/plan.md` -> `.forge/phases/milestone-{id}/{phase}-{name}/plan-{NN}.md`
+   - `{id}`=milestone, `{phase}`=phase# (preserved verbatim, NOT renumbered), `{name}`=kebab, `{NN}`=seq
+   - Ex: `.forge/phases/milestone-3/2-providers/plan-01.md`
 2. Frontmatter: phase, plan#, wave, deps, `slice_exception:` (optional, see Core Principle)
 3. must_haves:
    - **Truths:** User-observable outcomes (3-7). MUST be phrased as something the user can see, click, or receive -- not "model X exists" or "table Y created".
@@ -270,7 +270,7 @@ None -> skip to Step 8.
 
 ### Generate Specs
 
-**Location:** `.forge/phases/m{M}-{N}-{name}/specs/`
+**Location:** `.forge/phases/milestone-{id}/{phase}-{name}/specs/`
 Test files (`.test.ts`, `_test.go`, `test_*.py`):
 1. Import from `<files>` path
 2. Behavior from requirements (happy, edge, error)
@@ -278,7 +278,7 @@ Test files (`.test.ts`, `_test.go`, `test_*.py`):
 4. Mark pending (`it.skip()`, `@pytest.mark.skip`, `t.Skip()`)
 
 ```typescript
-// Example: .forge/phases/m1-1-auth/specs/login-endpoint.test.ts
+// Example: .forge/phases/milestone-1/1-auth/specs/login-endpoint.test.ts
 describe('POST /api/auth/login', () => {
   it.skip('returns 200 with valid token for correct credentials', () => {
     // From FR-001: "User can log in with email and password"
@@ -306,7 +306,7 @@ Specs -> type becomes `tdd`:
 <task type="tdd">
   <name>Implement login endpoint</name>
   <files>src/api/auth/login.ts</files>
-  <spec>.forge/phases/m1-1-auth/specs/login-endpoint.test.ts</spec>
+  <spec>.forge/phases/milestone-1/1-auth/specs/login-endpoint.test.ts</spec>
   <action>Make all tests in the spec file pass. Remove skip markers as you implement.</action>
   <verify>All spec tests pass: npm test -- login-endpoint</verify>
   <done>All skip markers removed, all tests green</done>

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

@@ -375,7 +375,7 @@ If the milestone being completed has `milestone.origin: {R-id}` set (promoted fr
 
 If the milestone's phases produced `contract.md` files (planning Step 6.1 Tier 1/2), close their lifecycle before completing the milestone. The durable contract is the ADR; the per-phase `contract.md` is a working delta that must be folded back in.
 
-1. Glob `.forge/phases/m{id}-*/contract.md`.
+1. Glob `.forge/phases/milestone-{id}/*/contract.md`.
 2. For each contract not yet `absorbed` (Tier-2 lands at `ratified` after the executing seam check; Tier-1 lands at `proposed` — both fold the same way now that the phase is verified):
    - Fold `delta` into its `governing_adr` — amend the ADR in `.forge/decisions/`, or supersede it (`Status: Superseded by ADR-{NNN}`) if the shape changed materially.
    - If a **new** integration point was introduced, add it to `.forge/contracts/index.yml` `integration_points:` (id, produces, consumes, governing_adr, summary).

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

@@ -18,16 +18,23 @@ Check if `.forge/dev-source` exists in the project root.
 
 Template directory: `{source}/packages/create-forge/template/`.
 
+### 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.)
+
 ## Step 2: File Classification
 
 | Category | Paths | Behavior |
 |----------|-------|----------|
-| **Framework-owned** | `.claude/agents/*.md`, `.claude/skills/*/SKILL.md` | Overwrite |
-| **Merge-owned** | `CLAUDE.md`, `.claude/settings.json` | Never auto-overwrite |
+| **Framework-owned** | `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.forge/FORGE.md` | Overwrite |
+| **Import-managed** | `CLAUDE.md` | Never overwrite content; migrate legacy forge sections + guarantee the `@.forge/FORGE.md` import line (Step 5) |
+| **Merge-owned** | `.claude/settings.json` | Smart-merge `forge.*` keys only (Step 5) |
 | **Template-only** | `.forge/templates/**`, `.forge/migrations/**`, `.forge/gitignore` → `.forge/.gitignore` | Overwrite |
 
 **Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements/`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
 
+**Preserve experimental skills.** Opt-in skills installed separately (e.g. `.claude/skills/orchestrating/` from `experimental/m10/`) are not in the base template. Never flag them as "removed from template" or delete them — leave them untouched.
+
 ## Step 3: Sync Framework-Owned Files
 
 For each framework-owned file in the source template:
@@ -44,11 +51,19 @@ Same process as Step 3 for `.forge/templates/**` and `.forge/migrations/**`. (Ma
 
 **Also sync the forge gitignore:** the source ships it as `.forge/gitignore` (npm strips files literally named `.gitignore` from a published tarball). Copy/refresh the source's `.forge/gitignore` into the project as `.forge/.gitignore` (overwrite — it is framework-owned). Report added/updated/unchanged like any template-only file.
 
-## Step 5: Handle Merge-Owned Files
+**Sync the framework prose file `.forge/FORGE.md`** (framework-owned single file — it holds the `# Forge` prose, formerly embedded in CLAUDE.md). Copy/refresh `{source}/packages/create-forge/template/.forge/FORGE.md` → `.forge/FORGE.md` (overwrite when different; report added/updated/unchanged). **Run this BEFORE the Step 5 CLAUDE.md pass** so a migrated import line never points at a missing file.
 
-**`CLAUDE.md`:**
-1. Read source and local versions
-2. If different → summarize changes (new/removed/modified sections) and let the user decide how to merge. Do not overwrite.
+## Step 5: Handle Import-Managed + Merge-Owned Files
+
+**`CLAUDE.md` (import-managed — one-pass auto-migration, no prompt):** mirror the npm bin's `ensureClaudeMdImport()` case-for-case. The framework prose lives in `.forge/FORGE.md` (synced in Step 4) — never write prose into CLAUDE.md, and never modify user content outside a legacy forge section.
+
+1. **No `CLAUDE.md`** → write the stub: one explanatory comment + the `@.forge/FORGE.md` import line. Report **created**.
+2. **Legacy `<!-- forge:start -->` / `<!-- forge:end -->` markers present** → replace the marker section *in place* with the `@.forge/FORGE.md` import line (position preserved), collapsing blank-line runs only at the two seams — never globally. Report **migrated**.
+3. **No markers, but a legacy `# Forge` header** (old installs appended prose to EOF) → strip from the header to end-of-file, append the import line. Report **migrated**.
+4. **Import line already present** (tolerating trailing whitespace / CRLF) → leave untouched. Report **unchanged**.
+5. **User-authored CLAUDE.md, no forge content, no import line** → append the comment + import line at EOF. Report **restored** (the import-line guarantee — Forge always loads its context).
+
+No manual-merge prompt for forge sections; migration is silent except the report line. User content outside the forge section is never modified, and the import line is never duplicated.
 
 **`.claude/settings.json`:**
 1. Read source and local versions
@@ -76,13 +91,17 @@ Removed from template: {N} files
   - .claude/agents/old-agent.md (still in your project)
   - ...
 
-Needs manual review: {N} files
-  - CLAUDE.md (new sections: "Upgrade Mechanism", modified: "Skill Routing")
-  - ...
+Migrated: {N} files
+  - CLAUDE.md (forge section extracted to .forge/FORGE.md — @import)
+
+Restored: {N} files
+  - CLAUDE.md (@.forge/FORGE.md import line re-appended)
 
 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.
@@ -152,7 +171,7 @@ Add the layers field now? (yes/no/show guide)
 Run from project root:
 
 ```bash
-grep -qE 'desire_paths:|metrics:|current_status:' .forge/state/index.yml && echo "legacy index"
+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
 ```
 
@@ -176,6 +195,38 @@ Migrate now? (yes/no/show guide)
 
 `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:
+
+```
+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)
+
+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`.
+
 ### Future migrations
 
 Add new detection blocks here for each Forge version that changes file layout. Pattern:

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

@@ -18,7 +18,7 @@ After `/clear`, load with fresh eyes — don't carry the executor's assumptions:
 ```
 Read: .forge/state/milestone-{id}.yml → current phase, plans completed
 Read: .forge/project.yml → tech stack (for running tests)
-Read: .forge/phases/m{M}-{N}-{name}/plan-{NN}.md → must_haves (truths, artifacts, key_links)
+Read: .forge/phases/milestone-{id}/{phase}-{name}/plan-{NN}.md → must_haves (truths, artifacts, key_links)
 Read: .forge/context.md → locked decisions
 Read: .forge/requirements/m{N}.yml → requirement IDs for coverage check (current milestone, resolved from state)
 Read: .forge/deferred-issues.md → known pre-existing failures (if exists; treat as advisory)

package/template/{CLAUDE.md → .forge/FORGE.md}

@@ -1,4 +1,3 @@
-<!-- forge:start -->
 # Forge
 
 Lean meta-prompting framework for Claude Code. Context engineering + constitutional governance on native primitives.
@@ -135,7 +134,7 @@ State lives in `.forge/`:
 - `state/desire-paths/` — Append-only framework-usage observations, one file per observation. Occurrence counts derived by globbing (no mutable counter).
 - `context.md` — Locked decisions + deferred ideas (discuss phase)
 - `research/milestone-{id}.md` — Research findings snapshot (dated, immutable)
-- `phases/m{M}-{N}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter
+- `phases/milestone-{id}/{phase}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter (`{id}`=milestone, `{phase}`=phase# preserved verbatim, `{name}`=kebab, `{NN}`=seq)
 - `refactor-backlog.yml` — Refactoring catalog, worked via quick-tasking
 - `archive/milestone-{id}/` — Archived milestone artifacts (archive-delete)
 
@@ -207,4 +206,3 @@ One commit per task. Format: `{type}({scope}): {description}`
 Types: `feat`, `fix`, `test`, `refactor`, `chore`, `docs`
 Never `git add .` or `git add -A` — stage individually.
 Phase handoffs additionally emit one scoped `chore(forge): sync state …` commit (see State Commit Protocol) so `.forge/` state never drifts out of git.
-<!-- forge:end -->

package/template/.forge/gitignore

@@ -2,7 +2,7 @@
 #
 # Everything under .forge/ IS durable and committed to version control, so
 # project state survives machine loss and can be pulled from any clone:
-#   project.yml constitution.md design-system.md context.md roadmap.yml
+#   FORGE.md project.yml constitution.md design-system.md context.md roadmap.yml
 #   requirements/ phases/ research/ decisions/ contracts/ audits/
 #   refactor-backlog.yml state/ templates/ migrations/
 #

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

@@ -20,9 +20,10 @@ Two problems this release fixes:
 ## Detection
 
 ```bash
-# Bloated/legacy index.yml — large, or still carrying desire_paths/metrics/narrative
+# 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
-grep -nE 'desire_paths:|metrics:|current_status:' .forge/state/index.yml   # any hit → migrate
+# 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
 ```
 
 The installer also prints a notice after `upgrade` when it detects a legacy `index.yml`.
@@ -60,7 +61,13 @@ For each entry under the old `desire_paths:` lists, create one file under `.forg
 .forge/state/desire-paths/{YYYY-MM-DD}-{type}-{milestone}-{slug}.yml
 ```
 
-Map the old list name to `type` (`deviation_patterns→deviation_pattern`, `tier_overrides→tier_override`, etc.). An old `occurrences: N` becomes **N files** (or one file plus a note — recurrence is now derived by counting files, not a stored number). Then delete the `desire_paths:` block from `index.yml`.
+Map the old list name to `type` (`deviation_patterns→deviation_pattern`, `tier_overrides→tier_override`, etc.). Migrate **one file per entry** — do *not* fabricate one-file-per-occurrence. The old `occurrences: N` is only an aggregate; collapse it to a single file and keep the count in a field (e.g. `detail.historical_occurrences: N`) if you want it. Forward recurrence is counted from *new* files.
+
+**Resolved vs open:**
+- **Still-open / could-recur** → file under `.forge/state/desire-paths/` (counts toward the future 3+ detection).
+- **Already resolved** (pattern fixed / framework already evolved) → file under `.forge/state/desire-paths/resolved/`. The active check globs `desire-paths/*.yml` (top level only), so `resolved/` is preserved for the audit trail but excluded from the count — matching how the `forge` skill archives resolved groups.
+
+Then delete the `desire_paths:` block from `index.yml`.
 
 ### 4. Drop `metrics:`
 
@@ -78,14 +85,18 @@ git commit -m "chore(forge): migrate to worktree-safe state (0.19.0)"
 ## Post-migration verification
 
 ```bash
-# index.yml is small and registry-only
-grep -qE 'desire_paths:|metrics:|current_status:' .forge/state/index.yml && echo "STILL LEGACY" || echo "OK: registry-only"
+# index.yml is registry-only — parse the YAML and check actual keys (a text grep
+# false-positives on the file's explanatory comments). Uses ruby (no pip yaml needed):
+ruby -ryaml -e 'd=YAML.load_file(".forge/state/index.yml"); bad=d.key?("metrics")||d.key?("desire_paths")||(d["milestones"]||[]).any?{|m| m.is_a?(Hash) && (m.key?("current_status")||m.key?("overall_percent"))}; puts bad ? "STILL LEGACY" : "OK: registry-only"'
+
+# (grep alternative — anchored + comment-stripped so it doesn't match the header)
+grep -vE '^[[:space:]]*#' .forge/state/index.yml | grep -qE '^[[:space:]]*(desire_paths|metrics|current_status):' && echo "STILL LEGACY" || echo "OK: registry-only"
 
 # rollup is idempotent — running /forge twice produces no diff to index.yml
 git diff --quiet .forge/state/index.yml && echo "OK: stable" || echo "rollup changed index — commit it"
 
-# desire-paths now live as files
-ls .forge/state/desire-paths/ 2>/dev/null
+# desire-paths now live as files (active at top level, resolved/ archived separately)
+ls .forge/state/desire-paths/ .forge/state/desire-paths/resolved/ 2>/dev/null
 ```
 
 ## What changes downstream

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

@@ -0,0 +1,168 @@
+# Migration Guide: Nested Phase Layout (Forge 0.20.0)
+
+Applies to projects initialized before 0.20.0 that have one or more flat phase
+directories under `.forge/phases/`.
+
+## Why
+
+Phase directories used to live **flat** under `.forge/phases/`, one dir per
+phase, named `m{milestone}-{phase}-{name}/`:
+
+```
+.forge/phases/
+  m1-1-schema-and-templates/
+  m1-2-skill-and-agent-updates/
+  m9-13-schema-and-templates/
+  m10-01-orchestration/
+  ...
+```
+
+At a handful of milestones this is fine. At ~100 milestones the flat directory
+becomes a context tax: any `ls .forge/phases/` or glob over it dumps hundreds of
+sibling entries into an agent's window, most of them irrelevant to the milestone
+being worked. Per Article XI (context is sacred), listings should scope to the
+milestone in hand.
+
+0.20.0 **nests** phase dirs one level under a per-milestone parent:
+
+```
+.forge/phases/
+  milestone-1/
+    1-schema-and-templates/
+    2-skill-and-agent-updates/
+  milestone-9/
+    13-schema-and-templates/
+  milestone-10/
+    01-orchestration/
+  ...
+```
+
+Now `ls .forge/phases/milestone-9/` shows only milestone 9's phases.
+
+## What does NOT change
+
+- **Phase numbers are preserved verbatim — nothing is renumbered.**
+  `m9-13-schema-and-templates` → `milestone-9/13-schema-and-templates`. The
+  phase number `13` stays `13`. (Phase numbers in this framework are globally
+  sequential, not per-milestone — that is intentional and untouched.)
+- **State cursor and roadmap need no edits to phase numbers.** The cursor stores
+  `current.phase` (int) + `current.phase_name` (string), never a path. Skills
+  compose the path at runtime. Because the phase number and name are unchanged,
+  every existing cursor stays valid — only the folder territory moves.
+- **Plan file contents are untouched.** Each `plan-{NN}.md` is byte-identical
+  after migration; only its parent path changes.
+
+## Detection
+
+A flat (un-migrated) layout has directories matching `m{id}-{phase}-{name}`
+**directly** under `.forge/phases/`:
+
+```bash
+ls .forge/phases/ | grep -E '^m[0-9]+-[0-9]+-' && echo "FLAT — migrate" || echo "nested — no-op"
+```
+
+Already-nested projects have only `milestone-{id}/` dirs at that level and the
+check prints `nested — no-op`.
+
+## Defensive parse
+
+The migration must tolerate **variable-width** milestone IDs **and**
+**variable-width** phase numbers. Real-world dirs include single-digit
+(`m1-1-x`), zero-padded (`m10-01-x`), and double-digit phase numbers
+(`m7-11-x`, `m9-13-x`). Use this regex, anchored to the dir basename:
+
+```
+^m([0-9]+)-([0-9]+)-(.+)$
+   │        │        └─ capture 3: kebab-case phase name
+   │        └─ capture 2: phase number (preserve verbatim, including any zero-pad)
+   └─ capture 1: milestone id
+```
+
+Capture group 2 is copied through **as written** — do not strip a leading zero,
+do not renumber.
+
+## Mapping
+
+```
+m{ID}-{PHASE}-{name}/   →   milestone-{ID}/{PHASE}-{name}/
+```
+
+Examples:
+
+| Flat | Nested |
+|------|--------|
+| `m1-1-schema-and-templates/` | `milestone-1/1-schema-and-templates/` |
+| `m9-13-schema-and-templates/` | `milestone-9/13-schema-and-templates/` |
+| `m10-01-orchestration/` | `milestone-10/01-orchestration/` |
+| `m7-11-refactor-promotion-and-audit/` | `milestone-7/11-refactor-promotion-and-audit/` |
+
+One milestone parent may receive multiple phase subdirs (e.g. `milestone-1/`
+gets `1-…`, `2-…`, `3-…`).
+
+## Migration steps
+
+### 1. Secure current state first
+
+```bash
+git add .forge/
+git commit -m "chore(forge): secure .forge state before 0.20.0 migration"
+```
+
+### 2. Move each flat dir to its nested home
+
+Use `git mv` so history follows the files and `git status` records a rename
+(not delete+add):
+
+```bash
+cd .forge/phases
+for d in m[0-9]*-[0-9]*-*/; do
+  d=${d%/}
+  [[ $d =~ ^m([0-9]+)-([0-9]+)-(.+)$ ]] || continue
+  id=${BASH_REMATCH[1]}; phase=${BASH_REMATCH[2]}; name=${BASH_REMATCH[3]}
+  mkdir -p "milestone-$id"
+  git mv "$d" "milestone-$id/$phase-$name"
+done
+```
+
+(Run from the repo so `git mv` resolves; adjust the `cd` to your `.forge/phases`
+path. The loop preserves `phase` verbatim — no renumbering.)
+
+### 3. Update roadmap `milestone_dir` references (if present)
+
+Some roadmaps pin an explicit `milestone_dir:` per phase. Rewrite any flat value
+to the nested form, e.g.:
+
+```yaml
+milestone_dir: "m10-01-orchestration"      # before
+milestone_dir: "milestone-10/01-orchestration"  # after
+```
+
+Phase numbers in the roadmap are **not** edited — only the path string.
+
+### 4. Verify
+
+```bash
+# No flat dirs remain directly under phases/:
+ls .forge/phases/ | grep -E '^m[0-9]+-[0-9]+-' || echo CLEAN
+
+# Plan-file count unchanged (compare to your pre-migration count):
+find .forge/phases -name 'plan*.md' | wc -l
+
+# git tracks the moves as renames, not delete+add:
+git status --short          # expect R  lines, no D + ?? pairs
+```
+
+### 5. Commit
+
+```bash
+git add .forge/
+git commit -m "chore(forge): migrate phase dirs to nested layout (0.20.0)"
+```
+
+## Notes
+
+- Idempotent: re-running detection on a nested project is a no-op (`CLEAN`).
+- No data loss: this is a pure rename. If `find … plan*.md | wc -l` differs
+  before vs. after, **stop and investigate** — a dir failed to parse.
+- The `upgrading` skill (Step 7) detects the flat layout after an upgrade and
+  offers to run this migration via `quick-tasking`. It never auto-migrates.

package/template/.forge/templates/contract.md

@@ -1,6 +1,6 @@
 # Phase Contract: {integration point}
 
-Copy to `.forge/phases/m{M}-{N}-{name}/contract.md` when planning **Step 6.1** detects a cross-layer delta (Tier 1 or 2). Pins the NEW or CHANGED interface shape the producing and consuming layers must agree on for this phase, so an agent building one layer in isolation does not have to guess the other's shape.
+Copy to `.forge/phases/milestone-{id}/{phase}-{name}/contract.md` when planning **Step 6.1** detects a cross-layer delta (Tier 1 or 2). Pins the NEW or CHANGED interface shape the producing and consuming layers must agree on for this phase, so an agent building one layer in isolation does not have to guess the other's shape.
 
 Lifecycle: pinned by the producer plan (NNa) BEFORE the consumer plan (NNb) builds against it -> ratified at the Tier-2 gate -> folded into the governing ADR when the phase lands (`status: absorbed`). The durable contract is the ADR; this file is the working delta on top of it.
 

package/template/.forge/templates/framework-absorption/gsd.md

@@ -22,7 +22,7 @@ CONTEXT.md with "NON-NEGOTIABLE" or "DEFERRED" sections
 | `ROADMAP.md` | `.forge/roadmap.yml` | Extract phases, milestones. Add dependency references between phases. Convert to YAML. |
 | `STATE.md` | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` | Extract current phase number, progress, active blockers, recent decisions. Split into global index and per-milestone state. |
 | `CONTEXT.md` | `.forge/context.md` | NON-NEGOTIABLE → Locked Decisions. DEFERRED → Deferred Ideas. DISCRETION → Discretion Areas. Minimal format change needed. |
-| `PLAN.md` | `.forge/phases/m{M}-{N}-{name}/plan.md` | Keep XML task format. Add `must_haves` YAML frontmatter. Split per-phase if combined. |
+| `PLAN.md` | `.forge/phases/milestone-{id}/{phase}-{name}/plan.md` | Keep XML task format. Add `must_haves` YAML frontmatter. Split per-phase if combined. |
 | `references/ui-brand.md` | `.forge/design-system.md` | Extract component rules, brand guidelines. Convert to component mapping table format. |
 | `references/tdd.md` | `.forge/constitution.md` Article II | Inform Test-First article gates with project-specific testing approach. |
 | `references/verification-patterns.md` | Informs `verifying` skill | Extract project-specific verification patterns. Add to constitution or context. |

package/template/.forge/templates/plan.md

@@ -1,7 +1,7 @@
 # Phase Plan Template
 
-Copy to `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md` for each plan in a phase.
-`{M}` = milestone ID, `{N}` = phase number within milestone, `{name}` = kebab-case phase name.
+Copy to `.forge/phases/milestone-{id}/{phase}-{name}/plan-{NN}.md` for each plan in a phase.
+`{id}` = milestone ID, `{phase}` = phase number (preserved verbatim, never renumbered), `{name}` = kebab-case phase name, `{NN}` = plan sequence within the phase.
 
 ---
 

package/template/.forge/templates/roadmap.yml

@@ -21,9 +21,10 @@ roadmap:
       name: ""                         # e.g., "MVP", "Admin Dashboard"
       phases: []                       # List of phase numbers belonging to this milestone
 
-  # Phases are scoped within milestones. Each phase has a local number (1, 2, 3...)
-  # within its milestone. Directory naming: .forge/phases/m{milestone_id}-{phase_num}-{name}/
-  # Example: m1-1-foundation/, m1-2-auth/, m2-1-dashboard/
+  # Phases belong to milestones (see each milestone's `phases:` list). Phase numbers
+  # are preserved verbatim and never renumbered.
+  # Directory naming: .forge/phases/milestone-{milestone_id}/{phase_num}-{name}/
+  # Example: milestone-1/1-foundation/, milestone-1/2-auth/, milestone-2/3-dashboard/
   phases:
     - id: 1
       name: ""                       # Vertical slice name, e.g., "User can sign up"

package/template/.forge/templates/state/index.yml

@@ -17,8 +17,9 @@ milestones:                            # Registry rolled up from state/milestone
     status: not_started                # mirrors current.status: not_started | active | deferred | complete
     last_updated: null                 # mirrors current.last_updated — used for resume default selection
 
-# NOTE — removed from this file by design (M11):
-#   metrics:      had zero writers; derive from `git log` if ever needed.
-#   desire_paths: now append-only files under state/desire-paths/ (one per
-#                 observation) so concurrent agents never collide. Occurrence
-#                 counts are derived by globbing that directory, not mutated here.
+# NOTE — removed from this file by design (M11). (Tokens below are spaced to
+# avoid tripping naive legacy-detection greps that scan for "<key>:".)
+#   metrics    — had zero writers; derive from `git log` if ever needed.
+#   desire-paths — now append-only files under state/desire-paths/ (one per
+#                  observation) so concurrent agents never collide. Occurrence
+#                  counts are derived by globbing that directory, not mutated here.