@daniellins/power-claude 0.16.3

package/scripts/validate-update-scope-motor.js

@@ -0,0 +1,421 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * validate-update-scope-motor.js — Story SF10.20 / ADR-019 (`DF-SF10.20-4`, `DF-SF10.20-5`).
+ *
+ * Dois mecanismos, um arquivo:
+ *
+ * A) `power-claude update --scope motor`. O teste que carrega o peso é o da ARMADILHA:
+ *    `adopt --yes && update --yes` PRESERVA o script de motor velho (adopt.js marca
+ *    divergência como `origin:'modified'`; update.js preserva) e ainda assim reporta
+ *    sucesso — foi o que teria acontecido se a SF10.20 tivesse seguido a presunção
+ *    original. O escopo motor tem que corrigir o mesmo fixture.
+ *
+ * B) Atribuição de skew de capacidade em `loadWorkflow` (`capabilityGaps` /
+ *    `annotateCapabilitySkew`): a falha do preflight passa a dizer que a culpada é a
+ *    INSTALAÇÃO, com as duas causas possíveis e o comando de correção.
+ *
+ * NOTA DE AUTORIDADE (`DF-SF10.20-1`): este arquivo é prova de NÃO-REGRESSÃO do
+ * mecanismo. Ele NÃO é o enforcement — o enforcement é o preflight do motor na árvore
+ * instalada do usuário. Nada aqui deve virar a única evidência de que o gate funciona:
+ * a evidência que conta está no Dev Record da story, colhida no `second-brain`.
+ *
+ * Node >= 18, sem dependências externas.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const CLI = path.join(REPO_ROOT, 'bin', 'cli.js');
+const TEMPLATE_DIR = path.join(REPO_ROOT, 'template');
+
+const results = [];
+function check(label, ok, detail) {
+  results.push({ label, ok, detail });
+  console.log(`[${ok ? 'OK   ' : 'FALHA'}] ${label}${detail ? ` — ${detail}` : ''}`);
+  return ok;
+}
+
+function cp(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function cli(args, cwd) {
+  return spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: 'utf8', timeout: 120000 });
+}
+
+/**
+ * Instalação-fixture montada À MÃO (sem manifest) — a mesma forma do defeito real:
+ * `scripts/pc-run-pod.cjs` presente porém DEFASADO, `scripts/veto-checks/` ausente.
+ */
+function makeFixture() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-scope-motor-'));
+  // Owner das entradas do motor (ADR-007 Decisão 3): `pods/squad-forge` é o owner de
+  // validate-pod-workflow.cjs/smoke-pod-workflow.cjs e `skill:pc-run-pod` o de
+  // pc-run-pod.cjs — sem eles o escopo PULA justamente os arquivos sob teste.
+  fs.mkdirSync(path.join(dir, 'pods', 'demo', 'workflows'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'pods', 'squad-forge'), { recursive: true });
+  cp(path.join(TEMPLATE_DIR, '.claude', 'CLAUDE.md'), path.join(dir, '.claude', 'CLAUDE.md'));
+  for (const skill of fs.readdirSync(path.join(TEMPLATE_DIR, '.claude', 'skills'))) {
+    fs.mkdirSync(path.join(dir, '.claude', 'skills', skill), { recursive: true });
+  }
+  // Motor "sincronizado à mão em algum momento do passado": copiado e depois derivado.
+  cp(path.join(REPO_ROOT, 'scripts', 'pc-run-pod.cjs'), path.join(dir, 'scripts', 'pc-run-pod.cjs'));
+  fs.appendFileSync(path.join(dir, 'scripts', 'pc-run-pod.cjs'), '\n// motor defasado (fixture)\n');
+  cp(path.join(REPO_ROOT, 'scripts', 'validate-budgets.js'), path.join(dir, 'scripts', 'validate-budgets.js'));
+  return dir;
+}
+
+function hash(p) {
+  return require('../installer/manifest').sha256OfFile(p);
+}
+
+function main() {
+  console.log('POWER CLAUDE — validate-update-scope-motor (SF10.20)\n');
+  const tmpdirs = [];
+  try {
+    // ---------------------------------------------------------------------
+    // A1. A ARMADILHA: adopt --yes && update --yes PRESERVA o motor velho.
+    // ---------------------------------------------------------------------
+    const trap = makeFixture();
+    tmpdirs.push(trap);
+    const trapRunner = path.join(trap, 'scripts', 'pc-run-pod.cjs');
+    const staleHash = hash(trapRunner);
+    const freshHash = hash(path.join(REPO_ROOT, 'scripts', 'pc-run-pod.cjs'));
+    check('fixture: motor instalado diverge do framework', staleHash !== freshHash);
+
+    const adoptTrap = cli(['adopt', '--yes'], trap);
+    check('adopt --yes sai 0 na instalação sem manifest', adoptTrap.status === 0, `exit ${adoptTrap.status}`);
+    check('adopt --yes NÃO escreve arquivo de motor (só o manifest)', hash(trapRunner) === staleHash);
+
+    const updateTrap = cli(['update', '--yes'], trap);
+    check('update --yes (sem escopo) sai 0 — reporta SUCESSO', updateTrap.status === 0, `exit ${updateTrap.status}`);
+    check(
+      'ARMADILHA confirmada: update --yes sem escopo PRESERVA o motor defasado',
+      hash(trapRunner) === staleHash,
+      'é por isso que --scope motor existe (ADR-019 DF-SF10.20-5)'
+    );
+
+    // Mesmo fixture, agora com escopo: tem que corrigir o que a armadilha preservou.
+    const scopedTrap = cli(['update', '--scope', 'motor', '--yes'], trap);
+    check('update --scope motor sai 0', scopedTrap.status === 0, `exit ${scopedTrap.status}`);
+    check(
+      'update --scope motor SOBRESCREVE o motor defasado (divergência = defasagem)',
+      hash(trapRunner) === freshHash
+    );
+    check(
+      'update --scope motor instala os blessed ausentes (scripts/veto-checks/)',
+      fs.existsSync(path.join(trap, 'scripts', 'veto-checks', 'phash-gate.cjs'))
+    );
+
+    // ---------------------------------------------------------------------
+    // A2. Auditabilidade e contenção do escopo.
+    // ---------------------------------------------------------------------
+    const fresh = makeFixture();
+    tmpdirs.push(fresh);
+    cli(['adopt', '--yes'], fresh);
+    const beforeTemplateMiss = fs.existsSync(path.join(fresh, '.claude', 'settings.json'));
+    const scoped = cli(['update', '--scope', 'motor', '--yes'], fresh);
+    const out = scoped.stdout || '';
+    check('tabela de hashes é impressa', out.includes('sha256 instalado → sha256 framework'));
+    check('tabela marca o defasado ANTES de escrever', /DEFASADO\s+scripts\/pc-run-pod\.cjs/.test(out));
+    check('relatório distingue sobrescritos de instalados', out.includes('Sobrescritos (defasados):') && out.includes('Instalados (ausentes):'));
+    check('avisa sobre o landmine do update sem escopo', out.includes('SEM --scope motor') && out.includes('docs/mecanismos/update-scope-motor.md'));
+    check(
+      'escopo NÃO instala arquivo de template (settings.json continua ausente)',
+      fs.existsSync(path.join(fresh, '.claude', 'settings.json')) === beforeTemplateMiss &&
+        !fs.existsSync(path.join(fresh, '.claude', 'settings.json'))
+    );
+    const manifestAfter = JSON.parse(fs.readFileSync(path.join(fresh, '.power-claude', 'manifest.json'), 'utf8'));
+    const runnerEntry = manifestAfter.files.find((f) => f.path === 'scripts/pc-run-pod.cjs');
+    check('manifest passa a registrar o hash NOVO do motor (sem origin:modified)', Boolean(runnerEntry) && runnerEntry.sha256 === freshHash && !runnerEntry.origin);
+    const noise = out.includes('não faz mais parte do template');
+    check('escopo não emite ruído de "saiu do template" sobre entradas fora do escopo', !noise);
+
+    // Idempotência.
+    const again = cli(['update', '--scope', 'motor', '--yes'], fresh);
+    check('segundo update --scope motor é no-op', again.status === 0 && (again.stdout || '').includes('Motor já sincronizado'));
+
+    // ---------------------------------------------------------------------
+    // A3. SF11.1 — REGRESSÃO: no-op recarimba o REGISTRO (frameworkRoot/updatedAt).
+    //
+    // O defeito que faltava cobrir: `updateScopedMotor` retornava em
+    // `toWrite.length === 0` ANTES de `writeManifest` — único lugar que grava
+    // `frameworkRoot`. Numa instalação já sincronizada (o caso comum depois do
+    // primeiro sync) NENHUM comando suportado reancorava o campo: `adopt` recusa com
+    // manifest presente, e o `update` escopado saía cedo. O campo apontando para um
+    // checkout efêmero já apagado degrada silenciosamente o comando de correção da
+    // SF10.20 para placeholder. Aqui o cenário é montado explicitamente: manifest
+    // apontando para caminho inexistente + motor 100% sincronizado.
+    // ---------------------------------------------------------------------
+    const staleMfPath = path.join(fresh, '.power-claude', 'manifest.json');
+    const beforeMf = JSON.parse(fs.readFileSync(staleMfPath, 'utf8'));
+    const orphanRoot = path.join(os.tmpdir(), 'pc-wt-efemero-que-sumiu');
+    fs.writeFileSync(
+      staleMfPath,
+      JSON.stringify({ ...beforeMf, frameworkRoot: orphanRoot, updatedAt: '2000-01-01T00:00:00.000Z' }, null, 2) + '\n'
+    );
+    const reanchor = cli(['update', '--scope', 'motor', '--yes'], fresh);
+    const reanchorOut = reanchor.stdout || '';
+    const afterMf = JSON.parse(fs.readFileSync(staleMfPath, 'utf8'));
+    check('no-op (nada a escrever) ainda sai 0', reanchor.status === 0 && reanchorOut.includes('Motor já sincronizado'), `exit ${reanchor.status}`);
+    check(
+      'SF11.1: no-op RECARIMBA frameworkRoot órfão para o repo que rodou o comando',
+      afterMf.frameworkRoot === REPO_ROOT,
+      `${orphanRoot} → ${afterMf.frameworkRoot}`
+    );
+    check('SF11.1: no-op atualiza updatedAt', afterMf.updatedAt !== '2000-01-01T00:00:00.000Z' && !Number.isNaN(Date.parse(afterMf.updatedAt)), afterMf.updatedAt);
+    check(
+      'SF11.1: no-op NÃO altera nenhuma entrada de files (nada perdido, nada reclassificado)',
+      JSON.stringify(afterMf.files) === JSON.stringify(beforeMf.files),
+      `${beforeMf.files.length} → ${afterMf.files.length} entradas`
+    );
+    check('SF11.1: no-op NÃO bumpa version nem mexe em installedAt', afterMf.version === beforeMf.version && afterMf.installedAt === beforeMf.installedAt);
+    check(
+      'SF11.1: o relatório do no-op não alega escrita de arquivo',
+      /0 arquivos escritos/.test(reanchorOut) && !/Sobrescritos \(defasados\)/.test(reanchorOut)
+    );
+    // O campo recarimbado é utilizável, não só bonito: o CLI que ele aponta executa.
+    const reanchoredCli = path.join(afterMf.frameworkRoot, 'bin', 'cli.js');
+    const reanchoredProbe = fs.existsSync(reanchoredCli)
+      ? spawnSync(process.execPath, [reanchoredCli, '--version'], { encoding: 'utf8', timeout: 60000 })
+      : { status: 1, stdout: '' };
+    check(
+      'SF11.1: ACIONABILIDADE — o frameworkRoot recarimbado hospeda um CLI que executa',
+      reanchoredProbe.status === 0 && (reanchoredProbe.stdout || '').trim() === require('../package.json').version,
+      `exit ${reanchoredProbe.status}, stdout "${(reanchoredProbe.stdout || '').trim()}"`
+    );
+
+    // A4. SF11.1 — guard proativo do doctor sobre frameworkRoot (AVISO, nunca FALHA).
+    fs.writeFileSync(staleMfPath, JSON.stringify({ ...afterMf, frameworkRoot: orphanRoot }, null, 2) + '\n');
+    const docOrphan = cli(['doctor'], fresh);
+    const docOrphanOut = docOrphan.stdout || '';
+    check(
+      'SF11.1: doctor AVISA quando frameworkRoot não hospeda bin/cli.js',
+      /\[AVISO\].*frameworkRoot do manifest/.test(docOrphanOut),
+      (docOrphanOut.split('\n').find((l) => /frameworkRoot do manifest/.test(l)) || '').trim()
+    );
+    check('SF11.1: o aviso cita o caminho problemático', docOrphanOut.includes(orphanRoot));
+    check('SF11.1: o aviso cita o comando de correção', /frameworkRoot do manifest.*update --scope motor/.test(docOrphanOut));
+    check('SF11.1: o guard de frameworkRoot NUNCA é FALHA (registro, não oráculo)', !/\[FALHA\].*frameworkRoot do manifest/.test(docOrphanOut));
+    // Positivo: com o campo válido, o mesmo check passa como OK — nenhum falso-positivo
+    // numa instalação sadia (é o caso dos checkouts/worktrees reais em uso).
+    cli(['update', '--scope', 'motor', '--yes'], fresh);
+    const docHealthy = cli(['doctor'], fresh);
+    check(
+      'SF11.1: frameworkRoot válido → check passa OK (sem falso-positivo)',
+      /\[OK\s*\].*frameworkRoot do manifest/.test(docHealthy.stdout || ''),
+      (String(docHealthy.stdout || '').split('\n').find((l) => /frameworkRoot do manifest/.test(l)) || '').trim()
+    );
+
+    // Escopo inválido e uso fora do update.
+    const badScope = cli(['update', '--scope', 'tudo', '--yes'], fresh);
+    check('escopo desconhecido é recusado (exit 2)', badScope.status === 2, `exit ${badScope.status}`);
+    const scopeOnInstall = cli(['doctor', '--scope', 'motor'], fresh);
+    check('--scope fora do update é recusado (exit 2)', scopeOnInstall.status === 2, `exit ${scopeOnInstall.status}`);
+
+    // planMotorSync é puro: chamá-lo não muda disco.
+    const { planMotorSync } = require('../installer/update');
+    const beforeRunner = hash(path.join(fresh, 'scripts', 'pc-run-pod.cjs'));
+    const plan = planMotorSync({ pkgRoot: REPO_ROOT, destDir: fresh });
+    check('planMotorSync não escreve nada', hash(path.join(fresh, 'scripts', 'pc-run-pod.cjs')) === beforeRunner);
+    check('planMotorSync classifica todos os estados conhecidos', plan.every((r) => ['same', 'stale', 'missing', 'skipped-owner'].includes(r.state)));
+
+    // ---------------------------------------------------------------------
+    // B. Atribuição de skew de capacidade (DF-SF10.20-4).
+    // ---------------------------------------------------------------------
+    const runner = require('../scripts/pc-run-pod.cjs');
+    const wfDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-skew-wf-'));
+    tmpdirs.push(wfDir);
+
+    // (i) tipo de veto que este motor não conhece.
+    const wfUnknownType = path.join(wfDir, 'wf-unknown-type.yaml');
+    fs.writeFileSync(wfUnknownType, [
+      'name: skew-fixture', 'version: 0.1', 'steps:',
+      '  - id: alfa', '    agent: a', '    output: out/a.md',
+      '    veto:', '      assertions:',
+      '        - type: capacidade_do_futuro', '          section: "## X"',
+      '',
+    ].join('\n'));
+    const gapsA = runner.capabilityGaps(wfUnknownType);
+    check('capabilityGaps detecta tipo de veto desconhecido', gapsA.length === 1 && gapsA[0].includes('capacidade_do_futuro'), gapsA[0]);
+
+    // (ii) command_check apontando para blessed não instalado neste motor.
+    const wfMissingBlessed = path.join(wfDir, 'wf-missing-blessed.yaml');
+    fs.writeFileSync(wfMissingBlessed, [
+      'name: skew-fixture', 'version: 0.1', 'steps:',
+      '  - id: alfa', '    agent: a', '    output: out/a.md',
+      '    veto:', '      assertions:',
+      '        - type: command_check', '          command: gate-que-nao-existe.cjs',
+      '',
+    ].join('\n'));
+    const gapsB = runner.capabilityGaps(wfMissingBlessed);
+    check('capabilityGaps detecta blessed ausente', gapsB.length === 1 && gapsB[0].includes('gate-que-nao-existe.cjs'), gapsB[0]);
+
+    // (iii) wf sadio: zero gap → nenhuma atribuição espúria.
+    const wfSane = path.join(wfDir, 'wf-sane.yaml');
+    fs.writeFileSync(wfSane, [
+      'name: skew-fixture', 'version: 0.1', 'steps:',
+      '  - id: alfa', '    agent: a', '    output: out/a.md',
+      '    veto:', '      assertions:',
+      '        - type: section_exists', '          section: "## X"',
+      '',
+    ].join('\n'));
+    check('wf sadio não produz gap (sem atribuição espúria)', runner.capabilityGaps(wfSane).length === 0);
+
+    const plain = new Error('etapa "alfa": algum outro erro de contrato');
+    const kept = runner.annotateCapabilitySkew(plain, wfSane);
+    check('falha de contrato comum mantém a mensagem intacta', kept.message === 'etapa "alfa": algum outro erro de contrato');
+
+    // (iv) contrato da mensagem enriquecida.
+    const annotated = runner.annotateCapabilitySkew(new Error('etapa "alfa": veto.assertions[0].type inválido'), wfUnknownType);
+    const msg = annotated.message;
+    const required = [
+      ['preserva a mensagem original', 'veto.assertions[0].type inválido'],
+      ['atribui a falha à INSTALAÇÃO', 'ATRIBUIÇÃO: esta falha é da INSTALAÇÃO'],
+      ['nomeia o motor por path absoluto', path.join(REPO_ROOT, 'scripts', 'pc-run-pod.cjs')],
+      ['declara o estado da instalação', 'Instalação:'],
+      ['nomeia a capacidade que falta', 'capacidade_do_futuro'],
+      ['declara a causa 1 (instalação defasada)', 'INSTALAÇÃO DEFASADA'],
+      ['declara a causa 2 (wf inválido em qualquer versão)', 'não existe em nenhuma versão do motor'],
+    ];
+    for (const [label, needle] of required) check(`mensagem: ${label}`, msg.includes(needle), needle);
+    check('exceção mantém classe e identidade (só texto muda)', annotated instanceof Error && Array.isArray(annotated.capabilityGaps));
+
+    // (v) prova de execução: loadWorkflow falha ANTES de qualquer estado, com atribuição.
+    let threw = null;
+    try { runner.loadWorkflow(wfMissingBlessed, wfDir); } catch (e) { threw = e; }
+    check('loadWorkflow lança no preflight (antes de criar estado)', threw !== null);
+    check('mensagem do loadWorkflow carrega a atribuição', Boolean(threw) && threw.message.includes('ATRIBUIÇÃO: esta falha é da INSTALAÇÃO'));
+
+    // ---------------------------------------------------------------------
+    // C. Detector fora-de-banda do `doctor` (DF-SF10.20-4, item 2). A assimetria
+    //    que importa: o doctor roda do FRAMEWORK mas executa o validador do PROJETO.
+    // ---------------------------------------------------------------------
+    const docDir = makeFixture();
+    tmpdirs.push(docDir);
+    cli(['adopt', '--yes'], docDir);
+    cli(['update', '--scope', 'motor', '--yes'], docDir);
+    // Pod-canário COMPLETO e válido em pods/demo (wf + templates) — para que a única
+    // diferença entre o caso positivo e o negativo seja a CAPACIDADE exigida, e não
+    // um wf malformado por outro motivo.
+    const canaryDir = path.join(REPO_ROOT, 'scripts', '__fixtures__', 'smoke-canary');
+    // SF11.2/DF-SF11.2-4: os `agents/*.md` entram na cópia porque a leitura obrigatória da
+    // etapa passou a ser verificada em disco (runner e validador). Sem eles o wf seria
+    // inválido por OUTRO motivo, contaminando o contraste positivo×negativo deste bloco.
+    for (const rel of ['workflows/wf-canary.yaml', 'templates/research-tmpl.md', 'templates/report-tmpl.md', 'templates/synth-tmpl.md',
+      'agents/canary-researcher.md', 'agents/canary-synth.md', 'agents/canary-reporter.md']) {
+      cp(path.join(canaryDir, ...rel.split('/')), path.join(docDir, 'pods', 'demo', ...rel.split('/')));
+    }
+    const demoWf = path.join(docDir, 'pods', 'demo', 'workflows', 'wf-canary.yaml');
+    const canaryText = fs.readFileSync(demoWf, 'utf8');
+
+    // Negativa: o MESMO wf, com um único `type` trocado por capacidade que este motor
+    // não tem → o doctor FALHA e nomeia o wf.
+    fs.writeFileSync(demoWf, canaryText.replace('type: field_matches', 'type: phash_similarity'));
+    const docBad = cli(['doctor'], docDir);
+    const badOut = docBad.stdout || '';
+    check('doctor FALHA quando um wf instalado não é carregável pelo motor instalado', /\[FALHA\].*wf executável pelo motor instalado: pods\/demo\/workflows\/wf-canary\.yaml/.test(badOut));
+    check('doctor sai não-zero nesse caso', docBad.status !== 0, `exit ${docBad.status}`);
+    // Acionabilidade também na saída do doctor — mesma régua da seção D.
+    const docCli = [...badOut.matchAll(/node\s+(\S+bin\/cli\.js)/g)].map((m) => m[1]);
+    check('doctor dá comando de correção com caminho concreto', docCli.length > 0, docCli[0]);
+    check('ACIONABILIDADE: caminho de CLI impresso pelo doctor EXISTE', docCli.length > 0 && docCli.every((p) => fs.existsSync(p)));
+    check('doctor NÃO manda rodar npx power-claude', !/\bnpx\s+power-claude\b/.test(badOut));
+
+    // Positiva: o MESMO wf, íntegro → o mesmo check passa. (Prova que o FALHA acima é
+    // da capacidade, não de um efeito colateral do fixture.)
+    fs.writeFileSync(demoWf, canaryText);
+    const docGood = cli(['doctor'], docDir);
+    check('doctor passa no check quando o wf é carregável', /\[OK\s*\].*wf executável pelo motor instalado: pods\/demo\/workflows\/wf-canary\.yaml/.test(docGood.stdout || ''));
+
+    // ---------------------------------------------------------------------
+    // D. ACIONABILIDADE do comando de correção (finding 1 do gate SF10.20).
+    //
+    // Este bloco NÃO assere a string do comando. Asserir texto que o próprio dev
+    // escreveu é auto-atestação (lição SF10.8) — foi exatamente assim que passou a
+    // receita `npx power-claude`, que numa instalação sem package.json/node_modules/
+    // PATH resolve pelo REGISTRY PÚBLICO, onde o nome é de um pacote de TERCEIRO.
+    // Aqui se verifica que o comando IMPRESSO é executável no contexto em que é
+    // impresso: o path existe e responde como o CLI deste framework.
+    //
+    // Determinístico e OFFLINE: o único processo executado é `bin/cli.js --version`
+    // deste repositório. Nada é resolvido por rede, nada de terceiro é baixado.
+    // ---------------------------------------------------------------------
+
+    // O motor da INSTALAÇÃO (não o do framework) é quem produz a mensagem real.
+    const installedRunner = require(path.join(docDir, 'scripts', 'pc-run-pod.cjs'));
+    const wfGapInstalled = path.join(docDir, 'wf-gap.yaml');
+    fs.writeFileSync(wfGapInstalled, fs.readFileSync(wfUnknownType, 'utf8'));
+    const installedMsg = installedRunner.annotateCapabilitySkew(new Error('falha de contrato'), wfGapInstalled).message;
+
+    check('mensagem da instalação NÃO manda rodar npx (supply-chain do registry público)', !/\bnpx\s+power-claude\b/.test(installedMsg.replace('NÃO use "npx power-claude"', '')));
+
+    const cliMatches = [...installedMsg.matchAll(/node\s+(\S+bin\/cli\.js)/g)].map((m) => m[1]).filter((p) => !/[<>]/.test(p));
+    check('mensagem imprime um comando concreto com caminho para o CLI', cliMatches.length > 0, cliMatches[0]);
+    const allExist = cliMatches.length > 0 && cliMatches.every((p) => fs.existsSync(p));
+    check('ACIONABILIDADE: todo caminho de CLI impresso EXISTE em disco', allExist, cliMatches.join(' '));
+
+    if (allExist) {
+      const probe = spawnSync(process.execPath, [cliMatches[0], '--version'], { encoding: 'utf8', timeout: 60000 });
+      const version = require('../package.json').version;
+      check('ACIONABILIDADE: o CLI impresso executa e é ESTE framework', probe.status === 0 && (probe.stdout || '').trim() === version, `exit ${probe.status}, stdout "${(probe.stdout || '').trim()}" (esperado ${version})`);
+      const helpProbe = spawnSync(process.execPath, [cliMatches[0], '--help'], { encoding: 'utf8', timeout: 60000 });
+      check('ACIONABILIDADE: o CLI impresso reconhece os subcomandos citados', probe.status === 0 && /\badopt\b/.test(helpProbe.stdout || '') && /\bupdate\b/.test(helpProbe.stdout || ''));
+    }
+
+    // Degradação honesta: manifest apontando para framework inexistente.
+    const mfP = path.join(docDir, '.power-claude', 'manifest.json');
+    const mfOrig = fs.readFileSync(mfP, 'utf8');
+    const mfBroken = JSON.parse(mfOrig);
+    mfBroken.frameworkRoot = path.join(os.tmpdir(), 'power-claude-que-nao-existe');
+    fs.writeFileSync(mfP, JSON.stringify(mfBroken, null, 2));
+    delete require.cache[require.resolve(path.join(docDir, 'scripts', 'pc-run-pod.cjs'))];
+    const brokenRunner = require(path.join(docDir, 'scripts', 'pc-run-pod.cjs'));
+    const brokenMsg = brokenRunner.annotateCapabilitySkew(new Error('falha de contrato'), wfGapInstalled).message;
+    // Invariante: todo caminho CONCRETO impresso existe. Placeholder (`<...>`) é
+    // legítimo — anuncia que o caminho é desconhecido em vez de inventar um.
+    const brokenConcrete = [...brokenMsg.matchAll(/node\s+(\S+bin\/cli\.js)/g)].map((m) => m[1]).filter((p) => !/[<>]/.test(p));
+    check('framework movido/apagado: NÃO imprime comando concreto falso', brokenConcrete.length === 0, `concretos impressos: ${JSON.stringify(brokenConcrete)}`);
+    check('framework movido/apagado: degrada para placeholder explícito', brokenMsg.includes('<repo-power-claude>'));
+    check('framework movido/apagado: avisa contra npx', brokenMsg.includes('NÃO use "npx power-claude"'));
+    fs.writeFileSync(mfP, mfOrig);
+
+    // O manifest é quem carrega o caminho — carimbado pelo instalador, não adivinhado.
+    check('manifest registra frameworkRoot absoluto', JSON.parse(mfOrig).frameworkRoot === REPO_ROOT, JSON.parse(mfOrig).frameworkRoot);
+
+    // AVISO de versão: instalação atrás do framework.
+    const { compareVersions } = require('../installer/doctor');
+    check('compareVersions ordena versões corretamente', compareVersions('0.14.9', '0.15.0') < 0 && compareVersions('0.15.0', '0.15.0') === 0 && compareVersions('0.16.0', '0.15.0') > 0);
+    const mfPath = path.join(docDir, '.power-claude', 'manifest.json');
+    const mf = JSON.parse(fs.readFileSync(mfPath, 'utf8'));
+    mf.version = '0.0.1';
+    fs.writeFileSync(mfPath, JSON.stringify(mf, null, 2));
+    const docOld = cli(['doctor'], docDir);
+    check('doctor AVISA quando a instalação está atrás do framework', /\[AVISO\].*Versão da instalação vs\. framework/.test(docOld.stdout || ''));
+    check('o AVISO de versão NÃO é bloqueante (é o gate de capacidade que bloqueia)', !/\[FALHA\].*Versão da instalação/.test(docOld.stdout || ''));
+  } finally {
+    finish(tmpdirs);
+  }
+}
+
+function finish(tmpdirs) {
+  for (const d of tmpdirs) {
+    try { fs.rmSync(d, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+  const failed = results.filter((r) => !r.ok);
+  console.log(`\n${results.length - failed.length}/${results.length} checagens passaram.`);
+  if (failed.length > 0) {
+    console.error('validate-update-scope-motor FALHOU:');
+    for (const f of failed) console.error(`  - ${f.label}${f.detail ? ` (${f.detail})` : ''}`);
+    process.exit(1);
+  }
+  console.log('validate-update-scope-motor verde.');
+  process.exit(0);
+}
+
+main();

package/scripts/veto-checks/html-valid.cjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * html-valid.cjs — veto BLESSED (forma command_check, ADR-011). Confere que o HTML do
+ * artefato tem tags BALANCEADAS (parser de balanceamento mínimo, zero-dep — não htmlhint,
+ * por decisão do ADR-011 Decisão 3) e, opcionalmente, que tags exigidas estão presentes.
+ * Caso motivador (d): o `<title>` levou 3 rodadas (SF6.2/6.3/6.4) para fechar só com
+ * heurística de memória — `--require title` mecaniza a exigência.
+ *
+ * Uso: node scripts/veto-checks/html-valid.cjs <artefato> [--require <tag>]...
+ * Exit 0 = balanceado (e requeridos presentes); exit 1 = desbalanceado/faltando; exit 2 = uso.
+ *
+ * LIMITES HONESTOS (documentados): é um balanceador de tags, NÃO um validador HTML5
+ * completo — não checa aninhamento semântico (ex.: <li> fora de <ul>), atributos, nem
+ * DOCTYPE. Prova a CLASSE "tag aberta sem fechar / fechamento órfão / tag exigida ausente",
+ * que é o defeito de campo do caso (d). Void elements e self-closing são tratados.
+ */
+
+const fs = require('node:fs');
+
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link',
+  'meta', 'param', 'source', 'track', 'wbr',
+]);
+
+/** Balanceia tags. Retorna { ok, error }. Pura, testável. */
+function checkBalance(html) {
+  // Remove comentários, <script>/<style> (conteúdo não é markup), e DOCTYPE.
+  const cleaned = html
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<script\b[\s\S]*?<\/script>/gi, '')
+    .replace(/<style\b[\s\S]*?<\/style>/gi, '')
+    .replace(/<!doctype[^>]*>/gi, '');
+  const tagRe = /<\/?([a-zA-Z][a-zA-Z0-9-]*)\b[^>]*?(\/?)>/g;
+  const stack = [];
+  let m;
+  while ((m = tagRe.exec(cleaned)) !== null) {
+    const raw = m[0];
+    const name = m[1].toLowerCase();
+    const selfClosing = m[2] === '/';
+    const isClose = raw.startsWith('</');
+    if (isClose) {
+      if (VOID_ELEMENTS.has(name)) continue; // </br> etc. é ruído inofensivo
+      if (stack.length === 0 || stack[stack.length - 1] !== name) {
+        const top = stack.length ? stack[stack.length - 1] : '(nenhuma)';
+        return { ok: false, error: `fechamento </${name}> sem abertura correspondente (topo da pilha: <${top}>)` };
+      }
+      stack.pop();
+    } else if (!selfClosing && !VOID_ELEMENTS.has(name)) {
+      stack.push(name);
+    }
+  }
+  if (stack.length > 0) {
+    return { ok: false, error: `tag(s) aberta(s) sem fechar: ${stack.map((t) => `<${t}>`).join(', ')}` };
+  }
+  return { ok: true };
+}
+
+/** Presença de uma tag (abertura) no HTML. */
+function hasTag(html, tag) {
+  return new RegExp(`<${tag}\\b`, 'i').test(html);
+}
+
+function main() {
+  const artifact = process.argv[2];
+  if (!artifact || !fs.existsSync(artifact)) {
+    console.error(`html-valid: artefato não encontrado: ${artifact}`);
+    process.exit(2);
+  }
+  const required = [];
+  const rest = process.argv.slice(3);
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--require') required.push(String(rest[++i]).toLowerCase());
+  }
+  const html = fs.readFileSync(artifact, 'utf8');
+  const bal = checkBalance(html);
+  if (!bal.ok) {
+    console.error(`html-valid BLOQUEOU: ${bal.error}`);
+    process.exit(1);
+  }
+  const missing = required.filter((t) => !hasTag(html, t));
+  if (missing.length > 0) {
+    console.error(`html-valid BLOQUEOU: tag(s) exigida(s) ausente(s): ${missing.map((t) => `<${t}>`).join(', ')}`);
+    process.exit(1);
+  }
+  console.log(`html-valid OK: tags balanceadas${required.length ? `; requeridas presentes (${required.join(', ')})` : ''}`);
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = { checkBalance, hasTag, VOID_ELEMENTS };

package/scripts/veto-checks/lexical-check.cjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * lexical-check.cjs — veto BLESSED (forma command_check, ADR-011). Conta ocorrências de
+ * um padrão lexical no artefato e BLOQUEIA se acima de um limiar. Caso motivador (b): a
+ * regressão de travessões (em/en-dash) na R5 do benchmark passou por toda heurística de
+ * memória — a máquina agora conta de verdade. Node puro, zero-dep, determinístico e síncrono
+ * (fronteira ADR-002: forma avaliável por máquina, nunca julgamento de LLM).
+ *
+ * Uso (invocado pelo runner via execFileSync, sem shell):
+ *   node scripts/veto-checks/lexical-check.cjs <artefato> [--max N] [--pattern <regex-literal>]
+ *   default: --pattern "[—–]" (em-dash U+2014 / en-dash U+2013 — o "tell" de IA) --max 0
+ * Exit 0 = dentro do limiar; exit 1 = acima (bloqueia); exit 2 = erro de uso.
+ */
+
+const fs = require('node:fs');
+
+/** Conta ocorrências de `pattern` (regex source) em `text`. Pura, testável. */
+function countMatches(text, patternSource) {
+  const re = new RegExp(patternSource, 'gu');
+  const m = text.match(re);
+  return m ? m.length : 0;
+}
+
+function parseArgs(argv) {
+  const opts = { max: 0, pattern: '[\\u2014\\u2013]' };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--max') opts.max = Number.parseInt(argv[++i], 10);
+    else if (argv[i] === '--pattern') opts.pattern = argv[++i];
+  }
+  return opts;
+}
+
+function main() {
+  const artifact = process.argv[2];
+  if (!artifact || !fs.existsSync(artifact)) {
+    console.error(`lexical-check: artefato não encontrado: ${artifact}`);
+    process.exit(2);
+  }
+  const opts = parseArgs(process.argv.slice(3));
+  if (!Number.isInteger(opts.max) || opts.max < 0) {
+    console.error(`lexical-check: --max inválido: ${opts.max}`);
+    process.exit(2);
+  }
+  let count;
+  try {
+    count = countMatches(fs.readFileSync(artifact, 'utf8'), opts.pattern);
+  } catch (e) {
+    console.error(`lexical-check: regex inválida /${opts.pattern}/: ${e.message}`);
+    process.exit(2);
+  }
+  if (count > opts.max) {
+    console.error(`lexical-check BLOQUEOU: ${count} ocorrência(s) de /${opts.pattern}/ > limiar ${opts.max}`);
+    process.exit(1);
+  }
+  console.log(`lexical-check OK: ${count} ocorrência(s) de /${opts.pattern}/ <= ${opts.max}`);
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = { countMatches, parseArgs };