forge-orkes 0.18.1 → 0.19.2

package/bin/create-forge.js

@@ -18,6 +18,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'];
 
@@ -44,6 +67,21 @@ function copyDirRecursive(src, dest) {
   return count;
 }
 
+/**
+ * npm strips files literally named `.gitignore` from a published tarball (it
+ * treats them as ignore-rules, not content), so the template ships its forge
+ * gitignore as `gitignore`. Rename it to the real `.forge/.gitignore` dotfile
+ * in the destination. Idempotent: if `gitignore` is absent it does nothing; if
+ * a `.gitignore` already exists it is overwritten with the shipped canonical one.
+ */
+function materializeForgeGitignore(destForge) {
+  const shipped = path.join(destForge, 'gitignore');
+  const real = path.join(destForge, '.gitignore');
+  if (fs.existsSync(shipped)) {
+    fs.renameSync(shipped, real);
+  }
+}
+
 function prompt(question) {
   const rl = readline.createInterface({
     input: process.stdin,
@@ -91,7 +129,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;
 
@@ -123,6 +161,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);
@@ -275,6 +319,10 @@ async function install() {
   const forgeCount = copyDirRecursive(srcForge, destForge);
   console.log(`  Installed .forge/templates/ (${forgeCount} files)`);
 
+  // npm strips files literally named `.gitignore` from the published tarball, so
+  // the template ships it as `gitignore`. Materialize the real dotfile here.
+  materializeForgeGitignore(destForge);
+
   // Stamp version from package.json into settings.json
   const settingsPath = path.join(targetDir, SETTINGS_FILE);
   if (fs.existsSync(settingsPath)) {
@@ -343,6 +391,32 @@ function detectMissingLayersConfig() {
   return true;
 }
 
+/**
+ * Detect a pre-0.19.0 state/index.yml: 0.19.0 makes index.yml a thin derived
+ * registry (regenerated by rollup) and moves desire_paths to append-only files.
+ * A legacy index.yml still carries desire_paths:/metrics:/embedded narrative, or
+ * is large. Returns true if index.yml exists and looks legacy; false if missing
+ * (not yet initialized) or already a slim registry.
+ */
+function detectLegacyStateIndex() {
+  const indexYml = path.join(targetDir, '.forge', 'state', 'index.yml');
+  if (!fs.existsSync(indexYml)) return false;
+
+  let content;
+  try {
+    content = fs.readFileSync(indexYml, 'utf-8');
+  } catch {
+    return false;
+  }
+
+  // Legacy markers: shared accumulators or per-milestone narrative drifted in.
+  if (/^\s*(desire_paths|metrics|current_status):/m.test(content)) return true;
+  // A slim registry is small; KBs of index.yml means narrative crept in.
+  if (Buffer.byteLength(content, 'utf-8') > 4096) return true;
+
+  return false;
+}
+
 /**
  * After upgrade, surface any detected legacy file layouts the new framework
  * version no longer writes, or new config fields older projects lack.
@@ -382,6 +456,21 @@ function runPostUpgradeMigrationChecks() {
     console.log('    /forge then hand the guide to quick-tasking.');
     console.log();
   }
+
+  if (detectLegacyStateIndex()) {
+    console.log('  ⚠  Worktree-safe state: legacy state/index.yml detected (Forge 0.19.0)');
+    console.log('  ────────────────────────────────────────────────────────────────────');
+    console.log('  Forge 0.19.0 makes index.yml a derived registry (regenerated by rollup),');
+    console.log('  moves desire_paths to append-only files, and commits .forge/ state at every');
+    console.log('  phase handoff. Your index.yml predates this — it still carries desire_paths/');
+    console.log('  metrics or embedded narrative, which conflicts across git worktrees.');
+    console.log();
+    console.log('  Migration guide: .forge/migrations/0.19.0-worktree-safe-state.md');
+    console.log();
+    console.log('  This migration edits user-owned state, so it is guided — never automatic.');
+    console.log('  In Claude Code: /forge then hand the guide to quick-tasking.');
+    console.log();
+  }
 }
 
 async function upgrade() {
@@ -408,11 +497,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)
@@ -422,6 +528,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
@@ -431,6 +538,24 @@ 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
+  // named .gitignore); materialize/refresh it as `.forge/.gitignore`.
+  const giSrc = path.join(templateDir, '.forge', 'gitignore');
+  const giDest = path.join(targetDir, '.forge', '.gitignore');
+  if (fs.existsSync(giSrc)) {
+    const newContent = fs.readFileSync(giSrc, 'utf-8');
+    const existed = fs.existsSync(giDest);
+    const oldContent = existed ? fs.readFileSync(giDest, 'utf-8') : null;
+    if (oldContent !== newContent) {
+      fs.mkdirSync(path.dirname(giDest), { recursive: true });
+      fs.writeFileSync(giDest, newContent);
+      results[existed ? 'updated' : 'added'].push('.forge/.gitignore');
+    } else {
+      results.unchanged.push('.forge/.gitignore');
+    }
   }
 
   // 3. Smart-merge CLAUDE.md using section markers
@@ -483,6 +608,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.18.1",
+  "version": "0.19.2",
   "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

@@ -18,7 +18,7 @@ Execute plan tasks. Full dev tools, strict deviation rules. Plan says X, build X
 Plan: `.forge/phases/m{M}-{N}-{name}/plan.md`, context: `.forge/context.md`, state: `.forge/state/milestone-{id}.yml`.
 
 ## Output
-Committed code, updated `milestone-{id}.yml` (progress/deviations), updated `index.yml` (timestamp), execution summary.
+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.
 
 ## Deviation Rules
 
@@ -67,6 +67,7 @@ One change per commit. Stage specific files. Rules 1,3 get own commits. Test bef
 20+ files -> spawn fresh sub-agents via Task. Coordinate via milestone state. Approaching limits -> summarize, spawn fresh. State in `.forge/state/milestone-{id}.yml`.
 
 ### 6. Update State
+Write to `.forge/state/milestone-{id}.yml` only (advance `current` cursor + set `current.last_updated`). Never `index.yml`.
 ```yaml
 progress:
   - task: "{task name}"

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`.
+`.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).
 
 ## Process
 

package/template/.claude/agents/reviewer.md

@@ -27,7 +27,7 @@ Supplied by the reviewing skill at spawn:
 
 Additional context to read on start:
 - `.forge/project.yml` — stack, framework, database, dependencies
-- `.forge/state/milestone-{id}.yml` — milestone id + name
+- `.forge/state/milestone-{id}.yml` — milestone id + name (source of truth; index.yml is a derived registry)
 - `.forge/constitution.md` — active gates (if present)
 - `.forge/deferred-issues.md` — pre-existing failures (architecture mode only)
 

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

@@ -58,7 +58,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/state/milestone-{id}.yml → reported progress
+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

@@ -125,6 +125,7 @@ Document in `.forge/phases/m{M}-{N}-{name}/contracts/`.
 
 1. **Persist** — Confirm ADRs in `.forge/decisions/`, models and contracts in `.forge/phases/m{M}-{N}-{name}/`
 2. **Update state** — Set `current.status` to `planning` in `.forge/state/milestone-{id}.yml`
-3. **Recommend context clear:**
+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:**
 
-*"Architecture decisions written. `/clear` then `/forge` to continue with planning."*
+*"Architecture decisions written and synced. `/clear` then `/forge` to continue with planning."*

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

@@ -294,14 +294,14 @@ If no milestone exists (advisory discussion — forge routed here without tier/m
    - Multi-file, refactor, feature, service changes → **Standard**
    - Major architectural, multi-subsystem, multi-phase → **Full**
 3. **Create milestone.**
-   - Read `.forge/state/index.yml` (create from `.forge/templates/state/index.yml` if missing)
-   - Next ID = max existing ID + 1 (or 1 if none)
+   - Next ID = (max id across existing `.forge/state/milestone-*.yml`) + 1 (or 1 if none)
    - Create `milestone-{id}.yml` from `.forge/templates/state/milestone.yml`:
      - `milestone.id` = {id}, `milestone.name` = brief summary of discussion topic
      - `current.tier` = detected tier
      - `current.status` = `planning` (Standard) / `architecting` (Full) / `not_started` (Quick)
+     - `current.last_updated` = now
      - `decisions[]` = locked decisions from `context.md`
-   - Add entry to `index.yml`: `id`, `name`, `status: active`, `last_updated: now`
+   - Regenerate `.forge/state/index.yml` via the `forge` **Rollup** (read all `milestone-*.yml` → rewrite registry). Do not hand-add the entry. (Create `index.yml` from `.forge/templates/state/index.yml` first if missing.)
 4. **Update `context.md`** — scope decisions under `### M{id} — {name} (locked {date})`
 5. **Quick tier?** → *"Scope is Quick. `/clear` then `/forge {id}` for quick-tasking."* End.
 6. Proceed to Step B with new milestone.
@@ -323,4 +323,5 @@ If milestone exists → skip to Step B.
    - Add any unresolved items to `## Needs Resolution`
    - If `context.md` already exists (post-planning discussion), update relevant sections + log amendments
 2. **Update state** -- `current.status` = `planning` (`architecting` for Full) in milestone yml
-3. **Recommend clear:** *"State written and verified ({N} decisions in context.md). `/clear` then `/forge` for {planning/architecting}."*
+3. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after discussing — m{N} {name}"` (scoped; never `git add .`).
+4. **Recommend clear:** *"State synced and verified ({N} decisions in context.md). `/clear` then `/forge` for {planning/architecting}."*

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

@@ -241,19 +241,19 @@ Do NOT list test failures here — pre-existing failures belong in deferred-issu
 ```
 
 ## State Updates
-1. Update `.forge/state/milestone-{id}.yml` — advance `current` cursor (`current.plan`/`current.task`, and `current.phase` when a phase completes). Do **not** write a progress percent — it is derived on read by the `forge` skill from `current.phase` vs the roadmap phase count.
+1. Update `.forge/state/milestone-{id}.yml` — advance the `current` cursor (`current.plan`/`current.task`, and `current.phase` when a phase completes) and set `current.last_updated`. Do **not** write a progress percent — it is derived on read by the `forge` skill from `current.phase` vs the roadmap phase count.
 2. Record deviations in milestone state
-3. Update `.forge/state/index.yml` — set `last_updated` timestamp
+3. Do **not** write `.forge/state/index.yml` — it is a derived registry; the `forge` rollup regenerates it. Worktree agents write only their own milestone file.
 4. All plans in phase complete → transition to `verifying`
 
 **When deferring an individual phase or task** (writing `status: deferred` or `deferred: true` to a phase/task entry inside the milestone state file — as opposed to milestone-wide defer which goes through the forge skill's lifecycle flow): write `deferred_at` (ISO date today) and `deferred_reason` (one-line) siblings. Old entries without these fields parse fine — lazy migration. These feed the `deferred` aggregator skill.
 
 ## Desire Path Signals
 
-Log to `.forge/state/index.yml → desire_paths` (global, not per-milestone):
-- **Repeated deviations**: Same rule, same reason, more than once → `deviation_pattern`
-- **User corrections**: Repeated correction matching a prior one → `user_correction`, increment count
-- **Agent struggles**: Multiple attempts or user guidance needed → `agent_struggle`
+Append **one file per observation** to `.forge/state/desire-paths/` — copy `.forge/templates/state/desire-path.yml`, name it `{YYYY-MM-DD}-{type}-{milestone}-{slug}.yml`. Never write `index.yml` and never keep a counter; recurrence is derived by globbing (so concurrent worktrees only ever add files).
+- **Repeated deviations**: Same rule, same reason, more than once → `type: deviation_pattern`
+- **User corrections**: Repeated correction matching a prior one → `type: user_correction`
+- **Agent struggles**: Multiple attempts or user guidance needed → `type: agent_struggle`
 
 ## Cross-Layer Seam Check
 
@@ -269,7 +269,8 @@ After **both** layer plans are committed, the executing flow owns one final **se
 5. Leave the contract at `status: ratified` — the `reviewing` skill folds `delta` into the governing ADR (`status: absorbed`) at milestone landing. Do **not** absorb here.
 
 ## Phase Handoff
-1. Confirm persistence — summary documented, commits made, state updated, desire paths logged
+1. Confirm persistence — summary documented, commits made, state updated, desire-path files written
 2. **Run the Cross-Layer Seam Check** (above) if this phase was a Tier-2 contract split
-3. Set `current.status` to `verifying`
-4. Recommend: *"Tasks committed, state updated. `/clear` then `/forge` to continue with verifying."*
+3. Set `current.status` to `verifying` 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 executing — m{N} {phase-name}"`. Scoped — never `git add .`. Per-task code commits already landed; this captures the cursor + desire-path files at the phase boundary.
+5. Recommend: *"Tasks committed, state synced. `/clear` then `/forge` to continue with verifying."*

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

@@ -9,6 +9,22 @@ Entry point. Detect tier, route skills, manage transitions. New projects → ini
 
 ## Step 1: Read State
 
+### 1.0 State Rollup (index.yml is derived)
+
+`index.yml` is a **derived registry** — regenerate it from the milestone files before reading, and after any milestone CRUD (promote/defer/resume/delete). **Never hand-edit `index.yml`.**
+
+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}`, 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}` (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`).
+
 ### 1.1 Milestone Selection
 
 Check state files:
@@ -17,7 +33,7 @@ Check state files:
 3. Neither → init/tier detection.
 
 **With `state/index.yml`:**
-1. Read for active milestones
+1. Run **Rollup (1.0)** to regenerate `index.yml` from the milestone files, then read it for active milestones
 2. **Check arg first.** `/forge 2` or `/forge "Auth system"`:
    - Match IDs (exact) or names (case-insensitive substring)
    - Found → auto-select: *"Resuming {id}: [{name}] -- {current.status}, {percent}%"*
@@ -57,13 +73,8 @@ Check `.forge/refactor-backlog.yml`:
    - `milestone.name: "Promoted from {R-id}: {backlog item title}"`
    - `milestone.origin: {R-id}`
    - `current.tier: standard`, `current.status: researching`
-3. Append to `.forge/state/index.yml` `milestones:`:
-   ```yaml
-   - id: m-{R-id}
-     name: "Promoted from {R-id}: {title}"
-     status: active
-     last_updated: "{ISO date}"
-   ```
+   - `current.last_updated: {ISO date}`
+3. Run **Rollup (1.0)** — regenerates `index.yml` from the new milestone file (do not hand-append the registry entry). New milestone id is `m-{R-id}` from step 1; for numeric ids, allocate by scanning existing `milestone-*.yml` for the max id + 1.
 4. Append to `.forge/roadmap.yml` — one milestone entry + one phase (`refactor-{R-id}`, `requirements_source: refactor-backlog.yml#{R-id}`, `dependencies: []`).
 5. Update `.forge/refactor-backlog.yml` item: `status: in_progress`, add `promoted_to: m-{R-id}`.
 6. Confirm: *"Promoted {R-id} → milestone m-{R-id}. State + roadmap created. Routing to researching."*
@@ -71,16 +82,17 @@ Check `.forge/refactor-backlog.yml`:
 ```text
 backlog pickup → effort: standard
   ├─ write milestone-{m-R-id}.yml (origin: {R-id})
-  ├─ append index.yml + roadmap.yml
+  ├─ rollup index.yml + append roadmap.yml
   ├─ flip backlog item (in_progress + promoted_to)
   └─ fall through → Standard tier routing
 ```
 
 Downstream skills (researching, discussing, planning, executing, verifying, reviewing) see a normal milestone — no special branching.
 
-Check `desire_paths` 3+ occurrences:
-- *"Recurring: [{description}] ({N}x). Fix via [suggestion]?"*
-- Agree → apply, reset. Decline → note, don't nag.
+Check desire paths for 3+ occurrences: glob `.forge/state/desire-paths/*.yml`, group by `type` + normalized `note`, count each group.
+- 3+ in a group → *"Recurring: [{note}] ({N}x). Fix via [suggestion]?"*
+- Agree → apply; archive the group's files to `.forge/state/desire-paths/resolved/`. Decline → note, don't nag.
+- (Occurrence count is derived from file count — there is no counter to reset.)
 
 ### 1.3 Interface Check
 
@@ -111,19 +123,19 @@ No match → fall through to Step 2B (tier detection).
 
 1. Validate: milestone in `index.yml`, status not `deferred`
 2. Extract reason (text after "—"/"-" or second sentence). None → ask: *"Reason for deferring?"*
-3. Update `index.yml`: `status: deferred`, `last_updated`
-4. Update `milestone-{id}.yml`:
+3. Update `milestone-{id}.yml`:
    - `lifecycle.deferred_at` = ISO 8601 now
    - `lifecycle.deferred_reason` = reason
    - `lifecycle.status_before_defer` = copy of `current.status`
+4. Run **Rollup (1.0)** — `index.yml` now derives `status: deferred` from the milestone file (do not hand-edit it).
 5. Update `roadmap.yml`: all phases belonging to this milestone → `status: deferred`
 6. Confirm: *"Deferred milestone {id}: {name}. Was {status}, frozen at {current.status}. Reason: {reason}."*
 
 ### Resume Operation
 
 1. Validate: milestone in `index.yml`, status is `deferred`
-2. Update `index.yml`: `status: active`, `last_updated`
-3. Update `milestone-{id}.yml`: `lifecycle.resumed_at` = ISO 8601 now
+2. Update `milestone-{id}.yml`: `lifecycle.resumed_at` = ISO 8601 now
+3. Run **Rollup (1.0)** — `index.yml` now derives `status: active` from the milestone file.
 4. Confirm + route: *"Resumed milestone {id}: {name}. Picking up at {current.status}."*
 5. Fall through to normal routing (Step 3) — `current.status` already frozen at correct position
 
@@ -144,10 +156,9 @@ No match → fall through to Step 2B (tier detection).
    c. Copy phase dirs → archive `phases/`
    d. Copy research file → archive `research.md` (if exists)
    e. Copy audit files → archive `audits/` (if exists)
-   f. Remove originals after successful copy
-   g. Remove milestone entry from `index.yml`
-   h. Remove milestone + its phases from `roadmap.yml`
-   i. Update `index.yml` `last_updated`
+   f. Remove originals after successful copy (including `milestone-{id}.yml`)
+   g. Remove milestone + its phases from `roadmap.yml`
+   h. Run **Rollup (1.0)** — `index.yml` regenerates without the removed milestone
 5. Confirm: *"Archived milestone {id}: {name} → .forge/archive/milestone-{id}/. Removed from active state."*
 
 **Safety:** Copy-then-delete, not move. If copy fails, originals intact.
@@ -297,7 +308,7 @@ Phase transitions = clear boundaries. **Recommend `/clear`** after writing state
 | architecting | ADRs, data models, API contracts | planning |
 | planning | `.forge/phases/m{M}-{N}-{name}/`, `.forge/requirements/m{N}.yml`, roadmap.yml | executing |
 | executing | Committed code, execution summary, state | verifying |
-| verifying | Verification report, desire paths | reviewing |
+| verifying | Verification report, desire-path files (`state/desire-paths/`) | reviewing |
 
 ### Context Loading on Resume
 
@@ -314,4 +325,4 @@ Branches (any tier, on-demand): debugging (stuck) · designing (UI) · securing
 Phase boundaries: `[clear]` recommended between phases to reset context.
 ```
 
-Update `milestone-{id}.yml` + `index.yml` `last_updated` at each transition.
+Update `milestone-{id}.yml` at each transition (set `current.last_updated`). `index.yml` is **not** hand-edited — it is regenerated by Rollup (1.0) on the next `forge` run.

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

@@ -338,15 +338,7 @@ User selects per stack.
 3. Write `.forge/design-system.md` (if configured)
 4. Write `.forge/contracts/index.yml` (only if `layers:` has 2+ entries) — copy `.forge/templates/contracts-index.yml`, fill `layers:` from the confirmed list, leave `integration_points:` empty (first cross-layer phase populates them via planning Step 6.1)
 5. Init state:
-   - `.forge/state/index.yml`:
-     ```yaml
-     milestones:
-       - id: 1
-         name: "{project name}"
-         status: active                # not_started | active | deferred | complete
-         last_updated: "{date}"
-     ```
-   - `.forge/state/milestone-1.yml`:
+   - `.forge/state/milestone-1.yml` (the source of truth):
      ```yaml
      milestone:
        id: 1
@@ -358,8 +350,12 @@ User selects per stack.
        plan: null
        task: null
        status: not_started
+       last_updated: "{date}"
      ```
+   - `.forge/state/index.yml` — regenerate via the `forge` **Rollup** from the milestone file (do not hand-write the registry). It will derive `status: not_started` for milestone 1.
+   - `.forge/state/desire-paths/` — create the (empty) directory for append-only observations.
 6. Templates as needed
+7. **State-sync commit**: `git add .forge/` then `git commit -m "chore(forge): initialize forge state"` (scoped; never `git add .`) — so the new project's state is in git from the start.
 
 *"Initialized. Ready?"*
 

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

@@ -156,7 +156,7 @@ Before decomposing, classify whether this phase crosses a layer boundary with a
 **Tier-2 ratify gate** (the ONLY interruption; frame as contract-correctness, not "parallelize y/n"):
 > *"This phase changes the {integration point} contract ({governing ADR}). Delta: [summary]. plan-NNa ({producer}) pins it; plan-NNb ({consumer}) builds against it in parallel. Is this contract shape correct?"*
 
-Block the split until confirmed. Override ("keep it one plan") -> log to `state/index.yml` `desire_paths` (recurring overrides tune the threshold), fall back to Tier 1.
+Block the split until confirmed. Override ("keep it one plan") -> append a `type: tier_override` file to `.forge/state/desire-paths/` (recurring overrides tune the threshold), fall back to Tier 1.
 
 **Integration (Tier 2):** layer plans build isolated (per-layer worktrees). The phase's final task is a **seam check** owned by the executing flow (NOT a standing agent): merge the layer branches, verify the shape the producer emits matches what the consumer built against, per `contract.md`.
 
@@ -382,4 +382,5 @@ Done when approved.
 
 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. *"Plan written. `/clear` then `/forge` to continue."*
+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."*

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

@@ -70,7 +70,7 @@ 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 state — advance the `current` cursor if the task moved position, log deviations if any Rule 1-3 applied. Do **not** write a progress percent (derived on read by `forge`).
+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
 
 ### Without Milestone

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

@@ -125,6 +125,7 @@ Artifact uses the Finding Format above, with two adjustments: prepend `Date: {YY
 
 1. **Write artifact** (see Research Artifact section above).
 2. **Update state** — Set `current.status` to `discussing` in `.forge/state/milestone-{id}.yml`
-3. **Recommend context clear:**
+3. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after researching — m{N} {phase-name}"` (scoped; never `git add .`).
+4. **Recommend context clear:**
 
-*"Research complete. State written. `/clear` then `/forge` to continue with discussing."*
+*"Research complete. State synced. `/clear` then `/forge` to continue with discussing."*

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

@@ -335,7 +335,7 @@ Missing? Create from `.forge/templates/refactor-backlog.yml`.
 
 ### Route
 
-**HEALTHY/WARNINGS (accepted):** `current.status: complete` in milestone + index. *"Milestone [{name}] complete. {N} backlog items."* Beads: `bd complete`.
+**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`.
 
 **CRITICAL:** Don't complete. A) Fix->`planning` fix mode->re-verify->re-review. B) Accept risk->doc in report->complete.
 
@@ -387,5 +387,6 @@ If the milestone's phases produced `contract.md` files (planning Step 6.1 Tier 1
 1. Confirm report + backlog
 2. **Run promoted-milestone completion hook** (above) if `milestone.origin` set
 3. **Run Contract Landing** (above) for any cross-layer phases — fold ratified contracts into their ADRs
-4. Set `current.status: complete` and `current.completed_at: "<ISO 8601 timestamp>"`
-5. *"Milestone [{name}] complete. Report: `.forge/audits/milestone-{id}-health-report.md`. {N} backlog items. `/forge` or backlog."*
+4. Set `current.status: complete` and `current.completed_at: "<ISO 8601 timestamp>"` in `milestone-{id}.yml`, then regenerate `index.yml` via the `forge` **Rollup**
+5. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after reviewing — m{N} complete"` (scoped; never `git add .`).
+6. *"Milestone [{name}] complete. Report: `.forge/audits/milestone-{id}-health-report.md`. {N} backlog items. `/forge` or backlog."*

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

@@ -18,16 +18,22 @@ 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 |
-| **Template-only** | `.forge/templates/**`, `.forge/migrations/**` | Overwrite |
+| **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:
@@ -42,6 +48,8 @@ For each framework-owned file in the source template:
 
 Same process as Step 3 for `.forge/templates/**` and `.forge/migrations/**`. (Matches the npm bin's template-only dirs — keeps migration guides installed so the Step 7 pointers resolve via the in-Claude sync route, not just `npx forge-orkes upgrade`.)
 
+**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
 
 **`CLAUDE.md`:**
@@ -145,6 +153,35 @@ Add the layers field now? (yes/no/show guide)
 
 `upgrading` never edits `.forge/project.yml` directly — this is the only path that adds the field, via `quick-tasking`.
 
+### Pre-0.19.0 legacy `state/index.yml`
+
+Run from project root:
+
+```bash
+grep -qE '^[[:space:]]*(desire_paths|metrics|current_status):' .forge/state/index.yml && echo "legacy index"
+wc -c .forge/state/index.yml   # slim registry is a few hundred bytes; KBs = narrative drifted in
+```
+
+If `state/index.yml` carries `desire_paths:`/`metrics:`/embedded narrative or is large, surface:
+
+```
+Worktree-safe state: state/index.yml predates the derived registry (Forge 0.19.0)
+─────────────────────────────────────────────────────────────────────────────────
+Forge 0.19.0 makes index.yml a derived registry (regenerated by rollup), moves
+desire_paths to append-only files, and commits .forge/ at every phase handoff.
+A legacy index.yml conflicts across git worktrees.
+
+A migration guide is available at: .forge/migrations/0.19.0-worktree-safe-state.md
+
+Migrate now? (yes/no/show guide)
+```
+
+- **yes** → invoke `quick-tasking` skill, hand it the migration guide as the task definition (secure state, slim index.yml, split desire_paths into files, drop metrics, regenerate via rollup). This edits user-owned state — confirm each lossy step (the narrative extraction) with the user.
+- **show guide** → read and display the file, then re-ask
+- **no** → note in upgrade report. Skills still run against a legacy index.yml; it just won't gain worktree conflict-safety until migrated.
+
+`upgrading` never edits `.forge/state/` directly — migration runs via `quick-tasking`.
+
 ### Future migrations
 
 Add new detection blocks here for each Forge version that changes file layout. Pattern:

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

@@ -246,7 +246,7 @@ After gap closure:
 
 ## Desire Paths Retrospective
 
-After verification completes (PASSED or GAPS FOUND), run a quick retrospective on framework usage patterns. Update `.forge/state/index.yml → desire_paths` (global, not per-milestone).
+After verification completes (PASSED or GAPS FOUND), run a quick retrospective on framework usage patterns. Record each signal as **one new file** under `.forge/state/desire-paths/` (copy `.forge/templates/state/desire-path.yml`, name `{YYYY-MM-DD}-{type}-{milestone}-{slug}.yml`). Never write `index.yml`; recurrence is derived by globbing.
 
 ### Collect Signals
 
@@ -259,7 +259,7 @@ After verification completes (PASSED or GAPS FOUND), run a quick retrospective o
 
 **3. Skipped steps**: User ask to skip workflow steps? Repeated skips = friction without value.
 
-**4. Recurring friction**: Same problem from previous sessions? Check prior `desire_paths`. Increment counts.
+**4. Recurring friction**: Same problem from previous sessions? Glob `.forge/state/desire-paths/` for matching `type` + `note`; if it recurs, add another observation file (count is the file count — do not edit existing files).
 
 **5. Agent struggles**: Agent need multiple attempts or human intervention? Log task type and failure pattern.
 
@@ -289,8 +289,9 @@ Only suggest at 3+ occurrences. One-off issues are noise.
 
 After PASSED verdict:
 
-1. **Persist** — Confirm verification results documented, desire paths logged to `.forge/state/index.yml`
+1. **Persist** — Confirm verification report documented, desire-path files written to `.forge/state/desire-paths/`
 2. **Update state** — Set `current.status` to `reviewing` in `.forge/state/milestone-{id}.yml`
-3. **Recommend clear:** *"State written. `/clear` then `/forge` for reviewing."*
+3. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after verifying — m{N} {phase-name}"` (scoped; never `git add .`).
+4. **Recommend clear:** *"State synced. `/clear` then `/forge` for reviewing."*
 
 If GAPS found, route back to planning in gap-closure mode. Context clear applies after re-verified PASSED verdict.

package/template/.forge/gitignore

@@ -0,0 +1,30 @@
+# Forge state — durable vs ephemeral.
+#
+# 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
+#   requirements/ phases/ research/ decisions/ contracts/ audits/
+#   refactor-backlog.yml state/ templates/ migrations/
+#
+# The entries below are the ONLY ephemeral exceptions — session- or
+# machine-local artifacts that must never be committed.
+
+# Active-skill marker (session-specific, created by hooks)
+.active-skill
+
+# Upgrade artifacts (generated by npx forge-orkes upgrade)
+upgrade/
+
+# Local dev source path (user-specific)
+dev-source
+
+# OS cruft
+.DS_Store
+
+# M10 orchestrator runtime (per-machine; not part of repo)
+.mcp-server/claims.db
+.mcp-server/*.pid
+.mcp-server/node_modules/
+
+# Orchestration locks
+*.lock

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

@@ -0,0 +1,110 @@
+# Migration Guide: Worktree-Safe Durable State (Forge 0.19.0)
+
+Applies to projects initialized before 0.19.0 — especially any project run across multiple git worktrees.
+
+## Why
+
+Two problems this release fixes:
+
+1. **State drifted out of git.** Skills wrote `.forge/` state to disk but never committed it on a cadence, so milestone progress could live only on your local machine — lost on hardware failure, unrecoverable from a fresh clone.
+2. **`index.yml` conflicted across worktrees.** The global `state/index.yml` was hand-edited on every cursor advance and accumulated per-milestone narrative + shared `desire_paths` lists, so parallel worktrees collided on merge.
+
+0.19.0 makes `index.yml` a **derived registry** (regenerated by rollup from the per-milestone files), moves desire-paths to **append-only files**, and adds a **State Commit Protocol** (every phase handoff commits `.forge/`).
+
+## Prerequisites
+
+- Forge 0.19.0 installed (`npx forge-orkes upgrade`).
+- A clean-ish working tree (commit or stash unrelated changes first).
+- This migration edits **user-owned state** (`index.yml`, `desire_paths`), so it is **guided / human-confirmed** — never run blind. Narrative extraction in step 2 is a judgment call.
+
+## Detection
+
+```bash
+# Bloated/legacy index.yml — large, or still carrying the metrics/desire-paths/narrative blocks
+wc -c .forge/state/index.yml                 # » a few hundred bytes once migrated; KBs means legacy
+# 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`.
+
+## Migration steps
+
+### 1. Secure current state first
+
+Before changing anything, get today's state into git so nothing is lost mid-migration:
+
+```bash
+git add .forge/
+git commit -m "chore(forge): secure .forge state before 0.19.0 migration"
+```
+
+### 2. Slim `index.yml` to the derived registry
+
+Move any per-milestone narrative that drifted into `index.yml` (e.g. paragraph-long `current_status:` values) **out** to the relevant `state/milestone-{id}.yml` prose fields or the milestone's audit report. Reduce each `milestones:` entry to exactly:
+
+```yaml
+milestones:
+  - id: 1
+    name: "…"
+    status: complete        # not_started | active | deferred | complete
+    last_updated: "…"
+```
+
+This is the lossy/judgment step — do it with the agent and confirm each move. The header in `.forge/templates/state/index.yml` shows the target shape.
+
+### 3. Split `desire_paths:` into append-only files
+
+For each entry under the old `desire_paths:` lists, create one file under `.forge/state/desire-paths/` from `.forge/templates/state/desire-path.yml`:
+
+```
+.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.). 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:`
+
+Delete the `metrics:` block from `index.yml` (it had no writers). If you ever want the numbers, derive them from `git log`.
+
+### 5. Regenerate and commit
+
+Run `/forge` once — its rollup step regenerates `index.yml` deterministically from the milestone files. Confirm it matches your slimmed version, then commit:
+
+```bash
+git add .forge/
+git commit -m "chore(forge): migrate to worktree-safe state (0.19.0)"
+```
+
+## Post-migration verification
+
+```bash
+# 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 (active at top level, resolved/ archived separately)
+ls .forge/state/desire-paths/ .forge/state/desire-paths/resolved/ 2>/dev/null
+```
+
+## What changes downstream
+
+- Every phase handoff now emits a `chore(forge): sync state …` commit — your history gains small, regular state commits separate from code commits.
+- Worktree/parallel agents write only their own `milestone-{id}.yml` (+ append desire-path files); `index.yml` is regenerated by the orchestrator/`forge` rollup, so it no longer conflicts.
+- One agent per milestone — same-milestone parallel work is out of scope (the M10 claim layer guards it).
+
+## Rollback
+
+This migration only restructures state files; it does not touch code. To roll back, `git revert` the two migration commits (steps 1 and 5) — your pre-migration `index.yml` returns intact. The 0.19.0 skills will still run against a legacy `index.yml` (they just won't get the conflict-safety benefit until migrated).

package/template/.forge/templates/state/desire-path.yml

@@ -0,0 +1,31 @@
+# Forge Desire-Path Observation — APPEND-ONLY
+#
+# One observation = one new file under state/desire-paths/. NEVER edit an
+# existing observation in place and NEVER keep a mutable occurrence counter —
+# that is what used to make state/index.yml conflict across worktrees.
+#
+# Filename: state/desire-paths/{YYYY-MM-DD}-{type}-{milestone}-{slug}.yml
+#   e.g.   state/desire-paths/2026-06-10-recurring_friction-m7-uncommitted-state.yml
+# The date+type+milestone+slug make the name unique, so concurrent agents in
+# different worktrees only ever ADD files — git never has to merge content.
+#
+# Occurrence counts are DERIVED: the `forge` skill and the `verifying`
+# retrospective glob this directory and group by (type + normalized note).
+# A pattern appearing in 3+ files is a candidate for framework evolution.
+
+type: ""                 # deviation_pattern | tier_override | skipped_step |
+                         # recurring_friction | agent_struggle | user_correction
+milestone: ""            # e.g. "m7" (or "global" if not milestone-scoped)
+skill: ""                # skill that observed it (executing, planning, verifying, ...)
+first_seen: null         # ISO 8601 date this observation was recorded
+related_files: []        # source files involved, if any
+note: ""                 # one-line description — the grouping key for occurrence counts
+
+# Optional type-specific detail (fill what applies to `type`):
+detail:
+  detected: ""           # tier_override: what Forge detected
+  overridden_to: ""      # tier_override: what the user chose
+  rule: null             # deviation_pattern: 1 | 2 | 3
+  correction: ""         # user_correction: the repeated correction
+  failure_pattern: ""    # agent_struggle: how the task fails
+  step: ""               # skipped_step: the step skipped

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

@@ -1,51 +1,25 @@
-# Forge Global State — Cross-Milestone Index
-# Auto-managed by agents. Do not edit manually unless recovering from errors.
-# This file tracks global concerns. Per-milestone state lives in state/milestone-{id}.yml.
-
-milestones:                            # Active milestones and their high-level status
+# Forge Global State — Cross-Milestone Index (DERIVED)
+#
+# This file is REGENERATED by the `forge` skill's rollup step from
+# state/milestone-*.yml. Do NOT hand-edit it, and do NOT add per-milestone
+# cursor data or narrative here — that lives in state/milestone-{id}.yml.
+#
+# Worktree / parallel agent sessions MUST NOT write this file. Editing only the
+# per-milestone files (different files = no git conflict) and regenerating this
+# registry from them is what makes Forge state safe across many worktrees.
+#
+# Rollup is deterministic + idempotent: regenerating from the same milestone
+# files yields identical bytes, so concurrent regenerations never conflict.
+
+milestones:                            # Registry rolled up from state/milestone-{id}.yml
   - id: 1
-    name: ""                           # Human-readable milestone name from roadmap
-    status: not_started                # not_started | active | deferred | complete
-    last_updated: null                 # ISO 8601 timestamp — used for resume default selection
-
-metrics:
-  total_commits: 0
-  total_files_modified: 0
-  verification_passes: 0
-  verification_failures: 0
-  checkpoints_hit: 0
-
-# Desire Paths — Patterns in how the framework is actually used
-# Collected automatically by agents. Reviewed during verification retrospective.
-# When a pattern appears 3+ times, it becomes a candidate for framework evolution.
-# Desire paths are GLOBAL — they track framework usage across all milestones.
-desire_paths:
-  deviation_patterns: []               # Repeated Rule 1/2/3 deviations (same type, same area)
-    # - pattern: ""                    # e.g., "Rule 2: missing null checks in API handlers"
-    #   occurrences: 0
-    #   first_seen: null
-    #   last_seen: null
-
-  tier_overrides: []                   # User overriding auto-detected tier
-    # - detected: ""                   # What Forge detected
-    #   overridden_to: ""              # What user chose instead
-    #   reason: ""                     # Why (if stated)
-
-  skipped_steps: []                    # Steps users consistently skip or rush through
-    # - step: ""                       # e.g., "constitutional gate check"
-    #   skill: ""
-    #   times_skipped: 0
-
-  recurring_friction: []               # Same problem appearing across sessions
-    # - description: ""                # e.g., "Design system violations in form components"
-    #   occurrences: 0
-    #   related_files: []
-
-  agent_struggles: []                  # Tasks where agents consistently fail or need retries
-    # - task_type: ""                  # e.g., "Responsive layout implementation"
-    #   failure_pattern: ""
-    #   occurrences: 0
-
-  user_corrections: []                 # User correcting agent output in the same way repeatedly
-    # - correction: ""                 # e.g., "Always adds 'use client' directive"
-    #   occurrences: 0
+    name: ""                           # mirrors milestone-{id}.yml milestone.name
+    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). (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.

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

@@ -1,7 +1,12 @@
 # Forge Milestone State — Per-Milestone Cursor
 # Auto-managed by agents. Do not edit manually unless recovering from errors.
 # Copy to .forge/state/milestone-{id}.yml for each active milestone.
-# This file tracks one milestone's position. Global state lives in state/index.yml.
+#
+# SINGLE SOURCE OF TRUTH for this milestone. Exactly one agent/session owns this
+# file at a time (enforced by the M10 claim layer). state/index.yml is DERIVED
+# FROM this file by the `forge` rollup step — never the other way around.
+# Because each milestone has its own file, agents on different milestones never
+# touch the same file, so parallel worktrees produce no git conflicts here.
 
 milestone:
   id: null                             # Milestone ID from roadmap
@@ -16,6 +21,7 @@ current:
   task: null                           # Current task number within plan
   status: not_started                  # not_started | researching | discussing | planning | executing | verifying | reviewing | complete
   completed_at: null                    # ISO 8601 timestamp — set when status transitions to complete
+  last_updated: null                    # ISO 8601 — set at each transition; rolled up into index.yml registry for resume ordering
 
 # NO stored progress block. Progress percent is DERIVED on read, never stored.
 # The forge skill computes it from genuinely-maintained signals:

package/template/CLAUDE.md

@@ -130,8 +130,9 @@ State lives in `.forge/`:
 - `design-system.md` — Component mapping table
 - `requirements/m{N}.yml` — Per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. **FR-IDs, DEF-IDs, and NFR-IDs are globally unique across all milestone files** — `FR-001` may exist in exactly one `m{N}.yml`. Before adding a new ID, scan `.forge/requirements/*.yml` for the highest in-use number and continue the sequence. On collision (e.g. during a migration), keep the older milestone's ID and renumber the newer. Concurrent milestones each own their file — no cross-stream contention on file writes, but ID space is shared. Functional requirements may carry M9 e2e gate fields (`e2e`, `observable_outcome`, `observable_outcome_hash`, `validated`) — lazy migration, absent fields default to `e2e:false`/`validated:false`.
 - `roadmap.yml` — Phases, milestones, dependencies
-- `state/index.yml` — Global: active milestones, desire_paths, metrics
-- `state/milestone-{id}.yml` — Per-milestone cursor: position, progress, decisions, blockers
+- `state/index.yml` — DERIVED registry rolled up from milestone files (id, name, status, last_updated). Never hand-edited; never written by worktree agents.
+- `state/milestone-{id}.yml` — Per-milestone cursor (single source of truth): position, progress, decisions, blockers. One owner at a time.
+- `state/desire-paths/` — Append-only framework-usage observations, one file per observation. Occurrence counts derived by globbing (no mutable counter).
 - `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
@@ -143,6 +144,24 @@ State lives in `.forge/`:
 **Format**: YAML for machine state, Markdown for human content.
 **`current.status` is authoritative.** Complete only at `current.status == complete`. 100% tasks ≠ done — still needs verifying + reviewing.
 
+### State Commit Protocol
+
+`.forge/` durable state is **committed**, not just written to disk — so project state survives machine loss and is pullable from any clone. At every phase **Handoff**, after writing state, the completing skill runs one scoped state-sync commit:
+
+```
+git add .forge/        # scoped — respects .gitignore; never `git add .`
+git commit -m "chore(forge): sync state after {phase} — m{N} {phase-name}"
+```
+
+State-sync commits are separate from per-task code commits (which stay atomic during executing).
+
+### State Ownership (multi-worktree safety)
+
+- `state/milestone-{id}.yml` is the **single source of truth**; exactly one agent owns it at a time.
+- Worktree / parallel agents write **only** their own milestone file and **append** desire-path files. They **never** write `index.yml`.
+- `index.yml` is **regenerated by rollup** (read every `milestone-*.yml` → rewrite the registry) by the main/orchestrator session — on `forge` resume and at `orchestrating` teardown. The rollup is deterministic + idempotent, so it **is** the reconcile step — never a hand-merge.
+- Same-milestone parallel work is out of scope, guarded by the M10 claim layer.
+
 ## Deviation Rules
 
 **Full definitions:** `.claude/agents/executor.md`.
@@ -187,4 +206,5 @@ With Beads installed: `bd prime` (session context), `bd ready` (unblocked tasks)
 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 -->