forge-orkes 0.19.2 → 0.23.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 -->';
 
@@ -185,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';
 }
@@ -290,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');
@@ -323,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)) {
@@ -558,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') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.19.2",
+  "version": "0.23.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}`
@@ -105,6 +105,16 @@ feat(auth-01): implement JWT-based login
 - Include integration test for login flow
 ```
 
+## Version Bump Protocol
+
+When a task bumps the project version (`package.json` etc.) or adds a CHANGELOG entry:
+
+1. **Read the reserved number from `.forge/releases.yml`** — write ONLY the version this milestone reserved (Version Reservation Protocol, FORGE.md). Never invent a number at delivery.
+2. **No reservation? Reserve now** (planning predated the registry): `git pull`, take `max(version) + bump-level`, append one `{milestone, version, bump, reserved_at, summary}` entry, **commit + push the reservation BEFORE editing the version file** so a parallel session sees it taken.
+3. **Then** write the version + CHANGELOG entry in the normal atomic commit.
+
+This is what stops two parallel milestone sessions from grabbing the same number or clobbering each other's version edit — the registry, not the file, is the source of truth for "what number is mine."
+
 ## Multi-Agent Claim Convention [Experimental — M10]
 
 **Trigger:** active milestone state has `lifecycle.worktree_mode: active` (set by `orchestrating` skill). If absent or any other value → skip this section entirely; single-agent behavior unchanged.
@@ -116,7 +126,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 +231,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

@@ -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.
@@ -205,7 +205,13 @@ Tier + state → invoke via `Skill` tool. All phases use `Skill()`.
 
 **CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
-**Experimental:** if user invokes `orchestrating` skill (M10) and repo has it installed (`.claude/skills/orchestrating/` present + MCP server + claim-check hook), route through it **before** `executing` to bootstrap multi-agent worktree. Skill is opt-in per ADR-001; absent install → fall through to standard routing.
+**Experimental — M10 orchestration (auto-routes when installed).** Installing M10 *is* the consent: `forge` then auto-routes Standard/Full work through `orchestrating` **before** `executing` — no separate invocation to remember. Route through `Skill(orchestrating)` first when **all** hold:
+- **Installed:** `.claude/skills/orchestrating/` present + `forge-orchestrator` in `.mcp.json` + `.claude/hooks/forge-claim-check.sh` present.
+- **Not opted out:** `orchestration.auto` in `project.yml` ≠ `false` (absent = on; install = consent per ADR-001).
+- **Tier is Standard or Full.** Quick never auto-orchestrates (a worktree per typo is the wrong trade).
+- **Not already in a session:** active milestone has no `lifecycle.worktree_mode: active|degraded` (don't re-bootstrap inside a live session).
+
+`orchestrating` bootstrap stays the safety net — incompatible repo → it refuses, writes `worktree_mode: refused`, and `forge` continues single-agent. Absent install → standard routing. Manual `Skill(orchestrating)` still works for explicit control; set `orchestration.auto: false` in `project.yml` to opt back out.
 
 ### Auto-Routing (Always Deterministic)
 
@@ -306,7 +312,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>
@@ -381,6 +381,7 @@ Done when approved.
 ## Handoff
 
 1. **Persist** -- plans `.forge/phases/`, reqs `.forge/requirements/m{N}.yml`, roadmap `.forge/roadmap.yml`, context `.forge/context.md`
-2. **State** -- `current.status` = `executing` 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 planning — m{N} {phase-name}"` (scoped; never `git add .`).
-4. *"Plan written and synced. `/clear` then `/forge` to continue."*
+2. **Reserve version (if delivery bumps the version)** -- if any plan in this milestone will bump `package.json`/the project version, append ONE entry to `.forge/releases.yml` (Version Reservation Protocol, FORGE.md): pull first, set `version` = highest reserved `max()` bumped by this change's semver level, append `{milestone, version, bump, reserved_at, summary}`. **Never edit prior entries.** No version bump in scope → skip. Surface the reserved number to the user.
+3. **State** -- `current.status` = `executing` in `.forge/state/milestone-{id}.yml`
+4. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after planning — m{N} {phase-name}"` (scoped; never `git add .`). The `releases.yml` reservation rides in this commit — **push it** so a parallel session sees the number taken before they reserve.
+5. *"Plan written and synced. `/clear` then `/forge` to continue."*

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

@@ -70,8 +70,9 @@ Invoked via forge routing (mid-workflow or refactor-backlog item with milestone
 
 1. Read `.forge/state/milestone-{id}.yml` for current position
 2. Follow standard workflow (above)
-3. After commit: update `milestone-{id}.yml` — advance the `current` cursor if the task moved position and set `current.last_updated`; log deviations if any Rule 1-3 applied. Do **not** write a progress percent (derived on read by `forge`) and do **not** write `index.yml` (derived). Then **state-sync commit**: `git add .forge/` && `git commit -m "chore(forge): sync state after quick-task — m{N}"` (scoped; never `git add .`).
-4. Report: fix description, files changed, current position
+3. **If this task worked a refactor-backlog item:** in `.forge/refactor-backlog.yml` set that item's `status: done`, write `completed` (today, ISO) + `completed_by` (commit sha / one-line), THEN run the same **compaction-on-write** as `reviewing` Step 7 → "Status vocab + compaction-on-write" (normalize statuses → archive terminal items to `.forge/refactor-backlog-archive.yml` → leave only actionable items). Compaction is idempotent. (See reviewing Step 7 for the canonical rule — not repeated here.) This closes the loop: a worked item leaves the working backlog instead of lingering as `pending`.
+4. After commit: update `milestone-{id}.yml` — advance the `current` cursor if the task moved position and set `current.last_updated`; log deviations if any Rule 1-3 applied. Do **not** write a progress percent (derived on read by `forge`) and do **not** write `index.yml` (derived). Then **state-sync commit**: `git add .forge/` && `git commit -m "chore(forge): sync state after quick-task — m{N}"` (scoped; never `git add .`).
+5. Report: fix description, files changed, current position
 
 ### Without Milestone
 

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

@@ -333,6 +333,21 @@ Missing? Create from `.forge/templates/refactor-backlog.yml`.
 
 **When deferring an individual refactor item** (status flipped to `deferred`, as opposed to milestone-wide defer which goes through the forge skill): write `deferred_at` (ISO date today) and `deferred_reason` (one-line) siblings to `status: deferred`. Pre-existing items without these fields parse fine — lazy migration. These feed the `deferred` aggregator skill.
 
+### Status vocab + compaction-on-write
+
+**Canonical status vocab — the ONLY allowed values:** `pending | in_progress | done | dismissed | deferred`. Actionable = `pending|in_progress|deferred`. Terminal = `done|dismissed`.
+
+**Normalization map** (apply before any write): `completed`,`complete`,`closed` → `done`; `wont_fix`,`stale` → `dismissed`. Any other non-canonical value (`null`, free text, `promoted_to_m{N}`, …) → leave in place, surface for human triage in the review output (`"Backlog has {N} item(s) with unrecognized status — triage"`). Never silently drop.
+
+**Compaction-on-write** — run EVERY time you write the backlog, after appending new items:
+1. Normalize statuses via the map above.
+2. Move every terminal (`done|dismissed`) item — full record, intact — by **append** to `.forge/refactor-backlog-archive.yml` (create with a one-line header if absent: `# Forge Refactor Backlog — Archive (resolved/dismissed items). Append-only.`).
+3. Remove those items from `.forge/refactor-backlog.yml` so the working file holds only actionable + un-triaged items.
+
+Idempotent: a backlog with no terminal items and all-canonical statuses is left byte-unchanged. No item is ever lost — terminal items relocate, they are not deleted.
+
+**Size-gate check (advisory).** After compaction, if the working file still exceeds the FORGE.md size gate (150 KB), emit: `"Refactor backlog over size gate ({size}) even after compaction — {N} actionable items. Consider triaging stale pending items or promoting a cluster to Standard tier. Advisory — does not block."` (A busy project with hundreds of unworked pending items legitimately trips this; the signal is "triage the actionable backlog", not "archiving failed".)
+
 ### Route
 
 **HEALTHY/WARNINGS (accepted):** set `current.status: complete` in `milestone-{id}.yml`, then regenerate `index.yml` via the `forge` **Rollup** (do not hand-edit index). *"Milestone [{name}] complete. {N} backlog items."* Beads: `bd complete`.
@@ -375,7 +390,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

@@ -26,8 +26,9 @@ Read the source version (`{source}/packages/create-forge/package.json` `version`
 
 | 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`.
@@ -50,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
@@ -82,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.
@@ -182,6 +195,77 @@ 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`.
+
+### 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`.
+
 ### 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.
@@ -73,6 +72,7 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | `requirements/m{N}.yml` | 50 KB/file | Prevents scope creep |
 | `plan.md` | 30 KB | Keeps executor context <50% |
 | `constitution.md` | 10 KB | Gates must be scannable |
+| `refactor-backlog.yml` | 150 KB | Working backlog stays scannable; terminal items archive to `refactor-backlog-archive.yml` (advisory — flags, never blocks) |
 
 ### Fresh Agent Pattern
 Task touches 20+ files or complex subsystem → spawn fresh executor with isolated context. Prevents context rot.
@@ -135,8 +135,10 @@ 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
-- `refactor-backlog.yml` — Refactoring catalog, worked via quick-tasking
+- `phases/milestone-{id}/{phase}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter (`{id}`=milestone, `{phase}`=phase# preserved verbatim, `{name}`=kebab, `{NN}`=seq)
+- `refactor-backlog.yml` — Refactoring catalog (actionable items only), worked via quick-tasking. Canonical status vocab: `pending | in_progress | done | dismissed | deferred`. Terminal items auto-archive on the next reviewing/quick-tasking write (compaction-on-write).
+- `refactor-backlog-archive.yml` — Append-only terminal-item archive (`done`/`dismissed`); keeps the audit trail out of the working backlog.
+- `releases.yml` — Append-only version-reservation registry (cross-session coordination point; see Version Reservation Protocol)
 - `archive/milestone-{id}/` — Archived milestone artifacts (archive-delete)
 
 **Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions. Can be deferred (frozen in place) or archive-deleted.
@@ -162,6 +164,17 @@ State-sync commits are separate from per-task code commits (which stay atomic du
 - `index.yml` is **regenerated by rollup** (read every `milestone-*.yml` → rewrite the registry) by the main/orchestrator session — on `forge` resume and at `orchestrating` teardown. The rollup is deterministic + idempotent, so it **is** the reconcile step — never a hand-merge.
 - Same-milestone parallel work is out of scope, guarded by the M10 claim layer.
 
+### Version Reservation Protocol
+
+The project version + CHANGELOG slot are **shared resources** — when two milestones run in parallel sessions, each independently bumping `package.json`/version and adding a CHANGELOG entry collides. `.forge/releases.yml` removes the number from per-milestone scope.
+
+- **Reserve early, at planning.** When a milestone's delivery will bump the version, the `planning` skill appends ONE entry to `.forge/releases.yml`: `{milestone, version, bump, reserved_at, summary}`. The reserved version = highest `version:` in the file bumped by the change's semver level (capability → minor; fix/doc → patch — see version-bump criteria below).
+- **Append-only — never edit prior entries.** Distinct lines = no cross-session conflict. Commit + push the reservation BEFORE editing the version file, so a parallel session pulls and sees the number taken.
+- **Delivery never invents a number.** The `executing`/delivery step writes only the version reserved in `releases.yml`, then its CHANGELOG entry. If no reservation exists (milestone planned before this file), it reserves at delivery: pull, take `max() + bump`, append, push, then write.
+- **Race resolution.** Two near-simultaneous reservations: the second push rebases onto the first (append-only → clean), re-reads `max()`, takes the next number.
+
+**Version-bump criteria (0.x projects):** patch (`0.x.y`) = bug fix, doc tweak, sync-only, refinement. Minor (`0.x.0`) = new skill/agent/routing-row/auto-trigger/state-artifact/capability. Major (`x.0.0`) = post-1.0 breaking change. Default to minor when in doubt — a capability addition shipped as a patch drifts the version away from truth.
+
 ## Deviation Rules
 
 **Full definitions:** `.claude/agents/executor.md`.
@@ -207,4 +220,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.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/migrations/0.22.0-backlog-compaction.md

@@ -0,0 +1,186 @@
+# Migration Guide: Refactor-Backlog Compaction (Forge 0.22.0)
+
+Applies to projects whose `.forge/refactor-backlog.yml` has grown unbounded
+(terminal items never pruned) and/or has drifted off the canonical status
+vocabulary.
+
+## Why
+
+Before 0.22.0 the refactor backlog was **append-only** — the `reviewing` skill
+added items (`Next ID = max + 1`) but nothing ever removed resolved ones. Over a
+project's life, `done`/`dismissed` items accumulate forever, and the `status`
+field drifts into synonyms (`completed`, `complete`, `closed`) and junk
+(`null`, free text). One real project reached **9,256 lines / 439 items**, of
+which only ~220 were actionable — the rest was resolved-item sediment.
+
+Per Article XI (context is sacred), the working backlog must stay scannable. A
+multi-thousand-line YAML file is a context tax on every `reviewing`/`deferred`
+read and is impossible to triage by hand.
+
+0.22.0 keeps the working file **actionable-only**: terminal items move to an
+append-only archive, and statuses are normalized to a single vocabulary.
+
+## What changes
+
+- Terminal items (`done` | `dismissed`) move — full record intact — to
+  `.forge/refactor-backlog-archive.yml` (append-only).
+- Statuses normalize to the canonical set:
+  `pending | in_progress | done | dismissed | deferred`.
+- The working `.forge/refactor-backlog.yml` keeps only **actionable**
+  (`pending | in_progress | deferred`) and any **un-triaged** items.
+
+## What does NOT change
+
+- **No item is deleted.** Terminal items are relocated to the archive, not
+  dropped. The full record (`completed`, `completed_by`, `dismissed_reason`,
+  dates) is preserved — the audit trail just lives out of the working file.
+- **IDs are stable.** `R042` stays `R042` in whichever file it lands in.
+- **Actionable items are content-stable** apart from status normalization
+  (a legacy `completed` only ever appears on a terminal item, so actionable
+  items are typically byte-unchanged).
+- **`deferred` items stay in the working file** with their `deferred_at` /
+  `deferred_reason` — they are actionable (awaiting a revisit), not terminal.
+
+## Status normalization map
+
+Apply before splitting. Fold each legacy value to its canonical equivalent:
+
+| Legacy value(s) | Canonical |
+|-----------------|-----------|
+| `completed`, `complete`, `closed` | `done` |
+| `wont_fix`, `stale` | `dismissed` |
+| `pending`, `in_progress`, `done`, `dismissed`, `deferred` | (unchanged) |
+| anything else (`null`, `RegistrationStatus`, free text, `promoted_to_m{N}`) | **TRIAGE** |
+
+A `TRIAGE` value is **never** auto-resolved. Leave the item in the working file
+and surface it for a human decision: *"{N} item(s) have an unrecognized status —
+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:
+
+```bash
+F=.forge/refactor-backlog.yml
+[ -f "$F" ] || { echo "no backlog — no-op"; 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
+```
+
+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.
+
+## ⚠️ Environment gotcha (read before scripting)
+
+The Bash tool runs **zsh**, where `$BASH_REMATCH` / `=~` capture groups **do not
+populate** — a regex-capture loop written for bash silently produces empty
+captures and can corrupt output. Two rules:
+
+1. **Prefer a single-pass YAML-aware split over per-line regex.** This migration
+   relocates list items between two YAML files — operate on whole item blocks,
+   not field-by-field string surgery.
+2. If you must use `=~` capture, **wrap the loop in `bash -c '…'`** so it runs
+   under bash, not zsh.
+
+And the cardinal rule from prior migrations: **verify item count before == after
++ archived.** If the totals don't conserve, STOP and recover from git.
+
+## Procedure
+
+### 1. Secure current state first
+
+```bash
+git add .forge/refactor-backlog.yml
+git commit -m "chore(forge): secure backlog before 0.22.0 compaction"
+```
+
+### 2. Snapshot the original item count
+
+```bash
+N_BEFORE=$(grep -cE '^[[:space:]]*-?[[:space:]]*id:' .forge/refactor-backlog.yml)
+echo "items before: $N_BEFORE"
+```
+
+### 3. Normalize statuses
+
+Fold synonyms per the map above (`completed`/`complete`/`closed` → `done`;
+`wont_fix`/`stale` → `dismissed`). Record any value that is still non-canonical
+after normalization as the **TRIAGE** set — do not change it.
+
+### 4. Split into three buckets
+
+Walk the item list once and bucket each item by its (normalized) status:
+
+- **actionable** → `pending | in_progress | deferred`
+- **terminal** → `done | dismissed`
+- **triage** → anything else (unrecognized)
+
+Operate on whole item blocks (an item starts at `- id:` and runs until the next
+`- id:` or EOF). Preserve every field verbatim.
+
+### 5. Write the archive
+
+Append the **terminal** bucket (full records) to
+`.forge/refactor-backlog-archive.yml`. Create it if absent with a header:
+
+```yaml
+# Forge Refactor Backlog — Archive (resolved/dismissed items). Append-only.
+# Items relocated here by compaction; full record preserved for audit trail.
+items:
+```
+
+### 6. Rewrite the working file
+
+Rewrite `.forge/refactor-backlog.yml` with the **actionable + triage** buckets
+only (triage stays visible until a human resolves it). Keep the template header.
+
+### 7. Verify conservation — the hard gate
+
+```bash
+A=$(grep -cE '^[[:space:]]*-?[[:space:]]*id:' .forge/refactor-backlog.yml)        # actionable + triage
+B=$(grep -cE '^[[:space:]]*-?[[:space:]]*id:' .forge/refactor-backlog-archive.yml) # archived (subtract its template example if any)
+echo "working=$A archived=$B  sum=$((A+B))  before=$N_BEFORE"
+```
+
+`working + archived` **must equal** `N_BEFORE`. If it does not, **STOP** — do not
+commit; `git checkout .forge/refactor-backlog.yml` and investigate (a malformed
+item block failed to parse).
+
+### 8. Commit
+
+```bash
+git add .forge/refactor-backlog.yml .forge/refactor-backlog-archive.yml
+git commit -m "chore(forge): compact refactor backlog — archive terminal items (0.22.0)"
+```
+
+## After migration
+
+- The working file may still exceed the 150 KB gate if the project has hundreds
+  of genuinely-unworked `pending` items. That is a legitimate **triage** signal
+  ("work or dismiss stale items / promote a cluster to Standard tier"), **not** a
+  failed migration. Compaction archives resolved items; it does not invent triage
+  decisions about open ones.
+- From here on, `reviewing` Step 7 and `quick-tasking` compact on every write —
+  the backlog stays bounded without re-running this migration.
+
+## Rollback
+
+The whole operation is one commit over two files. `git revert <sha>` (or
+`git checkout <pre-migration-sha> -- .forge/refactor-backlog.yml` and delete the
+archive) fully reverses it — nothing was destroyed.
+
+## Notes
+
+- Idempotent: re-running on an already-compacted backlog archives nothing and
+  leaves the working file byte-unchanged.
+- The `upgrading` skill (Step 7) detects bloat/drift after an upgrade and offers
+  to run this migration via `quick-tasking`. It never edits the backlog directly.
+- Canonical copy of this guide:
+  https://github.com/Attuned-Media/forge/blob/main/docs/migrations/0.22.0-backlog-compaction.md

package/template/.forge/releases.yml

@@ -0,0 +1,29 @@
+# Forge Release Registry — version reservations across concurrent milestones
+#
+# PURPOSE: remove the version number + CHANGELOG slot from per-milestone scope so
+# two milestones running in parallel sessions never collide on your project's
+# version or pick the same number. This is the coordination point both sessions
+# read and append to.
+#
+# COMMITTED + APPEND-ONLY. Each milestone appends exactly ONE entry when it
+# reserves its version (at planning, or at delivery if planning predates this
+# file). Appending — never editing prior entries — is what keeps two sessions
+# from conflicting: distinct lines, no contention. Commit and push the
+# reservation so a parallel session pulls and sees numbers already taken.
+#
+# RULE: the next free version = highest `version:` in this file, bumped by the
+# change's semver level (capability = minor; fix/doc = patch). Delivery NEVER
+# writes a project version that is not reserved here first.
+#
+# RACE NOTE: reserve EARLY (at planning), commit + push the reservation BEFORE
+# editing the version. If two sessions reserve near-simultaneously, the second
+# push rebases onto the first (append-only → no conflict) and re-reads max() to
+# take the next number.
+
+releases: []
+# Example entry shape (delete this comment once you add a real one):
+#   - milestone: 1
+#     version: "0.2.0"
+#     bump: minor
+#     reserved_at: "YYYY-MM-DD"
+#     summary: "one-line description of the milestone"

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/refactor-backlog.yml

@@ -1,8 +1,13 @@
-# Forge Refactor Backlog
-# Auto-managed by the refactoring skill. Items added after milestone audits.
-# Work items via quick-tasking (effort: quick) or Standard tier (effort: standard).
+# Forge Refactor Backlog — actionable items only.
+# Auto-managed by the reviewing skill. Items added after milestone audits;
+# worked via quick-tasking (effort: quick) or Standard tier (effort: standard).
 #
-# Status vocab: pending | in_progress | done | dismissed | deferred
+# Status vocab (the ONLY allowed values): pending | in_progress | done | dismissed | deferred
+#   Actionable = pending | in_progress | deferred   Terminal = done | dismissed
+# Compaction-on-write: every reviewing/quick-tasking write normalizes statuses and
+#   moves terminal items (full record) to .forge/refactor-backlog-archive.yml, so this
+#   file holds only actionable items. No item is deleted — terminal items relocate.
+#   Legacy synonyms are normalized: completed/complete/closed → done; wont_fix/stale → dismissed.
 # Optional fields (lazy migration — only required on entries set to status: deferred going forward):
 #   deferred_at: ISO date when status flipped to deferred
 #   deferred_reason: one-line why; revisited when status changes

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"