forge-orkes 0.17.0 → 0.19.0

package/bin/create-forge.js

@@ -44,6 +44,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,
@@ -275,6 +290,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)) {
@@ -318,28 +337,111 @@ function detectLegacyRequirementsLayout() {
 }
 
 /**
- * After upgrade, surface any detected legacy file layouts that the new framework
- * version no longer writes. Non-interactive — prints a warning with a pointer to
- * the migration guide. Add new detection blocks here as future versions change layout.
+ * Detect a pre-0.17.0 project.yml that has no `layers:` field. Cross-layer
+ * contract detection (planning Step 6.1) reads `layers:`; without it the planner
+ * falls back to a coarse top-level-directory heuristic. Returns true if the field
+ * is absent and no contract index has been seeded. False if project.yml is missing
+ * (not yet initialized) or already migrated.
+ */
+function detectMissingLayersConfig() {
+  const projectYml = path.join(targetDir, '.forge', 'project.yml');
+  if (!fs.existsSync(projectYml)) return false;
+
+  let content;
+  try {
+    content = fs.readFileSync(projectYml, 'utf-8');
+  } catch {
+    return false;
+  }
+
+  // Already declared a layers: key (any value, including []) → migrated.
+  if (/^layers:/m.test(content)) return false;
+  // A seeded contract index implies layers were declared at init → migrated.
+  if (fs.existsSync(path.join(targetDir, '.forge', 'contracts', 'index.yml'))) return false;
+
+  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:|^\s*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.
+ * Non-interactive — prints a warning with a pointer to the migration guide.
+ * Add new detection blocks here as future versions change layout.
  */
 function runPostUpgradeMigrationChecks() {
   const legacyReqs = detectLegacyRequirementsLayout();
-  if (legacyReqs.length === 0) return;
+  if (legacyReqs.length > 0) {
+    console.log('  ⚠  Pre-0.10.0 requirements layout detected');
+    console.log('  ─────────────────────────────────────────');
+    console.log('  Found:');
+    for (const p of legacyReqs) {
+      console.log(`    ${p}`);
+    }
+    console.log();
+    console.log('  Forge 0.10.0+ uses per-milestone files at .forge/requirements/m{N}.yml.');
+    console.log('  Migration guide: .forge/migrations/0.10.0-per-milestone-requirements.md');
+    console.log();
+    console.log('  Run the migration before your next planning cycle. In Claude Code:');
+    console.log('    /forge then hand the guide to quick-tasking, or invoke Skill(quick-tasking)');
+    console.log('    with the guide path as the task definition.');
+    console.log();
+  }
+
+  if (detectMissingLayersConfig()) {
+    console.log('  ⚠  Cross-layer contracts: project.yml has no `layers:` field (Forge 0.17.0)');
+    console.log('  ──────────────────────────────────────────────────────────────────────');
+    console.log('  Forge 0.17.0 added cross-layer contract detection (planning Step 6.1),');
+    console.log('  which reads `layers:` from .forge/project.yml. Your project.yml predates');
+    console.log('  this field, so planning falls back to a coarse top-level-directory heuristic.');
+    console.log();
+    console.log('  Migration guide: .forge/migrations/0.17.0-cross-layer-contracts.md');
+    console.log();
+    console.log('  Quick fix: add a `layers:` list to .forge/project.yml — or `layers: []`');
+    console.log('  for a single-layer project to silence this notice. In Claude Code:');
+    console.log('    /forge then hand the guide to quick-tasking.');
+    console.log();
+  }
 
-  console.log('  ⚠  Pre-0.10.0 requirements layout detected');
-  console.log('  ─────────────────────────────────────────');
-  console.log('  Found:');
-  for (const p of legacyReqs) {
-    console.log(`    ${p}`);
+  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();
   }
-  console.log();
-  console.log('  Forge 0.10.0+ uses per-milestone files at .forge/requirements/m{N}.yml.');
-  console.log('  Migration guide: .forge/migrations/0.10.0-per-milestone-requirements.md');
-  console.log();
-  console.log('  Run the migration before your next planning cycle. In Claude Code:');
-  console.log('    /forge then hand the guide to quick-tasking, or invoke Skill(quick-tasking)');
-  console.log('    with the guide path as the task definition.');
-  console.log();
 }
 
 async function upgrade() {
@@ -391,6 +493,23 @@ async function upgrade() {
     results.removed.push(...dirResult.removed);
   }
 
+  // 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
   const claudeStatus = mergeClaudeMd();
   if (claudeStatus === 'replaced' || claudeStatus === 'appended') {

package/package.json

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

@@ -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 plan counter, update progress
+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}`, `current.last_updated`.
+3. Derive the registry `status`:
+   - **deferred** — `lifecycle.deferred_at` set and not superseded by a later `resumed_at`
+   - **complete** — `current.status == complete`
+   - **not_started** — `current.status == not_started`
+   - **active** — otherwise
+4. Rewrite `index.yml` `milestones:` (sorted by id) as `{id, name, status, last_updated: current.last_updated}`. No other keys.
+
+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,17 +33,24 @@ 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}, {overall_percent}%"*
+   - Found → auto-select: *"Resuming {id}: [{name}] -- {current.status}, {percent}%"*
    - No match → *"No match for '{arg}'. Active:"*
 3. **Multiple (no arg):** Show active + not_started milestones with status + `last_updated`. Default most recent. After main list, show **Deferred:** section (id, name, frozen status `was: {current.status}`, defer date, reason). *"{N} active. Most recent: [{name}] ({current.status}, {date}). This one, or switch?"*
-4. **One:** Auto-select. *"Resuming: [{name}] -- {current.status}, {overall_percent}%"*
+4. **One:** Auto-select. *"Resuming: [{name}] -- {current.status}, {percent}%"*
 5. **None active:** If deferred exist, mention them: *"No active milestones. {N} deferred — 'resume milestone {id}' to reactivate."* Else → init or create.
 6. Load `milestone-{id}.yml`
-7. **Route on `current.status`, NOT `overall_percent`.** Complete only at `complete`. 100% tasks ≠ done -- verifying + reviewing must run.
-8. Report + **immediately route** (Step 3). Show: `current.status`, phase labels (Executed/Verified/Pending/In progress -- **never "Complete" for unverified**), `overall_percent`. **No menus.** Position → action → invoke.
+7. **Route on `current.status`, NOT `{percent}`.** Complete only at `complete`. 100% phases ≠ done -- verifying + reviewing must run.
+8. Report + **immediately route** (Step 3). Show: `current.status`, phase labels (Executed/Verified/Pending/In progress -- **never "Complete" for unverified**), `{percent}`. **No menus.** Position → action → invoke.
+
+**`{percent}` is derived on read — never stored.** Compute it, don't look it up:
+- `total` = number of phases listed for this milestone in `.forge/roadmap.yml` (the milestone's `phases:` list length).
+- `done` = `current.status == complete` → `total`; else `max(0, current.phase - 1)` (phases before the active one count as done).
+- `{percent}` = `total > 0` → `round(done / total * 100)`; `total` unknown/0 → omit the percent from the line.
+
+Uses only signals that stay current (`current.phase`, `current.status`, the roadmap phase list). Old milestone files may still carry a vestigial `progress:` block — ignore it; derive anyway.
 
 Beads enabled (`forge.beads_integration: true`) → `bd prime`. Optional.
 
@@ -50,14 +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`
-   - `progress.last_update: {ISO date}`
-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."*
@@ -65,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
 
@@ -105,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
 
@@ -138,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.
@@ -196,7 +213,7 @@ Tier + state → invoke via `Skill` tool. All phases use `Skill()`.
 
 1. Read `milestone-{id}.yml` → 2. Check advancement → 3. `current.status` → skill → 4. Brief + route:
 
-*"Milestone {id}: {name} | {current.status} → {next} ({model}) | {overall_percent}% | Routing..."*
+*"Milestone {id}: {name} | {current.status} → {next} ({model}) | {percent}% | Routing..."*
 
 Briefing, not prompt -- default = forward.
 
@@ -291,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
 
@@ -308,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,8 +70,8 @@ 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 — increment `progress.overall_percent`, log deviations if any Rule 1-3 applied
-4. Report: fix description, files changed, milestone progress update
+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

@@ -24,7 +24,7 @@ Template directory: `{source}/packages/create-forge/template/`.
 |----------|-------|----------|
 | **Framework-owned** | `.claude/agents/*.md`, `.claude/skills/*/SKILL.md` | Overwrite |
 | **Merge-owned** | `CLAUDE.md`, `.claude/settings.json` | Never auto-overwrite |
-| **Template-only** | `.forge/templates/**` | 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`.
 
@@ -40,7 +40,9 @@ For each framework-owned file in the source template:
 
 ## Step 4: Sync Template-Only Files
 
-Same process as Step 3 for `.forge/templates/**`.
+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
 
@@ -116,6 +118,64 @@ Run the migration now? (yes/no/show guide)
 - **show guide** → read and display the file, then re-ask
 - **no** → note in upgrade report. Skills will continue reading the legacy path as deprecated; new writes still go to the new path, causing split-brain state. Recommend running migration before next planning cycle.
 
+### Pre-0.17.0 missing `layers:` field
+
+Run from project root:
+
+```bash
+grep -q '^layers:' .forge/project.yml || echo "no layers field"
+ls .forge/contracts/index.yml 2>/dev/null
+```
+
+If `project.yml` has no `layers:` key AND `.forge/contracts/index.yml` is absent, surface:
+
+```
+Cross-layer contracts: project.yml predates the `layers:` field (Forge 0.17.0)
+─────────────────────────────────────────────────────────────────────────────
+Forge 0.17.0 added cross-layer contract detection (planning Step 6.1), which
+reads `layers:` from .forge/project.yml. Without it, planning falls back to a
+coarse top-level-directory heuristic.
+
+A migration guide is available at: .forge/migrations/0.17.0-cross-layer-contracts.md
+
+Add the layers field now? (yes/no/show guide)
+```
+
+- **yes** → invoke `quick-tasking` skill, hand it the migration guide as the task definition (identify layers, write `layers:` to project.yml, seed `.forge/contracts/index.yml` for multi-layer projects)
+- **show guide** → read and display the file, then re-ask
+- **no** → note in upgrade report. Planning still works on the fallback heuristic; cross-layer detection is just imprecise until `layers:` is declared. A single-layer project can set `layers: []` to opt out and clear the notice.
+
+`upgrading` never edits `.forge/project.yml` directly — this is the only path that adds the field, via `quick-tasking`.
+
+### Pre-0.19.0 legacy `state/index.yml`
+
+Run from project root:
+
+```bash
+grep -qE '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.17.0-cross-layer-contracts.md

@@ -0,0 +1,110 @@
+# Migration Guide: Cross-Layer Contracts (Forge 0.17.0)
+
+Forge 0.17.0 adds **cross-layer contract detection** to planning (Step 6.1). When a phase introduces or changes an interface that one architectural layer *produces* and another *consumes*, the planner pins the shape in a `contract.md` so an agent building one layer in isolation never has to guess the other's shape.
+
+The detector reads a new `layers:` field from `.forge/project.yml`. Projects created before 0.17.0 have no `layers:` field, so the detector falls back to a coarse top-level-directory heuristic. This guide adds the field (and, for genuinely layered projects, a durable contract index) so detection runs precisely. Safe for an agent to run autonomously.
+
+## Why
+
+`upgrading` syncs framework files and reference templates but, by design, **never edits your live `.forge/project.yml`** — that is user-owned state. So the new `layers:` field is not added automatically on upgrade. Until it exists, planning Step 6.1 cannot read declared layers and falls back to guessing from top-level source directories, which is noisy and imprecise.
+
+Adding `layers:` once makes the detection deterministic. A single-layer project sets `layers: []` to opt out cleanly and silence the upgrade notice.
+
+## Prerequisites
+
+1. Forge framework files upgraded to ≥0.17.0 (run `npx forge-orkes upgrade`, or `Skill(upgrading)` for a local dev sync).
+2. Working tree clean or changes committed — this touches `project.yml` and optionally adds one new file.
+
+## Detection
+
+Run from project root. Migration is suggested if `layers:` is absent:
+
+```bash
+# No `layers:` key in project.yml → migration applies
+grep -q '^layers:' .forge/project.yml || echo "no layers field — migrate"
+
+# Already has a contract index? Then layers were declared at init — likely done.
+ls .forge/contracts/index.yml 2>/dev/null
+```
+
+If `project.yml` already contains a `layers:` key (any value, including `[]`), migration is complete — stop here.
+
+## Migration steps
+
+### 1. Identify the project's layers
+
+A **layer** is a directory whose code is *produced for* or *consumed by* another across a typed boundary — `engine ↔ ui`, `core ↔ plugins`, `api ↔ web`, `native ↔ bindings`. A single cohesive codebase with no internal producer→consumer boundary is **not** layered.
+
+```bash
+ls -d */ src/*/ 2>/dev/null        # top-level + src subdirs as candidates
+# Look for cross-boundary imports: ui importing engine types, generated bindings,
+# ABI/descriptor/schema files shared between directories.
+```
+
+Decisive litmus: *"Would an agent building one directory in isolation have to guess the shape another directory owns?"* If no — it is not a cross-layer boundary.
+
+### 2. Add the `layers:` field to project.yml
+
+**Multi-layer project** — list each layer as `{name, path}`:
+
+```yaml
+layers:
+  - name: engine
+    path: src/engine/
+  - name: ui
+    path: src/ui/
+```
+
+**Single-layer project** — declare empty to opt out and silence the upgrade notice:
+
+```yaml
+layers: []
+```
+
+Place it near the top of `project.yml` (the template puts it just after `tech_stack`). Keep the file under the 5 KB size gate.
+
+### 3. (Multi-layer only) Seed the durable contract index
+
+Standing integration points and their governing ADRs live in `.forge/contracts/index.yml`. Create it from the template so planning Step 6.1 can map an integration point to its authoritative ADR:
+
+```bash
+mkdir -p .forge/contracts
+cp .forge/templates/contracts-index.yml .forge/contracts/index.yml
+```
+
+Then edit `.forge/contracts/index.yml`:
+- Fill `layers:` to match what you wrote in `project.yml`.
+- Add one `integration_points:` entry per standing boundary, each pointing at its governing ADR in `.forge/decisions/`. Leave `integration_points: []` if you have no ADRs yet — the first cross-layer phase will populate it.
+
+Single-layer projects skip this step entirely.
+
+## Post-migration verification
+
+```bash
+# Should print the layers key (non-empty list, or [])
+grep -A4 '^layers:' .forge/project.yml
+
+# Multi-layer projects: index exists and is not the unfilled template
+test -f .forge/contracts/index.yml && echo "contract index present"
+```
+
+Commit as a single change:
+
+```
+chore(forge): declare layers for cross-layer contract detection (0.17.0)
+```
+
+## What changes downstream
+
+After migration, planning Step 6.1 reads declared layers instead of guessing:
+
+- **planning** classifies each phase: Tier 0 (no cross-layer delta), Tier 1 (pin `contract.md`, one plan), or Tier 2 (split into producer/consumer plans against a frozen contract).
+- **executing** runs a seam check on Tier-2 phases — merges the layer plans and verifies the producer's emitted shape matches what the consumer built against.
+- **reviewing** folds each phase `contract.md` delta into its governing ADR (`status: absorbed`) at milestone close.
+- `upgrading` continues to protect `.forge/project.yml` and `.forge/contracts/` as user-owned — it will not overwrite your `layers:` field on future upgrades.
+
+A project that stays `layers: []` keeps single-plan decomposition everywhere — the detector is a no-op, exactly as before 0.17.0.
+
+## Rollback
+
+Reversible by `git revert` of the migration commit. Removing the `layers:` field returns planning to the top-level-directory fallback; no other state is affected.

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

@@ -0,0 +1,99 @@
+# 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 desire_paths/metrics/narrative
+wc -c .forge/state/index.yml                 # » a few hundred bytes once migrated; KBs means legacy
+grep -nE 'desire_paths:|metrics:|current_status:' .forge/state/index.yml   # any hit → migrate
+```
+
+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.). An old `occurrences: N` becomes **N files** (or one file plus a note — recurrence is now derived by counting files, not a stored number). Then delete the `desire_paths:` block from `index.yml`.
+
+### 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 small and registry-only
+grep -qE 'desire_paths:|metrics:|current_status:' .forge/state/index.yml && echo "STILL LEGACY" || echo "OK: registry-only"
+
+# rollup is idempotent — running /forge twice produces no diff to index.yml
+git diff --quiet .forge/state/index.yml && echo "OK: stable" || echo "rollup changed index — commit it"
+
+# desire-paths now live as files
+ls .forge/state/desire-paths/ 2>/dev/null
+```
+
+## 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,24 @@
-# 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):
+#   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,18 +21,16 @@ 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
 
-progress:
-  phases_complete: 0                   # Number of roadmap phases with all tasks done
-  phases_total: 0                      # Total roadmap phases in this milestone
-  current_phase_percent: 0             # Task completion % within the current phase (0-100)
-  overall_percent: 0                   # Task completion % across all phases (0-100)
-  last_update: null                    # ISO 8601 timestamp
-  # NOTE: overall_percent measures TASK completion, not WORKFLOW completion.
-  # A milestone with 100% tasks done still needs verifying, auditing, and refactoring.
-  # The authoritative workflow position is current.status — not this percentage.
-  # Agents: do NOT set overall_percent above 100 or use it to determine if a milestone is "done".
-  # A milestone is only done when current.status == "complete".
+# NO stored progress block. Progress percent is DERIVED on read, never stored.
+# The forge skill computes it from genuinely-maintained signals:
+#   total  = number of phases listed for this milestone in roadmap.yml
+#   done   = current.phase - 1 (phases before the active one), or total when current.status == complete
+#   percent = round(done / total * 100)
+# Storing a percent here drifts — agents reliably advance current.phase/current.status
+# but did not reliably recompute a stored percentage. current.status is authoritative
+# for "is it done?" (only `complete` means done); the derived percent is display-only.
 
 decisions:                             # Locked decisions (synced from context.md)
   - decision: ""

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 -->