@polymorphism-tech/morph-spec 8.47.0 → 9.0.0

package/src/lib/plan/checks.js

@@ -0,0 +1,234 @@
+import { createHash } from 'crypto';
+import { existsSync, readFileSync } from 'fs';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+import { frozenBody } from '../../../framework/hooks/shared/errata.js';
+import { readAgentsJson } from '../specs/screen-checklist.js';
+import { findArtifactTerms } from './artifact-vocabulary.js';
+import { PROOF_KINDS, REUSE_VERDICTS, ADR_SCOPES, SECTIONS, CONFLICTS_HEADING } from './plan-parser.js';
+
+export const CHECKS_VERSION = 1;
+export const MAX_SLICE_FILES = 8;
+export const MAX_SLICES = 12;
+export const MAX_PARALLEL = 4;
+
+/** sha256 of the plan without its errata: appending a correction never invalidates checks.json. */
+export function planHash(text) {
+  return createHash('sha256').update(frozenBody(text), 'utf8').digest('hex');
+}
+
+/**
+ * Persona ids the project can dispatch: the installed agents.json, else the package's.
+ *
+ * @param {string} cwd
+ * @returns {string[]|null} null when no agents.json is readable — personas then go unchecked
+ */
+export function knownPersonas(cwd) {
+  const agents = readAgentsJson(cwd)?.agents;
+  return agents && typeof agents === 'object' ? Object.keys(agents) : null;
+}
+
+/** The ids on a dependency cycle, or null. */
+export function dependencyCycle(slices) {
+  const deps = new Map(slices.map((s) => [s.id, s.depends ?? []]));
+  const state = new Map();
+  const stack = [];
+  const visit = (id) => {
+    if (state.get(id) === 'done' || !deps.has(id)) return null;
+    if (state.get(id) === 'open') return stack.slice(stack.indexOf(id)).concat(id);
+    state.set(id, 'open');
+    stack.push(id);
+    for (const dep of deps.get(id)) {
+      const cycle = visit(dep);
+      if (cycle) return cycle;
+    }
+    stack.pop();
+    state.set(id, 'done');
+    return null;
+  };
+  for (const id of deps.keys()) {
+    const cycle = visit(id);
+    if (cycle) return cycle;
+  }
+  return null;
+}
+
+const fileKey = (f) => f.replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase();
+
+/**
+ * Waves of slices that may run at the same time: a slice joins a wave only
+ * after every slice it depends on ran in an earlier one, and never with a
+ * slice that touches one of its files. At most MAX_PARALLEL per wave.
+ *
+ * @param {{ id: string, depends?: string[], files?: string[] }[]} slices
+ * @returns {string[][]} empty when the dependencies have a cycle
+ */
+export function parallelGroups(slices) {
+  if (dependencyCycle(slices)) return [];
+  const ids = new Set(slices.map((s) => s.id));
+  const depth = new Map();
+  const depthOf = (slice) => {
+    if (depth.has(slice.id)) return depth.get(slice.id);
+    const parents = (slice.depends ?? []).filter((d) => ids.has(d)).map((d) => slices.find((s) => s.id === d));
+    const value = parents.length === 0 ? 0 : 1 + Math.max(...parents.map(depthOf));
+    depth.set(slice.id, value);
+    return value;
+  };
+  const layers = [];
+  for (const slice of slices) (layers[depthOf(slice)] ??= []).push(slice);
+
+  const groups = [];
+  for (const layer of layers.filter(Boolean)) {
+    const open = [];
+    for (const slice of layer) {
+      const files = new Set((slice.files ?? []).map(fileKey));
+      const group = open.find((g) => g.ids.length < MAX_PARALLEL && ![...files].some((f) => g.files.has(f)));
+      if (group) {
+        group.ids.push(slice.id);
+        files.forEach((f) => group.files.add(f));
+      } else {
+        open.push({ ids: [slice.id], files });
+      }
+    }
+    groups.push(...open.map((g) => g.ids));
+  }
+  return groups;
+}
+
+/**
+ * Judge a parsed plan.
+ *
+ * @param {ReturnType<import('./plan-parser.js').parsePlan>} plan
+ * @param {{ personas?: string[]|null, surfaces?: string[]|null }} [known]
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+export function validatePlan(plan, { personas = null, surfaces = null } = {}) {
+  const errors = [];
+  const warnings = [];
+  const at = (line) => (line ? ` (linha ${line})` : '');
+
+  for (const key of ['problem', 'scenarios', 'decisions', 'slices']) {
+    if (!plan.present[key]) errors.push(`seção obrigatória ausente: ## ${SECTIONS[key]}`);
+  }
+  if (plan.present.decisions && !plan.conflicts) {
+    errors.push(`### ${CONFLICTS_HEADING} ausente em ## ${SECTIONS.decisions} — escreva "nenhum" quando não houver`);
+  } else if (plan.conflicts && !plan.conflicts.text) {
+    errors.push(`### ${CONFLICTS_HEADING} está vazio${at(plan.conflicts.line)} — escreva "nenhum" quando não houver`);
+  }
+  if (plan.sectionsAfterErrata.length > 0) {
+    errors.push(`## ${SECTIONS.errata} precisa ser a última seção — depois dela: ${plan.sectionsAfterErrata.join(', ')}`);
+  }
+
+  const duplicated = (items) => items.map((i) => i.id).filter((id, i, all) => all.indexOf(id) !== i);
+  for (const [label, items] of [['cenário', plan.scenarios], ['fatia', plan.slices], ['ADR', plan.adrs]]) {
+    for (const id of new Set(duplicated(items))) errors.push(`${label} duplicado: ${id}`);
+  }
+
+  if (plan.present.scenarios && plan.scenarios.length === 0) {
+    errors.push(`## ${SECTIONS.scenarios} sem nenhum cenário no formato "- **C1** — Dado …, quando …, então …"`);
+  }
+  for (const c of plan.scenarios) {
+    if (c.proof === null) {
+      errors.push(`${c.id} sem "prova:" (${PROOF_KINDS.join(' | ')})${at(c.line)}`);
+    } else if (!PROOF_KINDS.includes(c.proof.toLowerCase())) {
+      errors.push(`${c.id}: prova "${c.proof}" fora de ${PROOF_KINDS.join(' | ')}${at(c.line)}`);
+    }
+    const terms = findArtifactTerms(c.text);
+    if (terms.length > 0 && !c.artifactWhy) {
+      errors.push(`${c.id} descreve artefato ("${terms.join(', ')}") sem "> Por que artefato:" — reescreva como efeito observável ou justifique${at(c.line)}`);
+    }
+  }
+
+  const scenarioIds = new Set(plan.scenarios.map((c) => c.id));
+  const sliceIds = new Set(plan.slices.map((s) => s.id));
+  const covered = new Set();
+  for (const s of plan.slices) {
+    if (!s.persona) {
+      errors.push(`${s.id} sem "- persona:"${at(s.line)}`);
+    } else if (personas && !personas.includes(s.persona)) {
+      errors.push(`${s.id}: persona "${s.persona}" não existe em agents.json (${personas.join(', ')})${at(s.line)}`);
+    }
+    if (s.files.length > MAX_SLICE_FILES) {
+      errors.push(`${s.id} toca ${s.files.length} arquivos — o teto é ${MAX_SLICE_FILES}; divida a fatia${at(s.line)}`);
+    }
+    for (const c of s.covers) {
+      if (scenarioIds.has(c)) covered.add(c);
+      else errors.push(`${s.id} cobre ${c}, que não existe em ## ${SECTIONS.scenarios}${at(s.line)}`);
+    }
+    for (const d of s.depends) {
+      if (!sliceIds.has(d)) errors.push(`${s.id} depende de ${d}, que não existe${at(s.line)}`);
+    }
+    if (s.covers.length === 0) warnings.push(`${s.id} não cobre nenhum cenário${at(s.line)}`);
+    if (s.unknownKeys.length > 0) warnings.push(`${s.id}: chave desconhecida ${s.unknownKeys.join(', ')}${at(s.line)}`);
+    if (s.surface && surfaces && !surfaces.includes(s.surface)) {
+      warnings.push(`${s.id}: superfície "${s.surface}" não é uma de ${surfaces.join(', ')}${at(s.line)}`);
+    }
+  }
+  for (const c of plan.scenarios) {
+    if (!covered.has(c.id)) errors.push(`${c.id} não é coberto por nenhuma fatia ("- cobre: ${c.id}")`);
+  }
+  const cycle = dependencyCycle(plan.slices);
+  if (cycle) errors.push(`ciclo em "depende": ${cycle.join(' → ')}`);
+  if (plan.slices.length > MAX_SLICES) warnings.push(`${plan.slices.length} fatias — acima de ${MAX_SLICES}, considere dividir a feature`);
+
+  for (const r of plan.reuse) {
+    if (!REUSE_VERDICTS.includes(r.verdict)) {
+      errors.push(`## ${SECTIONS.reuse}: veredito "${r.verdict}" de "${r.concept}" fora de ${REUSE_VERDICTS.join(' | ')}${at(r.line)}`);
+    } else if (r.verdict === 'CRIAR' && !r.why) {
+      warnings.push(`## ${SECTIONS.reuse}: CRIAR "${r.concept}" sem why${at(r.line)}`);
+    }
+  }
+  for (const a of plan.adrs) {
+    if (!ADR_SCOPES.includes(a.scope)) warnings.push(`${a.id} sem **Alcance:** ${ADR_SCOPES.join(' | ')}${at(a.line)}`);
+  }
+
+  return { errors, warnings };
+}
+
+/** The checks.json document for a parsed plan. */
+export function buildChecks(feature, text, plan) {
+  return {
+    version: CHECKS_VERSION,
+    feature,
+    planHash: planHash(text),
+    checks: plan.scenarios.map((c) => ({
+      id: c.id, text: c.text, proof: c.proof ? c.proof.toLowerCase() : null, artifactWhy: c.artifactWhy || null,
+    })),
+    slices: plan.slices.map((s) => ({
+      id: s.id, title: s.title, persona: s.persona, surface: s.surface,
+      standards: s.standards, files: s.files, depends: s.depends, covers: s.covers,
+    })),
+    reuse: plan.reuse.map(({ concept, verdict, target, why }) => ({ concept, verdict, target, why })),
+    adrs: plan.adrs.map((a) => ({ id: a.id, title: a.title, scope: ADR_SCOPES.includes(a.scope) ? a.scope : null })),
+  };
+}
+
+/**
+ * The feature's extracted checks and whether they still describe the plan on
+ * disk. plan-check writes them only with zero errors, so `fresh` also means
+ * the plan passed every plan-check rule (no slice over MAX_SLICE_FILES, every
+ * scenario covered).
+ *
+ * @returns {{ status: 'fresh'|'no-plan'|'no-checks'|'unreadable'|'stale', checks: object|null }}
+ */
+export function readPlanChecks(cwd, featureName) {
+  const planPath = getAbsoluteOutputPath(cwd, featureName, 'plan');
+  const checksPath = getAbsoluteOutputPath(cwd, featureName, 'checks');
+  if (!existsSync(planPath)) return { status: 'no-plan', checks: null };
+  if (!existsSync(checksPath)) return { status: 'no-checks', checks: null };
+  let checks;
+  try {
+    checks = JSON.parse(readFileSync(checksPath, 'utf8'));
+  } catch {
+    return { status: 'unreadable', checks: null };
+  }
+  if (checks?.version !== CHECKS_VERSION || !Array.isArray(checks.slices) || !Array.isArray(checks.checks)) {
+    return { status: 'unreadable', checks: null };
+  }
+  let plan;
+  try {
+    plan = readFileSync(planPath, 'utf8');
+  } catch {
+    return { status: 'no-plan', checks };
+  }
+  return { status: checks.planHash === planHash(plan) ? 'fresh' : 'stale', checks };
+}

package/src/lib/plan/plan-parser.js

@@ -0,0 +1,209 @@
+import { tableCells, isTableLine, SEPARATOR_ROW_RE } from '../specs/gfm-table.js';
+import { ARTIFACT_MARKER_RE } from './artifact-vocabulary.js';
+import { markdownLines } from '../../../framework/hooks/shared/errata.js';
+
+export const PROOF_KINDS = ['teste', 'e2e', 'eval', 'manual'];
+export const REUSE_VERDICTS = ['REUSAR', 'ESTENDER', 'CRIAR'];
+export const ADR_SCOPES = ['feature', 'projeto'];
+
+export const SECTIONS = {
+  problem: 'Problema',
+  outOfScope: 'Fora de escopo',
+  assumptions: 'Suposições não confirmadas',
+  scenarios: 'Cenários',
+  decisions: 'Decisões',
+  architecture: 'Arquitetura',
+  reuse: 'Reuso',
+  slices: 'Fatias',
+  contract: 'Contrato de implementação',
+  errata: 'Errata',
+};
+
+export const CONFLICTS_HEADING = 'Conflitos com o acervo';
+
+const SLICE_KEYS = {
+  persona: 'persona',
+  'superfície': 'surface',
+  superficie: 'surface',
+  standards: 'standards',
+  arquivos: 'files',
+  depende: 'depends',
+  cobre: 'covers',
+};
+
+const DASH = String.raw`\s+[—–-]\s+`;
+const SCENARIO_RE = new RegExp(String.raw`^[-*]\s+\*\*(C\d+)\*\*${DASH}(.+)$`);
+const ADR_RE = new RegExp(String.raw`^###\s+(ADR-\d+)${DASH}(.+?)\s*$`);
+const SLICE_RE = new RegExp(String.raw`^###\s+(F\d+)${DASH}(.+?)\s*$`);
+const PROOF_RE = /^\s*prova\s*:\s*(.*?)\s*$/i;
+const WHY_RE = new RegExp(String.raw`^\s*>\s*` + ARTIFACT_MARKER_RE.source + String.raw`\s*(.*?)\s*$`, 'i');
+const SCOPE_RE = /^\s*\*\*Alcance:\*\*\s*(.*?)\s*$/i;
+const SLICE_LINE_RE = /^\s*[-*]\s+([\p{L}]+)\s*:\s*(.*?)\s*$/u;
+
+const fold = (s) => s.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase().trim();
+
+const listOf = (value) => value
+  .split(',')
+  .map((v) => v.replace(/`/g, '').trim())
+  .filter((v) => v && !/^[—–-]$/.test(v) && fold(v) !== 'nenhum' && fold(v) !== 'nenhuma');
+
+function splitSections(lines) {
+  const sections = [];
+  let current = null;
+  for (const line of lines) {
+    const h2 = !line.fenced && /^##\s+(.+?)\s*$/.exec(line.raw);
+    if (h2 && !line.raw.startsWith('###')) {
+      current = { name: h2[1], line: line.n, lines: [] };
+      sections.push(current);
+      continue;
+    }
+    if (current) current.lines.push(line);
+  }
+  return sections;
+}
+
+function parseScenarios(lines) {
+  const scenarios = [];
+  let current = null;
+  for (const line of lines) {
+    if (line.fenced) { current = null; continue; }
+    const m = SCENARIO_RE.exec(line.raw);
+    if (m) {
+      current = { id: m[1], text: m[2].trim(), proof: null, artifactWhy: null, line: line.n };
+      scenarios.push(current);
+      continue;
+    }
+    if (!current) continue;
+    if (/^\s*$/.test(line.raw) || /^#/.test(line.raw) || /^[-*]\s/.test(line.raw)) { current = null; continue; }
+    const why = WHY_RE.exec(line.raw);
+    if (why) { current.artifactWhy = why[1] || ''; continue; }
+    const proof = PROOF_RE.exec(line.raw);
+    if (proof && current.proof === null) { current.proof = proof[1]; continue; }
+    if (/^\s*>/.test(line.raw)) continue;
+    current.text = `${current.text} ${line.raw.trim()}`;
+  }
+  return scenarios;
+}
+
+function parseDecisions(lines) {
+  const adrs = [];
+  let conflicts = null;
+  let current = null;
+  for (const line of lines) {
+    if (line.fenced) {
+      if (current?.kind === 'conflicts') conflicts.body.push(line.raw);
+      else if (current?.kind === 'adr') current.entry.body.push(line.raw);
+      continue;
+    }
+    const adr = ADR_RE.exec(line.raw);
+    if (adr) {
+      current = { kind: 'adr', entry: { id: adr[1], title: adr[2], scope: null, body: [], line: line.n } };
+      adrs.push(current.entry);
+      continue;
+    }
+    const h3 = /^###\s+(.+?)\s*$/.exec(line.raw);
+    if (h3) {
+      if (fold(h3[1]) === fold(CONFLICTS_HEADING)) {
+        conflicts = { line: line.n, body: [] };
+        current = { kind: 'conflicts' };
+      } else {
+        current = null;
+      }
+      continue;
+    }
+    if (current?.kind === 'adr') {
+      current.entry.body.push(line.raw);
+      const scope = current.entry.scope === null && SCOPE_RE.exec(line.raw);
+      if (scope) current.entry.scope = scope[1].replace(/`/g, '').trim().toLowerCase();
+    } else if (current?.kind === 'conflicts') {
+      conflicts.body.push(line.raw);
+    }
+  }
+  for (const a of adrs) a.body = a.body.join('\n').trim();
+  return {
+    adrs,
+    conflicts: conflicts && { line: conflicts.line, text: conflicts.body.join('\n').trim() },
+  };
+}
+
+function parseReuse(lines) {
+  const rows = [];
+  let header = null;
+  for (const line of lines) {
+    if (line.fenced || !isTableLine(line.raw) || SEPARATOR_ROW_RE.test(line.raw)) continue;
+    const cells = tableCells(line.raw);
+    if (!header) { header = cells.map(fold); continue; }
+    const at = (name) => cells[header.indexOf(name)] ?? '';
+    rows.push({
+      concept: at('conceito'),
+      verdict: at('veredito').replace(/`|\*/g, '').trim().toUpperCase(),
+      target: at('alvo'),
+      why: at('why'),
+      line: line.n,
+    });
+  }
+  return { header, rows };
+}
+
+function parseSlices(lines) {
+  const slices = [];
+  let current = null;
+  for (const line of lines) {
+    if (line.fenced) continue;
+    const m = SLICE_RE.exec(line.raw);
+    if (m) {
+      current = {
+        id: m[1], title: m[2], persona: null, surface: null,
+        standards: [], files: [], depends: [], covers: [], unknownKeys: [], line: line.n,
+      };
+      slices.push(current);
+      continue;
+    }
+    if (/^###\s/.test(line.raw)) { current = null; continue; }
+    if (!current) continue;
+    const kv = SLICE_LINE_RE.exec(line.raw);
+    if (!kv) continue;
+    const key = SLICE_KEYS[fold(kv[1])] ?? SLICE_KEYS[kv[1].toLowerCase()];
+    if (!key) { current.unknownKeys.push(kv[1]); continue; }
+    if (key === 'persona' || key === 'surface') {
+      const value = kv[2].replace(/`/g, '').trim();
+      current[key] = value && !/^[—–-]$/.test(value) ? value : null;
+    } else {
+      current[key] = listOf(kv[2]);
+    }
+  }
+  return slices;
+}
+
+/**
+ * Parse `2-plan/plan.md` into its structure. Pure: no validation, no I/O —
+ * `checks.js` judges what this returns.
+ *
+ * @param {string} text
+ */
+export function parsePlan(text) {
+  const lines = markdownLines(text);
+  const sections = splitSections(lines);
+  const byName = new Map();
+  for (const s of sections) {
+    const key = Object.keys(SECTIONS).find((k) => fold(SECTIONS[k]) === fold(s.name));
+    if (key && !byName.has(key)) byName.set(key, s);
+  }
+  const body = (key) => byName.get(key)?.lines ?? [];
+  const decisions = parseDecisions(body('decisions'));
+  const reuse = parseReuse(body('reuse'));
+  const errata = byName.get('errata');
+
+  return {
+    sections: sections.map((s) => ({ name: s.name, line: s.line, key: [...byName].find(([, v]) => v === s)?.[0] ?? null })),
+    present: Object.fromEntries(Object.keys(SECTIONS).map((k) => [k, byName.has(k)])),
+    scenarios: parseScenarios(body('scenarios')),
+    adrs: decisions.adrs,
+    conflicts: decisions.conflicts,
+    reuse: reuse.rows,
+    reuseHeader: reuse.header,
+    slices: parseSlices(body('slices')),
+    errata: errata ? errata.lines.map((l) => l.raw).join('\n').trim() : null,
+    sectionsAfterErrata: errata ? sections.filter((s) => s.line > errata.line).map((s) => s.name) : [],
+  };
+}

package/src/lib/plan/plan-template.js

@@ -0,0 +1,18 @@
+import { readFileSync } from 'fs';
+import { templateSourcePath, writeIfAbsent } from '../../core/templates/template-seed.js';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+
+const FEATURE_PLACEHOLDER = /\{\{FEATURE_NAME\}\}/g;
+
+export function planTemplatePath(cwd = process.cwd()) {
+  return templateSourcePath('plan', cwd);
+}
+
+export function renderPlanSkeleton(featureName, cwd = process.cwd()) {
+  return readFileSync(planTemplatePath(cwd), 'utf8').replace(FEATURE_PLACEHOLDER, featureName);
+}
+
+/** @returns {{ path: string, written: boolean }} `written: false` when the file already existed. */
+export function writePlanSkeleton(featureName, cwd = process.cwd()) {
+  return writeIfAbsent(getAbsoluteOutputPath(cwd, featureName, 'plan'), renderPlanSkeleton(featureName, cwd));
+}

package/src/lib/review-reports.js

@@ -0,0 +1,222 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { OUTPUT_SCHEMA, getAbsoluteOutputPath } from '../core/paths/output-schema.js';
+import { PARTIAL_MARKER } from '../../framework/hooks/shared/slice-progress.js';
+
+export const VERDICT_TOKEN = '**Verdict:**';
+export const REVIEWED_SHA_TOKEN = '**Reviewed-SHA:**';
+export const VERDICTS = ['SHIP', 'FIX'];
+export const BLOCKER_TYPES = ['check', 'teste', 'regressao', 'seguranca', 'escopo', 'arquitetura', 'performance'];
+export const CHECK_STATUSES = ['PROVADO', 'NÃO PROVADO', 'FALHA'];
+
+export const REVIEW_ROLES = {
+  verifier: { output: 'verifierReport', persona: 'morph-verifier' },
+  reviewer: { output: 'reviewerReport', persona: 'morph-reviewer' },
+  security: { output: 'securityReport', persona: 'morph-security' },
+};
+const ROLE_ORDER = Object.keys(REVIEW_ROLES);
+
+export const reviewFileName = (role) => OUTPUT_SCHEMA[REVIEW_ROLES[role].output].filename;
+
+// Append-only: uma reavaliação acrescenta ao fim, e vale o ÚLTIMO token/seção.
+const VERDICT_RE = /\*\*Verdict:\*\*\s*([A-Za-z]+)/g;
+const REVIEWED_SHA_RE = /\*\*Reviewed-SHA:\*\*\s*`?([0-9a-f]{7,40})/gi;
+const sectionRe = (title) => new RegExp(`^##\\s+${title}\\s*$`, 'gim');
+const BLOCKERS_SECTION_RE = sectionRe('Bloqueadores');
+const CHECKS_SECTION_RE = sectionRe('Checks');
+const MEDIA_SECTION_RE = /^##\s+M[íi]dia\s+gerada\s*$/m;
+const SCREEN_CHECKLIST_SECTION_RE = sectionRe('Checklist\\s+de\\s+tela');
+
+/** Hotfix: só o verificador, escrito pelo orquestrador sem dispatch. */
+export function requiredReviewRoles({ workType, securityRequired = false } = {}) {
+  if (workType === 'hotfix') return ['verifier'];
+  return securityRequired ? ['verifier', 'reviewer', 'security'] : ['verifier', 'reviewer'];
+}
+
+function sectionBodies(text, re) {
+  return [...text.matchAll(re)].map((m) => {
+    const rest = text.slice(m.index + m[0].length);
+    const next = rest.search(/^#{1,2}\s/m);
+    return next === -1 ? rest : rest.slice(0, next);
+  });
+}
+
+function lastSectionBody(text, re) {
+  const bodies = sectionBodies(text, re);
+  return bodies.length ? bodies[bodies.length - 1] : null;
+}
+
+const normalize = (s) => String(s ?? '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/\s+/g, ' ').trim();
+const cleanId = (s) => String(s ?? '').replace(/[*`_]/g, '').trim().toUpperCase();
+
+function tableRows(body) {
+  const rows = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (!/^\s*\|/.test(line)) continue;
+    const cells = line.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
+    if (cells.every((c) => /^:?-{2,}:?$/.test(c) || c === '')) continue;
+    rows.push(cells);
+  }
+  return rows;
+}
+
+/** `| id | tipo | onde | evidência |`; `untyped` = tipo fora de {@link BLOCKER_TYPES}. */
+function parseBlockers(body) {
+  const blockers = [];
+  const untyped = [];
+  for (const cells of tableRows(body)) {
+    if (/^#$|^id$/i.test(cells[0]) && /^tipo$/i.test(cells[1] ?? '')) continue;
+    const row = { id: cleanId(cells[0]), type: normalize(cells[1]), where: cells[2] ?? '', evidence: cells[3] ?? '' };
+    (BLOCKER_TYPES.includes(row.type) ? blockers : untyped).push(row);
+  }
+  return { blockers, untyped };
+}
+
+const STATUS_BY_KEY = Object.fromEntries(CHECK_STATUSES.map((s) => [normalize(s), s]));
+
+/**
+ * `| Cn | PROVADO|NÃO PROVADO|FALHA | evidência |` de TODAS as seções: uma confirmação
+ * traz só os Cn que mudou, então vale a última linha de cada Cn. Status por igualdade exata.
+ */
+function parseChecks(bodies) {
+  const byId = new Map();
+  for (const cells of bodies.flatMap(tableRows)) {
+    const id = cleanId(cells[0]);
+    if (!/^C\d+$/.test(id)) continue;
+    const raw = String(cells[1] ?? '').replace(/[*`]/g, '').trim();
+    byId.delete(id);
+    byId.set(id, { id, status: STATUS_BY_KEY[normalize(raw)] ?? raw, evidence: cells[2] ?? '' });
+  }
+  return [...byId.values()];
+}
+
+/** Um relatório de review lido do texto. `checks` é `null` sem a seção `## Checks`. */
+export function parseReviewReport(text) {
+  if (typeof text !== 'string') {
+    return { partial: false, verdict: undefined, blockers: [], untyped: [], superseded: [], checks: null, reviewedSha: null };
+  }
+  const firstLine = text.split(/\r?\n/).find((l) => l.trim() !== '') ?? '';
+  const verdicts = [...text.matchAll(VERDICT_RE)].map((m) => m[1].toUpperCase());
+  const blockersBody = lastSectionBody(text, BLOCKERS_SECTION_RE);
+  const checksBodies = sectionBodies(text, CHECKS_SECTION_RE);
+  const shas = [...text.matchAll(REVIEWED_SHA_RE)].map((m) => m[1]);
+  return {
+    partial: PARTIAL_MARKER.test(firstLine),
+    verdict: verdicts.length ? verdicts[verdicts.length - 1] : undefined,
+    ...(blockersBody === null ? { blockers: [], untyped: [] } : parseBlockers(blockersBody)),
+    superseded: verdicts.slice(0, -1),
+    checks: checksBodies.length === 0 ? null : parseChecks(checksBodies),
+    reviewedSha: shas.length ? shas[shas.length - 1] : null,
+  };
+}
+
+/**
+ * `missing`: sem arquivo. `partial`: `PARCIAL` na 1ª linha, com ou sem veredito.
+ * `unverdicted`: sem `**Verdict:** SHIP|FIX`. `ok`: legível — quem decide é o risk-detector.
+ */
+function stateOf(path, text) {
+  if (text === null) return { status: 'missing', path };
+  const parsed = parseReviewReport(text);
+  if (parsed.partial) return { status: 'partial', path, ...parsed };
+  if (!VERDICTS.includes(parsed.verdict)) return { status: 'unverdicted', path, ...parsed };
+  return { status: 'ok', path, ...parsed };
+}
+
+function readText(path) {
+  try {
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Os três relatórios a partir do diretório da feature — sem git; o dashboard lê árvores arquivadas. */
+export function reviewReportsFromDir(featureDir) {
+  const out = {};
+  for (const role of ROLE_ORDER) {
+    const path = join(featureDir, '4-review', reviewFileName(role));
+    out[role] = stateOf(path, readText(path));
+  }
+  return out;
+}
+
+export function reviewReportPath(cwd, featureName, role) {
+  return getAbsoluteOutputPath(cwd, featureName, REVIEW_ROLES[role].output);
+}
+
+export function reviewReports(cwd, featureName) {
+  return reviewReportsFromDir(join(cwd, '.morph', 'features', featureName));
+}
+
+/**
+ * Todo Cn precisa de uma linha, e só `PROVADO` cobre.
+ *
+ * @param {string[]} checkIds
+ * @param {{id: string, status: string}[]|null} rows - `parseReviewReport(...).checks`
+ * @returns {{ missing: string[], notProven: {id: string, status: string}[] }}
+ */
+export function checksCoverage(checkIds, rows) {
+  const byId = new Map((rows ?? []).map((r) => [r.id, r]));
+  const missing = [];
+  const notProven = [];
+  for (const id of checkIds.map(cleanId)) {
+    const row = byId.get(id);
+    if (!row) missing.push(id);
+    else if (row.status !== 'PROVADO') notProven.push({ id, status: row.status || 'vazio' });
+  }
+  return { missing, notProven };
+}
+
+/**
+ * O sinal que `reviewPause` (risk-detector) lê; `checkIds: null` = cobertura não conferível.
+ *
+ * @param {ReturnType<typeof reviewReportsFromDir>} reports
+ * @param {{ required: string[], checkIds: string[]|null }} opts
+ */
+export function reviewSignal(reports, { required, checkIds }) {
+  const out = { required, reports: {} };
+  for (const role of ROLE_ORDER) {
+    const r = reports[role];
+    if (!required.includes(role) && r.status === 'missing') continue;
+    out.reports[role] = r.status === 'missing'
+      ? { status: 'missing' }
+      : {
+        status: r.status,
+        verdict: r.verdict ?? null,
+        blockers: r.blockers.length,
+        blockerIds: r.blockers.map((b) => b.id),
+        untyped: r.untyped.length,
+        superseded: r.superseded,
+      };
+  }
+  out.checks = checkIds === null
+    ? { status: 'no-checks', missing: [], notProven: [] }
+    : { status: 'ok', total: checkIds.length, ...checksCoverage(checkIds, reports.verifier.checks) };
+  return out;
+}
+
+/**
+ * Veredito combinado para leitura (dashboard, list): FIX se qualquer relatório
+ * presente diz FIX ou tem bloqueador; SHIP só com todo exigido em SHIP.
+ */
+export function combinedVerdict(reports, required) {
+  const present = ROLE_ORDER.filter((r) => reports[r].status !== 'missing');
+  if (present.some((r) => reports[r].verdict === 'FIX' || reports[r].blockers.length > 0)) return 'FIX';
+  return required.every((r) => reports[r].status === 'ok' && reports[r].verdict === 'SHIP') ? 'SHIP' : null;
+}
+
+/** Todos os bloqueadores tipados dos relatórios presentes, com o papel que os abriu. */
+export function allBlockers(reports) {
+  return ROLE_ORDER.flatMap((role) => (reports[role].blockers ?? []).map((b) => ({ ...b, role })));
+}
+
+export function verifierMediaSection(cwd, featureName) {
+  const text = readText(reviewReportPath(cwd, featureName, 'verifier'));
+  return text !== null && MEDIA_SECTION_RE.test(text);
+}
+
+export function verifierScreenChecklist(cwd, featureName) {
+  const text = readText(reviewReportPath(cwd, featureName, 'verifier'));
+  const body = text === null ? null : lastSectionBody(text, SCREEN_CHECKLIST_SECTION_RE);
+  return body === null ? { section: false, body: '' } : { section: true, body };
+}