@polymorphism-tech/morph-spec 8.22.0 → 8.23.0

package/src/commands/state/finish.js

@@ -405,12 +405,17 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
 // ── output helpers ────────────────────────────────────────────────────────
 
 /**
- * Report the use cases the archive promoted into `.morph/specs/usecases/`.
- * Absent when nothing was promoted, so a feature with no use cases keeps the
- * exact output shape it had before this existed.
+ * Report the use cases the archive promoted into `.morph/specs/usecases/`, and
+ * any that were REFUSED for a numbering collision (`ucCollisions` — see
+ * `usecase-promoter.js`'s reservation-backed guard). Both absent when there is
+ * nothing to report, so a feature with no use cases keeps the exact output
+ * shape it had before either existed.
  */
 function promotedNote(arch) {
-  return arch?.promotedUseCases?.length ? { promotedUseCases: arch.promotedUseCases } : {};
+  return {
+    ...(arch?.promotedUseCases?.length ? { promotedUseCases: arch.promotedUseCases } : {}),
+    ...(arch?.refusedUseCases?.length ? { ucCollisions: arch.refusedUseCases } : {}),
+  };
 }
 
 function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {

package/src/commands/state/handoff.js

@@ -6,8 +6,9 @@
  * worktree session, a resumed session after a phase transition). The handoff
  * is the sanctioned way to carry context across: derived, regenerable, and
  * pointer-based (see handoff-generator.js). This command is also called
- * in-process by `worktree setup`, `create --worktree` and `advance` — the CLI
- * surface exists for the LLM/user to refresh the document on demand.
+ * in-process by `worktree setup`, `create --worktree`, `advance` and
+ * `approve` — the CLI surface exists for the LLM/user to refresh the
+ * document on demand.
  */
 
 import chalk from 'chalk';

package/src/commands/state/usecase.js

@@ -0,0 +1,77 @@
+/**
+ * `morph-spec usecase reserve [--count <n>] [--feature <name>] [--json]` —
+ * atomically mint the next N `UC-{nn}` numbers, shared across every worktree
+ * of this repo. See `usecase-registry.js` for why this exists (worktrees only
+ * ever see their own tree, so an independent max+1 scan collides).
+ *
+ * `--feature` is more than an audit label: `usecase-promoter.js`'s collision
+ * guard uses the reservation record to tell a legitimate cross-feature
+ * correction (never reserved — reusing a published number by design) from an
+ * accidental collision (both features reserved the same id). Passing it is
+ * how `morph-plan` gets that protection; omitting it degrades to "reserved,
+ * no owner recorded" — still collision-free, just unable to name the
+ * conflicting feature if one ever surfaces.
+ */
+
+import chalk from 'chalk';
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
+import { reserveUseCases } from '../../lib/specs/usecase-registry.js';
+
+/**
+ * Best-effort feature-name inference when `--feature` is omitted: only when
+ * exactly one active feature exists is the guess unambiguous. Anything else
+ * (zero, or more than one) is left null rather than guessed wrong — a wrong
+ * guess would poison the collision guard's provenance record.
+ */
+function inferActiveFeature(cwd) {
+  const featuresDir = join(cwd, '.morph', 'features');
+  try {
+    if (!existsSync(featuresDir)) return null;
+    const entries = readdirSync(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+    return entries.length === 1 ? entries[0].name : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{ count?: string, feature?: string, json?: boolean, cwd?: string }} [options]
+ */
+export function usecaseReserveCommand(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const count = Number.parseInt(options.count, 10);
+  const n = Number.isInteger(count) && count > 0 ? count : 1;
+  const feature = options.feature || inferActiveFeature(cwd) || null;
+
+  let gitCommonDir = null;
+  try { gitCommonDir = resolveGitCommonDir(cwd); } catch { gitCommonDir = null; }
+
+  let result;
+  try {
+    result = reserveUseCases(cwd, { feature, count: n, gitCommonDir });
+  } catch (error) {
+    if (options.json) {
+      console.log(JSON.stringify({ reserved: false, error: error.message }));
+      process.exit(1);
+    }
+    console.error(chalk.red(`\n❌ ${error.message}\n`));
+    process.exit(1);
+  }
+
+  const warning = gitCommonDir
+    ? null
+    : 'projeto fora de um repositório git — numeração protegida só localmente; paralelismo entre worktrees NÃO está garantido.';
+
+  if (options.json) {
+    console.log(JSON.stringify({ reserved: true, ...result, feature, warning }));
+    process.exit(0);
+  }
+
+  console.log(chalk.green(`\n✅ Reservado: ${result.numbers.join(' ')}`));
+  if (feature) console.log(chalk.gray(`   feature: ${feature}`));
+  if (warning) console.log(chalk.yellow(`⚠️  ${warning}\n`));
+  else console.log('');
+  process.exit(0);
+}

package/src/commands/validation/verify.js

@@ -53,6 +53,12 @@ function formatVerifyResult(result) {
     for (const line of result.feedback) lines.push(`  ${line}`);
   }
 
+  if (result.traceability?.warnings?.length > 0) {
+    lines.push('');
+    lines.push(chalk.yellow('Traceability warnings (advisory — never fails verify):'));
+    for (const w of result.traceability.warnings) lines.push(`  ⚠ ${w}`);
+  }
+
   lines.push('');
   return lines.join('\n');
 }

package/src/lib/generators/handoff-generator.js

@@ -9,8 +9,8 @@
  * Deterministic by construction — everything here is derived from feature.json,
  * tasks.json, decisions.md and the worktree env manifest. The document is
  * therefore REGENERABLE (never hand-edited, never merged): `morph-spec handoff`
- * rebuilds it, and setup/create/advance regenerate it at the moments a new
- * session is most likely to pick the feature up.
+ * rebuilds it, and setup/create/advance/approve regenerate it at the moments a
+ * new session is most likely to pick the feature up.
  *
  * Every section is fail-open: a missing tasks.json or a corrupt decisions.md
  * degrades that section, never the document.

package/src/lib/specs/usecase-promoter.js

@@ -12,15 +12,29 @@
  *     as a no-op rather than an error.
  *   - **No-op without the folder.** A feature with no use cases promotes nothing.
  *   - **Idempotent.** Re-promoting the same use case rewrites the same content.
- *   - **Overwrite by ID, not by filename.** `UC-07-old-slug.md` in the archive is
- *     REPLACED by an incoming `UC-07-new-slug.md`. Keying on the filename would
- *     leave two files claiming UC-07 the first time a slug is reworded — and the
- *     `bug` work type exists precisely to correct an existing use case.
+ *   - **Overwrite by ID, not by filename — with a collision backstop.**
+ *     `UC-07-old-slug.md` in the archive is REPLACED by an incoming
+ *     `UC-07-new-slug.md`. Keying on the filename would leave two files
+ *     claiming UC-07 the first time a slug is reworded — and the `bug` work
+ *     type exists precisely to correct an existing use case, from a DIFFERENT
+ *     feature than the one that first published it, sometimes rewording the
+ *     slug in the same pass. That legitimate case is INDISTINGUISHABLE, by
+ *     filename and slug alone, from two worktrees that independently minted
+ *     the SAME number for two UNRELATED use cases (the numbering-collision bug
+ *     this backstop exists for) — a user has already lost a use case this way
+ *     in production. The one signal that tells them apart is `usecase-registry.js`'s
+ *     reservation record: a feature that REPLACES a number it never reserved is
+ *     reusing a published UC by design (the bug/update flow); a feature that
+ *     REPLACES a number it DID reserve, and finds someone ELSE'S feature already
+ *     sitting on that ID, is the collision — refuse that one specific promotion
+ *     rather than silently destroy the other feature's use case.
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
-import { join } from 'path';
+import { basename, join, relative } from 'path';
 import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
+import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
+import { reservationOwner } from './usecase-registry.js';
 
 const UC = OUTPUT_SCHEMA.usecases;
 const UC_FILENAME_RE = new RegExp(UC.filenamePattern);
@@ -35,38 +49,102 @@ export function useCaseId(filename) {
 }
 
 /**
- * Rewrite the frontmatter `status:` to `implemented`.
+ * Set (or replace) a single top-level frontmatter field, preserving every
+ * other line, the original EOL style, and anything after the closing `---`.
  *
- * A file with no frontmatter is copied verbatim: the use case belongs to the
- * author, and inventing a header would be a silent edit of their document.
+ * A file with no frontmatter block is returned UNCHANGED: the use case
+ * belongs to the author, and inventing a header would be a silent edit of
+ * their document.
  *
  * @param {string} content
+ * @param {string} key
+ * @param {string} value
  * @returns {string}
  */
-export function stampImplemented(content) {
+function setFrontmatterField(content, key, value) {
   const m = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(content);
   if (!m || m.index !== 0) return content;
 
   const [full, open, body, close] = m;
   const eol = full.includes('\r\n') ? '\r\n' : '\n';
-  const statusLine = /^status:[ \t]*.*$/m;
-  const next = statusLine.test(body)
-    ? body.replace(statusLine, 'status: implemented')
-    : `${body}${eol}status: implemented`;
+  const fieldLine = new RegExp(`^${key}:[ \\t]*.*$`, 'm');
+  const next = fieldLine.test(body)
+    ? body.replace(fieldLine, `${key}: ${value}`)
+    : `${body}${eol}${key}: ${value}`;
 
   return open + next + close + content.slice(full.length);
 }
 
+/** Read a single top-level frontmatter field. `null` when absent or there is no frontmatter block. */
+function readFrontmatterField(content, key) {
+  const m = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(content);
+  if (!m || m.index !== 0) return null;
+  const line = new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, 'm').exec(m[2]);
+  return line ? line[1].trim() : null;
+}
+
+/**
+ * Rewrite the frontmatter `status:` to `implemented`.
+ *
+ * A file with no frontmatter is copied verbatim: the use case belongs to the
+ * author, and inventing a header would be a silent edit of their document.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function stampImplemented(content) {
+  return setFrontmatterField(content, 'status', 'implemented');
+}
+
+/**
+ * Stamp the promoting feature's name into `sourceFeature:` — the provenance
+ * record the collision guard (below) compares against a reservation to tell a
+ * legitimate cross-feature correction from an accidental numbering collision.
+ *
+ * @param {string} content
+ * @param {string} feature
+ * @returns {string}
+ */
+export function stampSourceFeature(content, feature) {
+  return setFrontmatterField(content, 'sourceFeature', feature);
+}
+
+/**
+ * Build the message for a refused promotion — named clearly enough that the
+ * next session (or human) can actually recover, not just "colisão".
+ *
+ * The recovery instruction has to be honest about WHERE the file sits: by the
+ * time this runs, `runArchive` has already moved the feature folder, and its
+ * own idempotent short-circuit (`existsSync(archivePath)`) means re-running
+ * `archive`/`finish` on this feature promotes NOTHING a second time — so
+ * "renumber and re-run finish" would be a lie. The file is wherever `srcDir`
+ * actually is (the feature's `2-plan/usecases/`, wherever that folder lives
+ * right now — pre- or post-archive, the caller decides), and recovery is
+ * either a fresh reservation + manual copy, or editing the archive in place.
+ *
+ * @returns {string}
+ */
+function collisionMessage({ id, incoming, existing, existingFeature, feature, relIncomingPath }) {
+  return `${id}: colisão de numeração — "${incoming}" (feature "${feature}") não pôde substituir "${existing}" ` +
+    `já promovido no acervo por "${existingFeature}". O arquivo continua em ${relIncomingPath}. ` +
+    'Se for um use case NOVO: renumere-o com `morph-spec usecase reserve` e promova manualmente para ' +
+    '.morph/specs/usecases/ (o finish/archive não reprocessa uma feature já arquivada). ' +
+    `Se for uma CORREÇÃO do mesmo UC publicado: edite .morph/specs/usecases/${existing} diretamente em vez de reservar um número novo.`;
+}
+
 /**
  * Copy every use case of a feature into the project's permanent archive.
  *
  * @param {string} cwd        - project root that owns `.morph/specs/`
  * @param {string} featureDir - the feature folder holding `2-plan/usecases/`
- * @returns {{ promoted: string[], replaced: string[] }} filenames, always arrays
+ * @returns {{ promoted: string[], replaced: string[], refused: Array<{id: string,
+ *   incoming: string, existing: string, existingFeature: string, message: string}> }}
+ *   filenames, always arrays
  */
 export function promoteUseCases(cwd, featureDir) {
-  const empty = { promoted: [], replaced: [] };
+  const empty = { promoted: [], replaced: [], refused: [] };
   const srcDir = join(featureDir, UC.phaseDir, UC.dirname);
+  const feature = basename(featureDir);
 
   let names;
   try {
@@ -80,6 +158,7 @@ export function promoteUseCases(cwd, featureDir) {
   const destDir = join(cwd, '.morph', 'specs', 'usecases');
   const promoted = [];
   const replaced = [];
+  const refused = [];
 
   try {
     mkdirSync(destDir, { recursive: true });
@@ -87,6 +166,11 @@ export function promoteUseCases(cwd, featureDir) {
     return empty;
   }
 
+  // Resolved ONCE per call — pure filesystem, no subprocess (git-paths.js) —
+  // and reused for every collision check below.
+  let gitCommonDir = null;
+  try { gitCommonDir = resolveGitCommonDir(cwd); } catch { gitCommonDir = null; }
+
   // Existing archive entries, indexed by use-case ID — the key the overwrite
   // rule is written against.
   const existingById = new Map();
@@ -99,22 +183,54 @@ export function promoteUseCases(cwd, featureDir) {
 
   for (const name of names) {
     try {
-      const content = stampImplemented(readFileSync(join(srcDir, name), 'utf8'));
       const id = useCaseId(name);
       const stale = id ? existingById.get(id) : null;
 
-      // Same ID under a different filename: drop the old file, or the archive
-      // would end up with two documents claiming the same UC number.
+      // Same ID under a different filename: normally the old file is dropped
+      // (a slug reword, or the `bug` flow correcting a published UC), or the
+      // archive would end up with two documents claiming the same UC number.
+      //
+      // Backstop: refuse instead when BOTH are true —
+      //   (a) THIS feature holds a reservation for `id` in usecase-registry.js
+      //       (it believes it MINTED a new number), and
+      //   (b) the archive entry already there was promoted by a DIFFERENT
+      //       feature (its stamped `sourceFeature` says so).
+      // A feature correcting a published UC never reserved that UC's number —
+      // it reused one already in the acervo — so that legitimate flow never
+      // trips this. Two features that each reserved the SAME number (the
+      // collision this exists for) always do. No reservation record at all
+      // (no git common dir, or a legacy archive entry predating this stamp) is
+      // fail-open: nothing to compare against, so nothing is refused.
       if (stale && stale !== name) {
+        let staleFeature = null;
+        try { staleFeature = readFrontmatterField(readFileSync(join(destDir, stale), 'utf8'), 'sourceFeature'); } catch { /* unreadable — no signal */ }
+        const incomingOwner = id ? reservationOwner(id, { cwd, gitCommonDir }) : null;
+
+        if (staleFeature && staleFeature !== feature && incomingOwner === feature) {
+          refused.push({
+            id,
+            incoming: name,
+            existing: stale,
+            existingFeature: staleFeature,
+            message: collisionMessage({
+              id, incoming: name, existing: stale, existingFeature: staleFeature, feature,
+              relIncomingPath: relative(cwd, join(srcDir, name)).replace(/\\/g, '/'),
+            }),
+          });
+          continue; // leave the existing archive entry untouched
+        }
+
         rmSync(join(destDir, stale), { force: true });
         replaced.push(stale);
       }
 
+      let content = stampImplemented(readFileSync(join(srcDir, name), 'utf8'));
+      content = stampSourceFeature(content, feature);
       writeFileSync(join(destDir, name), content, 'utf8');
       promoted.push(name);
       if (id) existingById.set(id, name);
     } catch { /* one unreadable use case must not sink the rest */ }
   }
 
-  return { promoted, replaced };
+  return { promoted, replaced, refused };
 }

package/src/lib/specs/usecase-registry.js

@@ -0,0 +1,237 @@
+/**
+ * usecase-registry.js — atomic, cross-worktree UC-{nn} number allocation.
+ *
+ * Two parallel worktrees planning at the same time each read the acervo
+ * (`.morph/specs/usecases/`) plus their OWN feature's `2-plan/usecases/`, take
+ * the max `UC-{nn}` and add one — but a worktree only ever sees its OWN tree.
+ * Sibling features' use cases live in SIBLING worktrees (feature.json and every
+ * UC file travel on the branch, not through any shared filesystem). Two
+ * worktrees both computing max+1 from the same stale max both mint `UC-07` —
+ * and at promotion time `usecase-promoter.js` overwrites by ID: the SECOND
+ * feature to close silently destroys the FIRST one's use case. A user lost
+ * work this way in production.
+ *
+ * This module closes the gap the same way `env-allocator.js` (port blocks) and
+ * `claim-registry.js` (feature ownership) already do: a registry file under the
+ * git COMMON dir, the one location every linked worktree of a repo shares —
+ * `<git-common-dir>/morph-spec/uc-registry.json`. Writes are tmp+rename; a
+ * corrupt registry reads as empty (fail-open — the cost is a re-seed from disk,
+ * never a crash).
+ *
+ * Unlike the other two registries, correctness here cannot be advisory: the
+ * whole point is that two concurrent callers must never receive the same
+ * number. `env-allocator`/`claim-registry` key by FEATURE, so two different
+ * features racing never contend for the same key; two worktrees reserving UC
+ * numbers race for the SAME counter. So allocation runs inside a real mutual
+ * exclusion lock (`uc-registry.lock`, `open(..., 'wx')` — atomic create-if-absent
+ * on every platform Node targets, including Windows) instead of the bare
+ * read-modify-write the other two registries use.
+ *
+ * No git (no common dir resolvable): falls back to a project-local registry
+ * under `.morph/logs/` (already gitignored) — this still prevents a single
+ * session from reserving the same number twice across repeated calls, but
+ * carries none of the cross-worktree guarantee. Callers must surface that
+ * degradation to the user.
+ */
+
+import {
+  closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync,
+  renameSync, statSync, unlinkSync, writeFileSync,
+} from 'fs';
+import { join } from 'path';
+
+/** A UC filename's leading `UC-{nn}` — deliberately NOT imported from
+ * `usecase-promoter.js`: that module will come to depend on THIS one (to look
+ * up who reserved a given number), and a two-way import would be circular. */
+const UC_ID_RE = /^(UC-(\d+))-/;
+
+/** `UC-7` (or any width) -> `UC-07` — the archive's zero-padded convention. */
+function formatUcId(n) {
+  return `UC-${String(n).padStart(2, '0')}`;
+}
+
+/** Directory holding both the registry file and its lock. */
+export function registryDir({ gitCommonDir, cwd }) {
+  return gitCommonDir ? join(gitCommonDir, 'morph-spec') : join(cwd, '.morph', 'logs');
+}
+
+/** Registry file path — shared (git common dir) or local-fallback (no git). */
+export function ucRegistryPath({ gitCommonDir, cwd }) {
+  return join(registryDir({ gitCommonDir, cwd }), 'uc-registry.json');
+}
+
+function readRegistry(path) {
+  try {
+    const raw = readFileSync(path, 'utf8').replace(/^/, '');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.reservations === 'object' && parsed.reservations !== null) {
+      return {
+        version: 1,
+        counter: Number.isInteger(parsed.counter) ? parsed.counter : 0,
+        reservations: parsed.reservations,
+      };
+    }
+  } catch { /* fail-open: absent or corrupt registry restarts empty */ }
+  return { version: 1, counter: 0, reservations: {} };
+}
+
+function writeRegistry(path, registry) {
+  mkdirSync(join(path, '..'), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+  renameSync(tmp, path);
+}
+
+/** Synchronous sleep — Node (unlike browsers) allows `Atomics.wait` on the main thread. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Run `fn` while holding an exclusive filesystem lock at `lockPath`.
+ *
+ * `openSync(path, 'wx')` is `O_CREAT | O_EXCL` — atomic create-or-fail, the
+ * only primitive this needs and one that behaves identically on POSIX and
+ * Windows. A lock file whose mtime is older than `staleMs` is assumed to be
+ * left behind by a crashed process and is force-recovered — an orphaned lock
+ * must never strand every future reservation.
+ *
+ * @param {string} lockPath
+ * @param {() => T} fn
+ * @returns {T}
+ * @template T
+ */
+function withLock(lockPath, fn, { timeoutMs = 5000, pollMs = 20, staleMs = 15000 } = {}) {
+  mkdirSync(join(lockPath, '..'), { recursive: true });
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    let fd;
+    try {
+      fd = openSync(lockPath, 'wx');
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const st = statSync(lockPath);
+        if (Date.now() - st.mtimeMs > staleMs) {
+          try { unlinkSync(lockPath); } catch { /* raced someone else's cleanup */ }
+          continue; // retry immediately — the stale lock is (probably) gone now
+        }
+      } catch { continue; } // lock vanished between openSync and statSync — retry
+      if (Date.now() >= deadline) {
+        throw new Error(`usecase-registry: could not acquire lock at ${lockPath} within ${timeoutMs}ms`);
+      }
+      sleepSync(pollMs);
+      continue;
+    }
+    try {
+      closeSync(fd);
+      return fn();
+    } finally {
+      try { unlinkSync(lockPath); } catch { /* best-effort */ }
+    }
+  }
+}
+
+/** Highest `UC-{nn}` number found among files matching the pattern in `dir`. 0 if none/unreadable. */
+function maxUcNumberInDir(dir) {
+  let max = 0;
+  try {
+    if (!existsSync(dir)) return 0;
+    for (const name of readdirSync(dir)) {
+      const m = UC_ID_RE.exec(name);
+      if (!m) continue;
+      const n = parseInt(m[2], 10);
+      if (Number.isFinite(n) && n > max) max = n;
+    }
+  } catch { /* unreadable dir — treat as empty, never fatal */ }
+  return max;
+}
+
+/** Highest UC number across every feature's `2-plan/usecases/`, under both `.morph/features/` and `.morph/archive/`, in THIS tree. */
+function maxUcNumberLocalTree(cwd) {
+  let max = 0;
+  for (const bucket of ['features', 'archive']) {
+    const bucketDir = join(cwd, '.morph', bucket);
+    try {
+      if (!existsSync(bucketDir)) continue;
+      for (const entry of readdirSync(bucketDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        max = Math.max(max, maxUcNumberInDir(join(bucketDir, entry.name, '2-plan', 'usecases')));
+      }
+    } catch { /* unreadable bucket — treat as empty */ }
+  }
+  return max;
+}
+
+/**
+ * The highest UC number this project tree can see right now: the permanent
+ * acervo, plus every feature (active OR archived-but-not-yet-promoted, see
+ * `usecase-promoter.js`'s refusal path) in THIS tree. Exported for tests and
+ * for callers that want to preview the seed without reserving anything.
+ *
+ * @param {string} cwd
+ * @returns {number}
+ */
+export function scanLocalMax(cwd) {
+  const acervoMax = maxUcNumberInDir(join(cwd, '.morph', 'specs', 'usecases'));
+  return Math.max(acervoMax, maxUcNumberLocalTree(cwd));
+}
+
+/**
+ * Atomically reserve the next `count` UC numbers, shared across every worktree
+ * of this repo when a git common dir is resolvable.
+ *
+ * The seed is recomputed on EVERY call as `max(registry.counter, scanLocalMax(cwd))`
+ * — monotonic by construction (a max can only grow), so this doubles as both
+ * "seed the counter on the first-ever reservation" and "never regress even if
+ * the registry were somehow behind disk" without needing a separate seeded flag.
+ *
+ * @param {string} cwd
+ * @param {{ feature?: string|null, count?: number, gitCommonDir?: string|null }} opts
+ * @returns {{ numbers: string[], base: number, count: number, shared: boolean, registryPath: string }}
+ */
+export function reserveUseCases(cwd, { feature = null, count = 1, gitCommonDir = null } = {}) {
+  const n = Number.isInteger(count) && count > 0 ? count : 1;
+  const dir = registryDir({ gitCommonDir, cwd });
+  const path = ucRegistryPath({ gitCommonDir, cwd });
+  mkdirSync(dir, { recursive: true });
+
+  return withLock(join(dir, 'uc-registry.lock'), () => {
+    const registry = readRegistry(path);
+    const base = Math.max(registry.counter || 0, scanLocalMax(cwd));
+
+    // Test-only: widen the critical section so a concurrency test can prove
+    // two REAL processes racing for this lock actually serialize, instead of
+    // just happening not to overlap. Mirrors `finish.js`'s MORPH_GH_BIN test
+    // injection. Unset in every real invocation.
+    const testDelay = Number.parseInt(process.env.MORPH_UC_RESERVE_TEST_DELAY_MS, 10);
+    if (Number.isFinite(testDelay) && testDelay > 0) sleepSync(testDelay);
+
+    const numbers = [];
+    const now = new Date().toISOString();
+    for (let i = 1; i <= n; i += 1) {
+      const id = formatUcId(base + i);
+      numbers.push(id);
+      registry.reservations[id] = { feature: feature || null, reservedAt: now };
+    }
+    registry.counter = base + n;
+    writeRegistry(path, registry);
+
+    return { numbers, base, count: n, shared: !!gitCommonDir, registryPath: path };
+  });
+}
+
+/**
+ * Which feature (if any) holds the reservation for a given `UC-{nn}` id.
+ * Read-only — no lock, a slightly stale read is harmless for this use (the
+ * promoter's collision backstop, never the allocation itself).
+ *
+ * @param {string} id - e.g. "UC-07"
+ * @param {{ cwd: string, gitCommonDir?: string|null }} opts
+ * @returns {string|null}
+ */
+export function reservationOwner(id, { cwd, gitCommonDir = null }) {
+  const path = ucRegistryPath({ gitCommonDir, cwd });
+  const registry = readRegistry(path);
+  return registry.reservations?.[id]?.feature ?? null;
+}