forge-orkes 0.39.0 → 0.42.0

package/bin/create-forge.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const readline = require('readline');
 const { execSync } = require('child_process');
@@ -68,7 +69,7 @@ function compareVersions(a, b) {
 }
 
 // Template-only: reference templates Forge controls
-const TEMPLATE_ONLY_DIRS = ['.forge/templates', '.forge/migrations'];
+const TEMPLATE_ONLY_DIRS = ['.forge/templates', '.forge/migrations', '.forge/adapters'];
 
 // Settings file gets smart-merge (overwrite forge.* keys, preserve user hooks)
 const SETTINGS_FILE = '.claude/settings.json';
@@ -155,7 +156,7 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
   const srcDir = path.join(templateDir, relDir);
   const destDir = path.join(targetDir, relDir);
 
-  const result = { updated: [], added: [], unchanged: [], removed: [], preserved: [] };
+  const result = { updated: [], added: [], unchanged: [], removed: [], preserved: [], removeCandidates: [] };
 
   if (!fs.existsSync(srcDir)) return result;
 
@@ -195,15 +196,13 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
       }
       const destPath = path.join(destDir, rel);
       if (autoClean) {
-        fs.unlinkSync(destPath);
-        // Remove empty parent dirs up to relDir
-        let dir = path.dirname(destPath);
-        while (dir !== destDir && fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
-          fs.rmdirSync(dir);
-          dir = path.dirname(dir);
-        }
+        // Defer deletion — collect the candidate; upgrade() confirms before
+        // removing (R066a). Empty-parent cleanup needs destDir, carried along.
+        result.removeCandidates.push({ destPath, destDir, displayPath });
+      } else {
+        // Template-only dirs: report-only, no deletion here (existing behavior).
+        result.removed.push(displayPath);
       }
-      result.removed.push(path.join(relDir, rel));
     }
   }
 
@@ -357,6 +356,11 @@ async function install() {
   }
 
   console.log(`\n  Forge v${pkgVersion} is ready. Start with: /forge\n`);
+
+  // Presence-gated: a fresh install normally has no Codex adapter, so this is a
+  // no-op — but if the target repo already carries a .agents/ / .codex/ tree
+  // (e.g. migrating in from another setup), note it may need regeneration.
+  noticeCodexAdapter();
 }
 
 /**
@@ -439,14 +443,19 @@ function runPostUpgradeMigrationChecks(installedVersion) {
 
     let stdout = '';
     try {
+      // Trust model: guides were re-synced from the (trusted) npm package in
+      // step 2 above before this runs, so the on-disk content is not
+      // attacker-controlled here; the only residual risk is a runaway/buggy
+      // detection block, bounded by `timeout`.
       stdout = execSync(script, {
         cwd: targetDir,
         shell: '/bin/bash',
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 10000, // 10s — a pathological guide throws (caught below) → no-op, loop continues
       });
     } catch {
-      // A non-zero exit or detection error is a no-op, not a failure — keep going.
+      // A non-zero exit, timeout, or detection error is a no-op, not a failure — keep going.
       continue;
     }
 
@@ -473,6 +482,26 @@ function runPostUpgradeMigrationChecks(installedVersion) {
   }
 }
 
+/**
+ * Sync a single standalone framework-owned file, overwriting when content
+ * differs. Records the outcome in `results` (added/updated/unchanged). Used for
+ * framework files that live outside the recursively-synced dirs (.forge/.gitignore,
+ * .forge/FORGE.md).
+ */
+function syncFrameworkFile(srcPath, destPath, displayName, results) {
+  if (!fs.existsSync(srcPath)) return;
+  const newContent = fs.readFileSync(srcPath, 'utf-8');
+  const existed = fs.existsSync(destPath);
+  const oldContent = existed ? fs.readFileSync(destPath, 'utf-8') : null;
+  if (oldContent !== newContent) {
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.writeFileSync(destPath, newContent);
+    results[existed ? 'updated' : 'added'].push(displayName);
+  } else {
+    results.unchanged.push(displayName);
+  }
+}
+
 async function upgrade() {
   console.log('\n  Forge Upgrade\n');
 
@@ -521,7 +550,9 @@ async function upgrade() {
     preserved: [],
   };
 
-  // 1. Process framework-owned directories (auto-clean stale files)
+  // 1. Process framework-owned directories (stale files are collected for a
+  //    confirmed removal pass below, not deleted inline — R066a).
+  const pendingRemovals = [];
   for (const dir of FRAMEWORK_OWNED_DIRS) {
     const dirResult = upgradeDir(dir, { autoClean: true });
     results.updated.push(...dirResult.updated);
@@ -529,6 +560,7 @@ async function upgrade() {
     results.unchanged.push(...dirResult.unchanged);
     results.removed.push(...dirResult.removed);
     results.preserved.push(...dirResult.preserved);
+    pendingRemovals.push(...dirResult.removeCandidates);
   }
 
   // 2. Process template-only directories
@@ -541,41 +573,59 @@ async function upgrade() {
     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');
+  // 2a. Confirm stale framework-file removals before deleting (R066a). Defaults
+  //     to yes (cleanup is the normal case); auto-confirms when non-interactive
+  //     (CI / piped stdin) or with --force/--yes, preserving prior behavior.
+  if (pendingRemovals.length > 0) {
+    const auto =
+      process.argv.includes('--force') ||
+      process.argv.includes('--yes') ||
+      !process.stdin.isTTY;
+    console.log(`  ${pendingRemovals.length} stale framework file(s) no longer in the template:`);
+    for (const c of pendingRemovals) console.log(`    ${c.displayPath}`);
+    let go = auto;
+    if (!auto) {
+      const ans = await prompt('  Remove these stale framework files? [Y/n] ');
+      go = ans === '' || ans === 'y' || ans === 'yes';
     }
-  }
-
-  // 2c. Sync the framework prose file .forge/FORGE.md (framework-owned single file,
-  // same overwrite-when-different pattern as 2b). MUST run before the CLAUDE.md pass
-  // so a migrated project's import line never points at a missing file.
-  const fmSrc = path.join(templateDir, '.forge', 'FORGE.md');
-  const fmDest = path.join(targetDir, '.forge', 'FORGE.md');
-  if (fs.existsSync(fmSrc)) {
-    const newContent = fs.readFileSync(fmSrc, 'utf-8');
-    const existed = fs.existsSync(fmDest);
-    const oldContent = existed ? fs.readFileSync(fmDest, 'utf-8') : null;
-    if (oldContent !== newContent) {
-      fs.mkdirSync(path.dirname(fmDest), { recursive: true });
-      fs.writeFileSync(fmDest, newContent);
-      results[existed ? 'updated' : 'added'].push('.forge/FORGE.md');
+    if (go) {
+      for (const c of pendingRemovals) {
+        if (fs.existsSync(c.destPath)) fs.unlinkSync(c.destPath);
+        // Remove now-empty parent dirs up to the synced root.
+        let dir = path.dirname(c.destPath);
+        while (dir !== c.destDir && fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
+          fs.rmdirSync(dir);
+          dir = path.dirname(dir);
+        }
+        results.removed.push(c.displayPath);
+      }
     } else {
-      results.unchanged.push('.forge/FORGE.md');
+      console.log('  Keeping stale files (skipped removal).');
+      for (const c of pendingRemovals) {
+        results.preserved.push(`${c.displayPath} (stale — kept by choice)`);
+      }
     }
+    console.log();
   }
 
+  // 2b. Sync the forge .gitignore. Shipped as `gitignore` (npm strips dotfiles
+  // named .gitignore); materialize/refresh it as `.forge/.gitignore`.
+  syncFrameworkFile(
+    path.join(templateDir, '.forge', 'gitignore'),
+    path.join(targetDir, '.forge', '.gitignore'),
+    '.forge/.gitignore',
+    results
+  );
+
+  // 2c. Sync the framework prose file .forge/FORGE.md. MUST run before the
+  // CLAUDE.md pass so a migrated project's import line never points at a missing file.
+  syncFrameworkFile(
+    path.join(templateDir, '.forge', 'FORGE.md'),
+    path.join(targetDir, '.forge', 'FORGE.md'),
+    '.forge/FORGE.md',
+    results
+  );
+
   // 3. Guarantee the CLAUDE.md import line; auto-migrate any legacy embedded section.
   const claudeStatus = ensureClaudeMdImport();
   if (claudeStatus === 'migrated') {
@@ -652,10 +702,90 @@ async function upgrade() {
   // Pass the version captured BEFORE upgradeSettings() stamped the new one, so the
   // migration range is (installed, source] against the freshly-synced guides.
   runPostUpgradeMigrationChecks(installedVersion);
+
+  // Presence-gated advisories (no generation, no rebase — notices only).
+  noticeCodexAdapter();
+  noticeWorktreeLag();
+}
+
+/**
+ * Presence-gated Codex-adapter staleness notice. The bin has no LLM, so it can
+ * only NOTICE that a Codex adapter (.agents/ / .codex/) may be stale after a
+ * .claude/ sync and point to the regeneration route (/upgrading Step 4b). It
+ * never generates, never writes .agents/, never adds .agents to
+ * FRAMEWORK_OWNED_DIRS. Silent when no Codex adapter is present.
+ */
+function noticeCodexAdapter() {
+  const hasCodex =
+    fs.existsSync(path.join(targetDir, '.agents')) ||
+    fs.existsSync(path.join(targetDir, '.codex'));
+  if (!hasCodex) return;
+  console.log('  Codex adapter detected (.agents/ / .codex/).');
+  console.log('    It may now be stale relative to the .claude/ source just synced.');
+  console.log('    This installer does not regenerate it (no LLM). To refresh it,');
+  console.log('    run the `/upgrading` skill — its Codex step offers regeneration');
+  console.log('    from .forge/adapters/codex-generation.md.\n');
+}
+
+/**
+ * Presence-gated worktree-lag notice (paired with /upgrading Step 8). An upgrade
+ * run touches only this checkout; live forge/m-* worktrees keep their
+ * branch-point framework files until rebased. The bin only NOTICES — it never
+ * rebases (a rebase can conflict). Silent when there are no live forge worktrees
+ * or this is not a git repo.
+ */
+function noticeWorktreeLag() {
+  let out;
+  try {
+    out = execSync('git worktree list --porcelain', {
+      cwd: targetDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString();
+  } catch {
+    return; // not a git repo / git unavailable
+  }
+  const lagging = [];
+  let curPath = null;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) curPath = line.slice('worktree '.length).trim();
+    else if (line.startsWith('branch ')) {
+      const br = line.slice('branch '.length).trim();
+      if (/^refs\/heads\/forge\/m-/.test(br) && curPath) {
+        lagging.push({ path: curPath, branch: br.replace('refs/heads/', '') });
+      }
+    }
+  }
+  if (!lagging.length) return;
+  console.log(`  ${lagging.length} live Forge worktree(s) lag this upgrade:`);
+  for (const w of lagging) {
+    console.log(`    ${w.path} (${w.branch})`);
+  }
+  console.log('    They keep their branch-point framework files until rebased.');
+  console.log('    Pick up this upgrade in each:  git -C <path> rebase main');
+  console.log('    (Gitignored carve-outs like .mcp.json / experimental hooks do not');
+  console.log('     rebase — re-run the experimental installer if the upgrade changed them.)\n');
 }
 
 // --- Entry point ---
 
+// cwd sanity (R066c): Forge writes .claude/, .forge/, and CLAUDE.md into the
+// current directory. Refuse the clearly-wrong locations (home dir, filesystem
+// root) unless --force, so an accidental run from the wrong place can't litter
+// framework files across $HOME or /.
+function assertSaneTargetDir() {
+  if (process.argv.includes('--force')) return;
+  const root = path.parse(targetDir).root;
+  if (targetDir === root || targetDir === os.homedir()) {
+    const where = targetDir === os.homedir() ? 'your home directory' : 'the filesystem root';
+    console.error(`  ✖ Refusing to run in ${where} (${targetDir}).`);
+    console.error('    Forge writes .claude/, .forge/, and CLAUDE.md into the current directory —');
+    console.error('    run it from a project root. To override: forge-orkes --force\n');
+    process.exit(1);
+  }
+}
+
+assertSaneTargetDir();
+
 const subcommand = process.argv[2];
 
 if (subcommand === 'upgrade') {

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "forge-orkes",
-  "version": "0.39.0",
+  "version": "0.42.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"
   },
+  "scripts": {
+    "release": "node scripts/release.js",
+    "release:audit": "node scripts/release.js audit"
+  },
   "files": [
     "bin/",
     "template/"

package/template/.claude/agents/tester.md

@@ -66,7 +66,7 @@ suite_audit:
     e2e: N
   runners: ["playwright", "vitest"]
   findings:
-    - category: flake | coverage_gap | anti_pattern | quarantine_candidate | ci_gap
+    - category: flake | coverage-gap | anti-pattern | quarantine-candidate | ci-gap
       file: "e2e/login.spec.ts"
       lines: "42-58"
       severity: critical | warning | info
@@ -141,12 +141,10 @@ Baked rules. Author mode follows all. Violations = rework.
 | Anti-Pattern | Mode | Why it's wrong |
 |--------------|------|----------------|
 | Writing source during audit | analyst | Read-only gate; fixes go through backlog + quick-tasking |
-| `sleep(1000)` or hardcoded waits | author | Masks race, creates flake |
 | Rubber-stamping suite as healthy | analyst | Defeats audit; real suites have findings |
 | Inventing YAML fields | analyst | Breaks testing skill aggregation |
 | Severity inflation / backlog spam | analyst | Degrades signal; reviewer bar applies |
 | Auto-fixing analyst findings | analyst | Violates deferred decision: no auto-queue analyst → author |
-| Shared page across tests | author | Leaks state; breaks test isolation |
-| CSS-selector locators over data-testid | author | Fragile; breaks on style refactor |
-| "Retry until pass" in CI | author | Hides flake; prefer quarantine |
 | Self-switching modes mid-run | either | Mode is set at spawn; exit cleanly and let skill re-spawn |
+
+**Author-mode flake anti-patterns** (`sleep`/hardcoded waits, shared `page` across tests, CSS selectors over `data-testid`, "retry until pass") are the **Flake-Resistant Rules** above — violating any numbered rule is an anti-pattern. Not repeated here.

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

@@ -28,6 +28,8 @@ When an architectural decision conflicts with vertical slicing (e.g., a framewor
 
 ## Architecture Decision Record (ADR)
 
+**Reserve the ADR number first (cross-worktree safety).** Before authoring a new ADR, allocate its number via the **ID Reservation Protocol** (FORGE.md): the next number is `max(highest `kind: adr` in `.forge/reservations.yml`, highest `ADR-NNN` in `.forge/decisions/`) + 1; append one `{kind: adr, id, milestone, reserved_at, summary}` entry to `.forge/reservations.yml`, **commit + push it**, *then* write the ADR file. Bare "scan `decisions/` for the highest + increment" only sees committed state, so two worktrees architecting in parallel both pick the same `ADR-NNN` and collide silently until merge (a multi-file renumber). See FORGE.md → **ID Reservation Protocol** for the full rule. No `reservations.yml` yet ⇒ scan as before and the first reservation creates it (lazy migration).
+
 Record every significant decision in `.forge/decisions/`:
 
 ```markdown

package/template/.claude/skills/chief-of-staff/SKILL.md

@@ -78,29 +78,25 @@ every field has one source and coverage is computed into the artifact. Run the
 rollup at the **start of Show and Sync**, and after any Start/Resume/Pause/Close
 edit to a stream file.
 
-Procedure (deterministic + idempotent — never hand-edit `active.yml`):
-
-1. Glob `.forge/streams/{stream}.yml`. Each → a row: `coordination` = the file's
-   `status`; plus goal, runtime (branch/worktree), ownership summary,
-   `merge_readiness` (from `merge.readiness`), `blocked_by`, `next_action`.
-2. For a stream with `stream.milestone: m-{id}`, read `phase` + activity from
-   `.forge/state/milestone-{id}.yml` (`current.status`, `last_updated`) — do not
-   store workflow phase in the stream file. Linked milestone `deferred`/`complete`/
-   absent → `phase` reflects that (and surface it: a deferred milestone's stream
-   should likely pause; offer it).
-3. Glob active milestones (`index.yml` `status: active`). Any with **no** stream
-   file → emit a derived `stream: implicit` row (phase from the milestone, no
-   coordination) so coverage is guaranteed — an active milestone is never silently
-   missing. Offer to materialize a stream file if it needs coordination (never
-   auto-create).
-4. Derive `merge_queue:` — one entry per stream with `merge.readiness: ready`.
-5. Write `active.yml` (`version`, `updated_at`, derived `streams:` sorted by id,
-   derived `merge_queue:`). No hand-edited keys.
+Procedure: run the **Stream Rollup** exactly as defined in FORGE.md → Stream
+Rollup — the deterministic join + write (glob stream files, derive each row's
+`coordination`/`merge_readiness`/`blocked_by`/`next_action`, read `phase` from the
+linked milestone, emit `stream: implicit` coverage rows, derive `merge_queue` from
+`merge.readiness: ready`, write `active.yml`) is **single-sourced there**. Never
+hand-edit `active.yml`. Beyond that deterministic write, the Chief adds two
+**interactive** steps the boot-time rollup omits:
+
+- **Deferred/complete linked milestone** → when a stream's `stream.milestone`
+  points at a `deferred`/`complete` milestone, surface it: the stream should
+  likely pause — offer it.
+- **Implicit row needs coordination** → when an active milestone has no stream
+  file (the rollup emits a `stream: implicit` row for coverage), offer to
+  materialize a stream file for it. **Never auto-create.**
 
 Note: invoked directly, `/chief-of-staff` does not run `forge`'s milestone Rollup,
-so `index.yml` may be slightly stale; read it as-is for step 3 and suggest a
-`/forge` pass if it looks off. The Chief writes `active.yml` (derived class); it
-never writes `index.yml` or any milestone file.
+so `index.yml` may be slightly stale; read it as-is when deriving implicit-row
+coverage and suggest a `/forge` pass if it looks off. The Chief writes `active.yml`
+(derived class); it never writes `index.yml` or any milestone file.
 
 ## Start Stream Flow
 
@@ -172,7 +168,7 @@ existing M10 state.
    - `ownership.owned_surfaces`, `shared_surfaces`, and `read_only_surfaces`
      as empty lists if unknown
    - `blockers` from milestone blockers or degraded/refused notes
-   - `context.milestone` pointing at `.forge/state/milestone-{id}.yml`
+   - `stream.milestone: "m-{id}"` — the rollup join key (phase derives from the linked milestone's state); this is the same link step 8 confirms
 7. Populate the stream brief with:
    - current milestone/phase/status
    - worktree path and branch
@@ -282,10 +278,11 @@ merge/rebase), and **cross-stream merge order**. A checkpoint stream that is
 cleanly auto-publishing needs no nudge here.
 
 1. **Ready-to-merge surfacing.** From `active.yml`, collect streams with
-   `status: ready` (and any `merge_queue` entries). For each, run the Merge Safe
-   Flow conditions. Unblocked + no conflicts → list under **Ready to merge** with
-   a one-line *"ready — integrate now"* and, if known, how long it has been ready
-   (from the stream's `last_sync` / brief date). Add/refresh its `merge_queue`
+   `coordination: ready` (the derived-row coordination field) plus any
+   `merge_queue` entries (derived from `merge.readiness: ready`). For each, run the
+   Merge Safe Flow conditions. Unblocked + no conflicts → list under **Ready to
+   merge** with a one-line *"ready — integrate now"* and, if known, how long it has
+   been ready (from the stream's `stream.updated_at` / brief date). Add/refresh its `merge_queue`
    entry (`status: waiting`). Blocked → list the named reason instead.
 2. **Idle-ready nudge.** A stream that has sat `ready` across **multiple Show/Sync
    passes** or whose branch is mergeable but untouched is the cadence smell.

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

@@ -32,8 +32,10 @@ git worktree list --porcelain 2>/dev/null \
 - Surfacing continues to Rollup + selection — but it is **no longer purely informational**. Enforcement is deferred to **1.1a**, which fires only for the *selected* milestone (booting from main to work an unrelated milestone stays free). Record which worktrees were reported here so 1.1a can match the selection against them. (See FORGE.md State Ownership for the full taxonomy.)
 
 **If `in_main_checkout: false`** (this session is itself a worktree) AND `forge.worktree_rebase_check: true` in `.forge/project.yml` (default `false` — opt-in):
-- Diff `.forge/` between this worktree's `HEAD` and `origin/main` (or `main` if no remote), restricted to the **shared-mutable** + **stable-shared** files per the FORGE.md taxonomy (`context.md`, `refactor-backlog.yml`, `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `requirements/m{N}.yml`).
-- Any differ → surface: *"`{file}` has changed on main since this worktree branched. Pull just this file (`git restore --source main -- {file}`), rebase, or skip?"* — operator decides.
+- Diff this worktree's `HEAD` against `origin/main` (or `main` if no remote) across **two** surfaces:
+  - **(a) shared `.forge/` state** — the **shared-mutable** + **stable-shared** files per the FORGE.md taxonomy: `context.md`, `refactor-backlog.yml`, `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `requirements/m{N}.yml`, `FORGE.md`.
+  - **(b) framework surface** — `.claude/skills/`, `.claude/agents/`, `.forge/FORGE.md` — the files a `/upgrading` run changes. This catches a **framework upgrade that landed on main after this worktree branched**: `upgrading` Step 8's producer-side offer is the primary path, but a worktree created (or forgotten) since the upgrade only finds out here. (Gitignored framework files — `.mcp.json`, experimental hooks — won't show in the diff; they propagate via the experimental installer, not git.)
+- Any differ → surface: *"`{file}` has changed on main since this worktree branched. Pull just this file (`git restore --source main -- {file}`), rebase, or skip?"* — operator decides. For a framework-surface (b) hit, lead with rebase (a partial restore of skills/agents is rarely what you want).
 - Setting absent or `false` → no-op.
 
 **Integration flag check (consumer — worktree only).** When `in_main_checkout: false`, check whether a checkpoint publish has landed work on main that this worktree should pull (FORGE.md → Stream Integration Checkpoints). Event-driven, not polled — read the flag first; act only if it is set:
@@ -52,7 +54,7 @@ Cross-machine note: the flag file is machine-local, so a worktree on another lap
 - Mismatch → one advisory line: *"recorded worktree path `{path}` for m{id} is not under the convention root `{root}` — likely a manual `git worktree add` or pre-convention state. Fix: `git worktree move {path} {root}/{anchor}` then update the recorded path. (Advisory; honors `orchestration.worktree_root`.)"*
 - Parent dir under the root, or no recorded path → silent. An explicit `orchestration.worktree_root` is honored by construction (the override **is** the root compared against), so a deliberately relocated root never false-warns.
 
-**Stream Rollup (active.yml is derived).** If `.forge/streams/` has any stream files, regenerate `.forge/streams/active.yml` from them + active milestones per FORGE.md → Stream Rollup, the same way step 1.0 regenerates `index.yml`. `active.yml` is derived — never read it as authoritative without rolling up first, and never hand-edit it. Runs in the main checkout (worktrees never write `active.yml`). No `streams/` dir → skip.
+**Stream Rollup (active.yml is derived).** If `.forge/streams/` has any stream files, regenerate `.forge/streams/active.yml` from them + active milestones per FORGE.md → Stream Rollup, the same way step 1.0 regenerates `index.yml`. **Run the 1.0 State Rollup (below) first** so `index.yml` is fresh — the Stream Rollup reads active milestones from it for implicit-row coverage, so on a boot where a just-merged milestone promotion lands, a stale `index.yml` would silently drop that milestone's coverage row. `active.yml` is derived — never read it as authoritative without rolling up first, and never hand-edit it. Runs in the main checkout (worktrees never write `active.yml`). No `streams/` dir → skip.
 
 **Ready-to-merge nudge (main checkout / streams without checkpoints).** From the just-regenerated `active.yml`, scan for streams with `coordination: ready` or a non-empty `merge_queue` **that are not auto-publishing via checkpoints**. Any present → one line: *"{N} stream(s) ready to merge — run `/chief-of-staff` (merge safe) to integrate."* Pointer only — the cadence logic lives in the Chief's Merge Cadence Check; `forge` never merges. Nothing pending → silent.
 
@@ -123,7 +125,7 @@ Single-owner-mutable state must be written by exactly one checkout. When this se
 Resolve the worktree path from the recorded `lifecycle.worktree_path` / `runtime.worktree`, or — if absent — from the base **Worktree Convention** (FORGE.md).
 
 **Completed milestone + live worktree → finalize, not gate (precedence).** The gate assumes the live worktree holds *in-progress, owned* work. A worktree whose milestone file is already `current.status: complete` — it set complete and merged to main, then a fresh main boot lands here — needs the **opposite** of a write-block: it needs wrapping up. So when the selected milestone is `complete` **and** still has a live worktree, do **not** raise the four-option ownership gate. Surface the finalize offer instead: *"m{id} is complete but its worktree `{path}` (`{branch}`) is still live — roll up `index.yml` and tear down the worktree + branch? [yes / keep]"*.
-- **yes** → confirm, then `git worktree remove {path}`, delete the branch, clear `lifecycle.worktree_*` on the milestone, and run **Rollup (1.0)**. (Never auto-remove without the explicit yes.)
+- **yes** → confirm, then `git worktree remove {path}`, delete the branch, clear `lifecycle.worktree_*` on the milestone, and run **Rollup (1.0)**. If a stream file backs this milestone, also close it — clear `runtime.worktree`, set `stream.status: closed` (or prompt) — and run the **Stream Rollup** so `active.yml` drops the row pointing at the torn-down worktree. (Never auto-remove without the explicit yes.)
 - **keep** → leave it; impose no write-block — a `complete` milestone has no live cursor left to fork.
 
 The gate (below) and this finalize path are mutually exclusive on `current.status`: `complete` → finalize; any other status with a live worktree → gate.
@@ -183,30 +185,7 @@ Downstream skills (researching, discussing, planning, executing, verifying, revi
 
 **Skip declined groups first.** Glob `.forge/state/desire-paths/declined/*.yml`; skip any group whose key (`type` + normalized `note`) already has a decline file — it stays dismissed, no re-nag.
 
-**Surface at 3+.** For each remaining group with 3+ files, name a CONCRETE fix from this table (co-located here so the reader that acts carries the map):
-
-| Type | Suggested evolution |
-|------|---------------------|
-| `deviation_pattern` | Add a pre-check to planning, or a new constitutional article |
-| `tier_override` | Adjust tier-detection heuristics in the forge skill |
-| `skipped_step` | Make the step optional, or merge it into another |
-| `recurring_friction` | Add guidance to the relevant skill, or create a template |
-| `agent_struggle` | Add examples or anti-patterns to the relevant skill |
-| `user_correction` | Add a rule to constitution / context.md / the relevant skill |
-
-Prompt: *"Recurring: [{note}] ({N}x, scope:{scope}). Fix: [concrete suggestion from table]. Apply / decline?"*
-
-- **Agree** → apply the fix; archive the group's files to `.forge/state/desire-paths/resolved/`.
-- **Decline** → write ONE file `.forge/state/desire-paths/declined/{date}-{type}-{slug}.yml` with `{group_key, declined_at, reason}`, so it never re-prompts. (Replaces the old "note, don't nag" — which wrote nothing, so the 3+ files re-nagged every boot.)
-- (Occurrence count is derived from file count — there is no counter to reset.)
-
-**Upstream transport — for `scope: framework` groups only** (ADR-012). A framework-scope signal's fix targets Forge's own skills/templates, which live in the Forge repo, not this project. So in addition to the Apply/decline prompt above:
-
-1. **Always** write a portable, self-contained block to `.forge/state/desire-paths/upstream/{date}-{type}-{slug}.md` — pattern, occurrence count, the sibling observation filenames, the suggested evolution (from the table), and `suggestion_target`. Formatted to paste cleanly into a GH issue. This is the durable floor; it survives even with no network/tooling.
-2. **Resolve `forge.upstream_repo`** from `project.yml`; if absent, default to `https://github.com/zayneupton/forge`. If resolvable **and** `gh` is on PATH → offer (don't auto-run — it publishes externally): `gh issue create --repo {upstream_repo} --title "[desire-path] {note}" --body-file {block}`. **The GH issue is the real close** — tracked, central, survives machine loss.
-3. If `gh`/url unavailable → note the block is on disk and harvestable by `upgrading` (which runs from a local Forge clone) into `{source}/docs/desire-paths-inbox/`.
-
-`project`-scope groups keep the in-project flow above — no upstream. Applying a framework fix locally (when this *is* the Forge repo) and routing it upstream are not mutually exclusive: in a user project you route; in the Forge repo you apply.
+**Surface at 3+.** For each remaining group with 3+ files (declined groups already skipped), **load `desire-paths-review.md` in this skill dir and follow it** — it carries the concrete fix-suggestion map (per `type`), the Apply/decline mechanics (archive to `resolved/` on apply; write a `declined/` file on decline — no re-nag), and the upstream transport for `scope: framework` signals (portable block + optional `gh issue` against `forge.upstream_repo`). Groups under 3 (the common boot) → nothing to surface; skip the load. (Occurrence count is derived from file count — no counter to reset.)
 
 ### 1.3 Interface Check
 

package/template/.claude/skills/forge/desire-paths-review.md

@@ -0,0 +1,37 @@
+# Desire-Path Review — Surfacing & Fix Map
+
+Loaded by `forge` boot (SKILL.md Step 1.2) **only when a desire-path group reaches
+3+ occurrences**. The cheap part of the review — glob, skip declined groups, count
+per group — stays inline in SKILL.md; this file carries the fix-suggestion map,
+the apply/decline mechanics, and the upstream transport for framework-scope
+signals, so the common boot (no group at 3+) never loads it.
+
+## Surface at 3+ — concrete fix map
+
+For each remaining group with 3+ files, name a CONCRETE fix from this table:
+
+| Type | Suggested evolution |
+|------|---------------------|
+| `deviation_pattern` | Add a pre-check to planning, or a new constitutional article |
+| `tier_override` | Adjust tier-detection heuristics in the forge skill |
+| `skipped_step` | Make the step optional, or merge it into another |
+| `recurring_friction` | Add guidance to the relevant skill, or create a template |
+| `agent_struggle` | Add examples or anti-patterns to the relevant skill |
+| `user_correction` | Add a rule to constitution / context.md / the relevant skill |
+
+Prompt: *"Recurring: [{note}] ({N}x, scope:{scope}). Fix: [concrete suggestion from table]. Apply / decline?"*
+
+- **Agree** → apply the fix; archive the group's files to `.forge/state/desire-paths/resolved/`.
+- **Decline** → write ONE file `.forge/state/desire-paths/declined/{date}-{type}-{slug}.yml` with `{group_key, declined_at, reason}`, so it never re-prompts. (Replaces the old "note, don't nag" — which wrote nothing, so the 3+ files re-nagged every boot.)
+- (Occurrence count is derived from file count — there is no counter to reset.)
+
+## Upstream transport — `scope: framework` groups only (ADR-012)
+
+A framework-scope signal's fix targets Forge's own skills/templates, which live in
+the Forge repo, not this project. So in addition to the Apply/decline prompt above:
+
+1. **Always** write a portable, self-contained block to `.forge/state/desire-paths/upstream/{date}-{type}-{slug}.md` — pattern, occurrence count, the sibling observation filenames, the suggested evolution (from the table), and `suggestion_target`. Formatted to paste cleanly into a GH issue. This is the durable floor; it survives even with no network/tooling.
+2. **Resolve `forge.upstream_repo`** from `project.yml`; if absent, default to `https://github.com/zayneupton/forge`. If resolvable **and** `gh` is on PATH → offer (don't auto-run — it publishes externally): `gh issue create --repo {upstream_repo} --title "[desire-path] {note}" --body-file {block}`. **The GH issue is the real close** — tracked, central, survives machine loss.
+3. If `gh`/url unavailable → note the block is on disk and harvestable by `upgrading` (which runs from a local Forge clone) into `{source}/docs/desire-paths-inbox/`.
+
+`project`-scope groups keep the in-project flow above — no upstream. Applying a framework fix locally (when this *is* the Forge repo) and routing it upstream are not mutually exclusive: in a user project you route; in the Forge repo you apply.

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

@@ -76,11 +76,11 @@ Resolve current milestone ID from `.forge/state/index.yml` (active milestone) or
 
 If missing, create from `.forge/templates/requirements.yml`:
 1. Extract from user description + research
-2. IDs: FR-001, FR-002... **Globally unique across milestones** -- check existing `.forge/requirements/*.yml` for highest FR-ID, continue sequence
+2. IDs: FR-001, FR-002... **Globally unique across milestones.** Allocate via the **ID Reservation Protocol** (FORGE.md): next = `max(highest `kind: fr` in `.forge/reservations.yml`, highest FR in `.forge/requirements/*.yml`) + 1; append `{kind: fr, id, milestone, reserved_at, summary}` to `.forge/reservations.yml`, **commit + push**, then write the FR. The reservation is what keeps concurrent worktrees from silently claiming the same FR number (bare scan-and-increment collides — see FORGE.md / ADR-016). No `reservations.yml` ⇒ scan as before; first reservation creates it.
 3. Acceptance: Given/When/Then
 4. Uncertain: `[NEEDS CLARIFICATION]`
 5. P1 (must) / P2 (should) / P3 (nice)
-6. Deferred: DEF-001... (also globally unique)
+6. Deferred: DEF-001..., and NFR-001... — **also globally unique; reserve the same way** (`kind: def` / `kind: nfr`) before writing.
 
 **E2E gate (M9):** For each functional requirement being added or refined:
 1. Decide `e2e: true|false` -- does this story need a post-validation e2e test?
@@ -135,6 +135,8 @@ This is the common case when starting a new milestone alongside an existing one.
 
 If a sibling milestone (e.g. m50) has state + requirements but is missing from `roadmap.yml`, that's a pre-existing gap -- flag to user, don't silently backfill.
 
+**Promoted-from-backlog milestone (`milestone.origin` set).** If `state/milestone-{N}.yml` carries `milestone.origin: {R-id}` (set by `forge` Step 1.2 when promoting a Standard-tier refactor item), no extra bookkeeping is needed here — the originating backlog item is flipped to `done` automatically when the milestone completes (see `reviewing` → **Promoted Milestone Completion Hook**). Just plan it as a normal milestone.
+
 ## Step 6: Decompose Tasks
 
 ### Step 6.1: Cross-Layer Contract Detection
@@ -364,7 +366,7 @@ Prompt pattern:
 
 - **yes** — defer to `testing` after planning completes; note in plan frontmatter
 - **no** — document rationale in `context.md` Discretion Areas
-- **later** — surface again at verifying gate if UI tests still missing
+- **later** — rides on the verifying **Interface Testing Gate**: when `interface` is declared in `project.yml`, that gate already BLOCKS at verifying if UI tests are still missing (no separate planning hook needed)
 
 Decision captured once, pre-code. Does not block planning.
 

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

@@ -52,15 +52,15 @@ Read: .github/workflows/* → CI config (ci-check mode, analyst CI sub-check)
 3. Agent appends actionable items to `.forge/refactor-backlog.yml`:
    ```yaml
    - id: T-{NNN}
-     source: testing-analyst
-     date: YYYY-MM-DD
-     category: flake | coverage-gap | anti-pattern | quarantine
+     milestone: {active milestone id}
+     category: flake | coverage-gap | anti-pattern | quarantine-candidate | ci-gap
      file: "path/to/test.spec.ts"
      lines: "NN-NN"
      description: "What's wrong"
      effort: quick | standard
      suggested_approach: "How to fix"
      status: pending
+     added: "YYYY-MM-DD"
    ```
    ID numbering: read existing backlog, find max T-NNN, increment. No gaps.
 4. Receive agent YAML output (`suite_audit:` block). Review for completeness.

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

@@ -81,12 +81,28 @@ For each skill dir present in the project's `.claude/skills/` but **absent from
 
 ## Step 4: Sync Template-Only Files
 
-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`.)
+Same process as Step 3 for `.forge/templates/**`, `.forge/migrations/**`, and `.forge/adapters/**`. (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`. `.forge/adapters/**` ships the platform-adapter generation protocols, e.g. `codex-generation.md`, so the Step 4b Codex step can hand it to `quick-tasking`.)
 
 **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.
 
 **Sync the framework prose file `.forge/FORGE.md`** (framework-owned single file — it holds the `# Forge` prose, formerly embedded in CLAUDE.md). Copy/refresh `{source}/packages/create-forge/template/.forge/FORGE.md` → `.forge/FORGE.md` (overwrite when different; report added/updated/unchanged). **Run this BEFORE the Step 5 CLAUDE.md pass** so a migrated import line never points at a missing file.
 
+## Step 4b: Codex Adapter (presence-gated — detect + offer, never auto)
+
+Forge ships a **Codex/AGENTS adapter** (`.agents/skills/` + `.codex/` wiring) for projects run on Codex. It is a *derived translation* of the canonical `.claude/` skills (ADR-014) and drifts whenever core moves — but `upgrading` syncs only `.claude/`, so the Codex adapter would silently rot. This step makes that staleness visible and one-keystroke-fixable, **without** ever generating it here (only an agent-as-Codex can author it natively).
+
+1. **Presence gate.** Glob the project root for `.agents/` and `.codex/`. **Neither exists → skip silently** — no prose, no prompt (Claude-only / greenfield projects are unaffected).
+2. **Either exists → report + offer.** The Codex adapter is present and may be stale relative to the `.claude/` source just synced in Steps 3–4. Offer regeneration:
+   ```
+   Codex adapter detected (.agents/ / .codex/). It may be stale vs the .claude/
+   source just synced. Regenerate it now? (yes / no)
+   ```
+   - **yes** → invoke `quick-tasking`, handing it `.forge/adapters/codex-generation.md` as the task definition (the **same delegation pattern as Step 7 migrations**). The protocol instructs an agent-as-Codex to author `.agents/` + `.codex/` from source using native primitives; a human reviews the diff before commit. `upgrading` itself **never** writes `.agents/` and never performs the translation.
+   - **no** → record `Codex adapter: stale, declined` for the Step 6 report.
+3. **Report line.** Add a `Codex adapter:` line to the Step 6 report — one of `regenerated` / `stale, declined` / `not present`.
+
+Presence-gated, never auto-runs, regeneration is agent-run via `quick-tasking`. The protocol doc itself reaches the project via the Step 4 `.forge/adapters/**` sync.
+
 ## Step 5: Handle Import-Managed + Merge-Owned Files
 
 **`CLAUDE.md` (import-managed — one-pass auto-migration, no prompt):** mirror the npm bin's `ensureClaudeMdImport()` case-for-case. The framework prose lives in `.forge/FORGE.md` (synced in Step 4) — never write prose into CLAUDE.md, and never modify user content outside a legacy forge section.
@@ -125,6 +141,8 @@ Experimental skills: {N}
   - orchestrating (from experimental/m10) — updated  [or: unchanged / STALE, declined]
   - ...
 
+Codex adapter: regenerated   [or: stale, declined / not present]
+
 Removed from template: {N} files
   - .claude/agents/old-agent.md (still in your project)
   - ...
@@ -175,3 +193,21 @@ Migrate now? (yes/no/show guide)
 ### Why there is no bookkeeping
 
 Recording "crossed" guides is implicit in the range. Once Step 5 stamps `forge.version` to `source`, a later run's range `(new installed, source]` excludes every guide already crossed — so nothing re-detects, with **no ledger or marker file**. The range also closes the install-run blind spot: detection keys off the guides **freshly synced this run** (Step 4) plus the **pre-stamp installed version**, so the run that installs new detection behavior uses the new guides, not this skill's own pre-sync prose.
+
+## Step 8: Propagate to Live Worktrees (offer, never auto)
+
+The sync lands framework files (`.claude/skills/`, `.claude/agents/`, `.forge/FORGE.md`, templates) in **this checkout only**. A live Forge worktree keeps running its branch-point copies until it pulls main in — and nothing else surfaces this: the integration flag (`.git/forge/integration-pending`) fires only on a verified **work** checkpoint, never on an upgrade, and `forge.worktree_rebase_check` is opt-in. So close the loop here, where the upgrade actually happened.
+
+1. **Main checkout only.** `git rev-parse --git-dir` == `--git-common-dir` → main; differ → this session **is** a worktree, so skip (run `/upgrading` from main to propagate). No remote/not a git repo → skip.
+2. **Commit the sync first** — a worktree can only rebase onto committed history, so uncommitted synced files won't propagate. If the sync is unstaged, prompt: *"Commit this upgrade on main before propagating? (e.g. `chore(forge): upgrade to v{new}`)"* and wait.
+3. **Enumerate live worktrees:** `git worktree list --porcelain`, branches matching `refs/heads/forge/m-*` (same scan as the `forge` boot preflight). None → done, silent.
+4. **Offer — never auto** (a rebase can conflict and needs human judgment):
+   ```
+   {N} live worktree(s) lag this upgrade (v{old} → v{new}):
+     - {path} ({branch})
+   Pick up v{new} in each:  git -C {path} rebase main
+   Rebase now? (each / list-only / skip)
+   ```
+   - **each** → run `git -C {path} rebase main` per worktree; on conflict, **stop that one**, report it, and move on — never force, never auto-resolve.
+   - **list-only / skip** → print the commands; the operator runs them when each worktree is at a safe stopping point.
+5. **Gitignored carve-outs don't rebase.** `.mcp.json`, experimental hooks (e.g. M10 `forge-claim-check*.sh`), and anything else gitignored is **not** carried by a rebase. If the upgrade changed them (e.g. an experimental skill was re-synced in Step 3b), each worktree must re-run the experimental installer (`experimental/{pkg}/install.sh`) — a rebase alone leaves them stale. Surface this line whenever Step 3b reported an experimental re-sync.

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

@@ -302,7 +302,7 @@ If GAPS found, route back to planning in gap-closure mode. Context clear applies
 Realizes producer-side continuous integration (FORGE.md → Stream Integration Checkpoints). Runs at Phase Handoff step 5, **only when all hold**:
 
 - the phase's plan frontmatter has `integration_checkpoint: true`;
-- the verdict is PASSED **and** `current.human_verified` is set (where required) — never publish unverified work;
+- the verdict is PASSED — never publish unverified work. (`current.human_verified` gates milestone **close**, *not* per-checkpoint publish: a non-final checkpoint phase publishes on PASS alone; the milestone's **final** checkpoint coincides with close, where the Human Verification Gate applies — so in practice only the last checkpoint also requires `human_verified`.)
 - the session is a **worktree** (`git rev-parse --git-dir` ≠ `--git-common-dir`). In a single checkout, skip — there is no main to fast-forward into.
 
 Then publish **fast-forward only**:

package/template/.forge/FORGE.md

@@ -125,14 +125,15 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | `streams/{stream}.yml` | 15 KB | Stream state stays resumable without becoming history |
 | `streams/{stream}/brief.md` | 8 KB | Stream context packet must fit into active session context |
 | `streams/{stream}/packages/{id}.yml` | 10 KB | Delegated work contract stays bounded |
+| `reservations.yml` | 50 KB | Append-only ID-reservation registry; one short line per ADR/DEF/FR/NFR reserved |
 
 ### Accumulating Artifacts
 
 Every new accumulating artifact needs: owner, size gate, archive/compaction rule,
 `derived` vs source-of-truth status, and migration behavior. Defaults:
 
-- `roadmap.yml`, `requirements/*.yml`, `releases.yml` are source-of-truth; load
-  scoped slices, not whole history.
+- `roadmap.yml`, `requirements/*.yml`, `releases.yml`, `reservations.yml` are
+  source-of-truth; load scoped slices, not whole history.
 - `phases/`, `audits/`, `research/`, `archive/`, and `context-archive.md` are
   historical; load only by milestone/stream/package/version.
 - Runtime/generated files (`.mcp-server/*.db*`, logs, spike DBs) are excluded
@@ -197,7 +198,7 @@ State lives in `.forge/`:
 - `project.yml` — Vision, stack, design system, verification, constraints (<5KB)
 - `constitution.md` — Active architectural gates
 - `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`.
+- `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, **reserve it via the ID Reservation Protocol** (append to `.forge/reservations.yml`, commit+push, then write) — the next number is `max(highest reserved, highest in `.forge/requirements/*.yml`) + 1`. That reservation is what makes the shared ID space safe across **concurrent worktrees**: bare scan-and-increment sees only committed state, so two worktrees branched from one baseline claim the same number and collide silently until merge (see ADR-016). On a residual collision (legacy/un-reserved, 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` — 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.
@@ -213,13 +214,14 @@ State lives in `.forge/`:
 - `refactor-backlog.yml` — Refactoring catalog (actionable items only), worked via quick-tasking. Canonical status vocab: `pending | in_progress | done | dismissed | deferred`. Terminal items auto-archive on the next reviewing/quick-tasking write (compaction-on-write).
 - `refactor-backlog-archive.yml` — Append-only terminal-item archive (`done`/`dismissed`); keeps the audit trail out of the working backlog.
 - `releases.yml` — Append-only version-reservation registry (cross-session coordination point; see Version Reservation Protocol)
+- `reservations.yml` — Append-only ID-reservation registry for ADR/DEF/FR/NFR numbers (cross-worktree coordination point; see ID Reservation Protocol)
 - `archive/milestone-{id}/` — Archived milestone artifacts (archive-delete)
 
 **Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions. Can be deferred (frozen in place) or archive-deleted.
 `index.yml status` gates routing: `not_started | active | deferred | complete`.
 
 **Stream Rollup (`active.yml` is derived).** Mirrors the milestone Rollup: `active.yml` is a pure projection, regenerated — never hand-edited — by a deterministic, idempotent **join** of two single-sourced inputs (ADR-015). Run by the main/orchestrator session and at `chief-of-staff` Show/Sync; worktrees never write it. Procedure:
-1. Glob `streams/{stream}.yml`. Each → a row carrying its coordination state (`coordination` = the file's `status`), goal, runtime, ownership summary, `merge.readiness`, blockers, next action — all from the stream file.
+1. Glob `streams/{stream}.yml`. Each → a row carrying its coordination state (`coordination` = the file's `status`), goal, runtime, ownership summary, `merge_readiness` (derived from the stream file's `merge.readiness`), `blocked_by`, `next_action` — all from the stream file.
 2. For a stream with `stream.milestone: m-{id}`, read `phase`/activity from `milestone-{id}.yml` (`current.status`, `last_updated`) — **not** stored in the stream file. A linked milestone that is `deferred`/`complete`/absent → the row's `phase` reflects that.
 3. Glob active milestones (from `index.yml`). Any active milestone with **no** stream file → emit a derived `stream: implicit` row (phase from the milestone, no coordination state) so coverage is guaranteed in the artifact — an active milestone can never be silently missing.
 4. Derive `merge_queue:` — one entry per stream with `merge.readiness: ready`.
@@ -248,10 +250,11 @@ with the work it describes. Every artifact has a sharing class:
 | Class | Files | Write rule |
 |---|---|---|
 | **Single-owner mutable** | `state/milestone-{id}.yml`, `phases/milestone-{id}/`, `research/milestone-{id}.md` | Exactly one writer at a time — the worktree (or main session) currently driving that milestone. **Other worktrees never touch it**, not even to read-then-write — they pull from main if they need it. |
+| **Single-owner mutable (per stream)** | `streams/{stream}.yml`, `streams/{stream}/brief.md`, `streams/{stream}/packages/*.yml` | The stream's **current driver** writes them — one writer at a time, like the milestone file. Distinct streams own distinct files (no cross-stream contention). `active.yml` is **derived** from them: a worktree driving a stream may write its own stream file but **never** `active.yml` or a peer stream's file. |
 | **Derived** | `state/index.yml`, `streams/active.yml` | Never hand-edited. Regenerated by rollup from their sources (`index.yml` ← `milestone-*.yml` via Rollup 1.0; `active.yml` ← per-stream files + active milestones via the Stream Rollup). Only the main/orchestrator session (and `chief-of-staff` for `active.yml`) runs rollup. |
-| **Append-only shared** | `releases.yml` (version reservations), `state/desire-paths/*` (one file per observation) | Many writers OK; structure prevents collision. `releases.yml` uses the Version Reservation Protocol (append + commit + push before depending on the slot); desire-paths use distinct filenames so two writers never touch the same file. |
+| **Append-only shared** | `releases.yml` (version reservations), `reservations.yml` (ADR/DEF/FR/NFR id reservations), `state/desire-paths/*` (one file per observation) | Many writers OK; structure prevents collision. `releases.yml` + `reservations.yml` use the reservation protocols (append + commit + push before depending on the number); desire-paths use distinct filenames so two writers never touch the same file. |
 | **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` (ID space `FR-`/`DEF-`/`NFR-` is globally shared even though each milestone owns its file) | Write only to your milestone/stream block. Within a block, append-only; strike through instead of rewriting. |
-| **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md` | Rarely changes after init. Canonical on main. Worktrees lag and pull on rebase. No special protocol — git handles it because the conflict surface is tiny. |
+| **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md`, `.claude/skills/`, `.claude/agents/` | Rarely changes except via `/upgrading`. Canonical on main; worktrees lag until they rebase. An upgrade run touches **only the checkout it runs in**, so after upgrading in main, live worktrees keep their branch-point framework files — `upgrading` **Step 8** enumerates live `forge/m-*` worktrees and offers to rebase each (never auto), and the opt-in `forge.worktree_rebase_check` watches these files as a boot-time safety net. Gitignored carve-outs (`.mcp.json`, experimental hooks) don't rebase — re-run the experimental installer if the upgrade changed them. |
 
 Cross-tree edits land on the current branch and are invisible to other worktrees
 until they pull/rebase. `forge` surfaces live worktrees at boot **and enforces
@@ -282,6 +285,18 @@ The project version + CHANGELOG slot are **shared resources** — when two miles
 
 **Version-bump criteria (0.x projects):** patch (`0.x.y`) = bug fix, doc tweak, sync-only, refinement. Minor (`0.x.0`) = new skill/agent/routing-row/auto-trigger/state-artifact/capability. Major (`x.0.0`) = post-1.0 breaking change. Default to minor when in doubt — a capability addition shipped as a patch drifts the version away from truth.
 
+### ID Reservation Protocol
+
+Sequential IDs — `ADR-NNN` (decision records), `DEF-NNN` (deferred issues), `FR-NNN`/`NFR-NNN` (requirements) — are **shared cross-worktree resources** the same way the version number is. "Scan the tree for the highest and increment" only sees *committed* state, so two streams branched from the same baseline each claim the same next number and collide **silently until merge** — a costly multi-file renumber pass (see [ADR-016](../docs/decisions/ADR-016-id-reservation-protocol.md)). `.forge/reservations.yml` removes the number from per-stream scope, exactly as `releases.yml` does for versions.
+
+- **Reserve before allocating.** Before authoring a new ADR or writing a new DEF/FR/NFR ID, append ONE entry to `.forge/reservations.yml` — `{kind, id, milestone, reserved_at, summary}`, `kind ∈ {adr, def, fr, nfr}` — then **commit + push it BEFORE creating the artifact**. A parallel worktree pulls and sees the number taken.
+- **Next number = `max(reserved, in-tree) + 1` per kind.** The higher of (a) the highest reservation for that kind in `reservations.yml` and (b) the highest ID of that kind actually landed in the tree. Taking both keeps it backward-compatible — landed IDs that were never reserved are still respected.
+- **Append-only — never edit prior entries.** Distinct lines = no contention. Race resolution: the second of two near-simultaneous reservations rebases onto the first (append-only → clean), re-reads `max()`, takes the next number.
+- **Reserve points.** `architecting` reserves an `adr` before authoring it; `planning` reserves `fr`/`nfr`/`def` before writing them into requirements. (Out of scope: `executing`'s `DI-NNN` deferred-*issue* ids in `deferred-issues.md` are a separate, more local namespace — not reserved here.)
+- **Lazy migration.** No `reservations.yml` ⇒ allocate as before (scan in-tree max); the first reservation creates the file. Existing projects are unaffected until they next allocate an ID.
+
+This is the cross-worktree mechanism the FR/DEF/NFR "globally unique" rule (State Management, above) previously lacked, and the first reservation rule ADR numbers have ever had. Versions stay in `releases.yml` (separate semver/CHANGELOG semantics); everything else reserves here.
+
 ## Deviation Rules
 
 **Full definitions:** `.claude/agents/executor.md`.

package/template/.forge/adapters/codex-generation.md

@@ -0,0 +1,90 @@
+# Codex/AGENTS Adapter — Generation Protocol
+
+**You are an agent running AS the Codex runtime.** Your job: (re)generate Forge's
+Codex/AGENTS adapter from the canonical source skills, using **Codex's own native
+primitives**. This is a *native authoring* task, not a find-replace — a swapped-nouns
+copy of the Claude adapter is wrong (FORGE.md Principle 2: adapter-native). Output is a
+**derived product**; the source below is the spec.
+
+Run via `quick-tasking` (handed this file by `/upgrading` Step 4b). A human reviews your
+output before commit. Regenerating *this* Forge repo's own `.agents/` is **DEF-040** —
+not your job unless explicitly asked.
+
+## 1. Source spec → output
+
+| Source of truth (the spec) | You author (the derived adapter) |
+|---|---|
+| `.claude/skills/<name>/*.md` | `.agents/skills/<name>/*.md` |
+| `.claude/agents/<name>.md` (if present) | `.agents/agents/<name>.md` |
+| `.claude/hooks/*.sh` + settings hooks | `.codex/hooks/*.sh` + `.codex/hooks.json` |
+| `CLAUDE.md` | `AGENTS.md` (keep the `@.forge/FORGE.md` import) |
+
+Source = `.claude/` for now. The platform-neutral core (M16) is **DEF-041 deferred**; when
+it lands, only this "source" pointer changes. `.forge/` protocol state is shared, **not**
+translated — never fork it.
+
+## 2. Layout deltas — cosmetic, always-true (apply mechanically)
+
+- skill dir `.claude/skills/` → `.agents/skills/`
+- agent dir `.claude/agents/` → `.agents/agents/`
+- hook dir `.claude/hooks/` → `.codex/hooks/`
+- config file `CLAUDE.md` → `AGENTS.md`
+- settings `.claude/settings.json` → Codex's settings equivalent
+- `Reviewer: Claude` → `Reviewer: Codex`; `Claude Code <X>` → `Codex <X>`
+
+**WARN — do NOT produce `.Codex` (capital C).** The real directories are lowercase
+`.agents/` (skills/agents) and `.codex/` (hooks). A `.Codex` token is the exact bug this
+protocol exists to kill — it must appear **nowhere** in your output.
+
+**Do NOT rewrite Claude *model ids*** (`claude-opus-*`, `claude-sonnet-*`, `claude-haiku-*`,
+`claude-fable-*`) — those are literal API identifiers, not branding. Leave them verbatim.
+
+## 3. Coupled mechanisms — handle with JUDGMENT, not substitution
+
+These four skills (`executing`, `forge`, `orchestrating`, `planning`) reference Claude-only
+runtime mechanics. A noun-swap corrupts them. For each, translate to Codex's real surface or
+drop the moot part:
+
+- **`EnterPlanMode`** (forge, planning). A Claude-native tool. → Map to Codex's plan/approval
+  convention if it has one; else **DROP** the "never use EnterPlanMode" prohibition (moot on
+  Codex) and keep the positive rule: *planning = invoke the planning skill*.
+- **ADR-007 session-id / file-claim identity / `forge-session-id.sh` SessionStart hook**
+  (orchestrating). → Translate to Codex's actual session concept; if Codex has none, mark
+  **N/A** — the claim layer degrades to single-session, which `orchestrating` already
+  tolerates.
+- **Native Task tools** (`TaskCreate`/`TaskUpdate`/`TaskList`, executing in-session UI). →
+  Map to Codex's equivalent; if none, note they were a Claude-only UI nicety and the
+  `.forge/state/` files remain the cross-session source of truth.
+
+## 4. `.codex/` wiring
+
+Author the hook scripts + `.codex/hooks.json` for Codex's real hook surface (its
+PreToolUse/PostToolUse analogs), preserving the **active-skill gate** behavior the
+`.claude/hooks/` versions enforce. If Codex exposes no hook surface, say so explicitly and
+have the skills self-enforce in prose instead of silently dropping the gate. Pre-existing
+`.codex/hooks/README.md` cleanup (stale "Claude Code PreToolUse" wording) is **DEF-042** —
+separate.
+
+## 5. Invariants — PRESERVE verbatim across adapters
+
+Translate **mechanics** (tool names, hook surface, paths, config filenames), **never the
+protocol**. These must read identically in `.agents/` and `.claude/`, so a regeneration is
+diffable for fidelity:
+
+- skill routing tables + workflow tiers (Quick / Standard / Full)
+- gate semantics — verification gates, the **Human Verification Gate** (close precondition)
+- state-ownership rules (single-owner / derived / append-only / shared classes)
+- the **Version Reservation Protocol** and atomic-commit rules
+- desire-path capture, milestone lifecycle, context size gates
+
+If a translation forces a change to any of these, you have over-reached — stop and flag it;
+the protocol does not move to fit a platform.
+
+## 6. How this runs
+
+1. `/upgrading` Step 4b detects `.agents/` or `.codex/` and offers regeneration; on **yes**
+   it hands you this file via `quick-tasking`.
+2. You author the adapter per §1–5 using native primitives.
+3. A human reviews the diff for fidelity (invariants intact, no `.Codex`, coupled mechanisms
+   handled) **before** anything is committed. `/upgrading` never writes `.agents/` itself.
+4. Output is the derived adapter; the source skills are untouched.

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

@@ -119,10 +119,18 @@ Use `git mv` so history follows the files and `git status` records a rename
 
 ```bash
 cd .forge/phases
+# POSIX parameter expansion — bash- AND zsh-safe. Do NOT use [[ =~ ]] + $BASH_REMATCH
+# here: under zsh (macOS default, and the shell quick-tasking runs this in) captures
+# land in $match, not $BASH_REMATCH, so id/phase/name expand empty and git mv
+# collapses every phase dir onto a malformed milestone-/- target.
 for d in m[0-9]*-[0-9]*-*/; do
   d=${d%/}
-  [[ $d =~ ^m([0-9]+)-([0-9]+)-(.+)$ ]] || continue
-  id=${BASH_REMATCH[1]}; phase=${BASH_REMATCH[2]}; name=${BASH_REMATCH[3]}
+  rest=${d#m}                                     # strip leading 'm'  → id-phase-name
+  id=${rest%%-*}                                   # digits before first '-'
+  rest=${rest#*-}                                  # drop 'id-'         → phase-name
+  phase=${rest%%-*}                                # digits before next '-'
+  name=${rest#*-}                                  # remainder (may contain '-')
+  case "$id$phase" in *[!0-9]*) continue;; esac    # skip if id/phase non-numeric
   mkdir -p "milestone-$id"
   git mv "$d" "milestone-$id/$phase-$name"
 done

package/template/.forge/migrations/0.41.0-generated-codex-adapter.md

@@ -0,0 +1,81 @@
+# Migration Guide: Agent-Regenerated Codex Adapter (Forge 0.41.0)
+
+Applies to projects that have a **Codex/AGENTS adapter** (`.agents/` and/or `.codex/`).
+Claude-only and greenfield projects are unaffected — this guide is silent for them.
+
+Forge 0.41.0 (ADR-014) stops treating `.agents/` as a hand-maintained or find-replaced
+second source. The Codex adapter is now a **derived translation** of the `.claude/` skills,
+**regenerated by an agent acting as the Codex runtime** from a shipped protocol
+(`.forge/adapters/codex-generation.md`), using Codex's native primitives. This kills the
+`.Codex`-token corruption an earlier naive find-replace produced and fixes the silent drift
+where `.agents/` rotted while `.claude/` advanced. Regeneration is **offered, never
+auto-applied** — `/upgrading` Step 4b hands the protocol to `quick-tasking`, and a human
+reviews the diff before commit.
+
+## Prerequisites
+
+1. On the 0.41.0 framework files — run `npx forge-orkes upgrade` (or the `/upgrading` skill)
+   first, so `.forge/adapters/codex-generation.md` is present.
+2. Working tree clean or changes committed — regeneration rewrites `.agents/` + `.codex/`.
+
+## Detection
+
+Prints `MIGRATE` when a Codex adapter exists but is missing the protocol, carries the broken
+`.Codex` token, or is older than the `.claude/` source. Silent + exit 0 otherwise (including
+Claude-only projects).
+
+```bash
+# Codex adapter present but stale/broken → regenerate via the protocol.
+{ [ -d .agents ] || [ -d .codex ]; } || exit 0          # Claude-only → nothing to do
+
+# (a) generation protocol not installed yet
+if [ ! -f .forge/adapters/codex-generation.md ]; then
+  echo "MIGRATE — Codex adapter present but the generation protocol is missing; sync framework files then regenerate"
+  exit 0
+fi
+
+# (b) broken: the .Codex corruption token anywhere in the adapter trees
+if grep -rqF '.Codex' .agents .codex 2>/dev/null; then
+  echo "MIGRATE — Codex adapter contains the broken .Codex token; regenerate from the protocol"
+  exit 0
+fi
+
+# (c) stale: newest source skill newer than newest adapter skill
+newest_src=$(ls -t .claude/skills/*/SKILL.md 2>/dev/null | head -1)
+newest_adapter=$(ls -t .agents/skills/*/SKILL.md 2>/dev/null | head -1)
+if [ -n "$newest_src" ] && [ -n "$newest_adapter" ] && [ "$newest_src" -nt "$newest_adapter" ]; then
+  echo "MIGRATE — Codex adapter is older than the .claude/ source; regenerate from the protocol"
+  exit 0
+fi
+exit 0
+```
+
+## Migration steps
+
+The migration is **never auto-applied**. In Claude Code it runs via the `quick-tasking`
+skill, which `/upgrading` Step 4b hands the protocol to on "yes".
+
+### 1. Ensure the protocol is present
+`.forge/adapters/codex-generation.md` ships with 0.41.0 — confirm `npx forge-orkes upgrade`
+(or `/upgrading`) has synced it.
+
+### 2. Regenerate (Codex-run, agent-authored)
+Run the regeneration **as the Codex runtime**, following `.forge/adapters/codex-generation.md`:
+author `.agents/skills/` + `.codex/` wiring from the `.claude/` source using native
+primitives. Do **not** find-replace; handle the coupled mechanisms (EnterPlanMode, ADR-007
+session-id/claim hook, native Task tools) with judgment per the protocol §3.
+
+### 3. Human review before commit
+Review the diff for fidelity: invariants intact (routing tables, tiers, gate semantics,
+state-ownership, version-reservation, atomic commits), **no `.Codex` token**, coupled
+mechanisms handled. Commit only after review. Lossy steps are confirmed first.
+
+## Validation
+
+```bash
+# No .Codex token survives anywhere in the regenerated adapter
+grep -rqF '.Codex' .agents .codex 2>/dev/null && echo "FAIL: .Codex token still present" || echo "OK: no .Codex token"
+# Every source skill has a corresponding adapter skill dir
+for d in .claude/skills/*/; do n=$(basename "$d"); [ -d ".agents/skills/$n" ] || echo "MISSING adapter skill: $n"; done
+echo "validation complete"
+```

package/template/.forge/migrations/0.42.0-id-reservation.md

@@ -0,0 +1,48 @@
+# Migration Guide: ID Reservation Protocol (Forge 0.42.0)
+
+Forge 0.42.0 ([ADR-016](https://github.com/Attuned-Media/forge/blob/main/docs/decisions/ADR-016-id-reservation-protocol.md), [forge#10](https://github.com/Attuned-Media/forge/issues/10)) adds a cross-worktree reservation mechanism for sequential IDs — `ADR-NNN`, `DEF-NNN`, `FR-NNN`, `NFR-NNN` — backed by a new append-only file `.forge/reservations.yml` (sibling to `releases.yml`). It closes the silent collision where two streams in parallel worktrees each "scan the tree for the highest + increment" and claim the same number, surfacing only at merge as a multi-file renumber.
+
+**Fully backward-compatible / lazy.** Nothing breaks without acting: with no `reservations.yml`, allocation behaves exactly as before (scan the in-tree max), and the first reservation creates the file. This guide just materialises the file so the protocol is active and visible immediately.
+
+## Detection
+
+Prints `MIGRATE` when the project has no `.forge/reservations.yml` yet. Silent + exit 0 once it exists.
+
+```bash
+[ -d .forge ] || exit 0                              # not a Forge project
+[ -f .forge/reservations.yml ] && exit 0             # already migrated → silent
+echo "MIGRATE — add .forge/reservations.yml to activate the ID Reservation Protocol (ADR/DEF/FR/NFR cross-worktree number reservation)"
+exit 0
+```
+
+## Migration steps
+
+One trivial, safe step — create the starter file. In Claude Code this runs via `quick-tasking`.
+
+### 1. Create `.forge/reservations.yml`
+
+Write the append-only starter (header + empty list). It needs no back-fill — the `max(reserved, in-tree)` allocation rule already respects every ADR/DEF/FR/NFR already landed in the tree, so existing IDs stay valid without being listed.
+
+```bash
+cat > .forge/reservations.yml <<'YML'
+# Forge ID Reservations — cross-worktree coordination for ADR / DEF / FR / NFR numbers
+# Reserve BEFORE allocating: append one entry, commit + push, THEN create the artifact.
+# Next number for a kind = max(highest reserved here, highest in-tree) + 1. kind ∈ {adr,def,fr,nfr}.
+# Append-only; never edit prior entries. See FORGE.md → ID Reservation Protocol + ADR-016.
+reservations: []
+YML
+git add .forge/reservations.yml
+git commit -m "chore(forge): add reservations.yml (ID Reservation Protocol, 0.42.0)"
+```
+
+### 2. From now on, reserve before allocating
+
+When `architecting` files a new ADR or `planning` writes a new FR/NFR/DEF, append `{kind, id, milestone, reserved_at, summary}` to `.forge/reservations.yml`, commit + push it, *then* create the artifact. The skills (0.42.0) prompt this automatically.
+
+## Validation
+
+```bash
+[ -f .forge/reservations.yml ] && echo "OK: reservations.yml present" || echo "FAIL: missing"
+grep -q '^reservations:' .forge/reservations.yml && echo "OK: has reservations key" || echo "FAIL: malformed"
+echo "validation complete"
+```

package/template/.forge/reservations.yml

@@ -0,0 +1,31 @@
+# Forge ID Reservations — cross-worktree coordination for ADR / DEF / FR / NFR numbers
+#
+# PURPOSE: remove sequential ID numbers from per-stream scope so two streams
+# running in parallel worktrees never silently claim the same ADR/DEF/FR/NFR
+# number (a collision that otherwise only surfaces at merge as a multi-file
+# renumber). Sibling to releases.yml, which does the same for version numbers.
+# See ADR-016 + FORGE.md → ID Reservation Protocol.
+#
+# COMMITTED + APPEND-ONLY. Reserve BEFORE allocating: append exactly one entry,
+# commit + push it, THEN create the ADR file / write the DEF/FR/NFR. Appending —
+# never editing prior entries — is what keeps parallel worktrees from conflicting
+# (distinct lines, no contention). A worktree pulls and sees taken numbers.
+#
+# RULE: next free number for a kind = max(highest reserved here for that kind,
+# highest actually in-tree for that kind) + 1. Taking the max of both keeps it
+# backward-compatible — landed IDs that predate this file are still respected.
+#
+# RACE: if two worktrees reserve near-simultaneously, the second push rebases
+# onto the first (append-only → clean), re-reads max(), takes the next number.
+#
+# LAZY MIGRATION: absent ⇒ allocate as before (scan in-tree max). This file
+# materialises on the first reservation. kind ∈ {adr, def, fr, nfr}.
+#
+#   reservations:
+#     - kind: adr
+#       id: ADR-036
+#       milestone: m-PLUG01
+#       reserved_at: "2026-06-26"
+#       summary: "Plugin-host scanner architecture"
+
+reservations: []