@daniellins/power-claude 0.16.3

package/scripts/__tests__/validate-story-acs.test.cjs

@@ -0,0 +1,607 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * validate-story-acs.test.cjs — suíte real do validador de ACs (Story
+ * SF13.1, `ADR-031`). Roda os 47 ACs da story, incluindo os 6 fixtures do
+ * Bloco E (comportamentais, não mockados) e o controle negativo do AC-32b.
+ *
+ * DESVIO DOCUMENTADO (Dev Agent Record da story tem os detalhes completos):
+ * os fixtures literais de `AC-14` e `AC-25` usam `test -f package.json`
+ * SEM `[Guarda]` como prova/placeholder — mas essa é EXATAMENTE a forma que
+ * `AC-32b` rotula, na própria story, como *"óbvio nasce-verde"* (linha 446),
+ * e que `AC-5`/Contexto(b) exigem que o validador REPROVE quando referenciada
+ * como `[Guarda] (prova: AC-M)` sem pareamento válido. Um validador que
+ * deixasse "test -f package.json" sem guarda passar como `ok` (a leitura
+ * literal de AC-14/AC-25) reabriria a MESMA classe de defeito que a story
+ * inteira existe para fechar — e contradiria AC-5, AC-13, AC-19, AC-22 e o
+ * próprio AC-32b. Implementei a regra normativa (Contexto (b), `ADR-031`
+ * Decisão 1) e, nestes 2 casos, testo o comportamento CORRETO em vez do
+ * literal — reportado como achado, não corrigido silenciosamente na story
+ * (fora da minha autoridade de edição nesta rodada).
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const MODULE_PATH = path.join(REPO_ROOT, 'scripts', 'validate-story-acs.cjs');
+const FIXTURES_DIR = path.join(REPO_ROOT, 'scripts', '__fixtures__', 'validate-story-acs-corpus');
+
+let failures = 0;
+function assert(ok, msg, extra) {
+  if (ok) {
+    console.log(`[OK   ] ${msg}`);
+  } else {
+    console.error(`[FALHA] ${msg}${extra !== undefined ? ' :: ' + JSON.stringify(extra) : ''}`);
+    failures++;
+  }
+}
+
+function freshModule() {
+  delete require.cache[require.resolve(MODULE_PATH)];
+  return require(MODULE_PATH);
+}
+
+const f = (lines) => lines.join('\n');
+
+function run() {
+  process.chdir(REPO_ROOT);
+  const m = freshModule();
+
+  // ---------------------------------------------------------------------
+  // Bloco A — Convenção e produtor
+  // ---------------------------------------------------------------------
+  {
+    const r = m.wouldBeRefused === undefined ? null : true;
+    assert(fs.existsSync(path.join(REPO_ROOT, 'docs', 'mecanismos', 'validador-de-acs-do-ciclo.md')), 'AC-1: doc de mecanismo existe');
+  }
+  {
+    const c = fs.readFileSync(path.join(REPO_ROOT, 'template', '.claude', 'agents', 'pc-planner.md'), 'utf8');
+    assert(/oraculo|oráculo/i.test(c), 'AC-2: pc-planner.md instrui emissão da fence oraculo');
+  }
+
+  // ---------------------------------------------------------------------
+  // Bloco B — Parsing
+  // ---------------------------------------------------------------------
+  {
+    const c = f(['exemplo fora da secao:', '```oraculo', 'test -f nada', '```', '', '## Acceptance Criteria', '', '**AC-X.** d', '```oraculo', 'test -f package.json', '```']);
+    const r = m.parseAcs(c);
+    assert(r.length === 1 && r[0].id === 'AC-X', 'AC-3: parseAcs restrito à seção, sem fence aninhado', r);
+  }
+  {
+    // Achado do QA (gate `sf13.1-validador-de-acs`, finding 1a): o marcador
+    // com anotação entre colchetes (`**AC-N [novo, ...].**`) é o estilo
+    // PREDOMINANTE já convencionado no projeto — 32 dos 43 cabeçalhos reais
+    // desta própria story usam essa forma ou prosa adicional dentro do
+    // negrito. `parseAcs` tem de casar as 3 formas.
+    const c = f(['## Acceptance Criteria', '', '**AC-1 [novo, B4].** descricao simples', '```oraculo', 'test -f package.json', '```', '', '**AC-2. Corpus 1 — titulo com prosa dentro do negrito.** descricao', '```oraculo', 'test -f package.json', '```']);
+    const r = m.parseAcs(c);
+    assert(r.length === 2 && r[0].id === 'AC-1' && r[1].id === 'AC-2', 'AC-3b [novo, achado do QA]: parseAcs casa anotação entre colchetes E prosa dentro do negrito', r);
+  }
+  {
+    // Achado do QA (finding 1b): fence-aware — string de fixture embutida
+    // (contendo `**AC-A.**`/```oraculo``` como DADO literal, não marcador
+    // real) dentro do PRÓPRIO oráculo de um AC não pode virar um AC novo
+    // nem truncar o comando real. Reproduz a forma exata do AC-14/AC-5 desta
+    // story (fixture com aspas simples aninhadas via `'\''`).
+    const c = f(['## Acceptance Criteria', '', "**AC-Y.** constroi fixture em memoria", '```oraculo', `node -e 'const f=(l)=>l.join("\\\\n");const c=f(["## Acceptance Criteria","","**AC-A.** irmao","` + '```' + `oraculo","test -f package.json","` + '```' + `"]);console.log(1)'`, '```']);
+    const r = m.parseAcs(c);
+    const hasFakeAc = r.find((x) => x.id === 'AC-A');
+    assert(r.length === 1 && r[0].id === 'AC-Y' && !hasFakeAc && /console\.log\(1\)/.test(r[0].oracleCmd || ''), 'AC-3c [novo, achado do QA]: fence-aware — marcador embutido em oráculo não vira AC novo, comando não trunca', r);
+  }
+  {
+    // Achado do QA: `'\''` (idioma bash — fecha aspa, aspa literal
+    // escapada, reabre aspa) precisa tokenizar como UM caractere de aspa
+    // literal inserido no meio da string, não como um backslash espúrio —
+    // reproduz o defeito real medido em AC-10c contra a story.
+    // Monta literalmente: node -e 'console.log('\''hi'\'')'
+    const Q = "'";
+    const IDIOM = Q + '\\' + Q + Q; // os 4 chars '\''
+    const idiomCmd = 'node -e ' + Q + "console.log(" + IDIOM + 'hi' + IDIOM + ')' + Q;
+    const rIdiom = m.runOracle(idiomCmd, { cwd: process.cwd(), timeoutMs: 5000 });
+    assert(rIdiom.refused !== true && rIdiom.exitCode === 0 && rIdiom.stdout.trim() === 'hi', "AC-10g [novo, achado do QA]: idioma bash '\\'' tokeniza como aspa literal, não como backslash espúrio", rIdiom);
+
+    const rSanity = m.runOracle("node -e 'const x=1;console.log(x)'", { cwd: process.cwd(), timeoutMs: 5000 });
+    assert(rSanity.refused !== true && rSanity.exitCode === 0 && rSanity.stdout.trim() === '1', 'AC-10h [novo, achado do QA]: sanidade de aspa simples simples continua íntegra após o fix de backslash', rSanity);
+  }
+  {
+    // PROVA NA ROTA REAL (gate `sf13.1-validador-de-acs`, ação sugerida do
+    // finding 1): o CLI contra a PRÓPRIA story tem de reconhecer os 47 ACs
+    // reais, com ids reais — não 22 fantasmas. Este é o teste que teria
+    // pego o FAIL antes do QA.
+    const story = fs.readFileSync(path.join(REPO_ROOT, 'docs', 'stories', 'sf13.1.story.md'), 'utf8');
+    const acsReal = m.parseAcs(story);
+    const idsCorrompidos = acsReal.filter((a) => a.id === 'AC-X' || a.id === 'AC-A' || a.id === 'AC-B' || a.id === 'AC-Z');
+    assert(acsReal.length === 47 && idsCorrompidos.length === 0, `ROTA REAL [novo, achado do QA]: parseAcs(sf13.1.story.md).length === 47 (obtido: ${acsReal.length}), zero ids fantasma`, acsReal.map((a) => a.id));
+    const r = m.validateStory(story, { cwd: process.cwd() });
+    assert(r.total === 47, `ROTA REAL: validateStory(sf13.1.story.md).total === 47 (obtido: ${r.total})`, r);
+  }
+  {
+    const c = f(['## Acceptance Criteria', '', '**AC-X.** d', '[Guarda] (prova: AC-Z)', '```oraculo', 'test -f package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.reprovados.find((x) => x.id === 'AC-X' && /prova nomeada n(a|ã)o existe/i.test(x.motivo));
+    assert(!!hit, 'AC-4: prova nomeada inexistente reprova', r);
+  }
+  {
+    const c = f(['## Acceptance Criteria', '', '**AC-X.** d', '[Guarda] (prova: AC-A) texto livre depois nao quebra o parser', '```oraculo', 'test -f package.json', '```', '', '**AC-A.** irmao', '```oraculo', 'test -f package.json', '```']);
+    const r = m.parseAcs(c);
+    const ac = r.find((x) => x.id === 'AC-X');
+    assert(!!(ac && ac.guarda && ac.guarda.forma === 'prova' && ac.guarda.provaId === 'AC-A'), 'AC-4b: parser aceita prosa após o grupo reconhecido', ac);
+  }
+  {
+    const c = f(['## Acceptance Criteria', '', '**AC-A.** guarda', '```oraculo', 'test -f package.json', '```', '', '**AC-B.** alvo', '[Guarda] (prova: AC-A)', '```oraculo', 'test -f package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.reprovados.find((x) => x.id === 'AC-B' && /cadeia guarda/i.test(x.motivo));
+    assert(!!hit, 'AC-5: cadeia guarda→guarda proibida', r);
+  }
+  {
+    const c = f(['## Acceptance Criteria', '', '**AC-X.** d', '[Guarda] (banana)', '```oraculo', 'test -f package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.reprovados.find((x) => x.id === 'AC-X' && /forma.*n(a|ã)o reconhecida/i.test(x.motivo));
+    assert(!!hit, 'AC-5b: forma de guarda não reconhecida ⇒ REPROVA (destino pinado)', r);
+  }
+  {
+    const c = f(['## Acceptance Criteria', '', '**AC-X.** d', '[Guarda] (sem irmao - ausencia declarada)', '```oraculo', '# espera: stdout-nao-vazio', 'test -f package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.reprovados.find((x) => x.id === 'AC-X' && /forma 2|ausencia|ausência/i.test(x.motivo));
+    assert(!!hit, 'AC-6: forma "sem irmão" exige asserção de ausência', r);
+  }
+  {
+    const c = f(['## Acceptance Criteria', '', '**AC-X.** d', '[Guarda] (citacao de fato pre-existente, nao prova de trabalho)', '```oraculo', 'test -f package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const inCit = r.citacoes && r.citacoes.find((x) => x.id === 'AC-X');
+    const notInOk = !r.ok.find((x) => x.id === 'AC-X');
+    assert(!!(inCit && notInOk), 'AC-6b: citação vai para `citacoes`, nunca `ok`', r);
+  }
+  {
+    const c = '## Acceptance Criteria\n\nSem nenhum AC com bloco.';
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    assert(r.naoDeterminados && r.naoDeterminados.length === 1, 'AC-7: arquivo sem nenhum oráculo — relatório fala', r);
+  }
+
+  // ---------------------------------------------------------------------
+  // Bloco C — Execução sem shell
+  // ---------------------------------------------------------------------
+  {
+    const r = m.runOracle('test -f package.json', { cwd: process.cwd(), timeoutMs: 5000 });
+    assert(r.exitCode === 0 && typeof r.stdout === 'string' && typeof r.durationMs === 'number', 'AC-8: runOracle via execFile-família', r);
+  }
+  {
+    const r = m.runOracle('awk BEGIN{print 1}', { cwd: process.cwd(), timeoutMs: 5000 });
+    assert(r.refused === true && /n(a|ã)o consegui determinar/i.test(r.refusalReason || ''), 'AC-9: cabeçalho fora da allow-list recusa falada', r);
+  }
+  {
+    const c = f(['## Acceptance Criteria', '', '**AC-X.** d', '```oraculo', 'awk BEGIN{print 1}', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.naoDeterminados.find((x) => x.id === 'AC-X');
+    const clean = !r.ok.find((x) => x.id === 'AC-X') && !r.reprovados.find((x) => x.id === 'AC-X') && !r.alertas.find((x) => x.id === 'AC-X');
+    assert(!!(hit && clean), 'AC-9b: recusa/timeout ⇒ naoDeterminados no relatório agregado', r);
+  }
+  {
+    const r = m.runOracle('grep -c a package.json | wc -l', { cwd: process.cwd(), timeoutMs: 5000 });
+    assert(r.refused === true, 'AC-10: metacaractere fora de aspas ⇒ recusa', r);
+  }
+  {
+    const r = m.runOracle('grep -c "a\\|b" package.json', { cwd: process.cwd(), timeoutMs: 5000 });
+    const ran = r.refused !== true && r.exitCode === 0 && typeof r.stdout === 'string' && r.stdout.trim().length > 0;
+    assert(ran, 'AC-10b: metacaractere dentro de aspas duplas roda de fato', r);
+  }
+  {
+    const r = m.runOracle("node -e 'console.log(1)'", { cwd: process.cwd(), timeoutMs: 5000 });
+    const ran = r.refused !== true && r.exitCode === 0 && r.stdout.trim() === '1';
+    assert(ran, 'AC-10c: aspa simples (forma dominante) roda de fato', r);
+  }
+  {
+    // AC-10d ENDURECIDO (gate `sf13.1-validador-de-acs`, findings 1/2): a
+    // asserção original (`refusals.length === 0`) é satisfazível por um
+    // array CORROMPIDO (parseAcs cortando cabeçalhos errado) tão facilmente
+    // quanto por um array correto — 0 recusas sobre 22 fantasmas também é
+    // 0. Isso é vacuidade na camada do PARSER, a mesma classe que a regra
+    // de convergência existe para impedir, só que um nível abaixo de onde
+    // ela mirava. Fecho: cruzar `parseAcs().length` com uma contagem
+    // INDEPENDENTE de cabeçalhos reais (`**AC-<id>` em início de linha,
+    // fora de fence — mesma definição normativa, mas sem reusar
+    // `parseAcs`/`AC_HEADER_RE` internamente: contada aqui por regex
+    // própria e comparada ao número publicado pela própria story, 47).
+    const story = fs.readFileSync(path.join(REPO_ROOT, 'docs', 'stories', 'sf13.1.story.md'), 'utf8');
+    const acs = m.parseAcs(story);
+    const refusals = acs.filter((a) => a.oracleCmd && m.wouldBeRefused(a.oracleCmd).refused);
+    const section = m.extractAcSection(story);
+    const fencedRanges = [];
+    {
+      const fre = /^```[^\n]*\n[\s\S]*?^```[ \t]*$/gm;
+      let fm;
+      while ((fm = fre.exec(section))) fencedRanges.push([fm.index, fm.index + fm[0].length]);
+    }
+    const headerRe = /^\*\*(AC-[A-Za-z0-9]+)\b/gm;
+    let hm;
+    let independentCount = 0;
+    while ((hm = headerRe.exec(section))) {
+      const insideFence = fencedRanges.some(([s2, e2]) => hm.index >= s2 && hm.index < e2);
+      if (!insideFence) independentCount += 1;
+    }
+    const noVacuidade = acs.length === independentCount && acs.length === 47;
+    assert(refusals.length === 0 && noVacuidade, `AC-10d: anti-vacuidade PURA — parseAcs().length (${acs.length}) === contagem independente (${independentCount}) === 47 publicado na story, E zero recusas`, { refusals, parsedCount: acs.length, independentCount });
+  }
+  {
+    const a = m.wouldBeRefused('awk BEGIN{print 1}');
+    const b = m.wouldBeRefused('grep -c a package.json | wc -l');
+    assert(a.refused === true && b.refused === true, 'AC-10e: wouldBeRefused — controle negativo (as 2 causas)', [a, b]);
+  }
+  {
+    const cmd1 = 'awk BEGIN{print 1}';
+    const cmd2 = 'test -f package.json';
+    const wA = m.wouldBeRefused(cmd1).refused;
+    const wB = m.wouldBeRefused(cmd2).refused;
+    const rA = m.runOracle(cmd1, { cwd: process.cwd(), timeoutMs: 5000 }).refused;
+    const rB = m.runOracle(cmd2, { cwd: process.cwd(), timeoutMs: 5000 }).refused;
+    assert(wA === true && rA === true && wB !== true && rB !== true, 'AC-10f: runOracle delega a wouldBeRefused (fonte única)', [wA, rA, wB, rB]);
+  }
+  {
+    const r = m.runOracle('git push origin main', { cwd: process.cwd(), timeoutMs: 5000 });
+    assert(r.refused === true, 'AC-11: sub-allow-list de git recusa push/commit/checkout/reset', r);
+  }
+  {
+    const r = m.runOracle('node -e "setInterval(function(){},1000)"', { cwd: process.cwd(), timeoutMs: 200 });
+    assert(r.timedOut === true, 'AC-12: timeout mata o processo filho', r);
+  }
+  {
+    const prevDepth = process.env.VSA_DEPTH;
+    process.env.VSA_DEPTH = '1';
+    const m2 = freshModule();
+    const c = f(['## Acceptance Criteria', '', '**AC-X.** d', '```oraculo', 'test -f package.json', '```']);
+    const r = m2.validateStory(c, { cwd: process.cwd() });
+    const hit = r.naoDeterminados.find((x) => x.id === 'AC-X' && x.causa === 'reentrancia');
+    assert(!!hit, 'AC-12b: guarda de reentrância — metade CONSUMIDORA', r);
+    if (prevDepth === undefined) delete process.env.VSA_DEPTH; else process.env.VSA_DEPTH = prevDepth;
+    freshModule();
+  }
+  {
+    const r = m.runOracle('node -e "console.log(process.env.VSA_DEPTH)"', { cwd: process.cwd(), timeoutMs: 5000 });
+    assert(r.stdout.trim() === '1', 'AC-12c: guarda de reentrância — metade PRODUTORA (env propagado)', r);
+  }
+
+  // ---------------------------------------------------------------------
+  // Bloco D — Classificação
+  // ---------------------------------------------------------------------
+  {
+    const c = f(['## Acceptance Criteria', '', '**AC-X.** d', '```oraculo', '# espera: stdout == 0', 'grep -c zzz-termo-inexistente-xyz package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.reprovados.find((x) => x.id === 'AC-X' && /nasce verde/i.test(x.motivo));
+    assert(!!hit, 'AC-13: nasce verde é a asserção declarada, não o exit code', r);
+  }
+  {
+    // DESVIO DOCUMENTADO (ver cabeçalho do arquivo): o AC-14 literal da story
+    // usa AC-A = `test -f package.json` SEM guarda como "prova" — que é
+    // exatamente o padrão que AC-5/AC-32b definem como nasce-verde óbvio.
+    // Testo o comportamento CORRETO (cadeia bloqueada) em vez do literal.
+    const c = f(['## Acceptance Criteria', '', '**AC-A.** irmao', '```oraculo', 'test -f package.json', '```', '', '**AC-X.** d', '[Guarda] (prova: AC-A)', '```oraculo', '# espera: stdout == 0', 'grep -c zzz-termo-inexistente-xyz package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const acA = r.reprovados.find((x) => x.id === 'AC-A' && /nasce verde/i.test(x.motivo));
+    const acX = r.reprovados.find((x) => x.id === 'AC-X' && /cadeia guarda/i.test(x.motivo));
+    assert(!!(acA && acX), 'AC-14 [DESVIO — ver cabeçalho]: prova apontando para alvo também nasce-verde é bloqueada, consistente com AC-5/AC-32b', r);
+  }
+  {
+    const s1 = 'node:internal/modules/cjs/loader:1573\n  throw err;\nError: Cannot find module x\n    at Module._resolveFilename (node:internal/modules/cjs/loader:1569:15)\n    at a (node:internal/modules/cjs/loader:1123:27)\n    at b (node:internal/modules/cjs/loader:1147:10)\n    at c (node:internal/modules/cjs/loader:1174:12)\n    at d (node:internal/modules/cjs/loader:1346:5)\n    at e (node:internal/modules/cjs/loader:261:19)\n    at f (node:internal/main/run_main_module:33:47) {\n  code: "MODULE_NOT_FOUND"\n}';
+    const r1 = m.isCrash({ exitCode: 1, stderr: s1 });
+    const s2 = "TypeError: Cannot read properties of undefined (reading X)\n    at Object.buildWorkflowYaml (scripts/forge-generate.cjs:398:9)";
+    const r2 = m.isCrash({ exitCode: 1, stderr: s2 });
+    assert(r1.crash === false && r2.crash === true, 'AC-15: precedência normativa de isCrash', [r1, r2]);
+  }
+  {
+    const c = f(['## Acceptance Criteria', '', '**AC-X.** d', '```oraculo', 'grep -c zzz-termo-inexistente-xyz package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.alertas.find((x) => x.id === 'AC-X' && /no-op/i.test(x.motivo));
+    assert(!!hit, 'AC-16: padrão de contagem ingênua ⇒ ALERTA no-op', r);
+  }
+  {
+    const a = m.evaluateAssertion({ exitCode: 1, stdout: '', stderr: '' }, { type: 'exit!=0' });
+    const b = m.evaluateAssertion({ exitCode: 0, stdout: '', stderr: '' }, { type: 'exit!=0' });
+    const c = m.evaluateAssertion({ exitCode: 0, stdout: 'x', stderr: '' }, { type: 'stdout-nao-vazio' });
+    const d = m.evaluateAssertion({ exitCode: 0, stdout: '', stderr: '' }, { type: 'stdout-nao-vazio' });
+    assert(a === true && b === false && c === true && d === false, 'AC-16b: as 5 formas de # espera — controle positivo e negativo', [a, b, c, d]);
+  }
+  {
+    const c = f(['## Status', '', 'InReview', '', '## Acceptance Criteria', '', '**AC-X.** d', '```oraculo', 'test -f package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.naoDeterminados.find((x) => x.id === 'AC-X' && x.causa === 'nasce-verde-pos-trabalho');
+    assert(!!hit, 'AC-16c: nasce verde é classe datada — InReview suspende', r);
+  }
+  {
+    const c = f(['## Acceptance Criteria', '', '**AC-X.** d', '```oraculo', '# espera: stdout-vazia', 'test -f package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.naoDeterminados.find((x) => x.id === 'AC-X' && x.causa === 'assercao-desconhecida');
+    const notOk = !r.ok.find((x) => x.id === 'AC-X');
+    assert(!!(hit && notOk), 'AC-16e: typo em # espera NUNCA cai no default exit0', r);
+  }
+  {
+    const c = f(['## Status', '', 'InReview', '', '## Acceptance Criteria', '', '**AC-X.** d', '```oraculo', 'node -e "null.x"', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.reprovados.find((x) => x.id === 'AC-X' && /comando quebrado/i.test(x.motivo));
+    assert(!!hit, 'AC-16d: gate por CLASSE — crash continua REPROVA em InReview', r);
+  }
+
+  // ---------------------------------------------------------------------
+  // Bloco E — Meta-prova: 5 corpus reais, comportamentais
+  // ---------------------------------------------------------------------
+  {
+    const c = fs.readFileSync(path.join(FIXTURES_DIR, 'corpus-1-noop-state-json.fixture.md'), 'utf8');
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.alertas.find((x) => /no-op/i.test(x.motivo));
+    assert(!!hit, 'AC-17: Corpus 1 (sf12.4b, no-op) — rodado de verdade', r);
+  }
+  {
+    const c = fs.readFileSync(path.join(FIXTURES_DIR, 'corpus-2-crash-buildworkflowyaml.fixture.md'), 'utf8');
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.reprovados.find((x) => /comando quebrado/i.test(x.motivo) && /TypeError/i.test(x.motivo));
+    assert(!!hit, 'AC-18: Corpus 2 (sf12.5a, crash) — TypeError real citado', r);
+  }
+  {
+    const c = fs.readFileSync(path.join(FIXTURES_DIR, 'corpus-3-nasce-verde-skip-modes.fixture.md'), 'utf8');
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.reprovados.find((x) => x.id === 'AC-3a' && /nasce verde/i.test(x.motivo));
+    assert(!!hit, 'AC-19: Corpus 3a (sem guarda) — REPROVA nasce verde', r);
+  }
+  {
+    const c = fs.readFileSync(path.join(FIXTURES_DIR, 'corpus-3-nasce-verde-skip-modes.fixture.md'), 'utf8');
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const bad = r.reprovados.find((x) => x.id === 'AC-3b');
+    assert(!bad, 'AC-20: Corpus 3b (com guarda) — NÃO reprova', r);
+  }
+  {
+    const c = fs.readFileSync(path.join(FIXTURES_DIR, 'corpus-4-guarda-sem-irmao.fixture.md'), 'utf8');
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const bad = r.reprovados.find((x) => x.id === 'AC-4');
+    assert(!bad, 'AC-21: Corpus 4 (guarda sem irmão possível) — NÃO reprova', r);
+  }
+  {
+    const c = fs.readFileSync(path.join(FIXTURES_DIR, 'corpus-5a-diff-stat-sem-guarda.fixture.md'), 'utf8');
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const hit = r.reprovados.find((x) => x.id === 'AC-5a' && /nasce verde/i.test(x.motivo));
+    assert(!!hit, 'AC-22: Corpus 5a (git diff --stat sob exit-code puro) — REPROVA', r);
+  }
+  {
+    const c = fs.readFileSync(path.join(REPO_ROOT, 'docs', 'mecanismos', 'validador-de-acs-do-ciclo.md'), 'utf8');
+    assert(/Corpus 5b/.test(c), 'AC-23: fronteira Corpus 5b declarada no doc de mecanismo', null);
+  }
+  {
+    let n = 0;
+    try {
+      n = fs.readdirSync(FIXTURES_DIR).filter((x) => x.endsWith('.fixture.md')).length;
+    } catch (e) { n = 0; }
+    assert(n === 6, 'AC-24: os 6 arquivos de fixture existem', n);
+  }
+
+  // ---------------------------------------------------------------------
+  // Bloco F — Relatório, CLI, integração com o PO
+  // ---------------------------------------------------------------------
+  {
+    // DESVIO DOCUMENTADO (ver cabeçalho do arquivo): AC-25 usa AC-A = `test
+    // -f package.json` SEM guarda esperando `ok` — mesmo padrão do AC-14,
+    // contradiz AC-5/AC-32b. Testo a categoria ALERTA (que não depende do
+    // caso conflitante) e confirmo que a AC nasce-verde é corretamente
+    // reprovada (não silenciada) — total conta as 2 entradas roteadas.
+    const c = f(['## Acceptance Criteria', '', '**AC-A.** ok', '```oraculo', 'test -f package.json', '```', '', '**AC-B.** alerta', '```oraculo', 'grep -c zzz-termo-inexistente-xyz package.json', '```']);
+    const r = m.validateStory(c, { cwd: process.cwd() });
+    const alOk = r.alertas.find((x) => x.id === 'AC-B');
+    const acAReprovado = r.reprovados.find((x) => x.id === 'AC-A' && /nasce verde/i.test(x.motivo));
+    assert(!!(alOk && acAReprovado && r.total === 2), 'AC-25 [DESVIO — ver cabeçalho]: relatório agregado com total/ok/reprovados/alertas corretos', r);
+  }
+  {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vsa-'));
+    // `test -f package.json` sem guarda seria nasce-verde (mesma classe do
+    // desvio AC-14/AC-25 — ver cabeçalho do arquivo); aqui a asserção
+    // precisa ser genuinamente FALSA hoje para cair em `ok` sem ambiguidade.
+    const bodyOk = f(['## Acceptance Criteria', '', '**AC-A.** ok', '```oraculo', 'test -f arquivo-que-nao-existe-vsa-fixture.txt', '```']);
+    const bodyAlerta = f(['## Acceptance Criteria', '', '**AC-B.** alerta', '```oraculo', 'grep -c zzz-termo-inexistente-xyz package.json', '```']);
+    fs.writeFileSync(path.join(dir, 'a.story.md'), bodyOk);
+    fs.writeFileSync(path.join(dir, 'b.story.md'), bodyAlerta);
+    const r = m.validateStoryBatch(dir, { cwd: process.cwd() });
+    // Positivo: 2 arquivos DIFERENTES agregados de fato (não só a contagem
+    // de arquivos) — 1 ok de a.story.md + 1 alerta de b.story.md somados.
+    const agregouOk = r.ok.find((x) => x.id === 'AC-A');
+    const agregouAlerta = r.alertas.find((x) => x.id === 'AC-B');
+    assert(r.files === 2 && r.total === 2 && !!agregouOk && !!agregouAlerta, 'AC-26: validateStoryBatch agrega ok+alertas de 2 arquivos DIFERENTES (não só files===2)', r);
+  }
+  {
+    // AC-26 CONTROLE NEGATIVO (finding 4 do gate — regra de convergência:
+    // validateStoryBatch só tinha caso positivo). Diretório real, sem
+    // NENHUM `*.story.md` — glob vazio não pode virar exceção nem contar
+    // como se tivesse processado algo.
+    const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vsa-empty-'));
+    fs.writeFileSync(path.join(emptyDir, 'nota.txt'), 'não é story');
+    const r = m.validateStoryBatch(emptyDir, { cwd: process.cwd() });
+    assert(r.files === 0 && r.total === 0 && r.ok.length === 0 && r.reprovados.length === 0, 'AC-26 [controle negativo]: diretório sem *.story.md — files=0, sem exceção', r);
+  }
+  {
+    const c = fs.readFileSync(path.join(REPO_ROOT, 'template', '.claude', 'skills', 'pc-validate-story', 'SKILL.md'), 'utf8');
+    const i = c.indexOf('ACs testaveis e rastreaveis');
+    const i2 = c.indexOf('ACs testáveis e rastreáveis');
+    const idx = i >= 0 ? i : i2;
+    const near = idx >= 0 ? c.slice(idx, idx + 600) : '';
+    assert(idx >= 0 && near.indexOf('validate-story-acs') >= 0, 'AC-27: SKILL.md ancora a instrução no item 3', null);
+  }
+  {
+    const r = m.runOracle('node scripts/validate-story-acs.cjs /caminho/que/nao/existe.story.md', { cwd: process.cwd(), timeoutMs: 5000 });
+    const noRawTrace = !/at Object\.|at Module\._compile|node:internal/.test(r.stderr || '');
+    assert(r.exitCode !== 0 && noRawTrace, 'AC-28: CLI sobre arquivo inexistente — erro limpo, sem stack cru', r);
+  }
+
+  // ---------------------------------------------------------------------
+  // Bloco G — Guardas gerais / auto-referência com controle negativo
+  // ---------------------------------------------------------------------
+  {
+    // SF12.6/ADR-030 Bloco C/D: `scripts/forge-generate.cjs` deixou de ser "motor congelado"
+    // — é o GERADOR de pods (`*new`/`*upgrade-pod`/`*migrate-squad`/`*harden-learning`), que
+    // evolui a cada story da linha ADR-030 (SF12.4a/SF12.4b/SF12.5a/SF12.5b/SF12.6...). Um
+    // AC permanente que exige "eternamente intocado" quebraria toda story futura que o toque
+    // legitimamente — retirado do escopo desta checagem; DF2-1 (zero linha de motor) segue
+    // provado para os 2 scripts de RUNTIME (pc-run-pod.cjs/validate-pod-workflow.cjs), que são
+    // os que a decisão original (SF11.11) de fato cobria.
+    const r = m.runOracle('git diff --stat -- scripts/pc-run-pod.cjs scripts/validate-pod-workflow.cjs', { cwd: process.cwd(), timeoutMs: 5000 });
+    assert(r.refused !== true && r.stdout.trim() === '', 'AC-29: motor de runtime intocado (DF2-1) — git diff --stat vazio (pc-run-pod.cjs/validate-pod-workflow.cjs; forge-generate.cjs evolui por story, SF12.6)', r);
+  }
+  {
+    const c = fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8');
+    assert(/validate-story-acs/.test(c), 'AC-30: package.json referencia validate-story-acs no scripts.test', null);
+  }
+  {
+    const c = fs.readFileSync(path.join(REPO_ROOT, 'docs', 'mecanismos', 'validador-de-acs-do-ciclo.md'), 'utf8');
+    assert(/vocabulario|vocabulário/i.test(c), 'AC-31: fronteiras declaradas (vocabulário + Corpus 5b) no doc', null);
+  }
+  {
+    const mutant = f(['## Acceptance Criteria', '', '**AC-M.** mutante', '```oraculo', 'test -f package.json', '```']);
+    const rm = m.validateStory(mutant, { cwd: process.cwd() });
+    const mutantCaught = rm.reprovados.find((x) => x.id === 'AC-M' && /nasce verde/i.test(x.motivo));
+    assert(!!mutantCaught, 'AC-32b: controle negativo — mutante nasce-verde é REPROVADO', rm);
+  }
+
+  // ---------------------------------------------------------------------
+  // Story SF13.7 — `parseGuarda` distingue CITAÇÃO (code span / fence) de USO
+  // real. Cada caso vem PAREADO: o que NÃO deve ser reconhecido junto com o
+  // que DEVE — um fix que simplesmente parasse de reconhecer `[Guarda]`
+  // zeraria os falsos positivos e cegaria o instrumento, e é exatamente isso
+  // que os controles positivos abaixo impedem de passar.
+  // ---------------------------------------------------------------------
+  {
+    // --- Controle NEGATIVO: citação entre crases não é uso (AC-1) ---
+    const body = [
+      'descricao cita `[Guarda] (prova: AC-CITADO)` como exemplo, mas o guarda real eh outro:',
+      '[Guarda] (sem irmao - ausencia declarada)',
+      '```oraculo',
+      '# espera: stdout-vazio',
+      'test -f arquivo-que-nao-existe-xyz123',
+      '```',
+    ].join('\n');
+    const g = m.parseGuarda(body);
+    assert(
+      !!g && g.forma === 'sem-irmao',
+      'SF13.7/AC-1: citação em code span é ignorada e vence o uso REAL da linha seguinte',
+      g,
+    );
+  }
+  {
+    // --- Controle POSITIVO pareado: uso real SEM citação segue reconhecido ---
+    const body = ['descricao real do AC.', '[Guarda] (prova: AC-A)', '```oraculo', 'test -f package.json', '```'].join('\n');
+    const g = m.parseGuarda(body);
+    assert(
+      !!g && g.forma === 'prova' && g.provaId === 'AC-A',
+      'SF13.7/AC-2: controle positivo — `[Guarda] (prova: AC-A)` sem citação continua reconhecido',
+      g,
+    );
+  }
+  {
+    // --- Controle POSITIVO das outras 2 formas (o fix não cega a família) ---
+    const semIrmao = m.parseGuarda('d\n[Guarda] (sem irmão — ausência declarada)\n');
+    const citacao = m.parseGuarda('d\n[Guarda] (citação de fato pré-existente, não prova de trabalho)\n');
+    const desconhecida = m.parseGuarda('d\n[Guarda] (banana)\n');
+    assert(
+      semIrmao && semIrmao.forma === 'sem-irmao'
+        && citacao && citacao.forma === 'citacao'
+        && desconhecida && desconhecida.forma === 'desconhecida',
+      'SF13.7/AC-2b: as 3 formas + a não reconhecida continuam classificadas quando o uso é real',
+      { semIrmao, citacao, desconhecida },
+    );
+  }
+  {
+    // --- SF13.9/M5: o caso que a restrição de "mesma linha" de
+    //     `computeInlineCodeRanges` de fato protege. Fixture e asserção exatas
+    //     do gate `sf13.7-conserto-do-instrumento.yaml`
+    //     (`finding_4_julgamento.teste_que_mata_M5`), executadas pelo QA nas
+    //     duas direções: COM a restrição dá `AC-A`; SEM ela dá `null`.
+    //     Existe porque `AC-29` de `sf13.1` — o caso que o comentário do fonte
+    //     citava — NÃO exercita a restrição: sob M5 ele continua `sem-irmao` e
+    //     nenhum AC ficava vermelho, então o mutante sobrevivia. ---
+    const body = [
+      'prosa com crase orfa ` aberta aqui',
+      '[Guarda] (prova: AC-A)',
+      'mais prosa com ` outra crase',
+      '```oraculo',
+      'test -f package.json',
+      '```',
+    ].join('\n');
+    const g = m.parseGuarda(body);
+    assert(
+      !!g && g.forma === 'prova' && g.provaId === 'AC-A',
+      'SF13.9/M5: crase órfã não pareia ATRAVÉS de linhas — o guarda REAL entre as duas continua reconhecido (AC-A)',
+      g,
+    );
+  }
+  {
+    // --- Citação DENTRO de fence (fixture literal em ```oraculo) não é uso ---
+    const body = ['descricao sem guarda propria.', '```oraculo', 'node -e \'const c="[Guarda] (prova: AC-Z)";\'', '```'].join('\n');
+    assert(
+      m.parseGuarda(body) === null,
+      'SF13.7/AC-1b: `[Guarda]` como dado literal dentro da fence do oráculo não é etiqueta aplicada',
+      m.parseGuarda(body),
+    );
+  }
+  {
+    // --- Precedência: escolhe a ocorrência REAL, não a primeira TEXTUAL ---
+    const body = ['cita `[Guarda] (prova: AC-CITADO)` na prosa', '[Guarda] (prova: AC-REAL)', '```oraculo', 'test -f package.json', '```'].join('\n');
+    const g = m.parseGuarda(body);
+    assert(
+      !!g && g.provaId === 'AC-REAL',
+      'SF13.7/AC-1c: citação e uso com textos DIFERENTES — vence o uso real, não o 1º match textual',
+      g,
+    );
+  }
+  {
+    // --- Regressão no corpus REAL: AC-29 de sf13.1 (citação e uso idênticos,
+    //     em linhas consecutivas) continua classificado `sem-irmao` (AC-3) ---
+    const c = fs.readFileSync(path.join(REPO_ROOT, 'docs', 'stories', 'sf13.1.story.md'), 'utf8');
+    const ac29 = m.parseAcs(c).find((a) => a.id === 'AC-29');
+    assert(
+      !!ac29 && !!ac29.guarda && ac29.guarda.forma === 'sem-irmao',
+      'SF13.7/AC-3: corpus real — AC-29 de sf13.1 (citação + uso idênticos) mantém `sem-irmao`',
+      ac29 && ac29.guarda,
+    );
+  }
+  {
+    // --- Corpus real, contabilidade COMPLETA (não amostra): a única guarda
+    //     REAL de sf13.1 é a do AC-29; as outras 8 eram citação em code span.
+    //     É o que prova que o fix não removeu nenhum verdadeiro positivo. ---
+    const c = fs.readFileSync(path.join(REPO_ROOT, 'docs', 'stories', 'sf13.1.story.md'), 'utf8');
+    const comGuarda = m.parseAcs(c).filter((a) => a.guarda).map((a) => a.id);
+    assert(
+      comGuarda.length === 1 && comGuarda[0] === 'AC-29',
+      'SF13.7/AC-4: corpus real sf13.1 — exatamente 1 guarda real reconhecida (AC-29)',
+      comGuarda,
+    );
+  }
+  {
+    // --- Campos que o HOOK consome não mudam com o fix (fundamento do
+    //     gatilho `pc-architect` NÃO ATIVO, AC-6): `parseGuarda` só altera
+    //     `.guarda`, nunca `hasOraculo`/`oracleCmd`/`oracleEmpty`/`espera`. ---
+    const c = f([
+      '## Acceptance Criteria',
+      '',
+      '**AC-X.** cita `[Guarda] (prova: AC-CITADO)` na prosa',
+      '```oraculo',
+      '# espera: stdout == OK',
+      'test -f package.json',
+      '```',
+    ]);
+    const ac = m.parseAcs(c).find((a) => a.id === 'AC-X');
+    assert(
+      !!ac && ac.hasOraculo === true && ac.oracleCmd === 'test -f package.json'
+        && ac.oracleEmpty === false && !!ac.espera && ac.espera.type === 'stdout==',
+      'SF13.7/AC-6: campos consumidos pelo hook (hasOraculo/oracleCmd/oracleEmpty/espera) intactos',
+      ac,
+    );
+  }
+
+  // ---------------------------------------------------------------------
+  // Sumário
+  // ---------------------------------------------------------------------
+  if (failures > 0) {
+    console.error(`\n${failures} asserção(ões) falharam.`);
+    process.exitCode = 1;
+  } else {
+    console.log('\nTodas as asserções passaram.');
+  }
+}
+
+run();