@daniellins/power-claude 0.16.3

package/scripts/veto-checks/render-gate.cjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * render-gate.cjs — veto BLESSED (forma command_check, ADR-011). RENDERIZA o HTML do
+ * artefato em headless Chrome e detecta OVERFLOW de layout (conteúdo que estoura a
+ * viewport ou uma caixa) — o defeito de campo (a): 2 interfaces quebradas na R5 passaram
+ * por todo veto textual; "o braço que fazia render+inspeção peça a peça não quebrou".
+ *
+ * ZERO-DEP npm (ADR-011 Decisão 3): usa o binário de sistema headless Chrome via
+ * execFileSync (nunca uma lib npm). DEPENDÊNCIA AUSENTE = FAIL-LOUD (exit 3, mensagem
+ * acionável), NUNCA skip-silencioso — um veto que pula quando a ferramenta falta é
+ * green-fake (o artefato embarca não-verificado com o run parecendo limpo).
+ *
+ * MECANISMO: injeta (numa CÓPIA temporária, sem mutar o artefato) um <script> de medição
+ * que marca `document.documentElement[data-render-gate] = OVERFLOW|OK` conforme
+ * scrollWidth/scrollHeight excedam a viewport ou uma caixa sem overflow rolável; roda
+ * `chrome --headless --dump-dom` e lê o marcador do DOM renderizado.
+ *
+ * LIMITES HONESTOS (documentados — ADR-011 Decisão 3, render-gate portável só onde há
+ * headless browser): detecta OVERFLOW/CORTE por métrica de scroll; NÃO detecta colisão
+ * visual por z-index/sobreposição de cor, contraste, nem estética. Viewport é parâmetro
+ * (--width/--height; default 1080×1350, retrato Instagram). Onde não há Chrome, BLOQUEIA
+ * com mensagem (nunca falso-verde). Direção FAIL-CLOSED por design (na dúvida, bloqueia).
+ * CONTEÚDO DEVE SER PINADO À MOLDURA: o artefato precisa fixar `html,body{width:W;height:H}`
+ * casando a viewport (--width/--height); um elemento de largura EXATAMENTE igual à viewport
+ * num body NÃO-pinado toca a borda e é reportado como overflow de borda (falso-positivo de
+ * borda, fail-closed) — os slides de pod já são autorados pinados à moldura, então não ocorre
+ * no uso pretendido (MINOR-1 do gate SF7.2).
+ *
+ * Uso: node scripts/veto-checks/render-gate.cjs <artefato.html> [--width N] [--height N]
+ * Exit 0 = sem overflow; exit 1 = overflow detectado (bloqueia); exit 2 = uso;
+ * exit 3 = Chrome ausente (fail-loud) ou falha ao renderizar.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const CHROME_CANDIDATES = [
+  'google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser', 'chrome',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+];
+
+/** Testa se um candidato é um Chrome utilizável. */
+function usable(cand) {
+  try {
+    if (cand.includes('/')) return fs.existsSync(cand) ? cand : null; // caminho absoluto
+    execFileSync(cand, ['--version'], { stdio: 'ignore', timeout: 8000 }); // nome no PATH
+    return cand;
+  } catch { return null; }
+}
+
+/**
+ * Resolve um binário de Chrome utilizável, ou null (→ fail-loud no chamador).
+ * Se CHROME_BIN está SETADO, é honrado ESTRITAMENTE: inválido → null (fail-loud), SEM
+ * fallback silencioso para outro navegador (um veto que troca de ferramenta por baixo dos
+ * panos seria green-fake). Sem CHROME_BIN, varre os candidatos conhecidos.
+ */
+function probeChrome() {
+  if (process.env.CHROME_BIN) return usable(process.env.CHROME_BIN);
+  for (const cand of CHROME_CANDIDATES) {
+    const u = usable(cand);
+    if (u) return u;
+  }
+  return null;
+}
+
+// Medição VIEWPORT-INDEPENDENTE: compara cada elemento (body + descendentes) com a PRÓPRIA
+// caixa (scrollWidth/Height vs clientWidth/Height). NÃO usa documentElement.clientHeight, que
+// em headless retorna a viewport interna (menor que --window-size por causa do cromo da
+// janela) e geraria falso-positivo. Um filho que estoura a caixa de overflow:hidden do pai
+// aparece como scroll no PAI — é o corte real que queremos pegar.
+const MEASURE_SCRIPT = `
+<script>(function(){
+  function overflowing(){
+    // TOL=8px: ignora ruído de métricas de texto (line-height apertado faz scrollHeight
+    // exceder clientHeight por ~1-4px sem corte real). Os defeitos de campo (interface
+    // quebrada, caixa estourando a moldura) são GROSSEIROS (centenas de px). LIMITE HONESTO:
+    // este gate pega corte GROSSEIRO, não descender clipado por sub-pixel.
+    var TOL=8, root=document.body;
+    if (!root) return false;
+    var els=[root].concat([].slice.call(root.querySelectorAll('*')));
+    for (var i=0;i<els.length;i++){
+      var e=els[i], cs=getComputedStyle(e);
+      if (cs.display==='none' || cs.visibility==='hidden') continue;
+      var scrollable=/auto|scroll/.test((cs.overflow||'')+(cs.overflowX||'')+(cs.overflowY||''));
+      if (!scrollable && (e.scrollWidth>e.clientWidth+TOL || e.scrollHeight>e.clientHeight+TOL)) return true;
+    }
+    return false;
+  }
+  try { document.documentElement.setAttribute('data-render-gate', overflowing()?'OVERFLOW':'OK'); }
+  catch(err){ document.documentElement.setAttribute('data-render-gate','ERROR'); }
+})();</script>`;
+
+/** Decide o veredito a partir do DOM renderizado (dump-dom). Pura, testável. */
+function decideFromDom(domHtml) {
+  const m = domHtml.match(/data-render-gate="([^"]*)"/);
+  if (!m) return { ok: false, verdict: 'no-marker', reason: 'marcador de medição ausente no DOM renderizado (script não executou?)' };
+  if (m[1] === 'OK') return { ok: true, verdict: 'OK' };
+  if (m[1] === 'OVERFLOW') return { ok: false, verdict: 'OVERFLOW', reason: 'conteúdo estoura a viewport ou uma caixa não-rolável (overflow/corte)' };
+  return { ok: false, verdict: m[1], reason: `medição retornou "${m[1]}"` };
+}
+
+function renderDom(chromeBin, htmlPath, width, height) {
+  return execFileSync(chromeBin, [
+    '--headless=new', '--disable-gpu', '--no-sandbox', '--hide-scrollbars',
+    `--window-size=${width},${height}`, '--virtual-time-budget=4000',
+    '--dump-dom', `file://${htmlPath}`,
+  ], { encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+function parseArgs(argv) {
+  const o = { width: 1080, height: 1350 };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--width') o.width = Number.parseInt(argv[++i], 10);
+    else if (argv[i] === '--height') o.height = Number.parseInt(argv[++i], 10);
+  }
+  return o;
+}
+
+function main() {
+  const artifact = process.argv[2];
+  if (!artifact || !fs.existsSync(artifact)) {
+    console.error(`render-gate: artefato não encontrado: ${artifact}`);
+    process.exit(2);
+  }
+  const { width, height } = parseArgs(process.argv.slice(3));
+
+  const chromeBin = probeChrome();
+  if (!chromeBin) {
+    console.error('render-gate BLOQUEOU (fail-loud): headless Chrome não encontrado. ' +
+      'Defina CHROME_BIN ou instale google-chrome/chromium. Não é possível verificar a ' +
+      'renderização — BLOQUEANDO em vez de pular (skip = green-fake).');
+    process.exit(3);
+  }
+
+  // Cópia temporária com o script de medição anexado (não muta o artefato; scripts não
+  // afetam o layout, então a medição reflete o render real).
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-render-gate-'));
+  const tmpHtml = path.join(tmpDir, 'measured.html');
+  let dom;
+  try {
+    fs.writeFileSync(tmpHtml, fs.readFileSync(artifact, 'utf8') + MEASURE_SCRIPT, 'utf8');
+    dom = renderDom(chromeBin, tmpHtml, width, height);
+  } catch (e) {
+    console.error(`render-gate BLOQUEOU (fail-loud): falha ao renderizar em ${chromeBin}: ${e.message}`);
+    process.exit(3);
+  } finally {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+
+  const r = decideFromDom(dom);
+  if (r.ok) {
+    console.log(`render-gate OK: sem overflow em ${width}×${height} (${chromeBin.split('/').pop()}).`);
+    process.exit(0);
+  }
+  console.error(`render-gate BLOQUEOU: ${r.reason} (veredito ${r.verdict}).`);
+  process.exit(r.verdict === 'no-marker' ? 3 : 1);
+}
+
+if (require.main === module) main();
+
+module.exports = { probeChrome, decideFromDom, parseArgs, CHROME_CANDIDATES };

package/scripts/veto-checks/render-png.cjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * render-png.cjs — veto BLESSED (forma command_check, ADR-011) que PRODUZ o entregável de
+ * publicacao e o VERIFICA por maquina, ANTES do checkpoint humano da etapa.
+ *
+ * Story SF11.11 / ADR-025 (`DF-SF11.11-1`..`-4`). O problema que ele resolve: o pod entregava
+ * HTML e o dono publicava PNG renderizado a mao, fora do caminho governado — logo ele aprovava
+ * uma coisa e publicava outra. Como `verifyStep` (onde os vetos rodam) e chamado por
+ * `advance()` ANTES de `isBlocking`/`awaiting_approval`, declarar a renderizacao aqui faz os
+ * PNGs existirem, medidos e aprovados por maquina, no instante em que o humano e convocado —
+ * em QUALQUER modo (`verifyStep`/`evalVeto` nao leem `mode`), sem uma linha de motor.
+ *
+ * GENERICO POR CONTRATO (ADR-025 `DF-SF11.11-1`): nenhum nome de pod, de peca ou de dominio
+ * mora aqui. Tudo que e especifico do pod vem por argumento LITERAL do `wf` (ADR-011 proibe
+ * interpolacao): quantos arquivos, que dimensao, de onde e para onde.
+ *
+ * ZERO-DEP npm (ADR-011 Decisao 3): headless Chrome de sistema via execFileSync. DEPENDENCIA
+ * AUSENTE = FAIL-LOUD (exit 3), NUNCA skip-silencioso. NAO EXISTE escape hatch: nenhuma flag,
+ * nenhuma env var e nenhum ramo de codigo faz este script sair 0 sem ter renderizado e medido
+ * as `--expect` pecas (decisao do dono, 2026-08-03: uma rodada sem Chrome NAO FECHA, nem
+ * entregando HTML — a alternativa reintroduziria a degradacao silenciosa que a SF11.4b
+ * eliminou). `probeChrome` e REUSADO de `render-gate.cjs` (mesma recusa de fallback silencioso
+ * quando CHROME_BIN esta setado e invalido) — este script nao reimplementa a sonda.
+ *
+ * O QUE ELE PROVA: que existem EXATAMENTE `--expect` arquivos `.html` no dir declarado, que o
+ * Chrome conseguiu renderizar cada um, e que cada PNG gerado tem `--width`x`--height` EXATOS,
+ * lidos do IHDR do proprio arquivo (`readUInt32BE(16)`/`readUInt32BE(20)`), comparados com
+ * `===`. Igualdade de inteiros: sem tolerancia, sem `+/-`, sem limiar calibravel (ADR-018
+ * `DF4-5` — o oraculo e o formato de publicacao declarado no `wf`, nao uma amostragem).
+ *
+ * O QUE ELE NAO PROVA (dito antes que alguem descubra): que a peca esta bonita, que o texto
+ * coube, que o contraste presta ou que o encaixe copy x canvas ficou bom. Isso e JULGAMENTO
+ * HUMANO no checkpoint (fronteira ADR-002), agora com a evidencia certa na mao. Overflow de
+ * layout tem script proprio (`render-gate.cjs`) e NAO entra aqui (ADR-025 `DF-SF11.11-13`,
+ * divida 1).
+ *
+ * LIMITE HONESTO DA CHECAGEM DE DIMENSAO (MEDIDO na implementacao da SF11.11, corrigindo o que
+ * o ADR-025 supunha): a dimensao do PNG e ditada pelo `--window-size` do Chrome, NAO pelo CSS
+ * do documento. Medido: um HTML pinado a 1080x2000 e outro a 900x700, renderizados com
+ * `--window-size=1080,1350`, produzem os DOIS um PNG 1080x1350. Logo esta checagem NAO e um
+ * veto sobre o CONTEUDO do HTML — e uma POS-CONDICAO SOBRE O RENDERIZADOR: ela pega o
+ * renderizador que desobedece a moldura (escala de tela dobrada/HiDPI, PNG truncado ou
+ * corrompido, binario que sai 0 escrevendo outra coisa — a classe de green-fake que o
+ * chromium-snap produziu na VPS, achado 1 do provisionamento). Isso continua valendo a pena e
+ * continua sendo igualdade binaria sem limiar; o que NAO se pode afirmar e que "HTML com altura
+ * errada bloqueia aqui". Quem pega defeito de encaixe no canvas e o olho humano no checkpoint,
+ * e (divida 1) o `render-gate.cjs`.
+ *
+ * Uso (o motor passa o artefato da etapa como argv[2] — invariante runDir/artifacts/<step>.md):
+ *   node scripts/veto-checks/render-png.cjs <artefato.md> \
+ *     --html-dir <rel> --out-dir <rel> --width N --height N --expect N
+ *
+ * Exit 0 = `--expect` PNGs gerados, todos na dimensao exata.
+ * Exit 1 = VETO DE CONTEUDO: contagem de HTML != --expect, ou dimensao medida != pedida.
+ * Exit 2 = wiring/uso invalido: artefato inexistente, argumento ausente/invalido, dir
+ *          resolvendo FORA do runDir, dir de HTML inexistente.
+ * Exit 3 = FAIL-LOUD de dependencia: Chrome ausente/invalido, ou falha ao renderizar/escrever.
+ * Qualquer exit != 0 vira `no()` no `evalVeto` => etapa BLOQUEADA => o checkpoint nao acontece.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+// Reuso, nao extensao (Dev Notes da SF11.11): `render-gate.cjs` recebe UM html e mede overflow;
+// este recebe o artefato da etapa e produz o entregavel. O que e comum e a SONDA de Chrome, e
+// ela existe uma unica vez — duplicar seria arriscar duas doutrinas de fail-loud divergindo.
+const { probeChrome } = require('./render-gate.cjs');
+
+const BLOCK_BEGIN = '<!-- pc:entregavel-png:inicio -->';
+const BLOCK_END = '<!-- pc:entregavel-png:fim -->';
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/** Erro de USO/WIRING (exit 2). Separado do fail-loud de dependencia (exit 3) por classe. */
+class UsageError extends Error {}
+
+// ---------------------------------------------------------------------------
+// Funcoes puras (testaveis sem Chrome e sem disco).
+// ---------------------------------------------------------------------------
+
+/**
+ * Le a dimensao do IHDR de um buffer PNG. NAO usa heuristica: exige a assinatura PNG de 8 bytes
+ * e le os dois uint32 big-endian do IHDR. Buffer que nao e PNG => { ok:false } (nunca um palpite).
+ */
+function readPngDimensions(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 24) {
+    return { ok: false, reason: 'arquivo com menos de 24 bytes — nao ha IHDR para ler' };
+  }
+  if (!buf.subarray(0, 8).equals(PNG_SIGNATURE)) {
+    return { ok: false, reason: 'assinatura PNG ausente (os 8 primeiros bytes nao sao 89 50 4E 47 0D 0A 1A 0A)' };
+  }
+  if (buf.subarray(12, 16).toString('latin1') !== 'IHDR') {
+    return { ok: false, reason: 'primeiro chunk nao e IHDR — PNG malformado' };
+  }
+  return { ok: true, width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+
+/**
+ * Veredito de dimensao: IGUALDADE DE INTEIROS, os dois lados. Nenhuma tolerancia, nenhum
+ * `Math.abs`, nenhum `>=`/`<=` — 1 pixel de diferenca BLOQUEIA (ADR-018 `DF4-5`).
+ */
+function dimensionMatches(measured, width, height) {
+  return measured.width === width && measured.height === height;
+}
+
+/**
+ * Veredito de cardinalidade: igualdade EXATA contra o conjunto declarado no `wf`. Nao e limiar
+ * (`--min`): pacote incompleto nao e pacote, e pacote com peca a mais tambem nao.
+ */
+function countMatches(found, expect) {
+  return found === expect;
+}
+
+/** Parse dos args LITERAIS. Argumento ausente/invalido => UsageError (exit 2), nunca default. */
+function parseArgs(argv) {
+  const o = { htmlDir: null, outDir: null, width: null, height: null, expect: null };
+  const int = (raw, flag) => {
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isInteger(n) || n <= 0 || String(n) !== String(raw)) {
+      throw new UsageError(`${flag} exige um inteiro positivo (recebido: ${JSON.stringify(raw)})`);
+    }
+    return n;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    switch (argv[i]) {
+      case '--html-dir': o.htmlDir = argv[++i]; break;
+      case '--out-dir': o.outDir = argv[++i]; break;
+      case '--width': o.width = int(argv[++i], '--width'); break;
+      case '--height': o.height = int(argv[++i], '--height'); break;
+      case '--expect': o.expect = int(argv[++i], '--expect'); break;
+      default:
+        throw new UsageError(`argumento desconhecido: ${JSON.stringify(argv[i])}`);
+    }
+  }
+  for (const [k, flag] of [['htmlDir', '--html-dir'], ['outDir', '--out-dir'], ['width', '--width'], ['height', '--height'], ['expect', '--expect']]) {
+    if (o[k] === null || o[k] === undefined) throw new UsageError(`argumento obrigatorio ausente: ${flag}`);
+  }
+  return o;
+}
+
+/**
+ * Resolve um dir de arg LITERAL relativo ao dir do artefato, exigindo contencao no runDir.
+ * Mesmo molde de `phash-gate.cjs:474-482` — um `wf` nao pode fazer este script ler/escrever
+ * fora do run que o invocou.
+ */
+function resolveWithin(runDir, artDir, rel, label) {
+  const abs = path.resolve(artDir, rel);
+  const root = path.resolve(runDir);
+  if (abs !== root && !abs.startsWith(root + path.sep)) {
+    throw new UsageError(`${label} "${rel}" resolve FORA do runDir (${abs}) — recusado`);
+  }
+  return abs;
+}
+
+/** Lista os `.html` do dir (nao-recursivo), em ordem estavel por nome. */
+function listHtml(dir) {
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && /\.html?$/i.test(e.name))
+    .map((e) => e.name)
+    .sort((a, b) => a.localeCompare(b, 'en'));
+}
+
+/** Bloco delimitado, humano-legivel e grep-avel, gravado no artefato da etapa. */
+function renderBlock({ rows, width, height, outRel, chromeLabel, failures }) {
+  // ATENCAO: o bloco e escrito DENTRO do artefato da etapa, que continua sendo lido por outros
+  // vetos na mesma verificacao e nas retentativas. Nada aqui pode introduzir um caractere que
+  // outro veto do mesmo `wf` bane (ex.: travessao em/en-dash sob `lexical-check`), nem um
+  // heading que colida com a conformidade de template. Ha teste para isso.
+  const L = [BLOCK_BEGIN, '', '## Entregavel de publicacao (PNG): verificado por maquina', ''];
+  L.push(`Gerado e medido por \`render-png.cjs\` ANTES do checkpoint desta etapa (ADR-025). Dimensao exigida: ${width}x${height};`);
+  L.push(`destino: \`${outRel}\`; renderizador: ${chromeLabel}.`);
+  L.push('');
+  L.push('| Peca (PNG) | Dimensao medida (IHDR) | sha256 | Veredito |');
+  L.push('|---|---|---|---|');
+  for (const r of rows) {
+    const dim = r.measured.ok ? `${r.measured.width}x${r.measured.height}` : `ILEGIVEL (${r.measured.reason})`;
+    L.push(`| ${r.png} | ${dim} | ${r.sha256 || '-'} | ${r.verdict} |`);
+  }
+  L.push('');
+  if (failures.length > 0) {
+    L.push('### BLOQUEIO');
+    L.push('');
+    for (const f of failures) L.push(`- ${f}`);
+    L.push('');
+  }
+  L.push('### O que este bloco garante, e o que NAO garante (declarado, nao omitido)');
+  L.push('');
+  L.push(`- GARANTE: existem exatamente as pecas listadas, o Chrome renderizou cada uma, e a dimensao de cada PNG foi lida do IHDR`);
+  L.push('  do proprio arquivo e comparada por IGUALDADE de inteiros com o formato declarado no `wf`. Sem tolerancia, sem limiar.');
+  L.push('- NAO GARANTE: que a peca esteja bonita, que o texto tenha cabido, que o contraste preste ou que o encaixe copy x canvas');
+  L.push('  esteja bom. Isso e JULGAMENTO HUMANO no checkpoint (fronteira ADR-002). Overflow de layout tem script proprio');
+  L.push('  (`render-gate.cjs`) e NAO roda aqui.');
+  L.push('', BLOCK_END);
+  return L.join('\n');
+}
+
+/** Insere/SUBSTITUI o bloco no texto do artefato (idempotente entre retentativas da etapa). */
+function upsertBlock(text, block) {
+  const b = text.indexOf(BLOCK_BEGIN);
+  const e = text.indexOf(BLOCK_END);
+  if (b >= 0 && e > b) return `${text.slice(0, b)}${block}${text.slice(e + BLOCK_END.length)}`;
+  return `${text.replace(/\s*$/, '')}\n\n${block}\n`;
+}
+
+/** Nome do PNG derivado do HTML (mesmo stem, extensao trocada). */
+function pngNameFor(htmlName) {
+  return htmlName.replace(/\.html?$/i, '.png');
+}
+
+// ---------------------------------------------------------------------------
+// Render (unico ponto que toca processo externo).
+// ---------------------------------------------------------------------------
+
+/**
+ * Renderiza UM html em PNG. Argumentos identicos aos medidos no `*assess` da SF11.11, cujo
+ * resultado foi byte-a-byte identico ao render manual de referencia (sha256 bf4e809d...9d01).
+ */
+function renderOne(chromeBin, htmlAbs, pngAbs, width, height, timeoutMs) {
+  execFileSync(chromeBin, [
+    '--headless=new', '--disable-gpu', '--no-sandbox', '--hide-scrollbars',
+    '--force-device-scale-factor=1', `--window-size=${width},${height}`,
+    '--virtual-time-budget=4000', `--screenshot=${pngAbs}`, `file://${htmlAbs}`,
+  ], { encoding: 'utf8', timeout: timeoutMs, stdio: ['ignore', 'ignore', 'pipe'] });
+}
+
+const RENDER_TIMEOUT_MS = 60000;
+
+function main() {
+  const artifact = process.argv[2];
+  if (!artifact || artifact.startsWith('--') || !fs.existsSync(artifact)) {
+    console.error(`render-png: artefato nao encontrado: ${artifact} (uso: render-png.cjs <artefato.md> ` +
+      '--html-dir <rel> --out-dir <rel> --width N --height N --expect N)');
+    process.exit(2);
+  }
+
+  let opts; let htmlAbsDir; let outAbsDir; let runDir;
+  try {
+    opts = parseArgs(process.argv.slice(3));
+    const artDir = path.dirname(path.resolve(artifact));
+    runDir = path.dirname(artDir); // invariante runDir/artifacts/<step>.md
+    htmlAbsDir = resolveWithin(runDir, artDir, opts.htmlDir, '--html-dir');
+    outAbsDir = resolveWithin(runDir, artDir, opts.outDir, '--out-dir');
+    if (!fs.existsSync(htmlAbsDir) || !fs.statSync(htmlAbsDir).isDirectory()) {
+      throw new UsageError(`--html-dir "${opts.htmlDir}" nao existe ou nao e diretorio (${htmlAbsDir})`);
+    }
+  } catch (e) {
+    if (e instanceof UsageError) {
+      console.error(`render-png: ${e.message}`);
+      process.exit(2);
+    }
+    throw e;
+  }
+
+  const { width, height, expect } = opts;
+
+  // ── (1) CARDINALIDADE — igualdade exata, antes de gastar Chrome.
+  let htmlFiles;
+  try {
+    htmlFiles = listHtml(htmlAbsDir);
+  } catch (e) {
+    console.error(`render-png: falha ao listar --html-dir (${htmlAbsDir}): ${e.message}`);
+    process.exit(2);
+  }
+  if (!countMatches(htmlFiles.length, expect)) {
+    console.error(`render-png BLOQUEOU: esperado EXATAMENTE ${expect} arquivo(s) .html em ${path.relative(runDir, htmlAbsDir) || '.'}, ` +
+      `encontrado(s) ${htmlFiles.length}${htmlFiles.length ? ` [${htmlFiles.join(', ')}]` : ''}. ` +
+      'Pacote incompleto (ou com peca a mais) nao e pacote — nada foi renderizado.');
+    process.exit(1);
+  }
+
+  // ── (2) CHROME — fail-loud, sem fallback e sem escape hatch.
+  const chromeBin = probeChrome();
+  if (!chromeBin) {
+    console.error('render-png BLOQUEOU (fail-loud): headless Chrome nao encontrado. Instale google-chrome/chromium ' +
+      'ou defina CHROME_BIN apontando para um binario valido. NAO existe modo degradado: sem render nao ha entregavel ' +
+      'de publicacao, e entregar HTML no lugar seria aprovar um proxy do que se publica (ADR-025 DF-SF11.11-4).');
+    process.exit(3);
+  }
+
+  // ── (3) RENDER + MEDIDA. Falha de render = exit 3 (dependencia/ferramenta); dimensao errada
+  // = exit 1 (veto de conteudo). As classes nao se misturam: a causa fica legivel no run.
+  try {
+    fs.mkdirSync(outAbsDir, { recursive: true });
+  } catch (e) {
+    console.error(`render-png BLOQUEOU (fail-loud): nao foi possivel criar --out-dir (${outAbsDir}): ${e.message}`);
+    process.exit(3);
+  }
+
+  const rows = [];
+  const dimFailures = [];
+  for (const htmlName of htmlFiles) {
+    const htmlAbs = path.join(htmlAbsDir, htmlName);
+    const pngName = pngNameFor(htmlName);
+    const pngAbs = path.join(outAbsDir, pngName);
+    try {
+      fs.rmSync(pngAbs, { force: true }); // nunca medir o PNG da tentativa anterior
+      renderOne(chromeBin, htmlAbs, pngAbs, width, height, RENDER_TIMEOUT_MS);
+    } catch (e) {
+      const err = `${(e.stderr || '').toString().trim().split('\n').pop() || e.message}`;
+      console.error(`render-png BLOQUEOU (fail-loud): falha ao renderizar "${htmlName}" em ${chromeBin}: ${err}`);
+      process.exit(3);
+    }
+    if (!fs.existsSync(pngAbs)) {
+      console.error(`render-png BLOQUEOU (fail-loud): o Chrome saiu sem erro mas NAO escreveu o PNG de "${htmlName}" ` +
+        `(esperado em ${pngAbs}). Sem arquivo nao ha entregavel — bloqueando em vez de seguir.`);
+      process.exit(3);
+    }
+    const buf = fs.readFileSync(pngAbs);
+    const measured = readPngDimensions(buf);
+    if (!measured.ok) {
+      console.error(`render-png BLOQUEOU (fail-loud): "${pngName}" nao e um PNG legivel: ${measured.reason}.`);
+      process.exit(3);
+    }
+    const sha256 = crypto.createHash('sha256').update(buf).digest('hex');
+    const okDim = dimensionMatches(measured, width, height);
+    if (!okDim) {
+      dimFailures.push(`${pngName}: medido ${measured.width}x${measured.height}, exigido ${width}x${height} (origem: ${htmlName})`);
+    }
+    rows.push({ html: htmlName, png: pngName, measured, sha256, verdict: okDim ? 'OK' : 'DIMENSAO ERRADA' });
+  }
+
+  // ── (4) RASTRO no artefato (upsert idempotente), gravado tanto no verde quanto no bloqueio
+  // por dimensao: quem for consertar precisa ver o numero medido, nao so a mensagem do run.
+  const outRel = path.relative(runDir, outAbsDir) || '.';
+  const block = renderBlock({
+    rows, width, height, outRel,
+    chromeLabel: chromeBin.split('/').pop(),
+    failures: dimFailures,
+  });
+  try {
+    const raw = fs.readFileSync(path.resolve(artifact), 'utf8');
+    fs.writeFileSync(path.resolve(artifact), upsertBlock(raw, block), 'utf8');
+  } catch (e) {
+    console.error(`render-png: AVISO — gravacao do bloco no artefato falhou: ${e.message} ` +
+      '(o veredito abaixo NAO depende desta escrita)');
+  }
+
+  if (dimFailures.length > 0) {
+    console.error(`render-png BLOQUEOU: ${dimFailures.length} peca(s) fora de ${width}x${height} — ${dimFailures.join(' | ')}. ` +
+      'Dimensao e igualdade de inteiros lida do IHDR do PNG gerado: nao ha tolerancia a ajustar.');
+    process.exit(1);
+  }
+
+  console.log(`render-png OK: ${rows.length} PNG(s) gerados em ${outRel}, todos ${width}x${height} por IHDR ` +
+    `(${rows.map((r) => `${r.png}=${r.sha256.slice(0, 12)}`).join(', ')}). Renderizador: ${chromeBin.split('/').pop()}.`);
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  readPngDimensions, dimensionMatches, countMatches, parseArgs, resolveWithin,
+  listHtml, renderBlock, upsertBlock, pngNameFor, UsageError,
+  BLOCK_BEGIN, BLOCK_END, PNG_SIGNATURE,
+};