@polymorphism-tech/morph-spec 9.8.0 → 10.1.1

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')

package/src/lib/risk-detector.js

@@ -1,5 +1,5 @@
-import { MAX_SLICES } from './plan/checks.js';
 import { BLOCKER_TYPES, reviewFileName } from './review-reports.js';
+import { FIX_ATTEMPTS } from '../../framework/hooks/shared/next-step.js';
 import { isTestPath } from './graph/sanitize.js';
 import { isTestArtifact } from './worktree/ignored-triage.js';
 
@@ -55,7 +55,7 @@ function firstOf(items) {
 
 // Exportada porque approve/advance `auto` recusam pela mesma regra. Sem design de tela não conta,
 // e o legado chega sem problemas: a auditoria o isenta. Checklist
-// completo ainda deve o protótipo e os prints 1280/390 (`prototypes`).
+// completo ainda deve o protótipo, os prints 1280/390 e os estados (`prototypes`).
 export function uiuxChecklistPause(screenChecklist) {
   if (screenChecklist?.mockups !== true) return null;
   const problems = screenChecklist.problems ?? [];
@@ -95,6 +95,11 @@ export function reviewPause(signal) {
     return `${untyped} bloqueador(es) sem tipo de evidência (${BLOCKER_TYPES.join(' | ')})`
          + ' — sem evidência tipada não é bloqueador: reclassifique como nota ou complete a evidência';
   }
+  for (const [role, r] of present) {
+    if ((r.humanBlockerIds?.length ?? 0) > 0) {
+      return `${role} achou mudança irreversível que o plano não declara: ${firstOf(r.humanBlockerIds)} — o usuário decide`;
+    }
+  }
   for (const [role, r] of present) {
     if ((r.blockers ?? 0) > 0) return `${role} abriu ${r.blockers} bloqueador(es): ${firstOf(r.blockerIds ?? [])}`;
   }
@@ -162,7 +167,78 @@ export function planChecksPause(status) {
   return `${what} — rode \`morph-spec plan-check {feature}\` até zero erro antes do gate do plano`;
 }
 
+export const PAUSING_RUNGS = ['migrar', 'irreversível'];
+const MIGRATION_PATH_RE = /(^|\/)migrations?\//i;
+
+export function pausingRungs(checks) {
+  const list = Array.isArray(checks?.checks) ? checks.checks : [];
+  return list.filter((c) => PAUSING_RUNGS.includes(c.rung)).map((c) => ({ id: c.id, rung: c.rung }));
+}
+
+// Só o arquivo que É o contrato. Webhook e endpoint ficam com o revisor (`irreversivel`): o caminho não diz se quebra quem consome.
+const CONTRACT_PATH_RE = /(^|\/)(openapi|swagger)\.(ya?ml|json)$|\.proto$/i;
+
+const touchedBy = (re) => (changedFiles = []) =>
+  changedFiles.map((f) => f.replaceAll('\\', '/')).filter((f) => re.test(f) && !isTestOnly(f));
+export const migrationsTouched = touchedBy(MIGRATION_PATH_RE);
+export const contractsTouched = touchedBy(CONTRACT_PATH_RE);
+
+export const humanApprover = (approvedBy) => !!approvedBy && approvedBy !== 'auto' && !String(approvedBy).startsWith('policy:');
+
+// Regra única do gate-check (pausa) e do approve/advance automáticos do plano (recusa).
+export function rungPause(signals) {
+  const rungs = signals.rungs ?? [];
+  const named = rungs.map((r) => `${r.id} (${r.rung})`).join(', ');
+  if (signals.gate === 'plan') {
+    return rungs.length ? { signal: 'rung', reason: `${named} não se desfaz com revert — o usuário confirma antes de implementar` } : null;
+  }
+  if (signals.gate !== 'review') return null;
+  const migrations = signals.migrationsTouched ?? [];
+  if (migrations.length > 0 && rungs.length === 0) {
+    return { signal: 'rung-undeclared', reason: `a feature toca migration (${firstOf(migrations)}) e nenhum cenário declara \`degrau: migrar\` ou \`irreversível\`` };
+  }
+  const contracts = signals.contractsTouched ?? [];
+  if (contracts.length > 0 && !rungs.some((r) => r.rung === 'irreversível')) {
+    return { signal: 'rung-undeclared', reason: `a feature toca contrato externo (${firstOf(contracts)}) e nenhum cenário declara \`degrau: irreversível\`` };
+  }
+  if (rungs.length > 0 && !signals.planApprovedByHuman) return { signal: 'rung', reason: `${named} não passou por aprovação humana no plano` };
+  return null;
+}
+
+const PLAN_CRITIQUE_REASONS = {
+  missing: 'sem `2-plan/critica.md`',
+  'no-hash': '`2-plan/critica.md` sem `**Plan-Hash:**`',
+  stale: '`2-plan/critica.md` é de outra versão do plano e nenhum `**Aplicado-em:**` cobre a atual',
+};
+
+// Regra única do gate-check (pausa) e do approve/advance automáticos do plano (recusa).
+export function planCritiquePause(status) {
+  const what = PLAN_CRITIQUE_REASONS[status];
+  return what ? `${what} — despache a crítica em contexto fresco (morph-plan, references/critique.md) antes do gate do plano` : null;
+}
+
+// Pauses the session clears by doing the work the reason names; the rest wait for the human.
+const REPORT_SIGNALS = ['review-reports', 'screen-checklist', 'media-claims'];
+export const SESSION_SIGNALS = ['verify-red', 'verify-missing', 'verify-stale', 'e2e-skip', 'plan-checks', 'plan-critique', 'uiux-checklist', ...REPORT_SIGNALS];
+
+const reviewRounds = (review) => Math.max(0, ...Object.values(review?.reports ?? {}).map((r) => r.rounds ?? 0));
+const humanBlockers = (review) => Object.values(review?.reports ?? {}).some((r) => (r.humanBlockerIds?.length ?? 0) > 0);
+
+export function pauseResolver(signal, signals = {}) {
+  if (!SESSION_SIGNALS.includes(signal)) return 'human';
+  if (signal === 'verify-red' && (signals.failStreak ?? 0) >= FIX_ATTEMPTS) return 'human';
+  if (signal === 'e2e-skip' && classifyE2eSkip(signals.e2eReason) !== 'requested') return 'human';
+  if (REPORT_SIGNALS.includes(signal) && reviewRounds(signals.reviewReports) >= FIX_ATTEMPTS) return 'human';
+  if (signal === 'review-reports' && humanBlockers(signals.reviewReports)) return 'human';
+  return 'session';
+}
+
 export function shouldPauseGate(config, signals) {
+  const decision = pauseDecision(config, signals);
+  return decision.pause ? { ...decision, resolver: pauseResolver(decision.signal, signals) } : decision;
+}
+
+function pauseDecision(config, signals) {
   const trust = config?.trust ?? 'auto';
 
   if (trust === 'manual') {
@@ -301,15 +377,13 @@ export function shouldPauseGate(config, signals) {
   if (signals.gate === 'plan') {
     const reason = planChecksPause(signals.planChecks);
     if (reason) return { pause: true, signal: 'plan-checks', reason };
+    const critique = planCritiquePause(signals.planCritique);
+    if (critique) return { pause: true, signal: 'plan-critique', reason: critique };
   }
 
-  if (typeof signals.sliceCount === 'number' && signals.sliceCount > MAX_SLICES) {
-    return {
-      pause: true,
-      signal: 'slice-count',
-      reason: `${signals.sliceCount} fatias, acima de ${MAX_SLICES} — o plano é grande demais para uma feature`,
-    };
-  }
+  // Por último: o usuário só é chamado pelo degrau quando a sessão não tem mais nada a corrigir.
+  const rung = rungPause(signals);
+  if (rung) return { pause: true, ...rung };
 
   return { pause: false, signal: null, reason: '' };
 }
@@ -346,8 +420,13 @@ export function getRiskSignals(signals) {
   if (signals.gate === 'plan' && signals.planChecks && signals.planChecks !== 'fresh') {
     out.push(`checks.json ${signals.planChecks}`);
   }
-  if (typeof signals.sliceCount === 'number' && signals.sliceCount > MAX_SLICES) {
-    out.push(`${signals.sliceCount} fatias (acima de ${MAX_SLICES})`);
+  if (signals.gate === 'plan' && signals.planCritique) out.push(`crítica do plano: ${signals.planCritique}`);
+  if ((signals.rungs?.length ?? 0) > 0) out.push(`degrau: ${signals.rungs.map((r) => `${r.id} ${r.rung}`).join(', ')}`);
+  if (signals.gate === 'review' && (signals.migrationsTouched?.length ?? 0) > 0) {
+    out.push(`migration tocada: ${firstOf(signals.migrationsTouched)}`);
+  }
+  if (signals.gate === 'review' && (signals.contractsTouched?.length ?? 0) > 0) {
+    out.push(`contrato externo tocado: ${firstOf(signals.contractsTouched)}`);
   }
   if (signals.gate === 'review' && signals.mediaClaims?.featureGeneratesMedia === true) {
     out.push(signals.mediaClaims.section === true