forge-orkes 0.41.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');
@@ -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));
     }
   }
 
@@ -358,7 +357,9 @@ async function install() {
 
   console.log(`\n  Forge v${pkgVersion} is ready. Start with: /forge\n`);
 
-  // Presence-gated: if a Codex adapter is present, note it may need regeneration.
+  // 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();
 }
 
@@ -442,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;
     }
 
@@ -476,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');
 
@@ -524,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);
@@ -532,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
@@ -544,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') {
@@ -721,6 +768,24 @@ function noticeWorktreeLag() {
 
 // --- 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.41.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

@@ -54,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.
 
@@ -125,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.
@@ -185,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/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,8 +250,9 @@ 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`, `.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. |
 
@@ -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/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.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: []