@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

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

package/src/lib/specs/revocations.js

@@ -0,0 +1,156 @@
+/**
+ * The plan's declaration of what a feature supersedes in the project's acervo:
+ * the "UCs e ADRs que esta feature altera ou revoga" section of `spec.md`.
+ *
+ *   ## UCs e ADRs que esta feature altera ou revoga
+ *
+ *   | Id | Mudança | Substituto | Escopo em que o antigo ainda vale |
+ *   |---|---|---|---|
+ *   | UC-{nn} | parcial | UC-{nn} | {onde o antigo ainda vale} |
+ *   | {feature}/ADR-{nnn} | total | — | — |
+ *
+ * Columns are positional, so the header wording is free. Parsing is pure: the
+ * finish applies the entries (`acervo-lifecycle.js`), and `dag`/`usecase
+ * check` report the problems while `spec.md` can still be edited — it freezes
+ * at Gate 2, so a bad row found at close time can no longer be fixed there.
+ *
+ * Nothing ambiguous is applied: a row with any problem, and every row of an id
+ * declared twice, stays out of `entries`. A table inside a code fence is an
+ * example, never a declaration.
+ */
+
+import { SEPARATOR_ROW_RE, UC_ID_RE, isTableLine, tableCells } from './acervo-format.js';
+
+export const REVOCATIONS_TITLE = 'UCs e ADRs que esta feature altera ou revoga';
+
+/** ADR numbers restart in every feature, so only `{feature}/ADR-{nnn}` is unambiguous. */
+export const ADR_REF_RE = /^[a-z0-9][a-z0-9-]*\/ADR-\d+$/;
+
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+const FENCE_RE = /^\s*(```|~~~)/;
+const ID_TOKEN_RE = /\b(?:UC|ADR)-\d+\b/;
+/** A list item: the shape a revocation takes when the author skips the table. */
+const LIST_ITEM_RE = /^\s*(?:[-*+]|\d+[.)])\s/;
+
+const CHANGES = new Map([['total', 'total'], ['parcial', 'parcial'], ['partial', 'parcial']]);
+
+/** `—`, `–`, `-` and an empty cell all mean "none". */
+const isNone = (cell) => /^(?:—|–|-)?$/.test(cell);
+
+/** Id-like cells tolerate the typography an author reaches for: `code` and **bold**. */
+const bare = (cell) => cell.replace(/^[`*]+|[`*]+$/g, '').trim();
+
+/**
+ * The problems of one data row; `[]` = the row is applicable.
+ * @returns {{ entry: object|null, problems: Array<{ id: string|null, reason: string, message: string }> }}
+ */
+function readRow(line) {
+  const problems = [];
+  const problem = (id, reason, message) => problems.push({ id, reason, message });
+
+  const row = tableCells(line);
+  if (row.length < 4) {
+    problem(null, 'malformed-row', `linha com ${row.length} coluna(s), esperado 4 (Id | Mudança | Substituto | Escopo): ${line.trim()}`);
+    return { entry: null, problems };
+  }
+  const id = bare(row[0]);
+  const changeCell = bare(row[1]).toLowerCase();
+  const substitute = isNone(bare(row[2])) ? null : bare(row[2]);
+  const scope = isNone(row[3]) ? null : row[3];
+
+  const kind = UC_ID_RE.test(id) ? 'uc' : ADR_REF_RE.test(id) ? 'adr' : null;
+  if (!kind) {
+    problem(id || null, 'malformed-id', `"${id}" não é um UC-{nn} nem um {feature}/ADR-{nnn}`);
+    return { entry: null, problems };
+  }
+
+  const change = CHANGES.get(changeCell);
+  if (!change) problem(id, 'malformed-change', `${id}: mudança "${bare(row[1])}" — use total ou parcial`);
+
+  if (kind === 'uc' && !substitute) {
+    problem(id, 'missing-substitute', `${id}: UC revogado precisa do substituto (UC-{nn}) — é o superseded_by do acervo`);
+  } else if (substitute && !(kind === 'uc' ? UC_ID_RE : ADR_REF_RE).test(substitute)) {
+    problem(id, 'malformed-substitute',
+      `${id}: substituto "${substitute}" — esperado ${kind === 'uc' ? 'UC-{nn}' : '{feature}/ADR-{nnn}'}`);
+  } else if (substitute === id) {
+    problem(id, 'self-substitute', `${id}: o substituto é o próprio ${id}`);
+  }
+
+  if (change === 'parcial' && !scope) {
+    problem(id, 'missing-scope', `${id}: revogação parcial precisa dizer onde o antigo ainda vale (coluna Escopo)`);
+  } else if (change === 'total' && scope) {
+    problem(id, 'scope-on-total', `${id}: revogação total com escopo "${scope}" — se o antigo ainda vale em algum lugar, a mudança é parcial`);
+  }
+
+  return { entry: problems.length ? { id } : { kind, id, change, substitute, scope }, problems };
+}
+
+/**
+ * @param {string} content - the whole `spec.md`
+ * @returns {{
+ *   declared: boolean,
+ *   entries: Array<{ kind: 'uc'|'adr', id: string, change: 'total'|'parcial', substitute: string|null, scope: string|null }>,
+ *   problems: Array<{ id: string|null, reason: string, message: string }>
+ * }}
+ *   `declared: false` — no section at all (a plan written before it existed).
+ */
+export function parseRevocations(content) {
+  const lines = String(content ?? '').split(/\r?\n/);
+  const title = REVOCATIONS_TITLE.toLowerCase();
+
+  let start = -1;
+  let level = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const h = HEADING_RE.exec(lines[i]);
+    if (h && h[2].toLowerCase().startsWith(title)) { start = i + 1; level = h[1].length; break; }
+  }
+  if (start === -1) return { declared: false, entries: [], problems: [] };
+
+  let end = lines.length;
+  for (let i = start; i < lines.length; i++) {
+    const h = HEADING_RE.exec(lines[i]);
+    if (h && h[1].length <= level) { end = i; break; }
+  }
+
+  const problems = [];
+  const rows = []; // { id, entry } in order, applicable or not
+  let fenced = false;
+  let separatorSeen = false;
+  let tableLines = 0;
+
+  for (const line of lines.slice(start, end)) {
+    if (FENCE_RE.test(line)) { fenced = !fenced; continue; }
+    if (fenced) continue;
+
+    if (!isTableLine(line)) {
+      const stray = LIST_ITEM_RE.test(line) ? ID_TOKEN_RE.exec(line) : null;
+      if (stray) {
+        problems.push({ id: stray[0], reason: 'outside-table',
+          message: `${stray[0]} aparece fora da tabela — só as linhas da tabela são aplicadas no finish` });
+      }
+      continue;
+    }
+    tableLines++;
+    if (SEPARATOR_ROW_RE.test(line)) { separatorSeen = true; continue; }
+    if (!separatorSeen) continue; // the header row: its wording is free
+
+    const { entry, problems: rowProblems } = readRow(line);
+    problems.push(...rowProblems);
+    if (entry) rows.push(entry);
+  }
+
+  if (tableLines > 0 && !separatorSeen) {
+    problems.push({ id: null, reason: 'unreadable-table',
+      message: 'tabela ilegível — falta a linha separadora (|---|---|---|---) depois do cabeçalho; nenhuma linha foi lida' });
+  }
+
+  // An id declared twice is ambiguous as a whole: none of its rows applies.
+  const count = new Map();
+  for (const r of rows) count.set(r.id, (count.get(r.id) ?? 0) + 1);
+  for (const [id, n] of count) {
+    if (n > 1) problems.push({ id, reason: 'duplicate-id', message: `${id} aparece em ${n} linhas — nenhuma foi aplicada; deixe uma só` });
+  }
+  const entries = rows.filter((r) => r.kind && count.get(r.id) === 1);
+
+  return { declared: true, entries, problems };
+}

package/src/lib/specs/screen-checklist.js

@@ -0,0 +1,357 @@
+/**
+ * O checklist de tela do `1-design/mockups.md` — as decisões que uma tela de
+ * dados precisa (volume, paginação, ordenação, filtro, os três estados,
+ * mobile, abas) escritas por tela, na fase uiux.
+ *
+ * Existe porque o que o design não pergunta não vira `doneCriteria`, e o que
+ * não é critério ninguém entrega: telas de admin saíam listando tudo, sem
+ * paginar nem ordenar, com o design aprovado. Os leitores do MESMO parser:
+ *
+ *   - `gate-check uiux` pausa com os problemas nomeados;
+ *   - `approve`/`advance` com assinatura `auto` recusam a mesma pausa sem uma
+ *     decisão gravada (`uiuxAutoApprovalBlock`) — a regra é a do risk-detector;
+ *   - `gate-check review` exige que o avaliador registre a conferência de cada
+ *     item decidido contra a tela entregue (`checklistCoverage`).
+ *
+ * Mockup no formato ANTERIOR ao checklist (telas `## S001: …`, sem nenhuma
+ * `## Tela:`) é legado e isento, com a isenção gravada no sinal.
+ *
+ * O formato é o que a `morph-uiux` ensina: cada tela é um `## Tela: <nome>`, e
+ * dentro dela um `### Checklist de tela` com uma linha por item — tabela
+ * (`| Paginação | servidor, 25/página |`) ou lista (`- **Paginação:** …`).
+ * "Não se aplica" é resposta válida; vazio, "?" ou "a definir" não são.
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+import { evaluatorScreenChecklist } from '../evaluator-report.js';
+import { LEGACY_MOCKUP_EXEMPTION, uiuxChecklistPause } from '../risk-detector.js';
+
+const PACKAGE_AGENTS = fileURLToPath(new URL('../../../framework/agents.json', import.meta.url));
+
+/**
+ * Os itens, na ordem do template. `match` roda sobre o rótulo NORMALIZADO
+ * (minúsculas, sem acento): "Estado de erro", "Erro" e "**Erro:**" são o mesmo
+ * item. Um rótulo que casa com vários ("Estados (vazio/carregando/erro)")
+ * responde a todos eles.
+ */
+export const SCREEN_CHECKLIST_ITEMS = [
+  { id: 'superficie', label: 'Superfície', match: /\bsuperficie\b/ },
+  { id: 'volume', label: 'Volume esperado', match: /\bvolume\b/ },
+  { id: 'paginacao', label: 'Paginação', match: /\bpaginacao\b/ },
+  { id: 'ordenacao', label: 'Ordenação', match: /\bordenacao\b/ },
+  { id: 'filtro', label: 'Filtro', match: /\bfiltros?\b/ },
+  { id: 'vazio', label: 'Estado vazio', match: /\bvazio\b/ },
+  { id: 'carregando', label: 'Estado carregando', match: /\bcarregando\b|\bcarregamento\b/ },
+  { id: 'erro', label: 'Estado de erro', match: /\berro\b/ },
+  { id: 'mobile', label: 'Mobile', match: /\bmobile\b/ },
+  { id: 'abas', label: 'Abas', match: /\babas\b/ },
+];
+
+/**
+ * Itens que o avaliador não confere contra a tela: a superfície decide QUAIS
+ * standards a tela lê, não um comportamento que a tela entregue exiba.
+ */
+const NOT_VERIFIED_AT_REVIEW = new Set(['superficie']);
+
+/**
+ * Respostas que ocupam a célula sem decidir nada: as exatas, e as que COMEÇAM
+ * adiando a decisão ("a definir depois", "TBD.", "? talvez").
+ */
+const PLACEHOLDERS = new Set(['', '-', '--', '—', '–', '...', 'x', 'todo', 'definir', 'pendente']);
+const PLACEHOLDER_PREFIX_RE = /^(a definir|tbd|\?|…)/;
+
+/** O formato de mockup anterior ao checklist: telas `## S001: <nome>`. */
+const LEGACY_SCREEN_HEADING_RE = /^##\s+S\d+\s*:/i;
+
+const NOT_APPLICABLE_RE = /^(nao se aplica|n\/a)\b/;
+
+const SCREEN_HEADING_RE = /^##\s+tela\s*[:—–-]\s*(.+?)\s*#*\s*$/i;
+const CHECKLIST_HEADING_RE = /^(#{3,6})\s+checklist\b/i;
+
+/** Minúsculas, sem acento, sem marcação inline, espaços colapsados. */
+export function normalizeLabel(text) {
+  return String(text ?? '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[*_`"“”]/g, '')
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** Nome de tela comparável entre o mockup e o relatório do avaliador. */
+function screenKey(name) {
+  return normalizeLabel(name).replace(/^tela\s*[:—–-]\s*/, '').replace(/[.:;,]+$/, '');
+}
+
+/** Os itens que um rótulo responde. */
+function itemsOf(label) {
+  const norm = normalizeLabel(label);
+  return SCREEN_CHECKLIST_ITEMS.filter((item) => item.match.test(norm)).map((item) => item.id);
+}
+
+/**
+ * Uma linha de checklist como `[rótulo, resposta]`, ou null: linha de tabela
+ * (separador `|---|` fora) ou item de lista `- Rótulo: resposta`.
+ */
+function checklistRow(line) {
+  const trimmed = line.trim();
+  if (trimmed.startsWith('|')) {
+    const cells = tableCells(trimmed);
+    if (cells.length < 2 || cells.every((c) => /^:?-{2,}:?$/.test(c) || c === '')) return null;
+    return [cells[0], cells.slice(1).join(' ').trim()];
+  }
+  const bullet = /^[-*+]\s+(.+)$/.exec(trimmed.replace(/\*\*/g, ''));
+  if (!bullet) return null;
+  const colon = bullet[1].indexOf(':');
+  if (colon === -1) return null;
+  return [bullet[1].slice(0, colon), bullet[1].slice(colon + 1).trim()];
+}
+
+/** As células de uma linha de tabela markdown, sem as bordas. */
+export function tableCells(line) {
+  const inner = line.trim().replace(/^\|/, '').replace(/\|$/, '');
+  return inner.split(/(?<!\\)\|/).map((cell) => cell.trim());
+}
+
+/** Linhas fora de blocos cercados: um exemplo dentro de ``` não é uma tela. */
+function proseLines(markdown) {
+  const out = [];
+  let fenced = false;
+  for (const line of String(markdown ?? '').replace(/\r\n/g, '\n').split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) { fenced = !fenced; continue; }
+    if (!fenced) out.push(line);
+  }
+  return out;
+}
+
+/**
+ * As telas do mockup e o que o checklist de cada uma responde.
+ *
+ * @param {string} markdown - conteúdo do `1-design/mockups.md`
+ * @returns {Array<{ name: string, hasChecklist: boolean, answers: Map<string, string> }>}
+ */
+export function parseScreens(markdown) {
+  const screens = [];
+  let screen = null;
+  let checklistLevel = 0;
+
+  for (const line of proseLines(markdown)) {
+    const heading = /^(#{1,6})\s/.exec(line);
+    if (heading) {
+      const level = heading[1].length;
+      const named = SCREEN_HEADING_RE.exec(line);
+      if (level <= 2) {
+        screen = named && named[1].trim() ? { name: named[1].trim(), hasChecklist: false, answers: new Map() } : null;
+        if (screen) screens.push(screen);
+        checklistLevel = 0;
+        continue;
+      }
+      const checklist = CHECKLIST_HEADING_RE.exec(line);
+      if (screen && checklist) {
+        screen.hasChecklist = true;
+        checklistLevel = checklist[1].length;
+      } else if (checklistLevel && level <= checklistLevel) {
+        checklistLevel = 0;
+      }
+      continue;
+    }
+    if (!screen || !checklistLevel) continue;
+    const row = checklistRow(line);
+    if (!row) continue;
+    for (const id of itemsOf(row[0])) {
+      if (!screen.answers.has(id) || !screen.answers.get(id)) screen.answers.set(id, row[1]);
+    }
+  }
+  return screens;
+}
+
+function isPlaceholder(answer) {
+  const norm = normalizeLabel(answer).replace(/[.!;:,]+$/, '').trim();
+  return PLACEHOLDERS.has(norm) || PLACEHOLDER_PREFIX_RE.test(norm);
+}
+const isNotApplicable = (answer) => NOT_APPLICABLE_RE.test(normalizeLabel(answer));
+
+const labelOf = (id) => SCREEN_CHECKLIST_ITEMS.find((item) => item.id === id)?.label ?? id;
+
+/**
+ * As superfícies que a persona `ui-designer` declara no `agents.json` — o
+ * vocabulário válido do item `Superfície`, que o `morph-plan` §5a usa para
+ * somar os standards da tela em `tasks[].standards`. Lê a cópia instalada do
+ * projeto; sem ela (este repositório), a do pacote. Persona sem `surfaces`
+ * (instalação anterior ao campo) devolve null: o valor não é validado.
+ *
+ * @param {string} cwd
+ * @returns {string[]|null}
+ */
+export function knownSurfaces(cwd) {
+  for (const path of [join(cwd, '.morph', 'framework', 'agents.json'), PACKAGE_AGENTS]) {
+    if (!existsSync(path)) continue;
+    try {
+      const surfaces = JSON.parse(readFileSync(path, 'utf8'))?.agents?.['ui-designer']?.surfaces;
+      return surfaces && typeof surfaces === 'object' && !Array.isArray(surfaces) ? Object.keys(surfaces) : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/** A resposta de `Superfície` nomeia uma das superfícies conhecidas? */
+function namesSurface(answer, surfaces) {
+  const norm = normalizeLabel(answer);
+  return surfaces.some((key) => new RegExp(`(^|[^a-z0-9-])${key}([^a-z0-9-]|$)`).test(norm));
+}
+
+/**
+ * Audita o checklist do mockup: toda tela tem o bloco, e todo item tem uma
+ * resposta escrita — e, quando `surfaces` é dado, a `Superfície` é uma delas.
+ *
+ * Sem nenhuma `## Tela:`, o mockup é `legacy` (isento) só quando declara telas
+ * no formato antigo; qualquer outro formato é o problema "nenhuma tela
+ * declarada" — senão trocar o heading seria o atalho para pular o checklist.
+ *
+ * @param {string} markdown
+ * @returns {{ legacy: boolean, screens: Array<{ name: string, hasChecklist: boolean, missing: string[], unanswered: string[] }>,
+ *   problems: string[] }} `problems` vazio ⇔ checklist completo (ou isento)
+ */
+export function auditScreenChecklist(markdown, { surfaces = null } = {}) {
+  const parsed = parseScreens(markdown);
+  const problems = [];
+  if (parsed.length === 0) {
+    if (proseLines(markdown).some((line) => LEGACY_SCREEN_HEADING_RE.test(line))) {
+      return { legacy: true, screens: [], problems };
+    }
+    problems.push('nenhuma tela declarada no formato `## Tela: <nome>`');
+  }
+  const screens = parsed.map((screen) => {
+    const missing = [];
+    const unanswered = [];
+    for (const { id } of SCREEN_CHECKLIST_ITEMS) {
+      if (!screen.answers.has(id)) missing.push(id);
+      else if (isPlaceholder(screen.answers.get(id))) unanswered.push(id);
+    }
+    if (!screen.hasChecklist) {
+      problems.push(`tela "${screen.name}" sem \`### Checklist de tela\``);
+    } else {
+      if (missing.length) problems.push(`tela "${screen.name}": falta ${missing.map(labelOf).join(', ')}`);
+      if (unanswered.length) problems.push(`tela "${screen.name}": sem resposta em ${unanswered.map(labelOf).join(', ')}`);
+      const surface = screen.answers.get('superficie');
+      if (surfaces?.length && surface !== undefined && !isPlaceholder(surface) && !isNotApplicable(surface)
+          && !namesSurface(surface, surfaces)) {
+        problems.push(`tela "${screen.name}": Superfície "${surface}" não é uma das superfícies da ui-designer (${surfaces.join(', ')})`);
+      }
+    }
+    return { name: screen.name, hasChecklist: screen.hasChecklist, missing, unanswered };
+  });
+  return { legacy: false, screens, problems };
+}
+
+/**
+ * O sinal `screenChecklist` de um gate, lido do disco. COLETA, nunca decide:
+ * quem pausa é o risk-detector.
+ *
+ * `mockups: false` é "a feature não tem mockup" — nada a cobrar. No review, o
+ * que se cobra é a conferência (`uncovered`: itens decididos sem linha na
+ * seção do avaliador), não o design, que já passou pelo Gate uiux.
+ *
+ * @param {string} cwd
+ * @param {string} featureName
+ * @param {string} gateName
+ * @returns {{ mockups: boolean, legacy: boolean, screens: string[], problems: string[],
+ *   exempt?: string, section?: boolean, uncovered?: string[] }}
+ */
+export function collectScreenChecklist(cwd, featureName, gateName) {
+  const mockups = readMockups(cwd, featureName);
+  if (mockups === null) return { mockups: false, legacy: false, screens: [], problems: [] };
+  const audit = auditScreenChecklist(mockups, { surfaces: knownSurfaces(cwd) });
+  const signal = { mockups: true, legacy: audit.legacy, screens: audit.screens.map((s) => s.name), problems: audit.problems };
+  if (audit.legacy) signal.exempt = LEGACY_MOCKUP_EXEMPTION;
+  if (gateName === 'review') {
+    const report = evaluatorScreenChecklist(cwd, featureName);
+    signal.section = report.section;
+    signal.uncovered = checklistCoverage(mockups, report.section ? report.body : '');
+  }
+  return signal;
+}
+
+/**
+ * Por que o Gate uiux NÃO pode ser aprovado com assinatura `auto` — a pausa
+ * que o `gate-check uiux` daria pelo checklist —, ou null. Lido por `approve`
+ * e `advance`, para que uma aprovação automática nunca passe onde o gate-check
+ * pausaria. Uma decisão gravada com `pause: false` (o `gate-decision` manual,
+ * ou um gate-check que não pausou) é a resposta a essa pausa e destrava — só
+ * para o mockup que ela viu: a decisão guarda `mockupsHash`, e um mockup
+ * escrito ou mudado depois dela volta a ser conferido.
+ *
+ * @param {string} cwd
+ * @param {string} featureName
+ * @param {object} feature - o feature.json (lê `gateDecisions.uiux`)
+ * @returns {string|null}
+ */
+export function uiuxAutoApprovalBlock(cwd, featureName, feature) {
+  const decision = feature?.gateDecisions?.uiux;
+  if (decision?.pause === false && decision.mockupsHash === mockupsHash(cwd, featureName)) return null;
+  return uiuxChecklistPause(collectScreenChecklist(cwd, featureName, 'uiux'));
+}
+
+/**
+ * O que o avaliador deixou de conferir: por tela do mockup, os itens com
+ * decisão (nem "não se aplica", nem a superfície) sem linha na seção
+ * `## Checklist de tela` do relatório. Uma linha que o avaliador marca como
+ * não verificável conta como conferida — o que pausa é a AUSÊNCIA da linha.
+ *
+ * @param {string} designMarkdown - o `1-design/mockups.md`
+ * @param {string} reportSection - o corpo da seção do `evaluator-report.md`
+ * @returns {string[]} `"<tela>: <item>, <item>"` por tela com lacuna
+ */
+export function checklistCoverage(designMarkdown, reportSection) {
+  const covered = new Map();
+  for (const line of proseLines(reportSection)) {
+    if (!line.trim().startsWith('|')) continue;
+    const cells = tableCells(line);
+    if (cells.length < 2) continue;
+    const key = screenKey(cells[0]);
+    if (!covered.has(key)) covered.set(key, new Set());
+    for (const id of itemsOf(cells[1])) covered.get(key).add(id);
+  }
+
+  const gaps = [];
+  for (const screen of parseScreens(designMarkdown)) {
+    const done = covered.get(screenKey(screen.name)) ?? new Set();
+    const owed = [...screen.answers]
+      .filter(([id, answer]) => !NOT_VERIFIED_AT_REVIEW.has(id) && !isPlaceholder(answer) && !isNotApplicable(answer))
+      .map(([id]) => id)
+      .filter((id) => !done.has(id));
+    if (owed.length) gaps.push(`${screen.name}: ${owed.map(labelOf).join(', ')}`);
+  }
+  return gaps;
+}
+
+/**
+ * O `1-design/mockups.md` por conteúdo: BOM e CRLF não contam, para que o
+ * checkout de outra máquina seja o mesmo mockup.
+ *
+ * @param {string} cwd
+ * @param {string} featureName
+ * @returns {string|null} null sem mockup
+ */
+export function mockupsHash(cwd, featureName) {
+  const text = readMockups(cwd, featureName);
+  if (text === null) return null;
+  return createHash('sha256').update(text.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n')).digest('hex').slice(0, 16);
+}
+
+/** O `1-design/mockups.md` da feature, ou null quando ausente/ilegível. Nunca lança. */
+export function readMockups(cwd, featureName) {
+  try {
+    const path = getAbsoluteOutputPath(cwd, featureName, 'uiMockups');
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+  } catch {
+    return null;
+  }
+}