@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

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

@@ -33,9 +33,9 @@
  * Fail-open like the promoter: no `usecases/` folder means nothing to check.
  */
 
-import { existsSync, readdirSync, readFileSync } from 'fs';
+import { readFileSync } from 'fs';
 import { join } from 'path';
-import { useCaseId } from './usecase-promoter.js';
+import { isCanonicalUseCaseName, useCaseFilesById } from './acervo-format.js';
 
 /**
  * A post-condition line: `- **P2** — Cada veterinário traz suas especialidades`.
@@ -180,23 +180,18 @@ export function parsePostConditions(content) {
  * 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, postConditions: Array<{label: string, text: string}>, artifactJustified: Map<string, string>, fullText: Map<string, string> }>}
+ * @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();
-  if (!existsSync(usecasesDir)) return byId;
-
-  let names;
-  try {
-    names = readdirSync(usecasesDir).sort();
-  } catch {
-    return byId; // unreadable folder is "no use cases", never a crash
-  }
-
-  for (const file of names) {
-    const id = useCaseId(file);
-    if (!id || !file.endsWith('.md')) continue;
+  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);
@@ -206,7 +201,7 @@ export function loadUseCases(usecasesDir) {
         fullText.set(label, block.text);
         if (block.justified) artifactJustified.set(label, block.text);
       }
-      byId.set(id, { id, file, postConditions: parsePostConditions(content), artifactJustified, fullText });
+      byId.set(id, { id, file, nonCanonical, postConditions: parsePostConditions(content), artifactJustified, fullText });
     } catch { /* one unreadable use case must not sink the rest */ }
   }
   return byId;
@@ -241,6 +236,15 @@ export function checkUseCases(tasksData, usecasesDir) {
 
   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 }));

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

@@ -30,22 +30,26 @@
  *     rather than silently destroy the other feature's use case.
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
+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;
-const UC_FILENAME_RE = new RegExp(UC.filenamePattern);
 
 /** Project-relative path of the permanent use-case archive (git pathspec-ready). */
 export const SPECS_USECASES_PATHSPEC = join('.morph', 'specs', 'usecases');
 
-/** `UC-07-listar-veterinarios.md` → `UC-07`. Null when the name isn't a use case. */
-export function useCaseId(filename) {
-  const m = /^(UC-\d+)-/.exec(filename);
-  return m ? m[1] : null;
+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;
 }
 
 /**
@@ -58,33 +62,70 @@ export function useCaseId(filename) {
  *
  * @param {string} content
  * @param {string} key
- * @param {string} value
+ * @param {string} value - written as-is; quote it first when it is free text
  * @returns {string}
  */
-function setFrontmatterField(content, key, value) {
-  const m = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(content);
+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.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);
+/**
+ * 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]);
-  return line ? line[1].trim() : null;
+  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`.
+ * 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.
@@ -93,7 +134,32 @@ function readFrontmatterField(content, key) {
  * @returns {string}
  */
 export function stampImplemented(content) {
-  return setFrontmatterField(content, 'status', 'implemented');
+  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 };
 }
 
 /**
@@ -138,27 +204,24 @@ function collisionMessage({ id, incoming, existing, existingFeature, feature, re
  * @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}> }}
- *   filenames, always arrays
+ *   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: [] };
+  const empty = { promoted: [], replaced: [], refused: [], keptSuperseded: [] };
   const srcDir = join(featureDir, UC.phaseDir, UC.dirname);
   const feature = basename(featureDir);
 
-  let names;
-  try {
-    if (!existsSync(srcDir)) return empty;
-    names = readdirSync(srcDir).filter((n) => UC_FILENAME_RE.test(n)).sort();
-  } catch {
-    return empty;
-  }
+  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 });
@@ -173,18 +236,16 @@ export function promoteUseCases(cwd, featureDir) {
 
   // Existing archive entries, indexed by use-case ID — the key the overwrite
   // rule is written against.
-  const existingById = new Map();
-  try {
-    for (const name of readdirSync(destDir)) {
-      const id = UC_FILENAME_RE.test(name) ? useCaseId(name) : null;
-      if (id) existingById.set(id, name);
-    }
-  } catch { /* unreadable archive — treat as empty, never fatal */ }
+  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
@@ -202,8 +263,7 @@ export function promoteUseCases(cwd, featureDir) {
       // (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 staleFeature = previous === null ? null : readFrontmatterField(previous, 'sourceFeature');
         const incomingOwner = id ? reservationOwner(id, { cwd, gitCommonDir }) : null;
 
         if (staleFeature && staleFeature !== feature && incomingOwner === feature) {
@@ -224,13 +284,18 @@ export function promoteUseCases(cwd, featureDir) {
         replaced.push(stale);
       }
 
-      let content = stampImplemented(readFileSync(join(srcDir, name), 'utf8'));
-      content = stampSourceFeature(content, feature);
+      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 };
+  return { promoted, replaced, refused, keptSuperseded };
 }

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

@@ -40,10 +40,9 @@ import {
 } 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+))-/;
+// From acervo-format.js, not usecase-promoter.js: the promoter depends on THIS
+// module (to look up who reserved a number), and a two-way import is circular.
+import { useCaseId } from './acervo-format.js';
 
 /** `UC-7` (or any width) -> `UC-07` — the archive's zero-padded convention. */
 function formatUcId(n) {
@@ -138,9 +137,10 @@ function maxUcNumberInDir(dir) {
   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);
+      // Any `UC-{nn}-` prefix counts, canonical or not: a number already on disk is never handed out again.
+      const id = useCaseId(name);
+      if (!id) continue;
+      const n = parseInt(id.slice('UC-'.length), 10);
       if (Number.isFinite(n) && n > max) max = n;
     }
   } catch { /* unreadable dir — treat as empty, never fatal */ }

package/src/lib/tasks/tasks-json-parser.js

@@ -12,6 +12,7 @@ import fs from 'fs-extra';
 import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { UC_ID_RE } from '../specs/acervo-format.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SCHEMA_PATH = join(__dirname, '..', '..', '..', 'framework', 'schemas', 'tasks.schema.json');
@@ -26,8 +27,6 @@ export function getSchema() {
 const VALID_STATUS = ['pending', 'in_progress', 'done', 'skipped', 'blocked'];
 const VALID_EFFORT = ['S', 'M', 'L', 'XL'];
 const VALID_GROUP = ['backend', 'frontend', 'tests', 'infra', 'docs'];
-/** Use-case reference: the ID only (`UC-07`), never the filename. */
-const USECASE_RE = /^UC-\d+$/;
 /** Veredito de reuso por conceito — ver framework/schemas/tasks.schema.json. */
 const VALID_REUSE_VERDICT = ['REUSAR', 'ESTENDER', 'CRIAR'];
 
@@ -86,7 +85,7 @@ export function validateTasksJson(data) {
     // Optional: a task with no observable behaviour references no use case.
     // When present it must be the bare ID — `morph-spec dag` is the gate that
     // catches "UC-07-listar.md" or "UC7" before the plan reaches Gate 2.
-    if (task.usecase !== undefined && (typeof task.usecase !== 'string' || !USECASE_RE.test(task.usecase))) {
+    if (task.usecase !== undefined && (typeof task.usecase !== 'string' || !UC_ID_RE.test(task.usecase))) {
       errors.push(`${ctx}.usecase must match /^UC-\\d+$/ (the ID alone, e.g. "UC-07")`);
     }