@polymorphism-tech/morph-spec 10.5.4 → 10.7.0

package/src/commands/validation/verify.js

@@ -13,7 +13,7 @@ import { HeavyBusyError } from '../../lib/heavy/gate.js';
 import { afterHeavyRun } from '../../lib/heavy/cleanup.js';
 import { memoryBusyHint } from '../../lib/heavy/live-stacks.js';
 import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
-import { runCiVerify, CiUsageError, reusableLocalStamp } from '../../lib/ci/ci-verify.js';
+import { runCiVerify, CiUsageError, reusableLocalStamp, resolvePrProof } from '../../lib/ci/ci-verify.js';
 import { syncStackRules } from '../../lib/installers/stack-sync.js';
 import {
   DETACH_RUN_ENV, DETACH_STAGE_ENV, DETACH_WORKER_ENV, launchWorker, markWorkerExit, runFilesOf, superviseVerify,
@@ -137,6 +137,7 @@ async function runLocalVerify(featureName, options, fingerprint) {
       fingerprint,
       fresh: options.fresh,
       affected: options.affected,
+      excludeNodes: options.excludeNodes,
       timeout: options.timeout,
       skipTests: options.skipTests,
       skipBuild: options.skipBuild,
@@ -231,14 +232,19 @@ export async function verifyCommand(featureName, options = {}) {
   }
 
   let ci = null;
+  let prProof = null;
   if (options.ci) {
     const fresh = reusableLocalStamp(process.cwd(), feature.verification);
     if (fresh) exitWithReusedStamp(featureName, fresh, 'stamp verde e fresco — o CI não roda de novo', options);
+    prProof = resolvePrProof(process.cwd(), featureName, readMorphConfig(process.cwd()));
+    if (prProof?.local) console.error(chalk.yellow(`\n↪ completa local: ${prProof.local}\n`));
     try {
-      const outcome = await runCiVerify(process.cwd(), featureName, readMorphConfig(process.cwd()), {
+      const outcome = prProof ? null : await runCiVerify(process.cwd(), featureName, readMorphConfig(process.cwd()), {
         log: (line) => console.error(chalk.gray(`   ${line}`)),
       });
-      if (outcome.mode === 'ci') {
+      if (!outcome) {
+        // The PR proof has no run to wait for here: `finish --pr` waits for it.
+      } else if (outcome.mode === 'ci') {
         ci = outcome;
       } else if (outcome.mode === 'pending') {
         if (options.json) console.log(JSON.stringify({ status: 'pending', persisted: false, reason: outcome.reason }, null, 2));
@@ -259,7 +265,8 @@ export async function verifyCommand(featureName, options = {}) {
   // Taken before the run: it is the tree the run is about to read.
   const fingerprint = treeFingerprint(process.cwd());
 
-  const result = ci ? ci.result : await runLocalVerify(featureName, options, fingerprint);
+  const pendingPr = prProof?.covers ? prProof : null;
+  const result = ci ? ci.result : await runLocalVerify(featureName, { ...options, excludeNodes: pendingPr?.covers }, fingerprint);
 
   const cleanup = ci ? { status: 'skipped', reason: 'ci' } : afterHeavyRun({
     projectPath: process.cwd(),
@@ -305,6 +312,7 @@ export async function verifyCommand(featureName, options = {}) {
       ts: now,
       ...(result.flaky?.length ? { flaky: result.flaky } : {}),
       ...(ci ? { source: 'ci', ciRun: ci.run.url } : {}),
+      ...(pendingPr && result.status === 'pass' ? { pendingPr } : {}),
     };
     if (!scopedRun) await updateFeature(featureName, 'verification', stamp);
   }
@@ -334,6 +342,7 @@ export async function verifyCommand(featureName, options = {}) {
       Array.isArray(node.runs) ? { ...withoutOutput(node), runs: node.runs.map(withoutOutput) } : withoutOutput(node)]));
     const output = {
       ...result, nodes, persisted: persist, ...(persist ? {} : { reason }), repeatOf, cleanup,
+      ...(pendingPr ? { pendingPr } : {}),
       ...(ci ? { source: 'ci', ciRun: { id: ci.run.databaseId, url: ci.run.url, sha: ci.run.headSha }, workflowCreated: ci.created } : {}),
     };
     console.log(JSON.stringify(output, null, 2));

package/src/core/paths/output-schema.js

@@ -1,10 +1,12 @@
 import { join } from 'path';
 
+/** The one page of a feature, at its root: it belongs to no phase, and only the CLI writes it. */
+export const FEATURE_VIEW_FILE = 'feature.html';
+
 export const OUTPUT_SCHEMA = {
   plan:           { filename: 'plan.md',               phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   checks:         { filename: 'checks.json',           phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   planCritique:   { filename: 'critica.md',            phaseDir: '2-plan',      phase: 'plan',      protected: false },
-  planView:       { filename: 'plan.html',             phaseDir: '2-plan',      phase: 'plan',      protected: false },
 
   uiMockups:      { filename: 'mockups.md',            phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
 

package/src/lib/ci/ci-verify.js

@@ -8,7 +8,10 @@ import {
   CI_WORKFLOW_DIR, CI_WORKFLOW_FILE, ciAvailability, downloadResult, findCiWorkflow, pushBranch,
   uncommittedCode, waitForRun, workflowPushProblem,
 } from './github-ci.js';
+import { prProofConfig } from './pr-checks.js';
 import { renderCiWorkflow } from './workflow-scaffold.js';
+import { resolveTestNodes } from '../tasks/test-nodes.js';
+import { selectAffected } from '../verify/affected.js';
 
 export const CI_WAIT_MS = 50 * 60 * 1000;
 const APPEAR_MS = Number(process.env.MORPH_CI_APPEAR_MS ?? 90 * 1000);
@@ -58,6 +61,19 @@ export function reusableLocalStamp(root, stamp) {
   return treeMovedSince(root, stamp.sha, head) ? null : stamp;
 }
 
+/**
+ * `covers` = suites the PR's own checks prove, left out of the local run. `local` = run everything here,
+ * with the reason. Null = the project declared no PR proof. What the affected run would escalate stays local.
+ */
+export function resolvePrProof(root, featureName, config, { select = selectAffected } = {}) {
+  const proof = prProofConfig(config);
+  if (!proof) return null;
+  const avail = ciAvailability(root, featureName, config);
+  if (!avail.ok) return { local: avail.reason };
+  const selection = select({ projectPath: root, nodes: resolveTestNodes(root).nodes });
+  return selection.scope === 'full' ? { local: selection.reason } : proof;
+}
+
 // Every way CI cannot answer is `mode: 'local'` with the reason: no CI is never a pause. Only the
 // uploaded `verify --json` becomes a result, judged by the same stamp and rules as a local run.
 export async function runCiVerify(root, featureName, config, { log = () => {}, waitMs = CI_WAIT_MS, wait = waitForRun } = {}) {

package/src/lib/ci/pr-checks.js

@@ -0,0 +1,76 @@
+import { execFileSync } from 'child_process';
+import { resolveGh } from '../git/gh.js';
+
+const FAILED = new Set(['FAILURE', 'TIMED_OUT']);
+const PASSED = new Set(['SUCCESS', 'SKIPPED', 'NEUTRAL']);
+
+// A job killed by exhausted Actions quota fails within seconds without running a step.
+const MIN_JUDGED_MS = 30 * 1000;
+
+export const PR_WAIT_MS = 50 * 60 * 1000;
+
+/** The PR proof a project declared; null when it closes by merge, opted out of CI or declared nothing. */
+export function prProofConfig(config) {
+  if (config?.project?.ci === false || config?.finish?.mode === 'merge') return null;
+  const { workflows, covers } = config?.project?.prChecks ?? {};
+  const filled = (list) => Array.isArray(list) && list.length > 0;
+  return filled(workflows) && filled(covers) ? { workflows, covers } : null;
+}
+
+function neverRan(check) {
+  const elapsed = Date.parse(check.completedAt) - Date.parse(check.startedAt);
+  return !Number.isFinite(elapsed) || elapsed < MIN_JUDGED_MS;
+}
+
+/** Only a declared workflow counts: a green lint or deploy run says nothing about the suite. */
+export function judgeChecks(rollup, workflows) {
+  const checks = (rollup ?? []).filter((check) => workflows.includes(check.workflowName));
+  if (checks.length === 0) return { state: 'absent' };
+  if (checks.some((check) => check.status !== 'COMPLETED')) return { state: 'running' };
+
+  const failed = checks.filter((check) => FAILED.has(check.conclusion));
+  const real = failed.filter((check) => !neverRan(check));
+  if (real.length > 0) return { state: 'fail', failed: real };
+  if (failed.length > 0) return { state: 'no-verdict', reason: `${failed[0].workflowName} morreu sem rodar (cota do Actions?)` };
+
+  const undecided = checks.find((check) => !PASSED.has(check.conclusion));
+  if (undecided) return { state: 'no-verdict', reason: `${undecided.workflowName}: ${undecided.conclusion}` };
+  if (!checks.some((check) => check.conclusion === 'SUCCESS')) return { state: 'no-verdict', reason: 'nenhum check julgou o código' };
+  return { state: 'pass' };
+}
+
+function readPr(root, branch) {
+  try {
+    const { bin, prefix } = resolveGh();
+    return JSON.parse(execFileSync(bin, [...prefix, 'pr', 'view', branch, '--json', 'headRefOid,statusCheckRollup'], { cwd: root, stdio: 'pipe', timeout: 15000 }).toString());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Waits `appearMs` even when the first workflow already settled: the others may not have been created yet.
+ * @returns {Promise<{ state: 'pass'|'fail'|'no-verdict'|'pending', failed?: object[], reason?: string }>}
+ */
+export async function waitForPrChecks(root, { branch, sha, workflows, timeoutMs = PR_WAIT_MS,
+  appearMs = Number(process.env.MORPH_CI_APPEAR_MS ?? 90 * 1000), pollMs = 15000,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, read = readPr }) {
+  const start = now();
+  let misses = 0;
+  for (;;) {
+    const elapsed = now() - start;
+    const pr = read(root, branch);
+    if (pr === null) {
+      if (++misses >= 3) return { state: 'no-verdict', reason: 'gh pr view não respondeu' };
+    } else {
+      misses = 0;
+      const verdict = pr.headRefOid === sha ? judgeChecks(pr.statusCheckRollup, workflows) : { state: 'absent' };
+      if (elapsed >= appearMs) {
+        if (verdict.state === 'absent') return { state: 'no-verdict', reason: `nenhum check de ${workflows.join(', ')} neste commit` };
+        if (verdict.state !== 'running') return verdict;
+      }
+    }
+    if (elapsed >= timeoutMs) return { state: 'pending', reason: `checks não terminaram em ${Math.round(timeoutMs / 60000)} min` };
+    await sleep(pollMs);
+  }
+}

package/src/lib/plan/checks.js

@@ -40,11 +40,11 @@ function defaultsWarnings(plan, at) {
 }
 
 // Optional: absent is fine; present, every line is a transition the plan view can draw.
-function statesErrors(plan, at) {
-  if (!plan.present.states) return [];
-  const { transitions, invalid } = plan.states;
-  const errors = invalid.map((l) => `## ${SECTIONS.states}: "${l.raw}" não é transição — use "- origem → destino: gatilho"${at(l.line)}`);
-  if (transitions.length === 0 && invalid.length === 0) errors.push(`## ${SECTIONS.states} vazia — liste as transições ou apague a seção`);
+function transitionErrors(plan, key, at) {
+  if (!plan.present[key]) return [];
+  const { transitions, invalid } = plan[key === 'flow' ? 'flow' : 'states'];
+  const errors = invalid.map((l) => `## ${SECTIONS[key]}: "${l.raw}" não é transição — use "- origem → destino: gatilho"${at(l.line)}`);
+  if (transitions.length === 0 && invalid.length === 0) errors.push(`## ${SECTIONS[key]} vazia — liste as transições ou apague a seção`);
   return errors;
 }
 
@@ -120,7 +120,7 @@ export function validatePlan(plan, { workType = null, riskRules = true, text = n
   }
 
   errors.push(...defaultsErrors(plan, { workType, riskRules }, at));
-  errors.push(...statesErrors(plan, at));
+  errors.push(...transitionErrors(plan, 'states', at), ...transitionErrors(plan, 'flow', at));
   warnings.push(...defaultsWarnings(plan, at));
 
   const isSlices = (s) => /^fatias$/i.test(s.name.trim());

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

@@ -14,6 +14,7 @@ export const SECTIONS = {
   assumptions: 'Suposições não confirmadas',
   defaults: 'Padrões assumidos',
   states: 'Estados',
+  flow: 'Fluxo',
   scenarios: 'Cenários',
   decisions: 'Decisões',
   architecture: 'Arquitetura',
@@ -191,6 +192,8 @@ export function parsePlan(text) {
     reuseHeader: reuse.header,
     defaults: parseDefaults(body('defaults')),
     states: parseStates(body('states')),
+    flow: parseStates(body('flow')),
+    text: Object.fromEntries(Object.keys(SECTIONS).map((k) => [k, body(k).map((l) => l.raw).join('\n').trim()])),
     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/recap.js

@@ -2,7 +2,7 @@ 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 { stateMachineSvg } from '../view/flow-svg.js';
 import { reviewReportsFromDir } from '../review-reports.js';
 import { loadGraph, getFreshness } from '../graph/graph-loader.js';
 import { parseDiff, buildDiffTree, declarationDrift } from '../graph/diff-tree.js';
@@ -19,7 +19,7 @@ const git = (cwd, ...args) => execFileSync('git', args, { cwd, stdio: 'pipe', ma
  * 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 } = {}) {
+export function changeSummary(cwd, { base = null, statOnly = false } = {}) {
   let from = base;
   try {
     from ??= git(cwd, 'merge-base', detectDefaultBranch(cwd) || 'main', 'HEAD').trim();
@@ -33,6 +33,7 @@ export function changeSummary(cwd, { base = null } = {}) {
   } catch {
     return null;
   }
+  if (statOnly) return { stat, tree: null };
   const loaded = loadGraph(cwd);
   if (!loaded.ok || getFreshness(cwd, loaded.graph).state !== 'fresh') return { stat, tree: null };
   try {
@@ -88,7 +89,7 @@ export function recapScenes(r) {
     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>` : ''}`,
+    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;
@@ -135,6 +136,7 @@ export function recapScenes(r) {
 }
 
 const SCENE_MS = 9000;
+const TOKENS = readFileSync(new URL('../view/tokens.css', import.meta.url), 'utf8');
 
 /** `audio`: optional `{ [sceneId]: dataUri }`; without it the page narrates with the system voice. */
 export function renderRecapHtml(r, { audio = null } = {}) {
@@ -147,8 +149,7 @@ export function renderRecapHtml(r, { audio = null } = {}) {
 <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; } }
+${TOKENS}:root { --bg:var(--paper); --card:var(--panel); --fg:var(--ink); --hair:var(--rule); --accent:var(--route); }
 * { 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; }

package/src/lib/validators/verify-runner.js

@@ -105,7 +105,9 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
   // Usage errors are judged before the build: paying for a build to discover a typo
   // is the worst ordering, and a refusal after the cache was touched leaves a half-rewritten tree.
   const resolvedPlan = resolveTestNodes(projectPath);
-  const testPlan = options.selection ? { ...resolvedPlan, nodes: options.selection.nodes } : resolvedPlan;
+  const excluded = new Set(options.excludeNodes ?? []);
+  const scopedNodes = options.selection ? options.selection.nodes : resolvedPlan.nodes;
+  const testPlan = { ...resolvedPlan, nodes: scopedNodes.filter((node) => !excluded.has(node.id)) };
   const filter = parseTestFilter(options.filter);
   if (filter && !testPlan.nodes.some((node) => nodeMatchesFilter(node, filter))) {
     const declared = testPlan.nodes.map((node) => node.id).join(', ') || '(none)';
@@ -150,10 +152,11 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
     const kept = options.selection.nodes.map((n) => n.id).join(', ') || 'nenhuma';
     feedback.push(`[verify] rodada afetada, suítes: ${kept}; a completa roda uma vez antes da aprovação`);
   }
+  if (excluded.size > 0) feedback.push(`[verify] provadas pelo CI da PR no finish: ${[...excluded].join(', ')}`);
 
   // Only a complete run feeds or reads the cache: a partial one proves nothing about the nodes it left out.
   const cacheDir = fingerprint && !filter && !skipTests && !skipBuild && !skipE2e && !recordBaseline
-    && !refreshCache && !linux && !freshE2e
+    && !refreshCache && !linux && !freshE2e && excluded.size === 0
     ? resolveGitCommonDir(projectPath)
     : null;
   const reuse = planReuse(cacheDir && !fresh ? readVerifyCache(cacheDir, featureName) : null, fingerprint);
@@ -172,7 +175,7 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
     projectPath,
     testPlan,
     filter,
-    skipTests,
+    skipTests: skipTests || (excluded.size > 0 && testPlan.nodes.length === 0),
     buildNode: nodes.build,
     timeout: explicitTimeout,
     refreshCache,

package/src/lib/view/feature-html.js

@@ -0,0 +1,307 @@
+import { readFileSync } from 'fs';
+import { PROOF_KINDS, RISK_KINDS, REUSE_VERDICTS } from '../plan/plan-parser.js';
+import { renderRecapHtml } from '../recap/recap.js';
+import { stateMachineSvg } from './flow-svg.js';
+
+export const TOKENS_CSS = readFileSync(new URL('./tokens.css', import.meta.url), 'utf8');
+const PAGE_CSS = readFileSync(new URL('./feature-page.css', import.meta.url), 'utf8');
+const CLIENT_JS = readFileSync(new URL('./feature-page.client.js', import.meta.url), 'utf8');
+
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const WORK_LABEL = { feature: 'Feature', bug: 'Correção de bug', chore: 'Manutenção', hotfix: 'Hotfix' };
+const STATUS_LABEL = { pendente: 'Pendente', feito: 'Feito', bloqueado: 'Bloqueado' };
+const RUNG_TONE = { migrar: 'warn', 'irreversível': 'bad', irreversivel: 'bad' };
+const NONE_RE = /^(nenhum|nenhuma)\.?$/i;
+
+function linkifier(plan) {
+  const known = new Set([...plan.scenarios.map((c) => c.id), ...plan.adrs.map((a) => a.id)]);
+  const defaults = new Set(plan.defaults.items.map((d) => d.n));
+  const ref = (id, label) => `<a href="#${id}" data-ref="${id}">${label}</a>`;
+  return (escaped) => escaped
+    .replace(/\b(C\d+|ADR-\d+)\b/g, (m, id) => (known.has(id) ? ref(id, m) : m))
+    .replace(/\b([Pp]adrão) (\d+)\b/g, (m, word, n) => (defaults.has(Number(n)) ? ref(`P${n}`, `${word} ${n}`) : m));
+}
+
+function inline(text, link) {
+  return String(text).split(/(`[^`]+`)/).map((part) => {
+    if (/^`[^`]+`$/.test(part)) return `<code>${esc(part.slice(1, -1))}</code>`;
+    return link(esc(part)).replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
+  }).join('');
+}
+
+function blocks(markdown, link) {
+  const text = String(markdown ?? '').replace(/<!--[\s\S]*?-->/g, '');
+  const out = [];
+  let para = [];
+  let list = null;
+  let table = null;
+  let fence = null;
+  const closePara = () => { if (para.length) out.push(`<p>${inline(para.join(' '), link)}</p>`); para = []; };
+  const closeList = () => { if (list) out.push(`<ul>${list.map((i) => `<li>${inline(i, link)}</li>`).join('')}</ul>`); list = null; };
+  const closeTable = () => {
+    if (!table) return;
+    const [head, ...rows] = table;
+    const cells = (row, tag) => row.map((c) => `<${tag}>${inline(c, link)}</${tag}>`).join('');
+    out.push(`<div class="scroll-x"><table><thead><tr>${cells(head, 'th')}</tr></thead><tbody>${rows.map((r) => `<tr>${cells(r, 'td')}</tr>`).join('')}</tbody></table></div>`);
+    table = null;
+  };
+  const closeAll = () => { closePara(); closeList(); closeTable(); };
+  for (const line of text.split(/\r?\n/)) {
+    if (fence) {
+      if (/^\s*```/.test(line)) { out.push(`<pre><code>${esc(fence.join('\n'))}</code></pre>`); fence = null; } else fence.push(line);
+      continue;
+    }
+    if (/^\s*```/.test(line)) { closeAll(); fence = []; continue; }
+    if (!line.trim()) { closeAll(); continue; }
+    if (/^\s*\|/.test(line)) {
+      closePara(); closeList();
+      if (/^\s*\|[\s:|-]+\|?\s*$/.test(line)) continue;
+      (table ??= []).push(line.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim()));
+      continue;
+    }
+    closeTable();
+    const bullet = /^\s*[-*]\s+(.*)$/.exec(line);
+    if (bullet) { closePara(); (list ??= []).push(bullet[1]); continue; }
+    if (list && /^\s+\S/.test(line)) { list[list.length - 1] += ` ${line.trim()}`; continue; }
+    closeList();
+    const heading = /^#{1,6}\s+(.*)$/.exec(line);
+    if (heading) { closePara(); out.push(`<h3>${inline(heading[1], link)}</h3>`); continue; }
+    para.push(line.trim());
+  }
+  if (fence) out.push(`<pre><code>${esc(fence.join('\n'))}</code></pre>`);
+  closeAll();
+  return out.join('');
+}
+
+export function splitProblem(text) {
+  const m = /^\s*\**\s*Resultado buscado\s*:\s*\**\s*(.+)$/im.exec(text ?? '');
+  const outcome = m ? m[1].replace(/\*\*/g, '').trim() : null;
+  return { outcome, problem: m ? text.replace(m[0], '').trim() : text ?? '' };
+}
+
+const bulletsOf = (text) => String(text ?? '').replace(/<!--[\s\S]*?-->/g, '').split(/\r?\n/)
+  .map((l) => /^\s*[-*]\s+(.+)$/.exec(l)?.[1]).filter((l) => l && !NONE_RE.test(l.trim()));
+
+const conflictsOf = (plan) => {
+  const text = plan.conflicts?.text?.replace(/<!--[\s\S]*?-->/g, '').trim();
+  return text && !NONE_RE.test(text) ? text : null;
+};
+
+export function pendingAsks(view) {
+  const { plan } = view;
+  const asks = [];
+  for (const c of plan.scenarios) {
+    if (c.rung && c.rung.toLowerCase() !== 'refazer') asks.push({ id: c.id, verb: 'Revisar', action: 'Pedir ajuste', anchor: `ask-${c.id}`, text: `Não se desfaz com revert (degrau: ${c.rung}). ${c.text}`, tag: 'Degrau' });
+    if (c.status === 'bloqueado') asks.push({ id: c.id, verb: 'Destravar', action: 'Decidir', anchor: `ask-${c.id}-b`, text: `Bloqueado na implementação. ${c.evidence || c.text}`, tag: 'Bloqueio' });
+  }
+  bulletsOf(plan.text.assumptions).forEach((text, i) => asks.push({ id: `suposição ${i + 1}`, verb: 'Corrigir', action: 'Corrigir', anchor: `S${i + 1}`, text, tag: 'Suposição sem prova' }));
+  for (const d of plan.defaults.items) asks.push({ id: `padrão ${d.n}`, verb: 'Vetar', action: 'Vetar', anchor: `P${d.n}`, text: d.text, tag: `Padrão ${d.n}` });
+  return asks;
+}
+
+function askRow(a, link) {
+  return `<li id="${esc(a.anchor)}" data-ask="${esc(a.id)}" data-verb="${esc(a.verb)}"><div><p>${inline(a.text, link)}</p><span class="tag">${esc(a.tag)}</span></div><button type="button" class="toggle" aria-pressed="false">${esc(a.action)}</button></li>`;
+}
+
+function segmented(title, entries, filterable = true) {
+  const used = entries.filter((e) => e.n > 0);
+  if (!used.length) return '';
+  const total = used.reduce((sum, e) => sum + e.n, 0);
+  const attrs = (e) => (filterable ? `data-filter="${esc(e.key)}" data-jump` : 'disabled');
+  return `<div class="chart"><h3>${esc(title)}</h3><div class="seg" role="img" aria-label="${esc(used.map((e) => `${e.label}: ${e.n}`).join(', '))}">${used.map((e) => `<button type="button" ${attrs(e)} style="--n:${e.n};--c:var(--s${e.slot})" title="${esc(e.label)}: ${e.n} de ${total}" aria-label="${esc(e.label)}: ${e.n}"></button>`).join('')}</div><ul class="legend">${used.map((e) => `<li><i style="--c:var(--s${e.slot})"></i>${esc(e.label)} ${e.n}</li>`).join('')}</ul></div>`;
+}
+
+function riskBars(scenarios) {
+  const rows = RISK_KINDS.map((r) => ({ r, n: scenarios.filter((c) => c.risk?.toLowerCase() === r).length })).filter((x) => x.n);
+  if (!rows.length) return '';
+  const max = Math.max(...rows.map((x) => x.n));
+  return `<div class="chart"><h3>Risco que os cenários protegem</h3><ul class="bars">${rows.map((x) => `<li><button type="button" data-filter="${esc(x.r)}" data-jump title="Ver cenários de ${esc(x.r)}"><span>${esc(x.r)}</span><span class="track"><span class="fill" style="--share:${x.n / max}"></span></span><span>${x.n}</span></button></li>`).join('')}</ul></div>`;
+}
+
+function panorama(view, asks, link) {
+  const { plan } = view;
+  const { outcome, problem } = splitProblem(plan.text.problem);
+  const rungs = plan.scenarios.filter((c) => c.rung && c.rung.toLowerCase() !== 'refazer').length;
+  const proofs = PROOF_KINDS.map((k, i) => ({ key: k, label: k, slot: i + 1, n: plan.scenarios.filter((c) => c.proof?.toLowerCase() === k).length }));
+  const reuse = REUSE_VERDICTS.map((v, i) => ({ key: v, label: v.toLowerCase(), slot: i + 1, n: plan.reuse.filter((r) => r.verdict === v).length }));
+  const num = (href, n, label, alert = false) => `<li${alert ? ' class="alert"' : ''}><a href="${href}"><b>${n}</b>${esc(label)}</a></li>`;
+  return `<section id="panorama">
+${outcome ? `<p class="outcome">${inline(outcome, link)}</p>` : ''}
+<ul class="numbers">
+${num('#cenarios', plan.scenarios.length, plan.scenarios.length === 1 ? 'cenário define o pronto' : 'cenários definem o pronto')}
+${num('#decisoes', plan.adrs.length, plan.adrs.length === 1 ? 'decisão registrada' : 'decisões registradas')}
+${num('#decidir', asks.length, asks.length === 1 ? 'ponto para você olhar' : 'pontos para você olhar')}
+${rungs ? num('#decidir', rungs, 'sem volta por revert', true) : ''}
+</ul>
+${problem ? `<details class="fold" open><summary>O problema hoje</summary><div class="prose">${blocks(problem, link)}</div></details>` : ''}
+${segmented('Como cada cenário será provado', proofs)}
+${riskBars(plan.scenarios)}
+${segmented('Reaproveitar ou criar', reuse, false)}
+</section>`;
+}
+
+function gateSign(view) {
+  const g = view.gate;
+  if (g?.pause && g.resolver !== 'session') {
+    return `<div class="sign"><h3>O ${esc(g.label.toLowerCase())} espera sua decisão</h3><p>${inline(g.reason ?? 'Leia os pontos abaixo e responda no terminal.', (s) => s)}</p></div>`;
+  }
+  const approved = Object.values(view.gates).filter((x) => x === true || x?.approved === true).length;
+  return `<div class="sign clear"><h3>${approved ? 'Nenhuma decisão parada' : 'Gate ainda não chamado'}</h3><p>Você pode vetar qualquer padrão abaixo a qualquer momento.</p></div>`;
+}
+
+function decide(view, asks, link) {
+  const conflicts = conflictsOf(view.plan);
+  return `<section id="decidir"><h2>O que precisa de você</h2><p class="sub">Marque o que quer mudar. O que ficar sem marca está aceito. A resposta pronta aparece no rodapé para colar no terminal.</p>
+${gateSign(view)}
+${asks.length ? `<ul class="asks">${asks.map((a) => askRow(a, link)).join('')}</ul>` : '<p class="empty">Nenhum ponto em aberto neste plano.</p>'}
+${conflicts ? `<h3>Conflitos com decisões anteriores</h3><div class="prose">${blocks(conflicts, link)}</div>` : ''}
+${view.critique ? `<details class="fold"><summary>Ler a crítica independente do plano</summary><div class="prose">${blocks(view.critique, link)}</div></details>` : ''}
+</section>`;
+}
+
+function scenarioItem(c, cites, link) {
+  const state = c.proved === 'PROVADO' ? 'provado' : c.proved === 'FALHA' ? 'falha' : c.status;
+  const label = c.proved ?? STATUS_LABEL[c.status];
+  const tone = c.proved === 'PROVADO' || c.status === 'feito' ? 'ok' : c.proved === 'FALHA' || c.status === 'bloqueado' ? 'bad' : '';
+  const tags = [c.proof, c.risk, c.status, c.rung].filter(Boolean).map((t) => String(t).toLowerCase());
+  const rung = c.rung && c.rung.toLowerCase() !== 'refazer' ? `<span class="${RUNG_TONE[c.rung.toLowerCase()] ?? ''}">Degrau: ${esc(c.rung)}</span>` : '';
+  const adrs = cites.length ? `<span>${cites.map((id) => `<a href="#${id}" data-ref="${id}">${id}</a>`).join(', ')}</span>` : '';
+  const evidence = c.proof_note || c.evidence;
+  return `<li id="${esc(c.id)}" data-state="${state}" data-tags="${esc(tags.join(' '))}"><p><span class="id">${esc(c.id)}</span>${inline(c.text, link)}</p><div class="tags"><span class="${tone}">${esc(label)}</span>${c.proof ? `<span>Prova: ${esc(c.proof)}</span>` : ''}${c.risk ? `<span>Risco: ${esc(c.risk)}</span>` : ''}${rung}${adrs}</div>${evidence ? `<p class="evidence">${inline(evidence, link)}</p>` : ''}</li>`;
+}
+
+function scenariosSection(view, citesOf, link) {
+  const { scenarios } = view.plan;
+  const keys = (list) => [...new Set(list.filter(Boolean).map((k) => k.toLowerCase()))];
+  const filters = ['todos', ...keys(scenarios.map((c) => c.proof)), ...keys(scenarios.map((c) => c.risk)), ...keys(scenarios.map((c) => c.status))];
+  return `<section id="cenarios"><h2>O que vai estar pronto</h2><p class="sub">Cada ponto da linha é um comportamento que o verificador executa antes da entrega.</p>
+<div class="filters" role="group" aria-label="Filtrar cenários">${filters.map((f, i) => `<button type="button" data-filter="${esc(f)}" aria-pressed="${i === 0}">${esc(f)}</button>`).join('')}</div>
+<ol class="line">${scenarios.map((c) => scenarioItem(c, citesOf(c.id), link)).join('')}</ol></section>`;
+}
+
+const adrBody = (a) => a.body.replace(/^\s*\*\*Alcance:\*\*.*$/im, '').trim();
+
+function matrix(view, cited) {
+  const adrs = view.plan.adrs.filter((a) => cited.get(a.id).length);
+  if (!adrs.length) return '';
+  const ids = view.plan.scenarios.map((c) => c.id);
+  return `<h3>Qual decisão sustenta qual cenário</h3><div class="scroll-x"><table class="matrix"><thead><tr><th></th>${ids.map((id) => `<th><a href="#${id}" data-ref="${id}">${id}</a></th>`).join('')}</tr></thead><tbody>${adrs.map((a) => `<tr><th><a href="#${a.id}" data-ref="${a.id}">${a.id}</a></th>${ids.map((id) => `<td>${cited.get(a.id).includes(id) ? `<a href="#${id}" aria-label="${a.id} sustenta ${id}"></a>` : ''}</td>`).join('')}</tr>`).join('')}</tbody></table></div>`;
+}
+
+function decisions(view, cited, link) {
+  const { adrs } = view.plan;
+  return `<section id="decisoes"><h2>Decisões</h2><p class="sub">Abra uma decisão para ver o motivo. Os links levam aos cenários que dependem dela.</p>
+${adrs.length ? adrs.map((a) => `<details class="adr" id="${esc(a.id)}"><summary>${esc(a.id)}: ${esc(a.title)}${a.scope ? `<small>vale para ${a.scope === 'projeto' ? 'o projeto' : 'esta feature'}</small>` : ''}</summary><div class="prose">${blocks(adrBody(a), link)}</div></details>`).join('') : '<p class="empty">Este plano não registrou decisões de arquitetura.</p>'}
+${matrix(view, cited)}</section>`;
+}
+
+function howItWorks(view, link) {
+  const { plan } = view;
+  const flow = plan.flow?.transitions ?? [];
+  const states = plan.states?.transitions ?? [];
+  const reuse = plan.reuse.length ? `<h3>O que aproveita e o que nasce</h3><div class="scroll-x"><table><thead><tr><th>Conceito</th><th>Veredito</th><th>Onde</th></tr></thead><tbody>${plan.reuse.map((r) => `<tr><td>${inline(r.concept, link)}</td><td>${esc(r.verdict.toLowerCase())}</td><td>${inline(r.target, link)}${r.why ? `<br><small>${inline(r.why, link)}</small>` : ''}</td></tr>`).join('')}</tbody></table></div>` : '';
+  const out = plan.text.outOfScope;
+  return `<section id="como"><h2>Como funciona</h2>
+${flow.length ? `<h3>Fluxo</h3><div class="diagram">${stateMachineSvg(flow, 'Fluxo', 'flow')}</div>` : ''}
+${states.length ? `<h3>Estados</h3><div class="diagram">${stateMachineSvg(states, 'Máquina de estados', 'states')}</div>` : ''}
+${plan.text.architecture ? `<h3>Arquitetura</h3><div class="prose">${blocks(plan.text.architecture, link)}</div>` : ''}
+${reuse}
+${out ? `<h3>Fora de escopo</h3><div class="prose">${blocks(out, link)}</div>` : ''}
+${plan.text.contract ? `<details class="fold"><summary>Contrato de implementação</summary><div class="prose">${blocks(plan.text.contract, link)}</div></details>` : ''}
+${plan.errata ? `<h3>Errata</h3><div class="prose">${blocks(plan.errata, link)}</div>` : ''}
+</section>`;
+}
+
+const REVIEW_LABEL = { verifier: 'Verificador', reviewer: 'Revisor', security: 'Segurança' };
+
+function execution(view, link) {
+  const { progress, verification, reviews, design, changes } = view;
+  const started = progress?.done > 0 || progress?.blocked > 0 || verification || Object.values(reviews).some((r) => r.status !== 'missing');
+  if (!started && !design.length) return '';
+  const share = progress?.total ? progress.done / progress.total : 0;
+  const ring = progress?.total ? `<div class="gauge"><svg class="ring" viewBox="0 0 112 112" role="img" aria-label="${progress.done} de ${progress.total} cenários feitos"><circle class="base" cx="56" cy="56" r="45"/><circle class="part" cx="56" cy="56" r="45" style="--share:${share}"/></svg><div><b>${progress.done} de ${progress.total}</b>cenários feitos${progress.blocked ? `, ${progress.blocked} bloqueado${progress.blocked > 1 ? 's' : ''}` : ''}</div></div>` : '';
+  const stat = changes?.stat ? `<div class="gauge"><div><b>${changes.stat.files}</b>arquivos alterados, +${changes.stat.added} e −${changes.stat.removed} linhas</div></div>` : '';
+  const rows = [];
+  if (verification) {
+    const ok = verification.status === 'pass';
+    rows.push(`<li>Verify: <span class="${ok ? 'ok' : 'bad'}">${ok ? 'passou' : 'falhou'}</span>${verification.sha ? ` em <code>${esc(String(verification.sha).slice(0, 8))}</code>` : ''}</li>`);
+  }
+  for (const [role, r] of Object.entries(reviews)) {
+    if (r.status === 'missing') continue;
+    const tone = r.verdict === 'SHIP' ? 'ok' : r.verdict === 'FIX' ? 'bad' : 'wait';
+    rows.push(`<li>${REVIEW_LABEL[role]}: <span class="${tone}">${esc(r.verdict ?? 'em andamento')}</span>${r.blockers?.length ? `, ${r.blockers.length} bloqueador${r.blockers.length > 1 ? 'es' : ''}` : ''}</li>`);
+  }
+  const blockers = Object.values(reviews).flatMap((r) => r.blockers ?? []);
+  return `<section id="execucao"><h2>Execução e provas</h2>
+<div class="gauges">${ring}${stat}${rows.length ? `<ul class="status-list">${rows.join('')}</ul>` : ''}</div>
+${blockers.length ? `<h3>Bloqueadores da revisão</h3><div class="prose"><ul>${blockers.map((b) => `<li>${inline(`${b.id}: ${b.evidence || b.where}`, link)}</li>`).join('')}</ul></div>` : ''}
+${design.length ? `<h3>Telas</h3><ul class="shots">${design.map((d) => `<li><a href="${esc(d.href)}">${d.shot ? `<img src="${esc(d.shot)}" alt="" loading="lazy">` : ''}${esc(d.name)}${d.kind === 'opcoes' ? ' (opções)' : ''}</a></li>`).join('')}</ul>` : ''}
+</section>`;
+}
+
+function recapSection(view) {
+  if (!view.recap) return '';
+  return `<section id="recap"><h2>A história da feature</h2><p class="sub">Toque para ouvir o que foi feito, cena por cena.</p><iframe class="recap" title="Recap narrado" loading="lazy" srcdoc="${esc(renderRecapHtml(view.recap))}"></iframe></section>`;
+}
+
+function refsOf(plan) {
+  const refs = {};
+  for (const c of plan.scenarios) refs[c.id] = c.text.replace(/`/g, '');
+  for (const a of plan.adrs) refs[a.id] = a.title;
+  for (const d of plan.defaults.items) refs[`P${d.n}`] = d.text.replace(/`/g, '');
+  return JSON.stringify(refs).replace(/</g, '\\u003c');
+}
+
+export function renderFeatureHtml(view) {
+  const { plan } = view;
+  const link = linkifier(plan);
+  const asks = pendingAsks(view);
+  const ids = plan.scenarios.map((c) => c.id);
+  const cited = new Map(plan.adrs.map((a) => [a.id, ids.filter((id) => new RegExp(`\\b${id}\\b`).test(a.body))]));
+  const citesOf = (id) => plan.adrs.filter((a) => cited.get(a.id).includes(id)).map((a) => a.id);
+  const done = view.stations.filter((s) => s.done).length;
+  const exec = execution(view, link);
+  const recap = recapSection(view);
+  const nav = [
+    ['panorama', 'Panorama'], ['decidir', 'Decidir', asks.length], ['cenarios', 'Cenários'], ['decisoes', 'Decisões'], ['como', 'Como funciona'],
+    ...(exec ? [['execucao', 'Execução']] : []), ...(recap ? [['recap', 'Recap']] : []),
+  ];
+  const key = `${view.feature}:${(view.planHash ?? '').slice(0, 12)}`;
+  return `<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(view.feature)}</title>
+<style>
+${TOKENS_CSS}${PAGE_CSS}</style>
+</head>
+<body data-key="${esc(key)}" data-feature="${esc(view.feature)}">
+<header class="top">
+<p class="kind">${esc(WORK_LABEL[view.workType] ?? 'Feature')}</p>
+<h1>${esc(view.feature)}</h1>
+${view.description ? `<p class="ask">${esc(view.description)}</p>` : ''}
+<ol class="route" style="--done:${Math.min(1, done / Math.max(1, view.stations.length - 1)).toFixed(3)}">${view.stations.map((s) => `<li class="stop ${s.state}"${s.state === 'now' ? ' aria-current="step"' : ''}>${esc(s.label)}${s.note ? `<small>${esc(s.note)}</small>` : ''}</li>`).join('')}</ol>
+</header>
+<div class="shell">
+<nav class="side" aria-label="Seções">${nav.map(([id, label, badge]) => `<a href="#${id}">${esc(label)}${badge ? `<b>${badge}</b>` : ''}</a>`).join('')}</nav>
+<main>
+${panorama(view, asks, link)}
+${decide(view, asks, link)}
+${scenariosSection(view, citesOf, link)}
+${decisions(view, cited, link)}
+${howItWorks(view, link)}
+${exec}
+${recap}
+<p class="source">Gerada pelo morph-spec a partir de plan.md${view.planHash ? ` (${esc(view.planHash.slice(0, 12))})` : ''} e dos relatórios da feature. Atualize a aba para ver o estado mais recente. Para mudar o plano, edite o plan.md.</p>
+</main>
+</div>
+<div id="peek" role="tooltip"></div>
+<div id="tray" role="region" aria-label="Sua resposta"><span class="count"></span><button type="button" class="copy">Copiar resposta</button><button type="button" class="clear">Limpar</button></div>
+<script type="application/json" id="refs">${refsOf(plan)}</script>
+<script>
+${CLIENT_JS}</script>
+</body>
+</html>
+`;
+}