@polymorphism-tech/morph-spec 9.8.0 → 10.0.0

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

@@ -0,0 +1,125 @@
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+const NODE_W = 132;
+const NODE_H = 40;
+const GAP = 84;
+const LANE = 38;
+
+/** States in the order a reader meets them: breadth-first from the first transition's origin. */
+export function stateOrder(transitions) {
+  const order = [];
+  const seen = new Set();
+  const queue = transitions.length ? [transitions[0].from] : [];
+  const visit = (s) => { if (!seen.has(s)) { seen.add(s); queue.push(s); } };
+  if (queue.length) seen.add(queue[0]);
+  while (queue.length) {
+    const s = queue.shift();
+    order.push(s);
+    for (const t of transitions) if (t.from === s) visit(t.to);
+  }
+  for (const t of transitions) for (const s of [t.from, t.to]) if (!seen.has(s)) { seen.add(s); order.push(s); }
+  return order;
+}
+
+// One row of states; a forward transition arcs above, a backward one below, each in its own lane so
+// labels never stack; a self-transition loops over its node.
+export function stateMachineSvg(transitions) {
+  if (!transitions.length) return '';
+  const order = stateOrder(transitions);
+  const x = (s) => 24 + order.indexOf(s) * (NODE_W + GAP);
+  const span = (t) => Math.abs(order.indexOf(t.to) - order.indexOf(t.from));
+  const forward = transitions.filter((t) => order.indexOf(t.to) > order.indexOf(t.from)).sort((a, b) => span(a) - span(b));
+  const backward = transitions.filter((t) => order.indexOf(t.to) < order.indexOf(t.from)).sort((a, b) => span(a) - span(b));
+  const loops = transitions.filter((t) => t.to === t.from);
+  const top = 24 + (forward.length + (loops.length ? 1 : 0)) * LANE;
+  const height = top + NODE_H + 24 + backward.length * LANE;
+  const width = 48 + order.length * NODE_W + (order.length - 1) * GAP;
+  const mid = (s) => x(s) + NODE_W / 2;
+
+  const edge = (t, i, above) => {
+    const x1 = mid(t.from) + (above ? 18 : -18);
+    const x2 = mid(t.to) + (above ? -18 : 18);
+    const y0 = above ? top : top + NODE_H;
+    const y = above ? top - (i + 1) * LANE : top + NODE_H + (i + 1) * LANE;
+    const lx = (x1 + x2) / 2;
+    return `<path class="edge" d="M${x1} ${y0} C${x1} ${y} ${x2} ${y} ${x2} ${y0}" marker-end="url(#arrow)"/>`
+      + `<text class="edge-label" x="${lx}" y="${y + (above ? 0 : 14)}" text-anchor="middle"><title>${esc(t.trigger)}</title>${esc(t.trigger)}</text>`;
+  };
+  const loop = (t) => {
+    const cx = mid(t.from);
+    return `<path class="edge" d="M${cx - 14} ${top} C${cx - 30} ${top - LANE} ${cx + 30} ${top - LANE} ${cx + 14} ${top}" marker-end="url(#arrow)"/>`
+      + `<text class="edge-label" x="${cx}" y="${top - LANE + 4}" text-anchor="middle">${esc(t.trigger)}</text>`;
+  };
+
+  return `<svg class="machine" viewBox="0 0 ${width} ${height}" style="width:100%;min-width:${Math.round(width * 0.6)}px" role="img" aria-label="Máquina de estados: ${esc(order.join(', '))}">
+<defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" class="arrow-head"/></marker></defs>
+${forward.map((t, i) => edge(t, i, true)).join('\n')}
+${backward.map((t, i) => edge(t, i, false)).join('\n')}
+${loops.map(loop).join('\n')}
+${order.map((s) => `<g class="state"><rect x="${x(s)}" y="${top}" width="${NODE_W}" height="${NODE_H}" rx="10"/><text x="${mid(s)}" y="${top + NODE_H / 2 + 5}" text-anchor="middle">${esc(s)}</text></g>`).join('\n')}
+</svg>`;
+}
+
+const RUNG_TONE = { 'migrar': 'warn', 'irreversível': 'bad', 'irreversivel': 'bad' };
+
+function scenarioCard(c) {
+  const chips = [
+    c.proof && `<span class="chip">prova: ${esc(c.proof)}</span>`,
+    c.risk && `<span class="chip">risco: ${esc(c.risk)}</span>`,
+    c.rung && `<span class="chip ${RUNG_TONE[c.rung.toLowerCase()] ?? ''}">degrau: ${esc(c.rung)}</span>`,
+  ].filter(Boolean).join('');
+  return `<li class="card"><div class="cid">${esc(c.id)}</div><div><p>${esc(c.text)}</p>${chips ? `<div class="chips">${chips}</div>` : ''}</div></li>`;
+}
+
+export function renderPlanHtml(feature, plan, { planHash = null } = {}) {
+  const defaults = plan.defaults?.items ?? [];
+  const transitions = plan.states?.transitions ?? [];
+  const section = (title, body) => `<section><h2>${esc(title)}</h2>${body}</section>`;
+  return `<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Plano — ${esc(feature)}</title>
+<style>
+:root { --bg:#f6f7f9; --card:#fff; --fg:#14171c; --dim:#4b5260; --faint:#7a8291; --hair:#dfe3ea; --ok:#2f7d4f; --warn:#a35f00; --bad:#b4232f; --accent:#2d5bd7; }
+@media (prefers-color-scheme: dark) { :root { --bg:#0f1115; --card:#171a21; --fg:#e8ebf0; --dim:#b3bac6; --faint:#7f8796; --hair:#2a2f3a; --ok:#5cc28a; --warn:#e2a54b; --bad:#f07178; --accent:#8fb0ff; } }
+* { box-sizing:border-box; }
+body { margin:0; background:var(--bg); color:var(--fg); font:15px/1.55 system-ui, -apple-system, "Segoe UI", sans-serif; }
+main { max-width:920px; margin:0 auto; padding:40px 16px 64px; }
+h1 { font-size:28px; margin:0 0 4px; letter-spacing:-.01em; }
+.meta { color:var(--faint); font-size:13px; margin:0 0 32px; }
+h2 { font-size:15px; margin:32px 0 12px; }
+ul.cards { list-style:none; padding:0; margin:0; display:grid; gap:10px; }
+.card { display:grid; grid-template-columns:3rem minmax(0,1fr); gap:12px; background:var(--card); border:1px solid var(--hair); border-radius:12px; padding:14px 16px; }
+.card p { margin:0; }
+.cid { font:600 13px/1.6 ui-monospace, monospace; color:var(--accent); }
+.chips { display:flex; flex-wrap:wrap; gap:6px; margin-top:8px; }
+.chip { font-size:12px; color:var(--dim); border:1px solid var(--hair); border-radius:999px; padding:1px 9px; }
+.chip.warn { color:var(--warn); border-color:currentColor; }
+.chip.bad { color:var(--bad); border-color:currentColor; }
+ol.defaults { margin:0; padding-left:22px; color:var(--dim); }
+ol.defaults li { margin:4px 0; }
+.scroll { overflow-x:auto; background:var(--card); border:1px solid var(--hair); border-radius:12px; padding:12px; }
+.machine .state rect { fill:var(--bg); stroke:var(--accent); stroke-width:1.5; }
+.machine .state text { fill:var(--fg); font:600 13px system-ui, sans-serif; }
+.machine .edge { fill:none; stroke:var(--faint); stroke-width:1.5; }
+.machine .arrow-head { fill:var(--faint); }
+.machine .edge-label { fill:var(--dim); font:12px system-ui, sans-serif; paint-order:stroke; stroke:var(--card); stroke-width:4px; }
+.none { color:var(--faint); }
+</style>
+</head>
+<body>
+<main>
+<h1>${esc(feature)}</h1>
+<p class="meta">Visão do plano, só leitura — gerada pelo <code>morph-spec plan-check</code> a partir de 2-plan/plan.md${planHash ? ` (${esc(planHash.slice(0, 12))})` : ''}. Para mudar, edite o plan.md.</p>
+${section(`Cenários (${plan.scenarios.length})`, `<ul class="cards">${plan.scenarios.map(scenarioCard).join('')}</ul>`)}
+${transitions.length ? section('Estados', `<div class="scroll">${stateMachineSvg(transitions)}</div>`) : ''}
+${section('Padrões assumidos', defaults.length
+    ? `<ol class="defaults">${defaults.map((d) => `<li value="${d.n}">${esc(d.text)}</li>`).join('')}</ol><p class="meta">Para vetar um, responda "veta N" no gate.</p>`
+    : '<p class="none">Nenhum.</p>')}
+</main>
+</body>
+</html>
+`;
+}

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

@@ -4,6 +4,7 @@ import { markdownLines } from '../../../framework/hooks/shared/errata.js';
 
 export const PROOF_KINDS = ['teste', 'e2e', 'eval', 'manual', 'leitura'];
 export const RISK_KINDS = ['regra', 'dinheiro', 'contrato', 'concorrência', 'dado', 'regressão'];
+export const REWORK_RUNGS = ['refazer', 'desfazer', 'migrar', 'irreversível'];
 export const REUSE_VERDICTS = ['REUSAR', 'ESTENDER', 'CRIAR'];
 export const ADR_SCOPES = ['feature', 'projeto'];
 
@@ -11,44 +12,29 @@ export const SECTIONS = {
   problem: 'Problema',
   outOfScope: 'Fora de escopo',
   assumptions: 'Suposições não confirmadas',
+  defaults: 'Padrões assumidos',
+  states: 'Estados',
   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 RISK_RE = /^\s*risco\s*:\s*(.*?)\s*$/i;
+const RUNG_RE = /^\s*degrau\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;
@@ -71,7 +57,7 @@ function parseScenarios(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, risk: null, artifactWhy: null, line: line.n };
+      current = { id: m[1], text: m[2].trim(), proof: null, risk: null, rung: null, artifactWhy: null, line: line.n };
       scenarios.push(current);
       continue;
     }
@@ -83,6 +69,8 @@ function parseScenarios(lines) {
     if (proof && current.proof === null) { current.proof = proof[1]; continue; }
     const risk = RISK_RE.exec(line.raw);
     if (risk && current.risk === null) { current.risk = risk[1]; continue; }
+    const rung = RUNG_RE.exec(line.raw);
+    if (rung && current.rung === null) { current.rung = rung[1]; continue; }
     if (/^\s*>/.test(line.raw)) continue;
     current.text = `${current.text} ${line.raw.trim()}`;
   }
@@ -149,34 +137,34 @@ function parseReuse(lines) {
   return { header, rows };
 }
 
-function parseSlices(lines) {
-  const slices = [];
-  let current = null;
+function parseDefaults(lines) {
+  const items = [];
+  let none = false;
+  let comment = false;
   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]);
-    }
+    if (comment || line.raw.includes('<!--')) { comment = !line.raw.includes('-->'); continue; }
+    const m = /^\s*(\d+)[.)]\s+(.+?)\s*$/.exec(line.raw);
+    if (m) items.push({ n: Number(m[1]), text: m[2], line: line.n });
+    else if (/^\s*nenhum\.?\s*$/i.test(line.raw)) none = true;
+  }
+  return { items, none };
+}
+
+const TRANSITION_RE = /^\s*[-*]\s+(.+?)\s*(?:→|->)\s*(.+?)\s*:\s*(.+?)\s*$/;
+
+function parseStates(lines) {
+  const transitions = [];
+  const invalid = [];
+  let comment = false;
+  for (const line of lines) {
+    if (line.fenced || !line.raw.trim()) continue;
+    if (comment || line.raw.includes('<!--')) { comment = !line.raw.includes('-->'); continue; }
+    const m = TRANSITION_RE.exec(line.raw);
+    if (m) transitions.push({ from: m[1], to: m[2], trigger: m[3], line: line.n });
+    else invalid.push({ line: line.n, raw: line.raw.trim() });
   }
-  return slices;
+  return { transitions, invalid };
 }
 
 /** Pure: no validation, no I/O; `checks.js` judges what this returns. */
@@ -201,7 +189,8 @@ export function parsePlan(text) {
     conflicts: decisions.conflicts,
     reuse: reuse.rows,
     reuseHeader: reuse.header,
-    slices: parseSlices(body('slices')),
+    defaults: parseDefaults(body('defaults')),
+    states: parseStates(body('states')),
     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/recap/piper.js

@@ -0,0 +1,36 @@
+import { spawnSync } from 'child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'fs';
+import { homedir, tmpdir } from 'os';
+import { join } from 'path';
+import { findFirstOnPath } from '../../../framework/hooks/shared/morph-cli.js';
+
+export const PIPER_MODEL_DIR = join(homedir(), '.morph-spec', 'piper');
+
+/** The piper binary and a voice model, or why narration falls back to the system voice. */
+export function resolvePiper(env = process.env) {
+  const bin = findFirstOnPath(process.platform === 'win32' ? ['piper.exe'] : ['piper'], env);
+  if (!bin) return { ok: false, reason: 'piper fora do PATH (pip install piper-tts)' };
+  const model = env.MORPH_PIPER_MODEL
+    || [join(PIPER_MODEL_DIR, 'pt_BR-faber-medium.onnx')].find((m) => existsSync(m));
+  if (!model || !existsSync(model)) {
+    return { ok: false, reason: `sem modelo de voz: baixe pt_BR-faber-medium.onnx (+ .onnx.json) para ${PIPER_MODEL_DIR}, ou aponte MORPH_PIPER_MODEL` };
+  }
+  return { ok: true, bin, model };
+}
+
+/** `{ [sceneId]: dataUri }`, or null when piper fails on any scene: half-narrated is worse than the system voice. */
+export function narrateWithPiper(scenes, piper, { run = spawnSync } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'morph-recap-'));
+  try {
+    const audio = {};
+    for (const s of scenes) {
+      const out = join(dir, `${s.id}.wav`);
+      const r = run(piper.bin, ['--model', piper.model, '--output_file', out], { input: s.narration, windowsHide: true, stdio: ['pipe', 'ignore', 'pipe'] });
+      if (r.status !== 0 || !existsSync(out)) return null;
+      audio[s.id] = `data:audio/wav;base64,${readFileSync(out).toString('base64')}`;
+    }
+    return audio;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/src/lib/recap/recap.js

@@ -0,0 +1,232 @@
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { parsePlan } from '../plan/plan-parser.js';
+import { stateMachineSvg } from '../plan/plan-html.js';
+import { reviewReportsFromDir } from '../review-reports.js';
+import { loadGraph, getFreshness } from '../graph/graph-loader.js';
+import { parseDiff, buildDiffTree, declarationDrift } from '../graph/diff-tree.js';
+import { detectDefaultBranch } from '../git/default-branch.js';
+
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const GATE_LABEL = { plan: 'Plano', uiux: 'Design', review: 'Gate 3' };
+
+const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
+const readText = (path) => { try { return readFileSync(path, 'utf8'); } catch { return null; } };
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, stdio: 'pipe', maxBuffer: 64 << 20 }).toString();
+
+/**
+ * What changed on the branch: the call tree when the graph is of HEAD and its lines hold, else the
+ * plain file and line counts. Never throws; outside git it is null.
+ */
+export function changeSummary(cwd, { base = null } = {}) {
+  let from = base;
+  try {
+    from ??= git(cwd, 'merge-base', detectDefaultBranch(cwd) || 'main', 'HEAD').trim();
+  } catch {
+    return null;
+  }
+  let stat = null;
+  try {
+    const m = /(\d+) files? changed(?:, (\d+) insertions?\(\+\))?(?:, (\d+) deletions?\(-\))?/.exec(git(cwd, 'diff', '--shortstat', from, 'HEAD'));
+    stat = { files: Number(m?.[1] ?? 0), added: Number(m?.[2] ?? 0), removed: Number(m?.[3] ?? 0) };
+  } catch {
+    return null;
+  }
+  const loaded = loadGraph(cwd);
+  if (!loaded.ok || getFreshness(cwd, loaded.graph).state !== 'fresh') return { stat, tree: null };
+  try {
+    const tree = buildDiffTree(loaded.graph, parseDiff(git(cwd, 'diff', '-U0', '--no-renames', '--no-color', from, 'HEAD')));
+    const drift = declarationDrift(tree, (f) => { try { return git(cwd, 'show', `HEAD:${f}`).split(/\r?\n/); } catch { return []; } });
+    return { stat, tree: drift.length ? null : tree };
+  } catch {
+    return { stat, tree: null };
+  }
+}
+
+export function buildRecap(featureDir, feature, { changes = null, now = new Date() } = {}) {
+  const fj = readJson(join(featureDir, 'feature.json')) ?? {};
+  const planText = readText(join(featureDir, '2-plan', 'plan.md'));
+  const plan = planText ? parsePlan(planText) : null;
+  const verifier = reviewReportsFromDir(featureDir).verifier;
+  const proved = new Map((verifier?.checks ?? []).map((c) => [c.id, c]));
+  const scenarios = (plan?.scenarios ?? []).map((c) => ({ id: c.id, text: c.text, status: proved.get(c.id)?.status ?? null, evidence: proved.get(c.id)?.evidence ?? '' }));
+  const gates = Object.entries(fj.approvalGates ?? {})
+    .filter(([gate]) => GATE_LABEL[gate])
+    .map(([gate, g]) => ({
+      gate, approved: g === true || g?.approved === true, approvedBy: g?.approvedBy ?? null,
+      paused: fj.gateDecisions?.[gate]?.pause === true, reason: fj.gateDecisions?.[gate]?.reason ?? null,
+    }));
+  const started = Date.parse(fj.createdAt ?? '');
+  return {
+    feature,
+    description: fj.description ?? null,
+    workType: fj.workType ?? null,
+    days: Number.isNaN(started) ? null : Math.max(0, Math.round((now - started) / 86400000)),
+    scenarios,
+    transitions: plan?.states?.transitions ?? [],
+    gates,
+    changes,
+  };
+}
+
+function flatten(tree, limit) {
+  const out = [];
+  const walk = (n, depth) => {
+    if (out.length >= limit) return;
+    out.push({ depth, mark: n.mark, label: n.label, file: n.file, again: n.repeat || n.cycle });
+    n.children.forEach((c) => walk(c, depth + 1));
+  };
+  tree.roots.forEach((r) => walk(r, 0));
+  return out;
+}
+
+/** One scene per part of the story; `narration` is what is spoken and shown as the caption. */
+export function recapScenes(r) {
+  const scenes = [];
+  scenes.push({
+    id: 'abertura',
+    title: r.feature,
+    narration: `${r.feature}. ${r.description ?? ''} ${r.days !== null ? `Do início ao fim, ${r.days === 0 ? 'menos de um dia' : `${r.days} dia${r.days > 1 ? 's' : ''}`}.` : ''}`.replace(/\s+/g, ' ').trim(),
+    body: `<p class="lead">${esc(r.description ?? '')}</p>${r.days !== null ? `<p class="big">${r.days === 0 ? '< 1' : r.days} <span>dia${r.days === 1 ? '' : 's'}</span></p>` : ''}`,
+  });
+  if (r.scenarios.length) {
+    const ok = r.scenarios.filter((c) => c.status === 'PROVADO').length;
+    scenes.push({
+      id: 'cenarios',
+      title: 'O que ficou provado',
+      narration: `${ok} de ${r.scenarios.length} cenários provados pelo verificador. ${r.scenarios.slice(0, 4).map((c) => `${c.id}: ${c.text}`).join(' ')}`,
+      body: `<ul class="checks">${r.scenarios.map((c, i) => `<li style="--i:${i}"><b class="${c.status === 'PROVADO' ? 'ok' : 'warn'}">${c.status === 'PROVADO' ? '✓' : '·'}</b><span><em>${esc(c.id)}</em> ${esc(c.text)}${c.evidence ? `<small>${esc(c.evidence)}</small>` : ''}</span></li>`).join('')}</ul>`,
+    });
+  }
+  if (r.transitions.length) {
+    const states = new Set(r.transitions.flatMap((t) => [t.from, t.to]));
+    scenes.push({
+      id: 'estados',
+      title: 'Como os estados andam',
+      narration: `${states.size} estados e ${r.transitions.length} transições. ${r.transitions.slice(0, 4).map((t) => `De ${t.from} para ${t.to}, quando ${t.trigger}.`).join(' ')}`,
+      body: `<div class="machine-box">${stateMachineSvg(r.transitions)}</div>`,
+    });
+  }
+  if (r.changes) {
+    const { stat, tree } = r.changes;
+    const rows = tree ? flatten(tree, 14) : [];
+    scenes.push({
+      id: 'mudancas',
+      title: 'O que mudou no código',
+      narration: tree
+        ? `${tree.counts.added} símbolos novos e ${tree.counts.modified} alterados em ${stat.files} arquivos. ${tree.roots.slice(0, 3).map((n) => n.label.replace(/\(\)$/, '')).join(', ')} são os pontos de entrada.`
+        : `${stat.files} arquivos, ${stat.added} linhas a mais e ${stat.removed} a menos.`,
+      body: `<p class="stat"><b>${stat.files}</b> arquivos <b class="ok">+${stat.added}</b> <b class="bad">−${stat.removed}</b></p>${rows.length
+        ? `<ul class="tree">${rows.map((n, i) => `<li style="--i:${i};--d:${n.depth}"><b class="${n.mark === '+' ? 'ok' : 'warn'}">${n.mark}</b> ${esc(n.label)}${n.again ? ' <small>↑</small>' : ''} <small>${esc(n.file)}</small></li>`).join('')}</ul>`
+        : ''}`,
+    });
+  }
+  if (r.gates.length) {
+    const human = r.gates.filter((g) => g.paused);
+    scenes.push({
+      id: 'gates',
+      title: 'Por onde passou',
+      narration: `${r.gates.filter((g) => g.approved).length} gates aprovados. ${human.length ? `Pausou para você em ${human.map((g) => GATE_LABEL[g.gate]).join(' e ')}.` : 'Nenhuma pausa para você.'}`,
+      body: `<ol class="gates">${r.gates.map((g, i) => `<li style="--i:${i}"><b class="${g.approved ? 'ok' : 'warn'}">${g.approved ? '✓' : '·'}</b> ${GATE_LABEL[g.gate]}${g.approvedBy ? ` <small>por ${esc(g.approvedBy)}</small>` : ''}${g.paused && g.reason ? `<small class="why">pausou: ${esc(g.reason)}</small>` : ''}</li>`).join('')}</ol>`,
+    });
+  }
+  return scenes;
+}
+
+const SCENE_MS = 9000;
+
+/** `audio`: optional `{ [sceneId]: dataUri }`; without it the page narrates with the system voice. */
+export function renderRecapHtml(r, { audio = null } = {}) {
+  const scenes = recapScenes(r);
+  const data = JSON.stringify(scenes.map((s) => ({ id: s.id, narration: s.narration, audio: audio?.[s.id] ?? null }))).replace(/</g, '\\u003c');
+  return `<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Recap — ${esc(r.feature)}</title>
+<style>
+:root { --bg:#0f1115; --card:#171a21; --fg:#e8ebf0; --dim:#b3bac6; --faint:#7f8796; --hair:#2a2f3a; --ok:#5cc28a; --warn:#e2a54b; --bad:#f07178; --accent:#8fb0ff; }
+@media (prefers-color-scheme: light) { :root { --bg:#f6f7f9; --card:#fff; --fg:#14171c; --dim:#4b5260; --faint:#7a8291; --hair:#dfe3ea; --ok:#2f7d4f; --warn:#a35f00; --bad:#b4232f; --accent:#2d5bd7; } }
+* { box-sizing:border-box; }
+body { margin:0; min-height:100vh; background:var(--bg); color:var(--fg); font:16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; display:flex; flex-direction:column; }
+.stage { flex:1; position:relative; max-width:960px; width:100%; margin:0 auto; padding:40px 16px 16px; }
+.scene { position:absolute; inset:40px 16px 16px; opacity:0; transform:translateY(12px); transition:opacity .6s, transform .6s; pointer-events:none; overflow:auto; }
+.scene.on { opacity:1; transform:none; pointer-events:auto; }
+h1 { font-size:clamp(26px, 5vw, 44px); margin:0 0 20px; letter-spacing:-.02em; }
+.lead { font-size:20px; color:var(--dim); max-width:60ch; }
+.big { font-size:72px; font-weight:700; margin:24px 0 0; } .big span { font-size:20px; color:var(--faint); font-weight:400; }
+ul, ol { list-style:none; padding:0; margin:0; }
+.on li { animation:rise .5s both; animation-delay:calc(var(--i) * 120ms + 300ms); }
+@keyframes rise { from { opacity:0; transform:translateY(8px); } }
+@media (prefers-reduced-motion: reduce) { .scene, .on li { transition:none; animation:none; } }
+.checks li, .gates li { display:flex; gap:12px; padding:10px 0; border-bottom:1px solid var(--hair); }
+.checks em { font-style:normal; font-weight:600; color:var(--accent); margin-right:6px; }
+small { display:block; color:var(--faint); font-size:13px; }
+.tree li small, .gates li small { display:inline; margin-left:6px; }
+.gates .why { display:block; margin:4px 0 0; }
+.tree li { padding:4px 0 4px calc(var(--d) * 22px); font:14px/1.5 ui-monospace, monospace; }
+.stat { font-size:22px; } .stat b { margin-right:4px; }
+.ok { color:var(--ok); } .warn { color:var(--warn); } .bad { color:var(--bad); }
+.machine-box { background:var(--card); border:1px solid var(--hair); border-radius:12px; padding:12px; overflow-x:auto; }
+.machine .state rect { fill:var(--bg); stroke:var(--accent); stroke-width:1.5; } .machine .state text { fill:var(--fg); font:600 13px system-ui; }
+.machine .edge { fill:none; stroke:var(--faint); stroke-width:1.5; } .machine .arrow-head { fill:var(--faint); }
+.machine .edge-label { fill:var(--dim); font:12px system-ui; paint-order:stroke; stroke:var(--card); stroke-width:4px; }
+.bar { position:sticky; bottom:0; background:var(--card); border-top:1px solid var(--hair); }
+.caption { max-width:960px; margin:0 auto; padding:12px 16px 4px; color:var(--dim); min-height:3.2em; }
+.controls { max-width:960px; margin:0 auto; padding:4px 16px 12px; display:flex; gap:8px; align-items:center; flex-wrap:wrap; }
+button { background:transparent; color:var(--fg); border:1px solid var(--hair); border-radius:999px; padding:6px 14px; font:inherit; font-size:14px; cursor:pointer; min-height:36px; }
+button[aria-pressed="true"] { border-color:var(--accent); color:var(--accent); }
+.dots { margin-left:auto; display:flex; gap:6px; } .dots i { width:8px; height:8px; border-radius:50%; background:var(--hair); } .dots i.on { background:var(--accent); }
+</style>
+</head>
+<body>
+<main class="stage">
+${scenes.map((s, i) => `<section class="scene${i === 0 ? ' on' : ''}" data-scene="${i}" aria-hidden="${i !== 0}"><h1>${esc(s.title)}</h1>${s.body}</section>`).join('\n')}
+</main>
+<div class="bar">
+<p class="caption" aria-live="polite"></p>
+<div class="controls">
+<button id="play">▶ Tocar</button><button id="prev">←</button><button id="next">→</button><button id="voice" aria-pressed="true">Narração</button>
+<span class="dots">${scenes.map(() => '<i></i>').join('')}</span>
+</div>
+</div>
+<script>
+const SCENES = ${data};
+const els = [...document.querySelectorAll('.scene')], dots = [...document.querySelectorAll('.dots i')];
+const caption = document.querySelector('.caption'), voiceBtn = document.getElementById('voice'), playBtn = document.getElementById('play');
+let at = 0, playing = false, timer = null, clip = null;
+const voiceOn = () => voiceBtn.getAttribute('aria-pressed') === 'true';
+function stopSound() { clearTimeout(timer); if (clip) { clip.pause(); clip = null; } if (window.speechSynthesis) speechSynthesis.cancel(); }
+function advance() { if (playing && at < SCENES.length - 1) show(at + 1); else { playing = false; playBtn.textContent = '▶ Tocar'; } }
+function speak(s) {
+  if (!playing) return;
+  if (voiceOn() && s.audio) { clip = new Audio(s.audio); clip.onended = advance; clip.play().catch(() => { timer = setTimeout(advance, ${SCENE_MS}); }); return; }
+  if (voiceOn() && window.speechSynthesis) {
+    const u = new SpeechSynthesisUtterance(s.narration); u.lang = 'pt-BR';
+    const v = speechSynthesis.getVoices().find((x) => x.lang && x.lang.toLowerCase().startsWith('pt'));
+    if (v) u.voice = v;
+    u.onend = advance; u.onerror = () => { timer = setTimeout(advance, ${SCENE_MS}); };
+    speechSynthesis.speak(u); return;
+  }
+  timer = setTimeout(advance, ${SCENE_MS});
+}
+function show(i) {
+  stopSound(); at = i;
+  els.forEach((e, k) => { e.classList.toggle('on', k === i); e.setAttribute('aria-hidden', String(k !== i)); });
+  dots.forEach((d, k) => d.classList.toggle('on', k === i));
+  caption.textContent = SCENES[i].narration;
+  speak(SCENES[i]);
+}
+playBtn.onclick = () => { playing = !playing; playBtn.textContent = playing ? '❚❚ Pausar' : '▶ Tocar'; if (playing) show(at); else stopSound(); };
+document.getElementById('prev').onclick = () => show(Math.max(0, at - 1));
+document.getElementById('next').onclick = () => show(Math.min(SCENES.length - 1, at + 1));
+voiceBtn.onclick = () => { voiceBtn.setAttribute('aria-pressed', String(!voiceOn())); if (!voiceOn()) stopSound(); };
+document.addEventListener('keydown', (e) => { if (e.key === 'ArrowRight') document.getElementById('next').click(); if (e.key === 'ArrowLeft') document.getElementById('prev').click(); if (e.key === ' ') { e.preventDefault(); playBtn.click(); } });
+caption.textContent = SCENES[0].narration; dots[0].classList.add('on');
+</script>
+</body>
+</html>
+`;
+}

package/src/lib/review-reports.js

@@ -1,12 +1,14 @@
 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';
+import { PARTIAL_MARKER } from '../../framework/hooks/shared/report-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 BLOCKER_TYPES = ['check', 'teste', 'regressao', 'seguranca', 'escopo', 'arquitetura', 'performance', 'irreversivel'];
+// The plan is frozen by then: the session cannot declare the rung itself, only the human can accept it.
+export const HUMAN_BLOCKER_TYPES = ['irreversivel'];
 export const CHECK_STATUSES = ['PROVADO', 'NÃO PROVADO', 'FALHA'];
 
 export const REVIEW_ROLES = {
@@ -101,11 +103,31 @@ function parseChecks(bodies) {
   return [...byId.values()];
 }
 
-/** Um relatório de review lido do texto. `checks` é `null` sem a seção `## Checks`. */
+// A verdict at the start of a line opens a round; one quoted inside a note does not.
+const ROUND_START_RE = /^[ \t>*_]*\*\*Verdict:\*\*/gm;
+
+function splitRounds(text) {
+  const starts = [...text.matchAll(ROUND_START_RE)].map((m) => m.index);
+  if (starts.length < 2) return [text];
+  return starts.map((s, i) => text.slice(i === 0 ? 0 : s, starts[i + 1] ?? text.length));
+}
+
+/**
+ * Um relatório de review lido do texto. `checks` é `null` sem a seção `## Checks`.
+ * `rounds`: uma entrada por veredito, na ordem do arquivo, com o que aquela rodada escreveu.
+ */
 export function parseReviewReport(text) {
   if (typeof text !== 'string') {
-    return { partial: false, verdict: undefined, blockers: [], untyped: [], superseded: [], checks: null, reviewedSha: null };
+    return { partial: false, verdict: undefined, blockers: [], untyped: [], superseded: [], checks: null, reviewedSha: null, rounds: [] };
   }
+  const parsed = splitRounds(text).map(parseRound);
+  const last = parsed[parsed.length - 1];
+  const rounds = parsed.map((r) => ({ verdict: r.verdict ?? null, reviewedSha: r.reviewedSha, blockers: r.blockers, checks: r.checks }));
+  // Blockers belong to the round that wrote them: a confirmation without `## Bloqueadores` closes the earlier ones.
+  return { ...parseRound(text), blockers: last.blockers, untyped: last.untyped, rounds };
+}
+
+function parseRound(text) {
   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);
@@ -182,8 +204,10 @@ export function reviewSignal(reports, { required, checkIds }) {
         verdict: r.verdict ?? null,
         blockers: r.blockers.length,
         blockerIds: r.blockers.map((b) => b.id),
+        humanBlockerIds: r.blockers.filter((b) => HUMAN_BLOCKER_TYPES.includes(b.type)).map((b) => b.id),
         untyped: r.untyped.length,
         superseded: r.superseded,
+        rounds: r.rounds.length,
       };
   }
   out.checks = !required.includes('verifier')