@polymorphism-tech/morph-spec 8.22.0 → 8.24.1

package/src/commands/state/archive.js

@@ -63,7 +63,8 @@ function readReviewApproved(fjPath) {
  * @param {string} feature
  * @param {{ cwd?: string, force?: boolean, git?: boolean }} [opts]
  * @returns {{ ok: boolean, error?: string, archived?: boolean, alreadyArchived?: boolean,
- *   committed?: boolean, staged?: boolean, archivePath?: string, promotedUseCases?: string[] }}
+ *   committed?: boolean, staged?: boolean, archivePath?: string, promotedUseCases?: string[],
+ *   refusedUseCases?: Array<{id: string, incoming: string, existing: string, existingFeature: string, message: string}> }}
  */
 export function runArchive(feature, opts = {}) {
   const cwd = opts.cwd || process.cwd();
@@ -156,9 +157,11 @@ export function runArchive(feature, opts = {}) {
   //    (MORPH.md §2.2). Fail-open: any failure degrades to "promoted nothing",
   //    never to a refused close.
   let promotedUseCases = [];
+  let refusedUseCases = [];
   try {
-    const { promoted } = promoteUseCases(cwd, archivePath);
+    const { promoted, refused } = promoteUseCases(cwd, archivePath);
     promotedUseCases = promoted;
+    refusedUseCases = refused;
     if (promoted.length && useGit && staged) {
       // This staging exists for the NEW files: promoted use cases are untracked,
       // and the scoped `commit -- <pathspec>` below only knows paths git already
@@ -203,7 +206,7 @@ export function runArchive(feature, opts = {}) {
     } catch { /* index is derivable — non-fatal */ }
   }
 
-  return { ok: true, archived: true, committed, staged, archivePath, promotedUseCases };
+  return { ok: true, archived: true, committed, staged, archivePath, promotedUseCases, refusedUseCases };
 }
 
 /**
@@ -244,6 +247,12 @@ export async function archiveCommand(featureName, options = {}) {
     if (result.promotedUseCases?.length) {
       console.log(chalk.gray(`   ${result.promotedUseCases.length} use case(s) promoted → .morph/specs/usecases/ (status: implemented).`));
     }
+    if (result.refusedUseCases?.length) {
+      console.log(chalk.yellow(`\n⚠️  ${result.refusedUseCases.length} use case(s) NOT promoted — numbering collision:`));
+      for (const r of result.refusedUseCases) {
+        console.log(chalk.yellow(`   ${r.message}`));
+      }
+    }
     if (result.committed) console.log(chalk.gray(`   Move committed on the current branch.\n`));
     else if (result.staged) console.log(chalk.gray(`   Move staged in git; commit it when ready.\n`));
     else console.log('');

package/src/commands/state/finish.js

@@ -10,6 +10,7 @@ import {
   isValidFeatureName,
   buildBranchName,
   branchExists,
+  cwdIsInsideWorktree,
 } from '../project/worktree.js';
 import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
 import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js';
@@ -162,16 +163,14 @@ export async function finishCommand(feature, options = {}) {
     // a de-registered worktree, and a `relinkHint` telling the user to repair
     // by hand. Refuse HERE, before the first mutation — the cost is one
     // `cd`, and it is the exact failure observed in the ProspectPRO session.
-    const cwdNorm = resolve(cwd).replace(/\\/g, '/');
-    const wtNorm = resolve(worktreePath).replace(/\\/g, '/');
-    if (cwdNorm === wtNorm || cwdNorm.startsWith(`${wtNorm}/`)) {
+    if (cwdIsInsideWorktree(cwd, worktreePath)) {
       emit({
         finished: false,
         error: 'cwd-inside-worktree',
         feature,
         path: worktreePath,
         root,
-        hint: `saia do worktree antes do finish — o \`git worktree remove\` não consegue apagar o diretório de trabalho do próprio processo. Rode de novo a partir de "${root}"`,
+        hint: `saia do worktree antes do finish — a remoção não consegue apagar o diretório de trabalho do próprio processo. Rode de novo a partir de "${root}"`,
       });
       process.exit(1);
     }
@@ -405,12 +404,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 }) {
@@ -436,15 +440,25 @@ function teardownExtras(teardown, worktreePath, branch, deleteBranch) {
     if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
     if (teardown.ignoredBlocking.length) out.ignoredFiles = teardown.ignoredBlocking;
     out.cleanupHint = teardown.declineReason;
-    // The unlink runs before the removal by design (it is what keeps `git
-    // worktree remove` from following the junctions out into the primary root),
-    // so a declined removal always passes through a moment with the infra
-    // loose. The teardown now re-links on that path — report which of the two
-    // actually happened instead of always announcing the worse one (A4).
+    // The unlink runs before the removal by design (it is what keeps the removal
+    // from following the junctions out into the primary root), so every
+    // non-removal passes through a moment with the infra loose. What happens
+    // next depends on WHY, and the two must not be reported alike:
+    //   REFUSED — we proved removal unsafe, the user keeps working here, so the
+    //     teardown re-links (A4).
+    //   FAILED  — removal was the intent and a lock got in the way. The infra
+    //     stays down ON PURPOSE, so the retry (or anything pasted from an old
+    //     transcript) has nothing to traverse. Say so explicitly, or the user
+    //     reads a bare "failed" and reaches for the destructive command.
     out.relinked = teardown.relinked === true;
-    out.relinkHint = teardown.relinked
-      ? 'as junctions de infra foram soltas antes da tentativa e RESTAURADAS após a recusa — o worktree segue utilizável'
-      : `as junctions de infra foram soltas antes desta recusa e não puderam ser restauradas — para continuar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
+    if (!teardown.refused) {
+      if (teardown.infraLeftUnlinked?.length) out.infraLeftUnlinked = teardown.infraLeftUnlinked;
+      out.relinkHint = `a remoção falhou e as junctions de infra foram deixadas DESMONTADAS de propósito — qualquer nova tentativa é segura. Para voltar a trabalhar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
+    } else {
+      out.relinkHint = teardown.relinked
+        ? 'as junctions de infra foram soltas antes da tentativa e RESTAURADAS após a recusa — o worktree segue utilizável'
+        : `as junctions de infra foram soltas antes desta recusa e não puderam ser restauradas — para continuar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
+    }
   }
   return out;
 }

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