@polymorphism-tech/morph-spec 8.46.0 → 9.0.0

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

@@ -1,301 +0,0 @@
-/**
- * Cross-check between a feature's use cases and its `tasks.json`.
- *
- * This is the mechanical half of the use-case layer. Whether a post-condition is
- * *observable in a test* is semantic and stays with Gate 2 and the evaluator —
- * no checker can decide it. A narrower question IS decidable, though: a
- * post-condition phrased as "nenhum arquivo/grep/binário…" describes an
- * ARTIFACT, not behaviour, and that is a lexical warning `done-criteria-check.js`
- * raises against `dag`. A `> [!note] Por que artefato:` callout right below the
- * post-condition is how a use case justifies keeping it literal — this module
- * parses that callout (`parseArtifactJustifications`) so the lexical checker
- * can skip the labels an author already defended. What IS decidable beyond
- * that is the plumbing, and the plumbing is where the requirement actually
- * leaked before:
- *
- *   - a task pointing at a use case that does not exist  → ERROR (a broken plan)
- *   - a post-condition no task ever mentions            → warning (orphan)
- *   - a task on a use case whose `doneCriteria` carries → warning (paraphrased
- *     none of its post-conditions verbatim                instead of copied)
- *
- * Two deliberate asymmetries:
- *
- *   **Coverage is computed from the post-condition's side, never the task's.**
- *   `usecase` is optional by design — a technical task with no observable
- *   behaviour has none — so "task without a use case" is never a finding.
- *
- *   **Matching normalizes case and whitespace.** The rule is "copy the text
- *   verbatim", but a plan that prefixes the label (`"P2 — cada veterinário…"`)
- *   naturally lowercases the first letter. A raw `includes()` would reject the
- *   very example the `morph-plan` skill teaches. Accents and wording still have
- *   to match: that is the part worth being strict about.
- *
- * Fail-open like the promoter: no `usecases/` folder means nothing to check.
- */
-
-import { readFileSync } from 'fs';
-import { join } from 'path';
-import { isCanonicalUseCaseName, useCaseFilesById } from './acervo-format.js';
-
-/**
- * A post-condition line: `- **P2** — Cada veterinário traz suas especialidades`.
- * The separator is tolerant (em dash, en dash or hyphen) because the character
- * is a typing accident, not a decision.
- */
-const POSTCONDITION_RE = /^[ \t]*[-*][ \t]*\*\*(P\d+)\*\*[ \t]*[—–-][ \t]*(.+?)[ \t]*$/gm;
-
-/**
- * Single-line form of `POSTCONDITION_RE`, used to walk a document line by line.
- * DERIVED, never retyped: two hand copies drift, and a bullet shape only one
- * of them accepts makes its justification stop working in silence.
- */
-const POSTCONDITION_LINE_RE = new RegExp(POSTCONDITION_RE.source);
-
-/** Any bullet (not just a labelled post-condition) — closes an open block. */
-const BULLET_LINE_RE = /^\s*[-*]\s/;
-
-/** A markdown heading — closes an open block. */
-const HEADING_LINE_RE = /^\s*#/;
-
-/** A blockquote line — it belongs to a callout, never to the post-condition text. */
-const BLOCKQUOTE_LINE_RE = /^\s*>/;
-
-/**
- * The justification marker, ONE spelling for both forms: the callout below a
- * use-case post-condition (here) and the inline form in a task's own
- * `doneCriteria` (`done-criteria-check.js`). Tolerant of spacing — including
- * before the colon — because the spacing is a typing accident, not a decision.
- */
-export const ARTIFACT_MARKER_RE = /por\s+que\s+artefato\s*:/i;
-
-/**
- * The artifact-justification callout. It must live on its OWN line right
- * below the post-condition — never inline, because `POSTCONDITION_RE`
- * captures to end of line and that text travels literally into `doneCriteria`.
- * The foldable forms (`[!note]-`, `[!note]+`) are the same callout.
- */
-const ARTIFACT_NOTE_RE = new RegExp(String.raw`^\s*>\s*\[!note\][-+]?\s*` + ARTIFACT_MARKER_RE.source, 'i');
-
-/** Case-folded, whitespace-collapsed form used for containment tests. */
-export function normalize(text) {
-  return String(text).toLowerCase().replace(/\s+/g, ' ').trim();
-}
-
-/**
- * Parse every post-condition of a use-case document as a BLOCK: its full text
- * (first line + wrapped continuation) and whether a `> [!note] Por que
- * artefato:` callout justifies it.
- *
- * A post-condition bullet opens a block for its label; continuation lines
- * (wrapped post-condition text) are appended to the block's text; the block
- * closes at a blank line, a new bullet, or a heading — same shape as a
- * post-condition itself, so a callout separated by a blank line or living
- * under the NEXT bullet never counts.
- *
- * Blockquote lines are never post-condition text: they belong to the callout,
- * and a justification wrapped over two `>` lines is ordinary Obsidian style.
- * Once the blockquote opens, a following line without `>` is the quote's lazy
- * continuation (CommonMark), so it stays out of the text too. Appending either
- * to the post-condition produced a text no `doneCriteria` ever carries.
- *
- * A repeated label counts once — first wins, as in `parsePostConditions`.
- *
- * @param {string} content
- * @returns {Map<string, { text: string, justified: boolean }>}
- */
-export function parsePostConditionBlocks(content) {
-  const blocks = new Map();
-  let current = null; // { label, textParts: string[], justified: boolean, quoted: boolean }
-
-  const closeBlock = () => {
-    if (current && !blocks.has(current.label)) {
-      blocks.set(current.label, { text: current.textParts.join(' ').trim(), justified: current.justified });
-    }
-    current = null;
-  };
-
-  for (const line of String(content).split(/\r?\n/)) {
-    const bulletMatch = line.match(POSTCONDITION_LINE_RE);
-    if (bulletMatch) {
-      closeBlock();
-      current = { label: bulletMatch[1], textParts: [bulletMatch[2].trim()], justified: false, quoted: false };
-      continue;
-    }
-    if (!current) continue; // prose outside any post-condition block
-
-    if (line.trim() === '' || HEADING_LINE_RE.test(line) || BULLET_LINE_RE.test(line)) {
-      closeBlock();
-      continue;
-    }
-    if (BLOCKQUOTE_LINE_RE.test(line)) {
-      if (ARTIFACT_NOTE_RE.test(line)) current.justified = true;
-      current.quoted = true;
-      continue; // callout lines are metadata, never part of the post-condition text
-    }
-    if (current.quoted) continue; // lazy continuation of the blockquote
-    current.textParts.push(line.trim());
-  }
-  closeBlock();
-
-  return blocks;
-}
-
-/**
- * The justified post-conditions of a use-case document — the labels whose
- * block (see `parsePostConditionBlocks`) carried the callout.
- *
- * @param {string} content
- * @returns {Map<string, string>} label → full post-condition text (first line + continuation)
- */
-export function parseArtifactJustifications(content) {
-  const result = new Map();
-  for (const [label, block] of parsePostConditionBlocks(content)) {
-    if (block.justified) result.set(label, block.text);
-  }
-  return result;
-}
-
-/**
- * Parse one use-case document into its post-conditions.
- *
- * @param {string} content
- * @returns {Array<{ label: string, text: string }>}
- */
-export function parsePostConditions(content) {
-  const out = [];
-  const seen = new Set();
-  for (const m of String(content).matchAll(POSTCONDITION_RE)) {
-    const [, label, text] = m;
-    if (seen.has(label)) continue; // first wins — a repeated label is one post-condition
-    seen.add(label);
-    out.push({ label, text: text.trim() });
-  }
-  return out;
-}
-
-/**
- * Read every use case of a feature, keyed by ID.
- *
- * `fullText` maps EVERY label to its whole block (first line + wrapped
- * continuation); `postConditions[].text` stays the first line, which is what
- * the literal-carry check compares against.
- *
- * Any `UC-{nn}-….md` counts, canonical or not — installed plans rely on it.
- * `nonCanonical` lists the files of that id the promotion will not carry, so
- * `checkUseCases` can say so instead of the finish dropping them in silence.
- *
- * @param {string} usecasesDir - absolute path to `2-plan/usecases`
- * @returns {Map<string, { id: string, file: string, nonCanonical: string[], postConditions: Array<{label: string, text: string}>, artifactJustified: Map<string, string>, fullText: Map<string, string> }>}
- */
-export function loadUseCases(usecasesDir) {
-  const byId = new Map();
-  for (const [id, files] of useCaseFilesById(usecasesDir, { canonicalOnly: false })) {
-    const file = files[files.length - 1];
-    const nonCanonical = files.filter((f) => !isCanonicalUseCaseName(f));
-    try {
-      const content = readFileSync(join(usecasesDir, file), 'utf8');
-      const blocks = parsePostConditionBlocks(content);
-      const artifactJustified = new Map();
-      const fullText = new Map();
-      for (const [label, block] of blocks) {
-        fullText.set(label, block.text);
-        if (block.justified) artifactJustified.set(label, block.text);
-      }
-      byId.set(id, { id, file, nonCanonical, postConditions: parsePostConditions(content), artifactJustified, fullText });
-    } catch { /* one unreadable use case must not sink the rest */ }
-  }
-  return byId;
-}
-
-/**
- * Cross-check `tasks.json` against the feature's use cases.
- *
- * @param {Object} tasksData - parsed tasks.json (already schema-valid)
- * @param {string} usecasesDir - absolute path to `2-plan/usecases`
- * @returns {{ errors: string[], warnings: string[], checked: boolean }}
- *   `checked: false` means there were no use cases to check against.
- */
-export function checkUseCases(tasksData, usecasesDir) {
-  const errors = [];
-  const warnings = [];
-  const byId = loadUseCases(usecasesDir);
-  const tasks = Array.isArray(tasksData?.tasks) ? tasksData.tasks : [];
-
-  // A task referencing a use case that does not exist is a broken plan, and the
-  // check is exact: the file is there or it is not. This is the only finding
-  // that earns an error — everything below is advisory by construction.
-  for (const task of tasks) {
-    if (!task?.usecase) continue;
-    if (!byId.has(task.usecase)) {
-      const known = [...byId.keys()].sort().join(', ') || 'nenhum';
-      errors.push(
-        `${task.id}.usecase → ${task.usecase} não existe em 2-plan/usecases/ (encontrados: ${known})`
-      );
-    }
-  }
-
-  if (byId.size === 0) return { errors, warnings, checked: false };
-
-  for (const uc of byId.values()) {
-    for (const file of uc.nonCanonical) {
-      warnings.push(
-        `${uc.id} está em 2-plan/usecases/${file}, nome fora do padrão UC-{nn}-{slug}.md: ` +
-        'o finish não o promove ao acervo — renomeie'
-      );
-    }
-  }
-
-  // Pre-normalize every doneCriteria once: this is O(tasks × postConditions)
-  // and both are small, but the normalization itself is not free.
-  const criteria = tasks.map((t) => ({ id: t?.id, text: normalize(t?.doneCriteria || ''), usecase: t?.usecase }));
-
-  // Orphan post-conditions — computed from the post-condition's side, so a task
-  // without a `usecase` never counts against anyone.
-  //
-  // A use case NOBODY touches collapses into a single aggregated warning. The
-  // per-post-condition list is the useful shape while a plan is being closed
-  // (three of four covered → fix the fourth), but `dag` also runs on every
-  // implement cycle, where an untouched use case would repeat N identical lines
-  // forever. Losing the finding entirely would be worse: a use case written and
-  // then ignored by the whole plan is the failure this layer exists to catch.
-  for (const uc of byId.values()) {
-    const withText = uc.postConditions.filter((pc) => normalize(pc.text));
-    if (withText.length === 0) continue;
-
-    const orphans = withText.filter((pc) => !criteria.some((c) => c.text.includes(normalize(pc.text))));
-    if (orphans.length === 0) continue;
-
-    const untouched = orphans.length === withText.length && !criteria.some((c) => c.usecase === uc.id);
-    if (untouched) {
-      warnings.push(
-        `${uc.id} não é referenciado por nenhuma task — ${withText.length} pós-condição(ões) sem cobertura ` +
-        `(${withText.map((p) => p.label).join('/')})`
-      );
-      continue;
-    }
-    for (const pc of orphans) {
-      warnings.push(
-        `${uc.id} ${pc.label} não é coberta por nenhuma task — nenhum doneCriteria carrega "${pc.text}"`
-      );
-    }
-  }
-
-  // Tasks that claim a use case but paraphrased it instead of copying it.
-  for (const c of criteria) {
-    if (!c.usecase) continue;
-    const uc = byId.get(c.usecase);
-    if (!uc || uc.postConditions.length === 0) continue;
-    const carries = uc.postConditions.some((pc) => {
-      const needle = normalize(pc.text);
-      return needle && c.text.includes(needle);
-    });
-    if (!carries) {
-      warnings.push(
-        `${c.id}.doneCriteria não carrega nenhuma pós-condição de ${c.usecase} literalmente ` +
-        `(esperado o texto de ${uc.postConditions.map((p) => p.label).join('/')})`
-      );
-    }
-  }
-
-  return { errors, warnings, checked: true };
-}

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

@@ -1,301 +0,0 @@
-/**
- * Promotion of a feature's use cases into the project's permanent archive.
- *
- * A use case is born inside a feature (`2-plan/usecases/UC-{nn}-{slug}.md`) and
- * is promoted, at archive time, into `.morph/specs/usecases/` — the living
- * description of the system's behaviour, which outlives the feature that
- * introduced it. The archive is COMMITTED (no gitignore rule covers it).
- *
- * Contract, in the order it matters:
- *   - **Fail-open.** Every failure degrades to "nothing promoted". Promotion may
- *     never block the close of a feature — that is why the caller treats a throw
- *     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 — 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 { mkdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
-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';
-import { SUPERSEDED, useCaseFilesById, useCaseId } from './acervo-format.js';
-
-export { useCaseId };
-
-const UC = OUTPUT_SCHEMA.usecases;
-
-/** Project-relative path of the permanent use-case archive (git pathspec-ready). */
-export const SPECS_USECASES_PATHSPEC = join('.morph', 'specs', 'usecases');
-
-const FRONTMATTER_RE = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/;
-
-/** `true` when the document opens with a frontmatter block. */
-export function hasFrontmatter(content) {
-  const m = FRONTMATTER_RE.exec(content);
-  return !!m && m.index === 0;
-}
-
-/**
- * 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 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 - written as-is; quote it first when it is free text
- * @returns {string}
- */
-export function setFrontmatterField(content, key, value) {
-  const m = FRONTMATTER_RE.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 fieldLine = new RegExp(`^${key}:[ \\t]*.*$`, 'm');
-  // Function replacer: a value carrying `$&` or `$1` is text, not a pattern.
-  const next = fieldLine.test(body)
-    ? body.replace(fieldLine, () => `${key}: ${value}`)
-    : `${body}${eol}${key}: ${value}`;
-
-  return open + next + close + content.slice(full.length);
-}
-
-/**
- * Drop a single top-level frontmatter field (its whole line, EOL included).
- * Absent field or no frontmatter → content unchanged.
- *
- * @param {string} content
- * @param {string} key
- * @returns {string}
- */
-export function removeFrontmatterField(content, key) {
-  const m = FRONTMATTER_RE.exec(content);
-  if (!m || m.index !== 0) return content;
-
-  const [full, open, body, close] = m;
-  const lines = body.split(/(?<=\n)/);
-  const kept = lines.filter((line) => !new RegExp(`^${key}:`).test(line));
-  if (kept.length === lines.length) return content;
-  // The last kept line lost its EOL when the removed one was the final line;
-  // the closing delimiter carries its own leading EOL, so trim the dangling one.
-  const next = kept.join('').replace(/\r?\n$/, '');
-  return open + next + close + content.slice(full.length);
-}
-
-/**
- * Read a single top-level frontmatter field. `null` when absent or there is no
- * frontmatter block. A double-quoted value is read as the JSON string it is
- * written as (that is how free text such as `scope:` is stored); a
- * single-quoted one as YAML reads it (`''` is a quote).
- */
-export function readFrontmatterField(content, key) {
-  const m = FRONTMATTER_RE.exec(content);
-  if (!m || m.index !== 0) return null;
-  const line = new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, 'm').exec(m[2]);
-  if (!line) return null;
-  const raw = line[1].trim();
-  if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
-    try { return JSON.parse(raw); } catch { return raw; }
-  }
-  if (raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1).replace(/''/g, "'");
-  return raw;
-}
-
-/**
- * Rewrite the frontmatter `status:` to `implemented` — unless the use case is
- * superseded (its status says so, or it carries a `superseded_by`): a
- * promotion, such as a `bug` fix on the part that still holds, must never
- * hand the rest of it back its authority.
- *
- * 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) {
-  const superseded = readFrontmatterField(content, 'status') === SUPERSEDED
-    || readFrontmatterField(content, 'superseded_by') !== null;
-  return setFrontmatterField(content, 'status', superseded ? SUPERSEDED : 'implemented');
-}
-
-/**
- * Carry the acervo's supersession onto an incoming copy that does not declare
- * one — a copy taken before the revocation landed, or stripped of the fields
- * on the way. Without this the promotion would publish the old use case as
- * `implemented` again.
- *
- * @param {string} content  - the incoming copy
- * @param {string|null} previous - the acervo entry it replaces
- * @returns {{ content: string, supersededBy: string|null, scope: string|null }|null} null = nothing to carry
- */
-function inheritSupersession(content, previous) {
-  if (!previous || readFrontmatterField(previous, 'status') !== SUPERSEDED) return null;
-  if (readFrontmatterField(content, 'status') === SUPERSEDED || readFrontmatterField(content, 'superseded_by') !== null) return null;
-  if (!hasFrontmatter(content)) return null;
-
-  const supersededBy = readFrontmatterField(previous, 'superseded_by');
-  const scope = readFrontmatterField(previous, 'scope');
-  let next = setFrontmatterField(content, 'status', SUPERSEDED);
-  if (supersededBy) next = setFrontmatterField(next, 'superseded_by', supersededBy);
-  if (scope !== null) next = setFrontmatterField(next, 'scope', JSON.stringify(scope));
-  return { content: next, supersededBy, scope };
-}
-
-/**
- * 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[], refused: Array<{id: string,
- *   incoming: string, existing: string, existingFeature: string, message: string}>,
- *   keptSuperseded: Array<{id: string, file: string, supersededBy: string|null, scope?: string}> }}
- *   always arrays; `keptSuperseded` = promoted copies that stayed superseded
- *   because the acervo entry they replaced was
- */
-export function promoteUseCases(cwd, featureDir) {
-  const empty = { promoted: [], replaced: [], refused: [], keptSuperseded: [] };
-  const srcDir = join(featureDir, UC.phaseDir, UC.dirname);
-  const feature = basename(featureDir);
-
-  const names = [...useCaseFilesById(srcDir).values()].flat().sort();
-  if (!names.length) return empty;
-
-  const destDir = join(cwd, '.morph', 'specs', 'usecases');
-  const promoted = [];
-  const replaced = [];
-  const refused = [];
-  const keptSuperseded = [];
-
-  try {
-    mkdirSync(destDir, { recursive: true });
-  } catch {
-    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([...useCaseFilesById(destDir)].map(([id, files]) => [id, files[files.length - 1]]));
-
-  for (const name of names) {
-    try {
-      const id = useCaseId(name);
-      const stale = id ? existingById.get(id) : null;
-      let previous = null;
-      if (stale) {
-        try { previous = readFileSync(join(destDir, stale), 'utf8'); } catch { /* unreadable — no signal */ }
-      }
-
-      // 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) {
-        const staleFeature = previous === null ? null : readFrontmatterField(previous, 'sourceFeature');
-        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 = readFileSync(join(srcDir, name), 'utf8');
-      const kept = inheritSupersession(content, previous);
-      if (kept) {
-        content = kept.content;
-        keptSuperseded.push({ id, file: name, supersededBy: kept.supersededBy, ...(kept.scope !== null ? { scope: kept.scope } : {}) });
-      }
-      content = stampSourceFeature(stampImplemented(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, refused, keptSuperseded };
-}