@pathbit/agentdevkit 0.0.0-stage → 0.0.6

package/.pbai4devs/scripts/preparar-ferramentas/tests/bootstrap.test.mjs

@@ -0,0 +1,94 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { ensureRuntime, main, validateArchive, validateExtracted } from '../BOOTSTRAP.mjs';
+import { findExecutable } from '../../lib/runtime.mjs';
+
+const project = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const tar = findExecutable('tar');
+function fixture(t) {
+  assert.ok(tar, 'Native tar is required for archive integration tests.');
+  mkdirSync(join(project, '.agent-tests'), { recursive: true });
+  const root = mkdtempSync(join(project, '.agent-tests/bootstrap-node-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const platform = process.platform, arch = process.arch;
+  const key = platform === 'win32' ? `win-${arch}` : `${platform}-${arch}`;
+  const top = `node-v24.1.2-${key}`, extension = platform === 'win32' ? 'zip' : 'tar.gz';
+  const bundle = join(root, top); mkdirSync(bundle);
+  const write = (path, content) => { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, content); };
+  write(join(bundle, platform === 'win32' ? 'node.exe' : 'bin/node'), 'fixture-node');
+  write(join(bundle, platform === 'win32' ? 'node_modules/npm/bin/npm-cli.js' : 'lib/node_modules/npm/bin/npm-cli.js'), 'fixture-npm');
+  const archive = join(root, `${top}.${extension}`);
+  const packed = spawnSync(tar, [platform === 'win32' ? '-acf' : '-czf', archive, '-C', root, top], { encoding: 'utf8' });
+  assert.equal(packed.status, 0, packed.stderr);
+  const checksum = createHash('sha256').update(readFileSync(archive)).digest('hex');
+  let manifest = `${checksum}  ${top}.${extension}\n`, calls = 0;
+  const run = (file, args, options) => {
+    if (args[0] === '-p') {
+      if (!existsSync(file) || readFileSync(file, 'utf8') !== 'fixture-node') return { status: 1, stdout: '' };
+      return { status: 0, stdout: JSON.stringify({ version: '24.1.2', node: file, bun: false }) };
+    }
+    if (args[1] === '--version') return { status: existsSync(args[0]) && readFileSync(args[0], 'utf8') === 'fixture-npm' ? 0 : 1, stdout: '11.0.0\n' };
+    return spawnSync(file, args, options);
+  };
+  const options = { root, node: join(root, 'missing-node'), platform, arch, libc: 'glibc', run,
+    download: async (url, destination) => { calls++; if (url.endsWith('SHASUMS256.txt')) writeFileSync(destination, manifest); else copyFileSync(archive, destination); } };
+  return { root, options, archive, key, cache: join(root, '.pbai4devs/tools/.cache/runtime/node', key), setManifest: value => { manifest = value; }, calls: () => calls };
+}
+
+test('bootstrap Node extrai arquivo real, verifica npm e reutiliza cache sem rede', async t => {
+  const f = fixture(t), runtime = await ensureRuntime(f.options);
+  assert.equal(runtime.source, 'download'); assert.equal(runtime.version, '24.1.2'); assert.equal(f.calls(), 2);
+  assert.ok(existsSync(runtime.node)); assert.ok(existsSync(runtime.npm));
+  const cached = await ensureRuntime({ ...f.options, download: async () => { throw new Error('Network must not run'); } });
+  assert.equal(cached.source, 'cache'); assert.equal(cached.node, runtime.node);
+  assert.ok(readdirSync(f.cache).every(name => !name.startsWith('.stage.')));
+});
+
+test('checksum, manifesto ambíguo e download falho não promovem runtime', async t => {
+  for (const kind of ['checksum', 'manifest', 'download']) await t.test(kind, async subtest => {
+    const f = fixture(subtest), previous = join(f.cache, 'v24.1.2'); mkdirSync(previous, { recursive: true }); writeFileSync(join(previous, 'preserved'), 'original');
+    if (kind === 'checksum') f.setManifest(`${'0'.repeat(64)}  node-v24.1.2-${f.key}.${process.platform === 'win32' ? 'zip' : 'tar.gz'}\n`);
+    if (kind === 'manifest') f.setManifest('no matching official archive\n');
+    const options = kind === 'download' ? { ...f.options, download: async () => { throw new Error('offline'); } } : f.options;
+    await assert.rejects(ensureRuntime(options), /SHA-256|indisponivel|offline/);
+    assert.equal(readFileSync(join(previous, 'preserved'), 'utf8'), 'original');
+    assert.ok(readdirSync(f.cache).every(name => !name.startsWith('.stage.')));
+  });
+});
+
+test('validação recusa nomes fora da distribuição antes da extração', () => {
+  const top = 'node-v24.1.2-linux-x64';
+  assert.doesNotThrow(() => validateArchive(`${top}/bin/npm\n`, top));
+  for (const name of ['../../outside', `${top}/../outside`, '/absolute/file', `${top}/C:file`]) assert.throws(() => validateArchive(`${name}\n`, top), /fora/);
+});
+
+test('links internos extraídos são aceitos e links externos são recusados', t => {
+  const f = fixture(t), inside = join(f.root, 'inside'), outside = join(f.root, 'outside'); mkdirSync(inside); mkdirSync(outside); writeFileSync(join(inside, 'file'), 'safe');
+  try { symlinkSync('file', join(inside, 'link')); } catch (error) { if (['EPERM', 'EACCES'].includes(error.code)) { t.skip('No symlink privilege'); return; } throw error; }
+  assert.doesNotThrow(() => validateExtracted(inside));
+  symlinkSync(outside, join(inside, 'escape'), 'dir');
+  assert.throws(() => validateExtracted(inside), /fora/);
+});
+
+test('cache simbólico é recusado sem tocar alvo externo', async t => {
+  const f = fixture(t), outside = join(f.root, 'outside'); mkdirSync(outside);
+  const cacheRoot = join(f.root, '.pbai4devs/tools/.cache'); mkdirSync(dirname(cacheRoot), { recursive: true });
+  try { symlinkSync(outside, cacheRoot, 'dir'); } catch (error) { if (['EPERM', 'EACCES'].includes(error.code)) { t.skip('No symlink privilege'); return; } throw error; }
+  await assert.rejects(ensureRuntime(f.options), /link simbolico/); assert.deepEqual(readdirSync(outside), []);
+});
+
+test('opções inválidas falham antes de rede ou criação de cache', async () => {
+  await assert.rejects(main(['--runtime-only', 'all']), /nao aceita/);
+  await assert.rejects(main(['--unknown']), /runtime-only/);
+});
+
+test('runtime atual saudável não altera PATH nem grava cache', async t => {
+  const f = fixture(t), original = process.env.PATH;
+  const result = await ensureRuntime({ root: f.root, minimum: Number(process.versions.node.split('.')[0]) });
+  assert.equal(result.source, 'current'); assert.equal(process.env.PATH, original); assert.equal(existsSync(f.cache), false);
+});

package/.pbai4devs/scripts/preparar-ferramentas/tests/fixtures-vercel/just-bash/input.txt

@@ -0,0 +1,2 @@
+agentdevkit example
+outra linha

package/.pbai4devs/scripts/preparar-ferramentas/tests/fixtures-vercel/just-bash-overlay/input.txt

@@ -0,0 +1 @@
+Fixture para escrita somente em memória.

package/.pbai4devs/scripts/preparar-ferramentas/tests/fixtures-vercel/skills/agentdevkit-smoke/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: agentdevkit-smoke
+description: Fixture local para verificar descoberta sem instalar skills.
+---
+
+# AgentDevKit smoke local
+
+Use apenas para testar a descoberta local da CLI skills.

package/.pbai4devs/scripts/preparar-ferramentas/tests/fixtures-vercel/webreel/index.html

@@ -0,0 +1,6 @@
+<!doctype html>
+<html lang="pt-BR">
+  <meta charset="utf-8">
+  <title>AgentDevKit smoke local</title>
+  <h1>Fixture local de roteiro</h1>
+</html>

package/.pbai4devs/scripts/preparar-ferramentas/tests/fixtures-vercel/webreel/webreel.config.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://webreel.dev/schema/v1.json",
+  "videos": {
+    "agentdevkit-smoke": {
+      "url": "./index.html",
+      "viewport": { "width": 640, "height": 480 },
+      "steps": [{ "action": "pause", "ms": 10 }]
+    }
+  }
+}

package/.pbai4devs/scripts/revisar-entrega/README.md

@@ -0,0 +1,36 @@
+---
+description: Verificação dos documentos, da revisão e das evidências da entrega.
+---
+
+# Revisar entrega
+
+Após implementar, atualizar a documentação afetada e testar, gere o registro:
+
+```sh
+node .pbai4devs/scripts/revisar-entrega/SCRIPT.mjs prepare --id minha-mudanca
+```
+
+Use `--spec caminho/SPEC.md` para extrair os critérios `AC-001` da spec.
+`--scope arquivo` limita uma revisão; sem ele, o snapshot reúne alterações Git.
+Use `--document arquivo` para incluir PRD, design e outros documentos.
+README, AGENTS, CLAUDE e GEMINI versionáveis na raiz entram automaticamente na
+revisão, mesmo sem alterações. Saídas locais ignoradas fora do índice não são
+documentos obrigatórios; documentos rastreados continuam cobertos mesmo quando
+uma regra de ignore corresponde ao nome.
+Preencha decisões, resultados e evidências no JSON retornado; peça revisão
+independente, execute `seal <caminho/revisao.json>` e depois
+`check <caminho/revisao.json>` antes de concluir.
+
+O check recusa resultados pendentes, evidências ausentes/versionadas e arquivos
+alterados depois da revisão. Relatórios ficam em
+`.agent-tests/<id>/<execução>/`.
+O preparo preserva o escopo em `baseline.json`; o selo registra hashes do
+relatório e das provas em `seal.json`. Preserve esses metadados no fluxo.
+Mudanças posteriores exigem nova execução, preservando as evidências anteriores.
+Uma deleção staged com arquivo ainda presente e ignorado é registrada como
+`indexAction: untrack`. O snapshot preserva seu hash físico; alterações no
+arquivo, no ignore ou nessa ação do índice invalidam a revisão. Diferenças
+entre índice e conteúdo testado continuam bloqueadas, inclusive com `--scope`.
+O script confere o registro; a revisão semântica continua sendo responsabilidade
+do agente revisor. Veja a skill
+[atualizar-documentacao](../../skills/projeto/atualizar-documentacao/SKILL.md).

package/.pbai4devs/scripts/revisar-entrega/SCRIPT.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { isMain, projectRoot, requireNode } from '../lib/runtime.mjs';
+
+const fail = message => { throw new Error(message); };
+const slug = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const portable = value => value.split(sep).join('/');
+const nonempty = value => typeof value === 'string' && value.trim().length > 0;
+const completed = value => nonempty(value) && !/^(?:a definir|pendente|pending|todo|tbd|\.\.\.)[.!]?$/i.test(value.trim());
+const digest = file => createHash('sha256').update(readFileSync(file)).digest('hex');
+
+function pathInRoot(root, input) {
+  if (!nonempty(input) || /[\0\r\n]/.test(input)) fail('Caminho invalido.');
+  const name = portable(relative(root, resolve(root, input)));
+  if (!name || name === '..' || name.startsWith('../') || isAbsolute(name) || name.split('/').some(part => part.toLowerCase() === '.git')) fail(`Caminho fora do escopo: ${input}`);
+  let current = root;
+  for (const part of name.split('/')) {
+    current = join(current, part);
+    try { if (lstatSync(current).isSymbolicLink()) fail(`Link simbolico nao permitido: ${name}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return name;
+}
+
+function git(root, args, allowFailure = false) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 15000, windowsHide: true });
+  if ((result.error || result.status !== 0) && !allowFailure) fail(`Git: ${result.error?.message || result.stderr?.trim() || 'operacao falhou'}`);
+  return result;
+}
+
+function repository(root) {
+  const canonical = realpathSync(root);
+  const top = git(canonical, ['rev-parse', '--show-toplevel']).stdout.trim();
+  if (realpathSync(top) !== canonical) fail('Use a raiz do repositorio.');
+  return canonical;
+}
+
+function head(root) {
+  const result = git(root, ['rev-parse', '--verify', 'HEAD'], true);
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function ignored(root, file) {
+  return git(root, ['check-ignore', '--no-index', '-q', '--', file], true).status === 0;
+}
+
+function tracked(root, file) {
+  return git(root, ['--literal-pathspecs', 'ls-files', '--error-unmatch', '--', file], true).status === 0;
+}
+
+function ignoredPaths(root, files) {
+  if (!files.length) return new Set();
+  const result = spawnSync('git', ['check-ignore', '--no-index', '--stdin', '-z'], { cwd: root, input: files.join('\0') + '\0', encoding: 'utf8', timeout: 15000, windowsHide: true });
+  if (result.error || ![0, 1].includes(result.status)) fail(`Git: ${result.error?.message || result.stderr?.trim() || 'falha ao conferir ignores'}`);
+  return new Set(result.stdout.split('\0').filter(Boolean));
+}
+
+function stagedDeletions(root) {
+  return new Set(git(root, ['diff', '--cached', '--diff-filter=D', '--no-renames', '--name-only', '-z', '--']).stdout.split('\0').filter(Boolean));
+}
+
+function changedFiles(root) {
+  const baseline = head(root);
+  const versioned = git(root, baseline ? ['diff', '--name-only', '-z', 'HEAD', '--'] : ['ls-files', '-z']).stdout;
+  const untracked = git(root, ['ls-files', '--others', '--exclude-standard', '-z']).stdout;
+  return [...new Set((versioned + '\0' + untracked).split('\0').filter(Boolean))].sort();
+}
+
+function snapshot(root, mode, paths, documents = [], spec = null) {
+  const names = mode === 'git' ? [...changedFiles(root), ...paths] : paths;
+  const selected = [...new Set(names.map(file => pathInRoot(root, file)))].sort();
+  const deleted = stagedDeletions(root), local = ignoredPaths(root, selected);
+  const files = selected.map(path => {
+    if (path.toLowerCase().startsWith('.agent-tests/')) fail('Artefatos nao fazem parte do escopo versionado.');
+    const absolute = join(root, path);
+    if (!existsSync(absolute)) return { path, sha256: null };
+    if (!lstatSync(absolute).isFile()) fail(`Escopo exige arquivos: ${path}`);
+    return { path, sha256: createHash('sha256').update(readFileSync(absolute)).digest('hex'), ...(deleted.has(path) && local.has(path) ? { indexAction: 'untrack' } : {}) };
+  });
+  if (!files.length) fail('Nenhuma alteracao para revisar; indique --scope para uma revisao especifica.');
+  return { mode, head: head(root), files, documents, spec };
+}
+
+export function specCriteria(text) {
+  const section = text.match(/^## (?:Crit[eé]rios de aceite|Acceptance criteria)\s*\r?\n([\s\S]*?)(?=^## |$(?![\s\S]))/im)?.[1];
+  const ids = [...new Set((section || '').match(/\bAC-\d{3,}\b/g) || [])];
+  if (!ids.length) fail('A spec deve definir criterios AC-001, AC-002... na secao Criterios de aceite.');
+  return ids;
+}
+
+function expectedDocuments(root, state, extra = []) {
+  const existing = ['README.md', 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md', 'CONTRIBUTING.md', 'CHANGELOG.md', 'SECURITY.md'].filter(file => existsSync(join(root, file)));
+  const changed = state.files.filter(file => /\.mdc?$/i.test(file.path)).map(file => file.path);
+  const candidates = [...new Set([...existing, ...changed].map(file => pathInRoot(root, file)))];
+  const local = ignoredPaths(root, candidates);
+  const versioned = new Set(git(root, ['ls-files', '-z']).stdout.split('\0').filter(Boolean));
+  return [...new Set([...candidates.filter(file => !local.has(file) || versioned.has(file)), ...extra.map(file => pathInRoot(root, file))])].sort();
+}
+
+function checkIndex(root, state) {
+  const staged = new Set(git(root, ['diff', '--cached', '--name-only', '-z', '--']).stdout.split('\0').filter(Boolean));
+  const deleted = stagedDeletions(root);
+  const indexed = new Set(git(root, ['ls-files', '-z']).stdout.split('\0').filter(Boolean));
+  const local = ignoredPaths(root, state.files.filter(file => file.indexAction === 'untrack').map(file => file.path));
+  for (const file of state.files) {
+    if (file.indexAction === 'untrack') {
+      if (!staged.has(file.path) || !deleted.has(file.path) || indexed.has(file.path) || file.sha256 === null || !existsSync(join(root, file.path)) || !local.has(file.path)) fail(`Acao de desindexacao mudou: ${file.path}`);
+      continue;
+    }
+    if (file.indexAction !== undefined) fail(`Acao de indice invalida: ${file.path}`);
+    if (!staged.has(file.path)) continue;
+    const deletedButPresent = !indexed.has(file.path) && file.sha256 !== null;
+    const differs = git(root, ['--literal-pathspecs', 'diff', '--quiet', '--no-ext-diff', '--', file.path], true);
+    if (deletedButPresent || differs.error || differs.status !== 0) fail(`Indice Git difere do arquivo testado: ${file.path}`);
+  }
+}
+
+function artifact(root, file, prefix, mustExist) {
+  const path = pathInRoot(root, file);
+  if (!path.startsWith(prefix + '/')) fail(`Evidencia deve ficar em ${prefix}/: ${path}`);
+  if (!ignored(root, path) || tracked(root, path)) fail(`Artefato deve estar ignorado e fora do indice Git: ${path}`);
+  if (mustExist && (!existsSync(join(root, path)) || !lstatSync(join(root, path)).isFile() || lstatSync(join(root, path)).size === 0)) fail(`Evidencia ausente ou vazia: ${path}`);
+  return path;
+}
+
+export function prepareReview({ root = projectRoot, id, execution = new Date().toISOString().replace(/[^a-z0-9]/gi, '').toLowerCase(), spec = null, scope = [], documents = [], output } = {}) {
+  requireNode(); root = repository(root);
+  if (!slug.test(id || '') || !slug.test(execution)) fail('Use referencia e execucao como slugs em minusculas.');
+  const reference = spec ? pathInRoot(root, spec) : null;
+  if (reference && ignored(root, reference) && !tracked(root, reference)) fail('A spec deve ser um documento versionavel, fora dos artefatos ignorados.');
+  const criteria = reference ? specCriteria(readFileSync(join(root, reference), 'utf8')) : ['AC-001'];
+  let state = snapshot(root, scope.length ? 'scope' : 'git', [...scope, ...(reference ? [reference] : [])]);
+  const requiredDocs = expectedDocuments(root, state, documents);
+  const localDocuments = ignoredPaths(root, requiredDocs);
+  for (const file of requiredDocs) if (localDocuments.has(file) && !tracked(root, file)) fail(`Documento deve ser versionavel: ${file}`);
+  state = snapshot(root, scope.length ? 'scope' : 'git', [...state.files.map(file => file.path), ...requiredDocs], requiredDocs, reference);
+  const prefix = `.agent-tests/${id}/${execution}`;
+  const file = artifact(root, output || `${prefix}/revisao.json`, prefix, false);
+  const baselineFile = artifact(root, `${prefix}/baseline.json`, prefix, false);
+  if (existsSync(join(root, file)) || existsSync(join(root, baselineFile))) fail(`Relatorio ja existe; preserve-o e use outra execucao: ${file}`);
+  const baseline = { version: 1, reference: id, execution, spec: reference, snapshot: state, criteria };
+  mkdirSync(dirname(join(root, file)), { recursive: true });
+  writeFileSync(join(root, baselineFile), JSON.stringify(baseline, null, 2) + '\n', { flag: 'wx' });
+  const report = {
+    version: 1, reference: id, execution, spec: reference, snapshot: state,
+    baseline: { file: baselineFile, sha256: digest(join(root, baselineFile)) },
+    documentation: expectedDocuments(root, state, documents).map(path => ({ path, decision: 'pending', reason: '' })),
+    validation: criteria.map(criterion => ({ criterion, method: '', prerequisite: '', assertion: '', evidence: [], status: 'pending' })),
+    review: { status: 'pending', reviewer: '', findings: [] },
+  };
+  mkdirSync(dirname(join(root, file)), { recursive: true });
+  writeFileSync(join(root, file), JSON.stringify(report, null, 2) + '\n', { flag: 'wx' });
+  return { file, report };
+}
+
+function validateReview(file, { root = projectRoot, requireSeal = true } = {}) {
+  requireNode(); root = repository(root);
+  const reportPath = pathInRoot(root, file);
+  const report = JSON.parse(readFileSync(join(root, reportPath), 'utf8'));
+  if (report.version !== 1 || !slug.test(report.reference || '') || !slug.test(report.execution || '')) fail('Cabecalho de revisao invalido.');
+  const prefix = `.agent-tests/${report.reference}/${report.execution}`;
+  artifact(root, reportPath, prefix, true);
+  const baselineFile = artifact(root, `${prefix}/baseline.json`, prefix, true);
+  const baseline = JSON.parse(readFileSync(join(root, baselineFile), 'utf8'));
+  if (report.baseline?.file !== baselineFile || report.baseline.sha256 !== digest(join(root, baselineFile)) ||
+      baseline.reference !== report.reference || baseline.execution !== report.execution || baseline.spec !== report.spec ||
+      JSON.stringify(baseline.snapshot) !== JSON.stringify(report.snapshot)) fail('Baseline gerada diverge do relatorio; preserve os metadados e refaca o preparo.');
+  const state = report.snapshot;
+  if (!state || !['git', 'scope'].includes(state.mode) || !Array.isArray(state.files) || !Array.isArray(state.documents) || report.spec !== state.spec) fail('Snapshot ausente ou referencias alteradas.');
+  const requiredDocs = state.documents.map(file => pathInRoot(root, file));
+  const currentDocuments = expectedDocuments(root, state, requiredDocs);
+  if (currentDocuments.some(path => !requiredDocs.includes(path) || !state.files.some(file => file.path === path))) {
+    fail('Documentos obrigatorios mudaram depois do snapshot; refaca a revisao.');
+  }
+  const current = snapshot(root, state.mode, state.files.map(file => file.path), requiredDocs, state.spec);
+  if (JSON.stringify(current) !== JSON.stringify(state)) fail('Arquivos ou HEAD mudaram depois do snapshot; refaca a revisao.');
+  checkIndex(root, state);
+  if (!Array.isArray(report.documentation) || !Array.isArray(report.validation)) fail('Documentacao e validacoes sao obrigatorias.');
+  const docs = new Map();
+  for (const item of report.documentation) {
+    const path = pathInRoot(root, item.path);
+    if (docs.has(path) || !['updated', 'no-impact', 'not-applicable'].includes(item.decision) || !completed(item.reason)) fail(`Decisao de documentacao pendente/invalida: ${path}`);
+    if (item.decision !== 'not-applicable' && !existsSync(join(root, path))) fail(`Documento ausente: ${path}`);
+    if (item.decision === 'not-applicable' && existsSync(join(root, path))) fail(`Documento existente exige decisao de impacto: ${path}`);
+    docs.set(path, item);
+  }
+  for (const path of currentDocuments) if (!docs.has(path)) fail(`Documento sem revisao: ${path}`);
+  const ids = new Set();
+  const proofs = new Set();
+  for (const item of report.validation) {
+    if (!/^AC-\d{3,}$/.test(item.criterion || '') || ids.has(item.criterion)) fail('Criterio invalido ou duplicado.');
+    ids.add(item.criterion);
+    if (![item.method, item.prerequisite, item.assertion].every(completed)) fail(`Plano de validacao incompleto: ${item.criterion}`);
+    if (item.status !== 'passed' || !Array.isArray(item.evidence) || !item.evidence.length) fail(`Criterio sem prova aprovada: ${item.criterion}`);
+    for (const proof of item.evidence) proofs.add(artifact(root, proof, prefix, true));
+  }
+  if (!ids.size) fail('Nenhum criterio de aceite.');
+  for (const id of baseline.criteria) if (!ids.has(id)) fail(`Criterio da spec sem resultado: ${id}`);
+  if (report.review?.status !== 'approved' || !nonempty(report.review.reviewer) || !Array.isArray(report.review.findings)) fail('Revisao independente pendente.');
+  if (report.review.findings.some(item => !nonempty(item.id) || !nonempty(item.description) || item.status !== 'resolved')) fail('Achados de revisao ainda abertos.');
+  const seal = {
+    reportHash: digest(join(root, reportPath)), baselineHash: digest(join(root, baselineFile)),
+    evidence: [...proofs].sort().map(path => ({ path, sha256: digest(join(root, path)) })),
+  };
+  if (requireSeal) {
+    if (!existsSync(join(root, prefix, 'seal.json'))) fail('Revisao nao selada; conclua a revisao independente e execute seal.');
+    const sealPath = artifact(root, `${prefix}/seal.json`, prefix, true);
+    const recorded = JSON.parse(readFileSync(join(root, sealPath), 'utf8'));
+    if (JSON.stringify(recorded) !== JSON.stringify(seal)) fail('Relatorio, baseline ou evidencia alterados apos selar a revisao.');
+  }
+  return { root, prefix, seal, result: { status: 'passed', report: reportPath, criteria: ids.size, documents: docs.size } };
+}
+
+export function checkReview(file, { root = projectRoot } = {}) { return validateReview(file, { root, requireSeal: true }).result; }
+
+export function sealReview(file, options) {
+  const checked = validateReview(file, { ...options, requireSeal: false });
+  const path = artifact(checked.root, `${checked.prefix}/seal.json`, checked.prefix, false);
+  if (existsSync(join(checked.root, path))) return checkReview(file, options);
+  writeFileSync(join(checked.root, path), JSON.stringify(checked.seal, null, 2) + '\n', { flag: 'wx' });
+  return checkReview(file, options);
+}
+
+const usage = 'Uso: revisar-entrega prepare --id <slug> [--execution <slug>] [--spec <arquivo>] [--scope <arquivo>] [--document <arquivo>] [--output <artefato>]; seal|check <revisao.json>';
+export function main(args = process.argv.slice(2)) {
+  requireNode(); const [mode, ...rest] = args;
+  if (!mode || ['--help', '-h'].includes(mode)) { console.log(usage); return 0; }
+  if (mode === 'check' && rest.length === 1) { console.log(JSON.stringify(checkReview(rest[0]))); return 0; }
+  if (mode === 'seal' && rest.length === 1) { console.log(JSON.stringify(sealReview(rest[0]))); return 0; }
+  if (mode !== 'prepare') fail(usage);
+  const options = { scope: [], documents: [] };
+  const fields = { '--id': 'id', '--execution': 'execution', '--spec': 'spec', '--output': 'output' };
+  for (let i = 0; i < rest.length; i += 2) {
+    const value = rest[i + 1]; if (!value || value.startsWith('--')) fail(usage);
+    if (rest[i] === '--scope') options.scope.push(value);
+    else if (rest[i] === '--document') options.documents.push(value);
+    else if (fields[rest[i]]) { if (options[fields[rest[i]]] !== undefined) fail('Opcao duplicada.'); options[fields[rest[i]]] = value; }
+    else fail(usage);
+  }
+  console.log(JSON.stringify({ report: prepareReview(options).file, status: 'pending' })); return 0;
+}
+
+if (isMain(import.meta.url)) {
+  try { process.exitCode = main(); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}