@polymorphism-tech/morph-spec 8.37.0 → 8.38.0

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

package/src/lib/specs/adr-index.js

@@ -0,0 +1,169 @@
+/**
+ * The index of the ADRs that still hold across the project:
+ * `.morph/specs/adrs/`, one file per ADR, committed next to the use-case acervo.
+ *
+ * Every feature writes ADRs into its own `decisions.md`, and most of them only
+ * matter inside that feature. The index keeps the few that set a project-wide
+ * rule, so brainstorming and plan read one folder instead of every archived
+ * `decisions.md` — those stay as history, not as instruction.
+ *
+ * One file per ADR (`{feature}--ADR-{nnn}.md`), like the use-case acervo:
+ * parallel features that index different ADRs never touch the same file, so
+ * their archive commits merge cleanly — a single shared page conflicted on the
+ * second merge.
+ *
+ * Maintained by finish/archive alone, inside the archive commit:
+ *   - enters: an ADR of the closing feature whose block carries `**Alcance:** projeto`;
+ *   - leaves: an ADR the closing feature's `spec.md` revokes in full (file deleted);
+ *   - narrows: one it revokes in part keeps its file, with `scope:` where it still holds.
+ * Nothing to add or revoke → nothing is touched (nor created).
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { basename, join } from 'path';
+import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
+import { readFrontmatterField, setFrontmatterField } from './usecase-promoter.js';
+
+/** Project-relative path of the index folder (git pathspec-ready). */
+export const ADR_INDEX_PATHSPEC = join('.morph', 'specs', 'adrs');
+
+const ADR_HEADING_RE = /^(#{2,6})\s+(ADR-\d+)\b[\s:—–-]*(.*?)\s*$/;
+const ANY_HEADING_RE = /^(#{1,6})\s/;
+/** `**Alcance:** projeto` — also `**Alcance**: projeto`. */
+const PROJECT_SCOPE_RE = /^\s*\*\*Alcance:?\*\*:?\s*projeto\b/i;
+const INDEX_FILE_RE = /^([a-z0-9][a-z0-9-]*)--(ADR-\d+)\.md$/;
+
+/** `admin/ADR-001` ↔ `admin--ADR-001.md`. */
+export const adrFileName = (ref) => `${ref.replace('/', '--')}.md`;
+const refOf = (name) => {
+  const m = INDEX_FILE_RE.exec(name);
+  return m ? `${m[1]}/${m[2]}` : null;
+};
+
+/**
+ * The ADRs of one `decisions.md` marked as project-wide, each with its block.
+ *
+ * @param {string} content
+ * @returns {Array<{ adr: string, title: string, body: string }>}
+ */
+export function projectAdrs(content) {
+  const out = [];
+  let current = null; // { adr, title, level, marked, lines }
+  const close = () => {
+    if (current?.marked) out.push({ adr: current.adr, title: current.title, body: current.lines.join('\n').trim() });
+    current = null;
+  };
+
+  for (const line of String(content ?? '').split(/\r?\n/)) {
+    const adr = ADR_HEADING_RE.exec(line);
+    if (adr) {
+      close();
+      current = { adr: adr[2], title: adr[3], level: adr[1].length, marked: false, lines: [] };
+      continue;
+    }
+    const heading = ANY_HEADING_RE.exec(line);
+    if (current && heading && heading[1].length <= current.level) { close(); continue; }
+    if (!current) continue;
+    if (PROJECT_SCOPE_RE.test(line)) current.marked = true;
+    current.lines.push(line);
+  }
+  close();
+  return out;
+}
+
+function renderAdrFile({ ref, title, body }, feature) {
+  const decisions = `.morph/archive/${feature}/${OUTPUT_SCHEMA.decisions.phaseDir}/${OUTPUT_SCHEMA.decisions.filename}`;
+  return [
+    '---',
+    `adr: ${ref}`,
+    `title: ${JSON.stringify(title)}`,
+    `source: ${decisions}`,
+    '---',
+    '',
+    `# ${ref}: ${title}`,
+    '',
+    '> Mantido pelo `morph-spec finish` — não edite à mão. Vale no projeto até que o `spec.md` de uma',
+    '> feature o revogue: por inteiro, e este arquivo sai; em parte, e `scope:` diz onde ele ainda vale.',
+    '',
+    body,
+    '',
+  ].join('\n');
+}
+
+/**
+ * The ADRs the index holds; `[]` when there is none or it cannot be read.
+ *
+ * @returns {Array<{ ref: string, file: string, title: string|null, scope: string|null }>}
+ */
+export function readAdrIndex(cwd) {
+  const dir = join(cwd, ADR_INDEX_PATHSPEC);
+  try {
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir).sort().flatMap((file) => {
+      const ref = refOf(file);
+      if (!ref) return [];
+      let content = '';
+      try { content = readFileSync(join(dir, file), 'utf8'); } catch { /* listed, unreadable */ }
+      return [{ ref, file, title: readFrontmatterField(content, 'title'), scope: readFrontmatterField(content, 'scope') }];
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Apply a closing feature to the index: its project-wide ADRs enter, and the
+ * ADR revocations its `spec.md` declared delete a file (total) or narrow it
+ * (parcial).
+ *
+ * @param {string} cwd
+ * @param {string} featureDir - the feature folder (already archived, at close time)
+ * @param {Array<{ id: string, change: 'total'|'parcial', scope: string|null }>} revocations - ADR entries of `parseRevocations`
+ * @returns {{ changed: boolean, added: string[], revoked: string[], narrowed: string[],
+ *   problems: Array<{ id: string, reason: string, message: string }> }}
+ */
+export function updateAdrIndex(cwd, featureDir, revocations = []) {
+  const result = { changed: false, added: [], revoked: [], narrowed: [], problems: [] };
+  const feature = basename(featureDir);
+  const dir = join(cwd, ADR_INDEX_PATHSPEC);
+
+  let marked = [];
+  try {
+    const decisions = join(featureDir, OUTPUT_SCHEMA.decisions.phaseDir, OUTPUT_SCHEMA.decisions.filename);
+    if (existsSync(decisions)) marked = projectAdrs(readFileSync(decisions, 'utf8'));
+  } catch { /* unreadable decisions.md — nothing enters */ }
+
+  for (const { adr, title, body } of marked) {
+    const ref = `${feature}/${adr}`;
+    const path = join(dir, adrFileName(ref));
+    const next = renderAdrFile({ ref, title, body }, feature);
+    const existed = existsSync(path);
+    if (existed && readFileSync(path, 'utf8') === next) continue;
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, next, 'utf8');
+    result.changed = true;
+    if (!existed) result.added.push(ref);
+  }
+
+  for (const rev of revocations) {
+    const path = join(dir, adrFileName(rev.id));
+    if (!existsSync(path)) {
+      result.problems.push({
+        id: rev.id,
+        reason: 'adr-not-indexed',
+        message: `${rev.id} não está no índice de ADRs ativos (${ADR_INDEX_PATHSPEC.replace(/\\/g, '/')}/) — nada a retirar; o decisions.md arquivado segue como história`,
+      });
+      continue;
+    }
+    if (rev.change === 'total') {
+      rmSync(path, { force: true });
+      result.revoked.push(rev.id);
+    } else {
+      writeFileSync(path, setFrontmatterField(readFileSync(path, 'utf8'), 'scope', JSON.stringify(rev.scope)), 'utf8');
+      result.narrowed.push(rev.id);
+    }
+    result.changed = true;
+  }
+
+  return result;
+}