@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/src/lib/installers/memory-installer.js

@@ -1,5 +1,5 @@
 /**
- * Memory Installer — populates Claude Code persistent memory during morph-init.
+ * Memory Installer — populates Claude Code persistent memory during `morph-spec init`.
  *
  * Writes two memory files (project + reference) plus an entry in MEMORY.md
  * so future Claude Code sessions enter pre-contextualized about the
@@ -67,7 +67,6 @@ metadata:
 - When user mentions a feature, check \`.morph/features/\` first.
 - When user types \`/morph-proposal\`, invoke \`Skill(morph-proposal)\` directly.
 - In \`trust: "auto"\`, gates auto-pass; only AskUserQuestion on risk signals.
-- Prefer morph-* skills over superpowers:* equivalents in this project.
 `;
 }
 

package/src/lib/projects/registry.js

@@ -0,0 +1,154 @@
+/**
+ * Where the morph-spec projects on this machine are — the list the dashboard's
+ * portfolio reads. Nothing else records it: each project only knows its own
+ * `.morph/`.
+ *
+ * Three writers register a project as a side note of what they already do —
+ * `init`, `update` (never under `--dry-run`) and `dashboard` — and the
+ * dashboard adds and removes on request. Registering is fail-open: a registry
+ * that cannot be read or written never fails the command that tried.
+ *
+ * The file lives in the user's home (`~/.morph-spec/projects.json`, or
+ * `MORPH_PROJECTS_REGISTRY`), read through `os.homedir()` at call time so a
+ * suite that isolates the home also isolates this file. Paths under the
+ * system temp dir are never registered: the test suites run `init`/`update`
+ * there by the hundred, including through spawned CLIs that keep the real home.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { homedir, tmpdir } from 'os';
+import { join, resolve, basename, dirname } from 'path';
+import { atomicWriteJson } from '../../core/state/state-manager.js';
+import { canonicalPath, isInside } from '../tasks/test-runner.js';
+import { WORKTREE_DIR_NAMES } from '../worktree/dirs.js';
+
+export const REGISTRY_VERSION = 1;
+
+export function registryPath() {
+  return process.env.MORPH_PROJECTS_REGISTRY || join(homedir(), '.morph-spec', 'projects.json');
+}
+
+/** One spelling per directory: canonical, forward slashes (the registry is read back on any OS). */
+export function projectKey(dir) {
+  return canonicalPath(resolve(dir)).replace(/\\/g, '/');
+}
+
+const sameDir = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+
+/** A folder is a morph-spec project when morph-spec installed its config there. */
+export function isMorphProject(dir) {
+  return existsSync(join(dir, '.morph', 'config', 'config.json'));
+}
+
+/** A worktree checkout is part of its repo's project, never a project of its own. */
+function insideWorktreeContainer(dir) {
+  const parent = basename(dirname(dir));
+  return WORKTREE_DIR_NAMES.includes(parent);
+}
+
+function projectName(dir) {
+  try {
+    const config = JSON.parse(readFileSync(join(dir, '.morph', 'config', 'config.json'), 'utf8'));
+    const name = config?.project?.name;
+    // Some configs carry the project path as its name; the folder reads better.
+    return typeof name === 'string' && name.trim() && !/[\\/]/.test(name) ? name.trim() : basename(dir);
+  } catch {
+    return basename(dir);
+  }
+}
+
+/**
+ * The registered projects that still exist. A folder that was deleted or lost
+ * its `.morph/` drops out on read — the file is rewritten on the next write.
+ *
+ * @returns {{ version: number, projects: Array<{ dir: string, name: string, addedAt: string, lastSeenAt: string, source: string }> }}
+ */
+export function readRegistry() {
+  let data = null;
+  try {
+    const path = registryPath();
+    if (existsSync(path)) data = JSON.parse(readFileSync(path, 'utf8'));
+  } catch { /* unreadable registry reads as empty */ }
+  const projects = Array.isArray(data?.projects) ? data.projects : [];
+  return {
+    version: REGISTRY_VERSION,
+    projects: projects.filter((p) => typeof p?.dir === 'string' && isMorphProject(p.dir)),
+  };
+}
+
+function write(projects) {
+  atomicWriteJson(registryPath(), { version: REGISTRY_VERSION, projects });
+}
+
+/**
+ * Note that `dir` is a morph-spec project. Idempotent; refreshes `lastSeenAt`.
+ * Never throws.
+ *
+ * @param {string} dir
+ * @param {'init'|'update'|'dashboard'|'manual'} source
+ * @param {{ tempRoot?: string }} [opts] - test seam: the folder whose
+ *   projects are never registered (the system temp dir)
+ * @returns {boolean} true when the project is in the registry afterwards
+ */
+export function registerProject(dir, source, { tempRoot = tmpdir() } = {}) {
+  try {
+    const key = projectKey(dir);
+    if (isInside(canonicalPath(key), canonicalPath(tempRoot))) return false;
+    if (!isMorphProject(key) || insideWorktreeContainer(key)) return false;
+    const now = new Date().toISOString();
+    const { projects } = readRegistry();
+    const found = projects.find((p) => sameDir(p.dir, key));
+    if (found) {
+      found.lastSeenAt = now;
+      found.name = projectName(key);
+    } else {
+      projects.push({ dir: key, name: projectName(key), addedAt: now, lastSeenAt: now, source });
+    }
+    write(projects);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Take a project off the list. Its files are not touched. Never throws. */
+export function unregisterProject(dir) {
+  try {
+    const key = projectKey(dir);
+    const { projects } = readRegistry();
+    const kept = projects.filter((p) => !sameDir(p.dir, key));
+    if (kept.length !== projects.length) write(kept);
+    return kept.length !== projects.length;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * morph-spec projects directly under each root that are not registered yet —
+ * the portfolio offers them, the person decides. One level deep: a repos
+ * folder is the expected root, and a deeper walk would enter node_modules and
+ * worktrees for nothing.
+ *
+ * @param {string[]} roots
+ * @returns {Array<{ dir: string, name: string }>}
+ */
+export function discoverProjects(roots) {
+  const registered = readRegistry().projects.map((p) => p.dir);
+  const out = [];
+  const seen = new Set();
+  for (const root of roots) {
+    let entries = [];
+    try { entries = readdirSync(root, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name.startsWith('.') || e.name === 'node_modules') continue;
+      const dir = join(root, e.name);
+      if (!isMorphProject(dir)) continue;
+      const key = projectKey(dir);
+      if (seen.has(key.toLowerCase()) || registered.some((r) => sameDir(r, key))) continue;
+      seen.add(key.toLowerCase());
+      out.push({ dir: key, name: projectName(key) });
+    }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/lib/risk-detector.js

@@ -23,6 +23,10 @@
  *     evaluator-report.md. No ship, relatório SEM a seção `## Mutações` numa
  *     feature com código de produção pausa: score é opinião, mutação é prova
  *   - mediaClaims + gate: object      — { section, score, featureGeneratesMedia }
+ *   - screenChecklist + gate: object  — { mockups, legacy, screens, problems, exempt?,
+ *     section?, uncovered? } derivado do 1-design/mockups.md. No uiux, checklist
+ *     de tela incompleto pausa; no ship, item decidido sem a conferência do
+ *     avaliador pausa. Mockup legado é isento nos dois, com a razão listada
  *   - evalScore: number               — morph-eval score (pause if < 9)
  *   - taskCount: number               — total tasks (pause if > 20)
  */
@@ -133,6 +137,35 @@ function e2eScopeRefusal(klass, scope, reason) {
        + ' rode `morph-spec verify {feature}` (sem task) antes do ship';
 }
 
+/** A razão gravada no sinal quando o checklist de tela isenta um mockup legado. */
+export const LEGACY_MOCKUP_EXEMPTION = 'checklist dispensado: mockup no formato antigo';
+
+/** Os dois primeiros itens de uma lista, e quantos ficaram de fora. */
+function firstOf(items) {
+  const shown = items.slice(0, 2).join('; ');
+  return items.length > 2 ? `${shown} (+${items.length - 2})` : shown;
+}
+
+/**
+ * Por que o checklist de tela pausa o Gate uiux, ou null. Exportada porque o
+ * `approve`/`advance` com assinatura `auto` recusam pela MESMA regra: uma
+ * aprovação automática que passasse onde o gate-check pausa seria o atalho.
+ *
+ * Mockup ausente (`mockups: false`) não conta — nem toda feature de UI tem
+ * tela —, e o legado chega sem problemas: a auditoria o isenta.
+ *
+ * @param {object|undefined} screenChecklist - o sinal de `collectScreenChecklist`
+ * @returns {string|null}
+ */
+export function uiuxChecklistPause(screenChecklist) {
+  if (screenChecklist?.mockups !== true) return null;
+  const problems = screenChecklist.problems ?? [];
+  if (problems.length === 0) return null;
+  return `checklist de tela incompleto em 1-design/mockups.md: ${firstOf(problems)}`
+       + ' — volume, paginação, ordenação, filtro, os três estados, mobile e abas por tela'
+       + ' ("não se aplica" vale, se escrito)';
+}
+
 /**
  * @param {object} config - .morph/config/config.json contents (uses `trust`)
  * @param {object} signals
@@ -362,6 +395,36 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
+  // No fecho do DESIGN: o mockup declara telas sem o checklist de tela
+  // completo. É ele que faz paginação, ordenação, filtro e os três estados
+  // virarem `doneCriteria` — sem ele, uma lista de 2 000 linhas é aprovada
+  // listando tudo, e o implementador entrega exatamente o critério.
+  if (signals.gate === 'uiux') {
+    const reason = uiuxChecklistPause(signals.screenChecklist);
+    if (reason) return { pause: true, reason };
+  }
+
+  // No SHIP, depois da cláusula de mídia e pela mesma disciplina: o design
+  // decidiu itens de tela e o avaliador não registrou a conferência deles
+  // contra a tela entregue. Cobra-se o item DEVIDO (`uncovered`): tela toda
+  // "não se aplica", mockup legado ou ausente não devem nada.
+  if (signals.gate === 'review' && (signals.screenChecklist?.uncovered?.length ?? 0) > 0) {
+    const { section, uncovered } = signals.screenChecklist;
+    if (section !== true) {
+      return {
+        pause: true,
+        reason: `relatório do avaliador sem a seção \`## Checklist de tela\` — o design decidiu ${firstOf(uncovered)}`
+              + ' e a avaliação não registrou a conferência contra a tela entregue'
+              + ' (rubrica evals/rubrics/contracts.md, "Contrato de tela")',
+      };
+    }
+    return {
+      pause: true,
+      reason: `a seção \`## Checklist de tela\` não confere ${firstOf(uncovered)}`
+            + ' — uma linha por item decidido de cada tela, mesmo quando não verificável',
+    };
+  }
+
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     return {
       pause: true,
@@ -455,6 +518,33 @@ export function getRiskSignals(signals) {
     }
   }
 
+  // Listado mesmo quando NÃO pausa: a isenção (sem mockup, legado, nada
+  // devido) e o checklist conferido precisam ser distinguíveis de uma omissão.
+  if ((signals.gate === 'uiux' || signals.gate === 'review') && signals.screenChecklist) {
+    const { mockups, legacy, exempt, screens = [], problems = [], section, uncovered = [] } = signals.screenChecklist;
+    if (!mockups) {
+      out.push('sem 1-design/mockups.md — checklist de tela não se aplica');
+    } else if (legacy === true) {
+      out.push(exempt ?? LEGACY_MOCKUP_EXEMPTION);
+    } else if (signals.gate === 'uiux') {
+      out.push(problems.length > 0
+        ? `checklist de tela incompleto (${problems.length} problema(s))`
+        : `checklist de tela completo (${screens.length} tela(s))`);
+    } else if (uncovered.length > 0) {
+      out.push(section !== true
+        ? 'relatório sem a seção `## Checklist de tela`'
+        : `checklist de tela sem conferência em ${uncovered.length} tela(s)`);
+    } else if (screens.length === 0) {
+      // O design passou pela uiux sem tela nenhuma: nada a cobrar no ship, mas
+      // não pode ler igual a uma tela toda "não se aplica".
+      out.push(`checklist de tela: ${firstOf(problems)}`);
+    } else if (section === true) {
+      out.push(`checklist de tela conferido (${screens.length} tela(s))`);
+    } else {
+      out.push(`checklist de tela sem item a conferir (${screens.length} tela(s))`);
+    }
+  }
+
   return out;
 }
 

package/src/lib/specs/acervo-format.js

@@ -0,0 +1,70 @@
+/**
+ * The shapes every reader and writer of the acervo agrees on — one copy each.
+ * A second copy of any of these is how two readers start disagreeing about the
+ * same file: a use case one of them sees and the other does not, a table row
+ * one of them splits differently.
+ */
+
+import { existsSync, readdirSync } from 'fs';
+import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
+
+/** A use-case id: `UC-07`. */
+export const UC_ID_RE = /^UC-\d+$/;
+
+/** A use case no longer holds as the system's behaviour (or holds only in its `scope`). */
+export const SUPERSEDED = 'superseded';
+
+const UC_FILENAME_RE = new RegExp(OUTPUT_SCHEMA.usecases.filenamePattern);
+
+/** `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;
+}
+
+/** The name the promotion carries: `UC-{nn}-{slug}.md`, slug in lowercase kebab. */
+export const isCanonicalUseCaseName = (name) => UC_FILENAME_RE.test(name);
+
+/**
+ * Every use case in `dir`, grouped by id. By default only the canonical names
+ * — the ones the promotion ever carries. `canonicalOnly: false` also lists any
+ * `UC-{nn}-….md`, for the plan-time check that has always accepted them and
+ * now warns instead. An id with more than one file is a broken acervo, and
+ * readers must be able to see it rather than silently pick one.
+ *
+ * @param {string} dir
+ * @param {{ canonicalOnly?: boolean }} [options]
+ * @returns {Map<string, string[]>} id → filenames, sorted; empty when the folder is missing or unreadable
+ */
+export function useCaseFilesById(dir, { canonicalOnly = true } = {}) {
+  const byId = new Map();
+  try {
+    if (!existsSync(dir)) return byId;
+    for (const name of readdirSync(dir).sort()) {
+      const id = useCaseId(name);
+      if (!id || !name.endsWith('.md')) continue;
+      if (canonicalOnly && !isCanonicalUseCaseName(name)) continue;
+      if (!byId.has(id)) byId.set(id, []);
+      byId.get(id).push(name);
+    }
+  } catch { /* unreadable — nothing to see */ }
+  return byId;
+}
+
+/** A markdown table separator row: `|---|:--:|`, with or without the outer pipes. */
+export const SEPARATOR_ROW_RE = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
+
+/** A line that belongs to a table: it carries an unescaped pipe (GFM does not require the leading one). */
+export const isTableLine = (line) => /(?<!\\)\|/.test(line);
+
+/**
+ * Split a table row on unescaped pipes, outer pipes optional; `\|` inside a
+ * cell is a literal pipe.
+ *
+ * @param {string} row
+ * @returns {string[]} trimmed cells
+ */
+export function tableCells(row) {
+  const inner = row.trim().replace(/^\|/, '').replace(/(?<!\\)\|$/, '');
+  return inner.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, '|').trim());
+}

package/src/lib/specs/acervo-lifecycle.js

@@ -0,0 +1,264 @@
+/**
+ * Lifecycle of the project's acervo: a use case stops being the current
+ * behaviour when a later feature supersedes it.
+ *
+ *   status: superseded
+ *   superseded_by: UC-589
+ *   scope: "vitrine pública, fora de `.morph-admin-shell`"    ← only when partial
+ *
+ * Three roles live here:
+ *   - the ONE rule for that frontmatter (`supersessionProblems`) — the check
+ *     reads it, and the writer below only ever produces what it accepts;
+ *   - the close-time writer (`applySpecRevocations`): what the feature's
+ *     `spec.md` declared it revokes lands on `.morph/specs/usecases/` and on
+ *     the ADR index, fail-open like the promotion it follows;
+ *   - the plan-time check (`checkLifecycle`), shared by `dag` and `usecase
+ *     check`, run while `spec.md` can still be fixed.
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
+import {
+  SPECS_USECASES_PATHSPEC,
+  hasFrontmatter,
+  readFrontmatterField,
+  removeFrontmatterField,
+  setFrontmatterField,
+} from './usecase-promoter.js';
+import { SUPERSEDED, UC_ID_RE, useCaseFilesById } from './acervo-format.js';
+import { parseRevocations } from './revocations.js';
+import { ADR_INDEX_PATHSPEC, readAdrIndex, updateAdrIndex } from './adr-index.js';
+
+export { SUPERSEDED };
+
+const UC = OUTPUT_SCHEMA.usecases;
+const ACERVO_LABEL = SPECS_USECASES_PATHSPEC.replace(/\\/g, '/');
+const ADR_INDEX_LABEL = `${ADR_INDEX_PATHSPEC.replace(/\\/g, '/')}/`;
+
+/** @returns {{ status: string|null, supersededBy: string|null, scope: string|null }} */
+export function lifecycleOf(content) {
+  return {
+    status: readFrontmatterField(content, 'status'),
+    supersededBy: readFrontmatterField(content, 'superseded_by'),
+    scope: readFrontmatterField(content, 'scope'),
+  };
+}
+
+/**
+ * The rule for a use case's supersession frontmatter.
+ *
+ * @param {string} content
+ * @param {string} id - the use case's own id
+ * @returns {string[]} one line per problem; `[]` = well formed
+ */
+export function supersessionProblems(content, id) {
+  const { status, supersededBy, scope } = lifecycleOf(content);
+  const problems = [];
+  if (status === SUPERSEDED) {
+    if (!supersededBy) problems.push('status: superseded sem superseded_by');
+    else if (!UC_ID_RE.test(supersededBy)) problems.push(`superseded_by "${supersededBy}" não é um UC-{nn}`);
+    else if (supersededBy === id) problems.push('superseded_by aponta para o próprio use case');
+  } else if (supersededBy !== null || scope !== null) {
+    problems.push(`${supersededBy !== null ? 'superseded_by' : 'scope'} sem status: superseded`);
+  }
+  if (scope !== null && !String(scope).trim()) problems.push('scope vazio');
+  return problems;
+}
+
+function readOrNull(path) {
+  try { return readFileSync(path, 'utf8'); } catch { return null; }
+}
+
+const specPathOf = (featureDir) => join(featureDir, OUTPUT_SCHEMA.spec.phaseDir, OUTPUT_SCHEMA.spec.filename);
+
+/** A finished feature cannot be re-closed: the fix is the next feature's revocation row. */
+const FIX_NEXT_TIME = 'corrija a linha na seção de revogações do spec.md — a feature já arquivada não é reprocessada, ' +
+  'então a revogação corrigida entra no spec.md da próxima feature';
+
+/**
+ * Mark the acervo use cases the entries revoke. Runs after the promotion, so
+ * the acervo already holds every substitute this feature brought — except the
+ * ones the promotion refused, which only LOOK present (the file under that id
+ * belongs to another feature).
+ *
+ * @returns {{ superseded: Array<{id: string, file: string, supersededBy: string, scope?: string}>,
+ *   problems: Array<{id: string, reason: string, message: string}> }}
+ */
+function supersedeUseCases(cwd, entries, refusedIds) {
+  const superseded = [];
+  const problems = [];
+  if (!entries.length) return { superseded, problems };
+
+  const dir = join(cwd, SPECS_USECASES_PATHSPEC);
+  const files = useCaseFilesById(dir);
+  const problem = (id, reason, message) => problems.push({ id, reason, message });
+
+  for (const e of entries) {
+    const targets = files.get(e.id) ?? [];
+    if (targets.length === 0) {
+      problem(e.id, 'not-in-acervo', `${e.id} não está no acervo (${ACERVO_LABEL}/) — nada foi marcado; ${FIX_NEXT_TIME}`);
+      continue;
+    }
+    if (targets.length > 1) {
+      problem(e.id, 'duplicate-in-acervo',
+        `${e.id} tem ${targets.length} arquivos no acervo (${targets.join(', ')}) — nenhum foi marcado; o acervo precisa de um arquivo por UC`);
+      continue;
+    }
+    if (refusedIds.has(e.substitute)) {
+      problem(e.id, 'substitute-refused',
+        `o substituto ${e.substitute} de ${e.id} não foi promovido (colisão de numeração) — ${e.id} não foi marcado`);
+      continue;
+    }
+    if (!files.has(e.substitute)) {
+      problem(e.id, 'substitute-not-found',
+        `o substituto ${e.substitute} de ${e.id} não está no acervo — ${e.id} não foi marcado; ${FIX_NEXT_TIME}`);
+      continue;
+    }
+
+    const file = targets[0];
+    try {
+      const path = join(dir, file);
+      const before = readFileSync(path, 'utf8');
+      if (!hasFrontmatter(before)) {
+        problem(e.id, 'no-frontmatter', `${ACERVO_LABEL}/${file} não tem frontmatter — o status não foi aplicado`);
+        continue;
+      }
+      let next = setFrontmatterField(before, 'status', SUPERSEDED);
+      next = setFrontmatterField(next, 'superseded_by', e.substitute);
+      // JSON-quoted: free text with `: ` or a leading backtick breaks a bare YAML scalar.
+      next = e.scope
+        ? setFrontmatterField(next, 'scope', JSON.stringify(e.scope))
+        : removeFrontmatterField(next, 'scope');
+      if (next !== before) writeFileSync(path, next, 'utf8');
+      superseded.push({ id: e.id, file, supersededBy: e.substitute, ...(e.scope ? { scope: e.scope } : {}) });
+    } catch {
+      problem(e.id, 'unwritable', `${ACERVO_LABEL}/${file} não pôde ser lido/gravado — o status não foi aplicado`);
+    }
+  }
+  return { superseded, problems };
+}
+
+/**
+ * Apply, at close time, what the feature's `spec.md` declared it revokes.
+ * Fail-open: nothing here may refuse the close; what did not apply comes back
+ * in `problems`, next to the row's own parse problems.
+ *
+ * @param {string} cwd        - project root that owns `.morph/specs/`
+ * @param {string} featureDir - the feature folder (already moved to the archive)
+ * @param {{ refused?: Array<{ id: string }> }} [promotion] - the promotion's result, run just before
+ * @returns {{ superseded: Array<{id: string, file: string, supersededBy: string, scope?: string}>,
+ *   adrIndex: ReturnType<typeof updateAdrIndex>|null,
+ *   problems: Array<{id: string|null, reason: string, message: string}> }}
+ */
+export function applySpecRevocations(cwd, featureDir, promotion = {}) {
+  const out = { superseded: [], adrIndex: null, problems: [] };
+
+  const spec = readOrNull(specPathOf(featureDir));
+  const parsed = spec === null ? { entries: [], problems: [] } : parseRevocations(spec);
+  out.problems.push(...parsed.problems);
+
+  try {
+    const refusedIds = new Set((promotion.refused ?? []).map((r) => r.id));
+    const uc = supersedeUseCases(cwd, parsed.entries.filter((e) => e.kind === 'uc'), refusedIds);
+    out.superseded = uc.superseded;
+    out.problems.push(...uc.problems);
+  } catch { /* fail-open */ }
+
+  try {
+    out.adrIndex = updateAdrIndex(cwd, featureDir, parsed.entries.filter((e) => e.kind === 'adr'));
+    out.problems.push(...out.adrIndex.problems);
+  } catch { /* fail-open */ }
+
+  return out;
+}
+
+/**
+ * Plan-time check of a feature against the acervo's lifecycle.
+ *
+ * Warnings only, never errors: a superseded use case is a question for the
+ * plan, and the revocation rows are re-reported at close time anyway.
+ *
+ * @param {{ cwd: string, featureDir: string, tasksData?: object|null }} input
+ * @returns {{ warnings: string[] }}
+ */
+export function checkLifecycle({ cwd, featureDir, tasksData = null }) {
+  const warnings = [];
+  const acervoDir = join(cwd, SPECS_USECASES_PATHSPEC);
+  const ownDir = join(featureDir, UC.phaseDir, UC.dirname);
+  const acervo = useCaseFilesById(acervoDir);
+  const own = useCaseFilesById(ownDir);
+
+  const ownLife = new Map();
+  for (const [id, files] of own) {
+    const file = files[files.length - 1];
+    const content = readOrNull(join(ownDir, file));
+    if (content === null) continue;
+    ownLife.set(id, lifecycleOf(content));
+    for (const p of supersessionProblems(content, id)) warnings.push(`2-plan/usecases/${file}: ${p}`);
+  }
+
+  // The acervo can hold hundreds of use cases: read only the ones this plan touches.
+  const acervoLife = new Map();
+  const acervoOf = (id) => {
+    if (acervoLife.has(id)) return acervoLife.get(id);
+    const files = acervo.get(id) ?? [];
+    if (files.length > 1) warnings.push(`${ACERVO_LABEL}/: ${id} tem ${files.length} arquivos (${files.join(', ')}) — o acervo precisa de um arquivo por UC`);
+    const file = files[files.length - 1];
+    const content = file ? readOrNull(join(acervoDir, file)) : null;
+    const life = content === null ? null : lifecycleOf(content);
+    if (content !== null) {
+      for (const p of supersessionProblems(content, id)) warnings.push(`${ACERVO_LABEL}/${file}: ${p}`);
+    }
+    acervoLife.set(id, life);
+    return life;
+  };
+
+  const spec = readOrNull(specPathOf(featureDir));
+  const rev = spec === null ? { entries: [], problems: [] } : parseRevocations(spec);
+  for (const p of rev.problems) warnings.push(`spec.md, revogações: ${p.message}`);
+
+  const revokedHere = new Map();
+  let indexedAdrs = null;
+  for (const e of rev.entries) {
+    if (e.kind === 'adr') {
+      indexedAdrs ??= new Set(readAdrIndex(cwd).map((r) => r.ref));
+      if (!indexedAdrs.has(e.id)) {
+        warnings.push(`spec.md, revogações: ${e.id} não está no índice de ADRs ativos (${ADR_INDEX_LABEL}) — o finish não terá o que retirar`);
+      }
+      continue;
+    }
+    revokedHere.set(e.id, e);
+    if (!acervo.has(e.id)) {
+      warnings.push(`spec.md, revogações: ${e.id} não está no acervo (${ACERVO_LABEL}/) — o finish não terá o que marcar`);
+    } else {
+      acervoOf(e.id);
+    }
+    if (!acervo.has(e.substitute) && !own.has(e.substitute)) {
+      warnings.push(`spec.md, revogações: o substituto ${e.substitute} de ${e.id} não existe no acervo nem em 2-plan/usecases/ — o finish não aplicará a linha`);
+    }
+  }
+
+  const tasks = Array.isArray(tasksData?.tasks) ? tasksData.tasks : [];
+  for (const task of tasks) {
+    const id = task?.usecase;
+    if (!id) continue;
+    const inAcervo = acervoOf(id);
+    const inOwn = ownLife.get(id);
+    const here = revokedHere.get(id);
+
+    let where = null;
+    if (inAcervo?.status === SUPERSEDED) where = { src: 'está superseded no acervo', ...inAcervo };
+    else if (inOwn?.status === SUPERSEDED) where = { src: 'está superseded na cópia da feature', ...inOwn };
+    else if (here) where = { src: 'é revogado por esta feature (spec.md)', supersededBy: here.substitute, scope: here.scope };
+    if (!where) continue;
+
+    const by = where.supersededBy;
+    const detail = [by ? `substituto: ${by}` : 'sem substituto declarado', where.scope ? `ainda vale em: ${where.scope}` : null]
+      .filter(Boolean).join('; ');
+    const advice = where.scope ? 'confira que a task realiza a parte que ainda vale' : by ? `cite ${by}` : 'confira o acervo';
+    warnings.push(`${task.id}.usecase → ${id} ${where.src} (${detail}) — ${advice}`);
+  }
+
+  return { warnings };
+}