@daniellins/power-claude 0.16.3

package/scripts/validate-story-acs.cjs

@@ -0,0 +1,862 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * POWER CLAUDE — validate-story-acs.cjs (Story SF13.1, `ADR-031`)
+ *
+ * Dado o texto de uma story, roda de fato os oráculos que ela declara (bloco
+ * ` ```oraculo `, convenção v1.5 — comando + `# espera:`) e classifica cada
+ * AC em: `ok` | `reprovados` (nasce verde / comando quebrado) | `alertas`
+ * (oráculo pode ser no-op) | `citacoes` (Guarda forma 3, não conta como
+ * cobertura) | `semOraculo` (AC sem bloco — fora do alcance) |
+ * `naoDeterminados` (recusa/timeout/reentrância/typo/pós-trabalho/fence
+ * vazia — "não consegui determinar", nunca "passou" nem "falhou").
+ *
+ * Execução SEM shell (`ADR-031` D2): `spawnSync` (mesma família de
+ * `execFile*` — nunca `exec`/`shell:true`) com argv TOKENIZADO (aspas
+ * simples/duplas respeitadas); allow-list de cabeçalho + sub-allow-list de
+ * `git`; metacaractere de shell FORA DE ASPAS ⇒ recusa sem executar,
+ * relatório fala. A admissibilidade é decidida por `wouldBeRefused`, função
+ * PURA (zero subprocesso — `ADR-031` Emenda 7) — `runOracle` delega a ela
+ * como fonte única (Emenda 10, `AC-10f`).
+ *
+ * "Nasce verde" é a asserção declarada já ser verdadeira hoje contra o
+ * disco — não o exit code puro (`ADR-031` D1). É classe DATADA (Emenda 2):
+ * `## Status` `Draft`/`Ready` decide; `InReview`/`Done` suspende só o
+ * veredito de nasce-verde (`naoDeterminados`, causa
+ * `nasce-verde-pos-trabalho`); sem `## Status` ⇒ pré-trabalho. Comando
+ * quebrado e no-op são independentes do tempo — nunca suspensos (Emenda 4).
+ *
+ * Guarda de reentrância (Emenda 7, obrigatória de qualquer modo — a SF13.2
+ * roda isto por hook): `VSA_DEPTH` propagado no `env` de cada subprocesso
+ * (produtor, `AC-12c`); se o PRÓPRIO processo que chama `validateStory` já
+ * tem `VSA_DEPTH >= 1`, nenhum oráculo executa (consumidor, `AC-12b`) —
+ * tudo cai em `naoDeterminados`, `causa: "reentrancia"`.
+ *
+ * `causa` (campo estrutural de `naoDeterminados`, enum FECHADO de 7 —
+ * Emendas 8/11/12 + N12): `recusa` | `timeout` | `nasce-verde-pos-trabalho`
+ * | `reentrancia` | `arquivo-sem-oraculo` | `assercao-desconhecida` |
+ * `oraculo-vazio`. Nenhum consumidor filtra `naoDeterminados` por regex
+ * sobre `motivo` (Emenda 8) — o campo estrutural é o contrato. `# espera:`
+ * presente e não reconhecido NUNCA cai no default `exit0` (Emenda 11,
+ * `AC-16e`) — vira `assercao-desconhecida`, falado.
+ *
+ * `[Guarda]` — 3 formas endurecidas (B8): `(prova: AC-M)` (AC-M existe e
+ * NÃO é ele mesmo nasce-verde — proíbe cadeia guarda→guarda, `AC-5`);
+ * `(sem irmão — ausência declarada)` (só quando a asserção do próprio AC é
+ * de ausência, `stdout-vazio`/`stdout == 0`, `AC-6`); `(citação de fato
+ * pré-existente, não prova de trabalho)` (sempre em `citacoes`, nunca conta
+ * como cobertura, `AC-6b`). Forma NÃO reconhecida ⇒ REPROVA "forma de
+ * guarda não reconhecida" — destino pinado (Emenda 11, `AC-5b`).
+ *
+ * Escopo do parser: só dentro de `## Acceptance Criteria`, sem descer em
+ * fence aninhado antes da seção (`ADR-031` D2 item 6, B5).
+ *
+ * O instrumento não é seu próprio primeiro cliente (`ADR-031` Emenda 5/D1)
+ * — não há AC nesta story que rode `validateStory` sobre o próprio texto
+ * dela (isso seria reentrância, não auditoria); a 1ª aplicação real do
+ * self-check nasce-verde é a validação do PO da SF13.2.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const cp = require('node:child_process');
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+// `cwd` DECLARADO, nunca ambiente (`ADR-032` `DF-SF13.2-5` parte 2, SF13.2).
+//
+// A convenção documentada sempre disse "os oráculos são executados a partir
+// da raiz do repositório", mas o código presumia `process.cwd()` — duas
+// verdades diferentes. Medido antes do fix, mesma story, mesmo comando
+// (`test -f package.json` sem `[Guarda]`): invocado da raiz ⇒ `reprovados=1`
+// (nasce-verde corretamente detectado); invocado de `docs/` ⇒ `reprovados=0`
+// (o comando roda relativo a `docs/`, `package.json` não existe ali, e o
+// relatório sai limpo por engano). Um PO que abra o terminal na pasta do
+// arquivo — comportamento default de vários editores — lê um relatório que
+// PARECE verde e não é: exatamente a classe de falha silenciosa que a trava
+// de `Ready` existe para matar, aqui no próprio instrumento.
+//
+// `scripts/` é sempre 1 nível abaixo da raiz, no framework e na instalação
+// (ao contrário de `template/.claude/hooks/`, cuja profundidade muda) — por
+// isso a âncora em `__dirname` é determinística. Todo ponto que antes caía
+// em `process.cwd()` passa a cair aqui; quem quiser outra raiz continua
+// podendo declará-la por `opts.cwd`.
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+const HEADER_ALLOWLIST = new Set([
+  'test', 'grep', 'node', 'git', 'npm', 'ls', 'cat', 'wc', 'diff', 'head', 'tail', 'jq',
+]);
+
+const GIT_SUB_ALLOWLIST = new Set(['diff', 'log', 'status', 'ls-files', 'show']);
+
+const NAO_DETERMINADOS_CAUSAS = new Set([
+  'recusa',
+  'timeout',
+  'nasce-verde-pos-trabalho',
+  'reentrancia',
+  'arquivo-sem-oraculo',
+  'assercao-desconhecida',
+  'oraculo-vazio',
+]);
+
+function stripAccents(text) {
+  return String(text || '').normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+}
+
+// ---------------------------------------------------------------------------
+// `## Status` — mesmo precedente de `enforce-cycle-authority.cjs`
+// ---------------------------------------------------------------------------
+
+function normalizeStatusText(text) {
+  return String(text || '').replace(/\*\*/g, '').toLowerCase().trim();
+}
+
+function extractStatusSection(content) {
+  const match = /^##\s*Status\s*\n([\s\S]*?)(?=\n#{1,2}\s|\s*$)/m.exec(String(content || ''));
+  return match ? match[1] : '';
+}
+
+function readStoryStatus(content) {
+  const section = extractStatusSection(content);
+  if (!section) return null; // sem `## Status` — pré-trabalho (mutante/fixture isolado)
+  return normalizeStatusText(section);
+}
+
+function statusSuspendsNasceVerde(content) {
+  const status = readStoryStatus(content);
+  if (status === null) return false; // sem `## Status` ⇒ pré-trabalho
+  return status.includes('inreview') || status.includes('done');
+}
+
+// ---------------------------------------------------------------------------
+// Tokenização de argv (aspas simples/duplas respeitadas) + metacaractere
+// FORA de aspas (`ADR-031` Emenda 1) — usadas por `wouldBeRefused` E `runOracle`.
+// ---------------------------------------------------------------------------
+
+function tokenizeCommand(cmd) {
+  const tokens = [];
+  let current = '';
+  let started = false;
+  let inSingle = false;
+  let inDouble = false;
+  const s = String(cmd || '');
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inSingle) {
+      if (ch === "'") { inSingle = false; } else { current += ch; }
+      continue;
+    }
+    if (inDouble) {
+      if (ch === '"') { inDouble = false; } else { current += ch; }
+      continue;
+    }
+    if (ch === "'") { inSingle = true; started = true; continue; }
+    if (ch === '"') { inDouble = true; started = true; continue; }
+    // Backslash FORA de aspas escapa o PRÓXIMO caractere literalmente — é o
+    // que faz o idioma bash `'\''` (fechar aspa, aspa literal, reabrir aspa)
+    // funcionar como concatenação, em vez de inserir um backslash espúrio
+    // (achado do QA, gate `sf13.1-validador-de-acs`: AC-10c corrompido).
+    if (ch === '\\' && i + 1 < s.length) {
+      current += s[i + 1];
+      started = true;
+      i += 1;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (started) { tokens.push(current); current = ''; started = false; }
+      continue;
+    }
+    current += ch;
+    started = true;
+  }
+  if (started) tokens.push(current);
+  return tokens;
+}
+
+// Metacaractere de shell (`|`,`;`,`&&`,`||`,`>`,`>>`,`` ` ``,`$(`,`&`) FORA de
+// aspas — checar `|`,`;`,`&`,`>`,`` ` `` já cobre as formas duplicadas.
+function hasUnquotedMetachar(cmd) {
+  const s = String(cmd || '');
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inSingle) {
+      if (ch === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      if (ch === '"') inDouble = false;
+      continue;
+    }
+    if (ch === "'") { inSingle = true; continue; }
+    if (ch === '"') { inDouble = true; continue; }
+    // Mesmo escape de backslash do tokenizer: `\|`/`\&`/... FORA de aspas é
+    // o caractere literal escapado, não o metacaractere de shell.
+    if (ch === '\\' && i + 1 < s.length) { i += 1; continue; }
+    if (ch === '$' && s[i + 1] === '(') return true;
+    if (ch === '`' || ch === '|' || ch === ';' || ch === '&' || ch === '>') return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// `wouldBeRefused` — função PURA, zero subprocesso (`ADR-031` Emenda 7, E1).
+// ---------------------------------------------------------------------------
+
+function wouldBeRefused(cmd) {
+  const s = typeof cmd === 'string' ? cmd : '';
+  if (!s.trim()) {
+    return { refused: true, reason: 'não consegui determinar: comando vazio' };
+  }
+  if (hasUnquotedMetachar(s)) {
+    return { refused: true, reason: 'não consegui determinar: metacaractere de shell fora de aspas' };
+  }
+  const tokens = tokenizeCommand(s);
+  if (tokens.length === 0) {
+    return { refused: true, reason: 'não consegui determinar: comando vazio' };
+  }
+  const header = tokens[0];
+  if (!HEADER_ALLOWLIST.has(header)) {
+    return { refused: true, reason: 'não consegui determinar: comando não está na lista permitida' };
+  }
+  if (header === 'git') {
+    const sub = tokens[1];
+    if (!GIT_SUB_ALLOWLIST.has(sub)) {
+      return { refused: true, reason: 'não consegui determinar: subcomando git não está na lista permitida' };
+    }
+  }
+  return { refused: false, tokens };
+}
+
+// ---------------------------------------------------------------------------
+// `runOracle` — `spawnSync` (família `execFile*`, sem shell). Delega a
+// `wouldBeRefused` (fonte única, Emenda 10). Propaga `VSA_DEPTH`
+// incrementado no `env` do filho (produtor da guarda de reentrância, `AC-12c`).
+// ---------------------------------------------------------------------------
+
+function runOracle(cmd, options) {
+  const opts = options || {};
+  const cwd = opts.cwd || REPO_ROOT;
+  const timeoutMs = typeof opts.timeoutMs === 'number' ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+
+  const wb = wouldBeRefused(cmd);
+  if (wb.refused) {
+    return {
+      refused: true,
+      refusalReason: wb.reason,
+      exitCode: null,
+      stdout: '',
+      stderr: '',
+      timedOut: false,
+      durationMs: 0,
+    };
+  }
+
+  const [bin, ...args] = wb.tokens;
+  const baseEnv = opts.env || process.env;
+  const currentDepth = parseInt(baseEnv.VSA_DEPTH, 10);
+  const nextDepth = Number.isFinite(currentDepth) ? currentDepth + 1 : 1;
+  const childEnv = Object.assign({}, baseEnv, { VSA_DEPTH: String(nextDepth) });
+
+  const start = Date.now();
+  const result = cp.spawnSync(bin, args, {
+    cwd,
+    timeout: timeoutMs,
+    encoding: 'utf8',
+    env: childEnv,
+    killSignal: 'SIGKILL',
+  });
+  const durationMs = Date.now() - start;
+
+  const timedOut = !!(result.error && result.error.code === 'ETIMEDOUT') || result.signal === 'SIGKILL';
+  const spawnEnoent = !!(result.error && result.error.code === 'ENOENT');
+
+  return {
+    refused: false,
+    refusalReason: null,
+    exitCode: typeof result.status === 'number' ? result.status : (spawnEnoent ? 127 : null),
+    stdout: typeof result.stdout === 'string' ? result.stdout : '',
+    stderr: typeof result.stderr === 'string' ? result.stderr : (spawnEnoent ? String(result.error && result.error.message) : ''),
+    timedOut,
+    durationMs,
+    spawnError: result.error ? { code: result.error.code } : null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// `evaluateAssertion` — as 5 formas de `# espera:` (`ADR-031` D1).
+// ---------------------------------------------------------------------------
+
+function evaluateAssertion(result, espera) {
+  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
+  const type = espera && espera.type;
+  switch (type) {
+    case 'exit0':
+      return result.exitCode === 0;
+    case 'exit!=0':
+      return result.exitCode !== 0;
+    case 'stdout-vazio':
+      return stdout.trim() === '';
+    case 'stdout-nao-vazio':
+      return stdout.trim() !== '';
+    case 'stdout==':
+      return stdout.trim() === String(espera.value).trim();
+    default:
+      return false; // desconhecida — nunca chamado por classifyAc/validateStory
+  }
+}
+
+function parseEspera(rawText) {
+  const t = String(rawText || '').trim();
+  if (/^exit0$/i.test(t)) return { type: 'exit0' };
+  if (/^exit\s*!=\s*0$/i.test(t)) return { type: 'exit!=0' };
+  if (/^stdout-vazio$/i.test(t)) return { type: 'stdout-vazio' };
+  if (/^stdout-n(a|ã)o-vazio$/i.test(t)) return { type: 'stdout-nao-vazio' };
+  const eqMatch = /^stdout\s*==\s*(.+)$/.exec(t);
+  if (eqMatch) return { type: 'stdout==', value: eqMatch[1].trim() };
+  return { type: 'desconhecida', raw: t };
+}
+
+// ---------------------------------------------------------------------------
+// `isCrash` — precedência normativa (`ADR-031` D3).
+// ---------------------------------------------------------------------------
+
+function extractCrashSignature(stderr) {
+  const lines = String(stderr || '').split('\n');
+  for (const line of lines) {
+    if (/\b[A-Za-z]+Error:\s/.test(line) || /is not a function/.test(line)) {
+      return line.trim();
+    }
+  }
+  const first = String(stderr || '').trim().split('\n')[0];
+  return first || 'comando quebrado (crash)';
+}
+
+function isCrash(result) {
+  const stderr = typeof result.stderr === 'string' ? result.stderr : '';
+  const exitCode = result.exitCode;
+
+  // 1. ENOENT no spawn, exit 127/126 ⇒ estrutural.
+  if (result.spawnError && result.spawnError.code === 'ENOENT') {
+    return { crash: true, reason: 'comando não executa (ENOENT)' };
+  }
+  if (exitCode === 127 || exitCode === 126) {
+    return { crash: true, reason: 'comando não executa (exit ' + exitCode + ')' };
+  }
+
+  // 2. MODULE_NOT_FOUND / Cannot find module ⇒ falha pré-trabalho, NUNCA crash.
+  if (/MODULE_NOT_FOUND|Cannot find module/.test(stderr)) {
+    return { crash: false };
+  }
+
+  // 3. grep exit 2 + "No such file or directory" ⇒ alvo ausente, NUNCA crash.
+  if (exitCode === 2 && /No such file or directory/i.test(stderr)) {
+    return { crash: false };
+  }
+
+  // 4. Linha `<Nome>Error: ` / "is not a function" ⇒ crash.
+  if (/\b[A-Za-z]+Error:\s/.test(stderr) || /is not a function/.test(stderr)) {
+    return { crash: true, reason: extractCrashSignature(stderr) };
+  }
+
+  // 5. Linha de stack isolada NÃO é assinatura (removida — falso-positivo medido).
+  return { crash: false };
+}
+
+// ---------------------------------------------------------------------------
+// `looksLikeNaiveCounting` — padrão de contagem ingênua (`grep -c` sem
+// `-w`/`-x`/âncora) sob `# espera: exit0` (default ou explícito).
+// ---------------------------------------------------------------------------
+
+function looksLikeNaiveCounting(oracleCmd) {
+  const tokens = tokenizeCommand(oracleCmd);
+  if (tokens[0] !== 'grep') return false;
+  const flagTokens = tokens.slice(1).filter((t) => t.startsWith('-') && !t.startsWith('--'));
+  const hasCountFlag = flagTokens.some((t) => t.includes('c'));
+  if (!hasCountFlag) return false;
+  const hasDiscriminating = flagTokens.some((t) => t.includes('w') || t.includes('x'));
+  if (hasDiscriminating) return false;
+  const nonFlag = tokens.slice(1).filter((t) => !t.startsWith('-'));
+  const pattern = nonFlag[0] || '';
+  if (/[\^$]/.test(pattern)) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// `parseAcs` — escopo restrito a `## Acceptance Criteria`, sem descer em
+// fence aninhado (`ADR-031` D2 item 6, B5).
+// ---------------------------------------------------------------------------
+
+function extractAcSection(content) {
+  const text = String(content || '');
+  const startMatch = /^##[ \t]+Acceptance Criteria[ \t]*$/m.exec(text);
+  if (!startMatch) return '';
+  const startIdx = startMatch.index + startMatch[0].length;
+  const rest = text.slice(startIdx);
+  const endMatch = /^##[ \t]+\S/m.exec(rest);
+  const endIdx = endMatch ? endMatch.index : rest.length;
+  return rest.slice(0, endIdx);
+}
+
+// Ranges [start, end) de todo bloco fenced (``` ... ```) dentro de `text` —
+// usado para que `parseAcs` NUNCA trate um marcador de AC que apareça DENTRO
+// de um oráculo (ex.: string literal de fixture embutida em `node -e '...'`)
+// como um cabeçalho real (achado do QA, gate `sf13.1-validador-de-acs.yaml`,
+// finding 1b — "parseAcs não é fence-aware").
+function computeFencedRanges(text) {
+  const ranges = [];
+  // A fence real (CommonMark) abre e fecha em INÍCIO DE LINHA (`^`) — isso
+  // distingue de trecho inline como "` ```oraculo `" (usado na prosa desta
+  // própria story para DESCREVER a sintaxe da convenção), que NÃO abre um
+  // fence real e não pode ser tratado como se abrisse.
+  const re = /^```[^\n]*\n[\s\S]*?^```[ \t]*$/gm;
+  let m;
+  while ((m = re.exec(text))) {
+    ranges.push([m.index, m.index + m[0].length]);
+  }
+  return ranges;
+}
+
+function isWithinRanges(idx, ranges) {
+  return ranges.some(([start, end]) => idx >= start && idx < end);
+}
+
+// Ranges [start, end) de todo *code span* INLINE (crases) que NÃO esteja
+// dentro de um bloco fenced — usado por `parseGuarda` para distinguir a
+// etiqueta `[Guarda] (...)` CITADA como exemplo na prosa (entre crases,
+// descrevendo o que o AC testa) do uso REAL (etiqueta aplicada ao próprio AC).
+//
+// Regra CommonMark aplicada: uma corrida de N crases abre um span que fecha na
+// PRÓXIMA corrida de exatamente N crases — é isso que faz "` ```oraculo `"
+// (crase simples envolvendo uma tripla) ser UM span, não três.
+//
+// Restrição deliberada: o par precisa ficar na MESMA linha — uma crase ÓRFÃ não
+// pode "engolir" as linhas seguintes, onde o uso REAL costuma estar.
+//
+// LEITURA SUPERADA, NÃO REPETIR: `AC-29` de `sf13.1.story.md:425-426`
+// NÃO exercita esta restrição — medido no gate `sf13.7-conserto-do-instrumento.yaml`
+// (mutante M5: sem a restrição de mesma linha, `AC-29` continua `sem-irmao` e o
+// AC-3 daquela story continua VERDE, ou seja, o mutante sobrevive). A
+// justificativa anterior deste comentário, que citava `AC-29` como o caso
+// protegido, era FALSA.
+//
+// O caso que a restrição de fato protege é outro, e está no teste que a
+// acompanha (`scripts/__tests__/validate-story-acs.test.cjs`, "SF13.9/M5"):
+// crase órfã numa linha + `[Guarda]` real na linha seguinte + outra crase
+// depois ⇒ sem a restrição, as duas crases órfãs pareiam ATRAVÉS das linhas, o
+// guarda REAL cai dentro do span e `parseGuarda` devolve `null`.
+function computeInlineCodeRanges(text, fencedRanges) {
+  const runs = [];
+  const re = /`+/g;
+  let m;
+  while ((m = re.exec(text))) {
+    if (isWithinRanges(m.index, fencedRanges)) continue;
+    runs.push({ start: m.index, len: m[0].length });
+  }
+  const ranges = [];
+  let i = 0;
+  while (i < runs.length) {
+    let j = i + 1;
+    while (j < runs.length && runs[j].len !== runs[i].len) j++;
+    const sameLine = j < runs.length && !text.slice(runs[i].start, runs[j].start).includes('\n');
+    if (sameLine) {
+      ranges.push([runs[i].start, runs[j].start + runs[j].len]);
+      i = j + 1;
+    } else {
+      i += 1; // corrida sem fechamento na mesma linha ⇒ não abre span
+    }
+  }
+  return ranges;
+}
+
+function parseGuarda(body) {
+  // Exclusão ESTRUTURAL (posição do match relativa a fence/code span), NUNCA
+  // heurística de prosa — `ADR-031` Emenda 12: regex sobre prosa para asserir
+  // ausência é proibida, porque uma reescrita de frase a esvaziaria em
+  // silêncio. Um `[Guarda] (...)` que caia (a) dentro de um bloco fenced
+  // (dado literal de fixture dentro de ```oraculo) ou (b) dentro de um code
+  // span inline (citação da convenção) NÃO é etiqueta aplicada.
+  //
+  // Vale o PRIMEIRO match que SOBRA, não o primeiro match textual — a
+  // diferença importa quando citação e uso coexistem com texto idêntico
+  // (`AC-29` de `sf13.1.story.md`), caso em que a regex ingênua acertava por
+  // acidente. (Story SF13.7, 7 falsos positivos em `sf13.1.story.md`.)
+  const src = String(body || '');
+  const fencedRanges = computeFencedRanges(src);
+  const excluded = fencedRanges.concat(computeInlineCodeRanges(src, fencedRanges));
+  const re = /\[Guarda\]\s*\(([^)]*)\)/g;
+  let m = null;
+  let candidate;
+  while ((candidate = re.exec(src))) {
+    if (isWithinRanges(candidate.index, excluded)) continue;
+    m = candidate;
+    break;
+  }
+  if (!m) return null;
+  const inner = m[1].trim();
+  const normalized = stripAccents(inner.toLowerCase());
+  const provaMatch = /prova:\s*(AC-[A-Za-z0-9]+)/.exec(inner);
+  if (provaMatch) {
+    return { forma: 'prova', provaId: provaMatch[1], raw: inner };
+  }
+  if (normalized.includes('sem irmao')) {
+    return { forma: 'sem-irmao', raw: inner };
+  }
+  if (normalized.includes('citacao de fato') || normalized.includes('citacao')) {
+    return { forma: 'citacao', raw: inner };
+  }
+  return { forma: 'desconhecida', raw: inner };
+}
+
+function parseAcBody(id, body) {
+  const guarda = parseGuarda(body);
+  // Fence-aware (mesmo achado do QA aplicado aqui): abertura E fechamento
+  // precisam estar em INÍCIO DE LINHA. Sem `^`/`m`, um AC cujo oráculo
+  // contém, como dado literal (ex.: string de fixture embutida em
+  // `node -e '...'`), as substrings "```oraculo"/"```" no MEIO da linha
+  // (não delimitando um fence real) fazia o match lazy fechar cedo demais,
+  // truncando o comando real (AC-3 e outros — gate `sf13.1-validador-de-acs`,
+  // finding 1b).
+  const fenceMatch = /^```oraculo[ \t]*\r?\n([\s\S]*?)^```[ \t]*$/m.exec(body);
+  if (!fenceMatch) {
+    return { id, guarda, hasOraculo: false, oracleCmd: null, oracleEmpty: false, espera: null };
+  }
+  const lines = fenceMatch[1].split('\n').map((l) => l.replace(/\r$/, ''));
+  let espera = { type: 'exit0' }; // default (`ADR-031` D1, retrocompatível)
+  let cmdLine = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    if (cmdLine === null) {
+      const esperaMatch = /^#\s*espera:\s*(.+)$/i.exec(trimmed);
+      if (esperaMatch) {
+        espera = parseEspera(esperaMatch[1]);
+        continue;
+      }
+      cmdLine = trimmed;
+    }
+  }
+  const oracleEmpty = cmdLine === null;
+  return {
+    id,
+    guarda,
+    hasOraculo: true,
+    oracleCmd: oracleEmpty ? null : cmdLine,
+    oracleEmpty,
+    espera: oracleEmpty ? null : espera,
+  };
+}
+
+// Marcador de AC real, `ADR-031` §(b) e convenção já em uso no projeto: SEMPRE
+// no início de linha (`^`), `**AC-<id>` seguido de QUALQUER conteúdo em
+// negrito na mesma linha até o `**` de fechamento — cobre `**AC-1.**` (forma
+// simples), `**AC-2 [novo, ...].**` (anotação entre colchetes) e `**AC-17.
+// Corpus 1 — ....**` (prosa adicional dentro do próprio negrito). O achado do
+// QA (finding 1a): a forma anterior (`\*\*(AC-...)\.\*\*`) exigia `.**`
+// IMEDIATAMENTE após o id e não casava nenhuma das duas últimas formas —
+// 32 dos 43 cabeçalhos reais desta própria story usam uma delas.
+const AC_HEADER_RE = /^\*\*(AC-[A-Za-z0-9]+)\b[^\n]*?\*\*/gm;
+
+function parseAcs(content) {
+  const section = extractAcSection(content);
+  if (!section) return [];
+  const fencedRanges = computeFencedRanges(section);
+  const idRegex = new RegExp(AC_HEADER_RE.source, AC_HEADER_RE.flags);
+  const markers = [];
+  let m;
+  while ((m = idRegex.exec(section))) {
+    if (isWithinRanges(m.index, fencedRanges)) continue; // fence-aware (finding 1b)
+    markers.push({ id: m[1], headerEnd: m.index + m[0].length, headerStart: m.index });
+  }
+  const acs = [];
+  for (let i = 0; i < markers.length; i++) {
+    const start = markers[i].headerEnd;
+    const end = i + 1 < markers.length ? markers[i + 1].headerStart : section.length;
+    acs.push(parseAcBody(markers[i].id, section.slice(start, end)));
+  }
+  return acs;
+}
+
+// ---------------------------------------------------------------------------
+// `classifyAc` / `validateStory` — orquestração completa.
+// ---------------------------------------------------------------------------
+
+// Núcleo de avaliação de UM AC, sem conhecimento de outros ACs (usado tanto
+// para a classificação final quanto para o "veredito bruto" consultado pela
+// checagem de cadeia guarda→guarda).
+function computeCore(ac, ctx) {
+  if (!ac.hasOraculo) return { kind: 'semOraculo' };
+  if (ac.oracleEmpty) return { kind: 'oraculoVazio' };
+  if (ac.guarda && ac.guarda.forma === 'desconhecida') {
+    return { kind: 'guardaDesconhecida', detail: ac.guarda.raw };
+  }
+  if (ac.espera && ac.espera.type === 'desconhecida') {
+    return { kind: 'esperaDesconhecida', detail: ac.espera.raw };
+  }
+  if (ac.guarda && ac.guarda.forma === 'prova' && !ctx.acIds.has(ac.guarda.provaId)) {
+    return { kind: 'provaInexistente', detail: ac.guarda.provaId };
+  }
+  if (ac.guarda && ac.guarda.forma === 'sem-irmao') {
+    const t = ac.espera && ac.espera.type;
+    const isAusencia = t === 'stdout-vazio' || (t === 'stdout==' && String(ac.espera.value).trim() === '0');
+    if (!isAusencia) return { kind: 'formaAusenciaInvalida' };
+  }
+
+  if (ctx.reentrant) return { kind: 'reentrancia' };
+
+  const wb = wouldBeRefused(ac.oracleCmd);
+  if (wb.refused) return { kind: 'recusa', detail: wb.reason };
+
+  const result = runOracle(ac.oracleCmd, { cwd: ctx.cwd, timeoutMs: ctx.timeoutMs });
+  if (result.timedOut) return { kind: 'timeout' };
+
+  const crash = isCrash(result);
+  if (crash.crash) return { kind: 'crash', detail: crash.reason };
+
+  if (ac.espera.type === 'exit0' && looksLikeNaiveCounting(ac.oracleCmd)) {
+    return { kind: 'noop', detail: ac.oracleCmd };
+  }
+
+  const assertionTrue = evaluateAssertion(result, ac.espera);
+  return { kind: 'assertion', assertionTrue };
+}
+
+function finalizeAc(ac, core, ctx) {
+  switch (core.kind) {
+    case 'semOraculo':
+      return { bucket: 'semOraculo' };
+    case 'oraculoVazio':
+      return { bucket: 'naoDeterminados', causa: 'oraculo-vazio', motivo: 'declarou ```oraculo mas a fence está vazia — não pude medir' };
+    case 'guardaDesconhecida':
+      return { bucket: 'reprovados', motivo: 'forma de guarda não reconhecida: (' + core.detail + ')' };
+    case 'esperaDesconhecida':
+      return { bucket: 'naoDeterminados', causa: 'assercao-desconhecida', motivo: '`# espera:` presente e não reconhecido: "' + core.detail + '" — não decido por exit0 por omissão' };
+    case 'provaInexistente':
+      return { bucket: 'reprovados', motivo: 'prova nomeada não existe: ' + core.detail };
+    case 'formaAusenciaInvalida':
+      return { bucket: 'reprovados', motivo: 'forma 2 (sem irmão) exige asserção de ausência (stdout-vazio ou stdout == 0)' };
+    case 'reentrancia':
+      return { bucket: 'naoDeterminados', causa: 'reentrancia', motivo: 'execução aninhada recusada (VSA_DEPTH >= 1)' };
+    case 'recusa':
+      return { bucket: 'naoDeterminados', causa: 'recusa', motivo: core.detail };
+    case 'timeout':
+      return { bucket: 'naoDeterminados', causa: 'timeout', motivo: 'tempo limite excedido' };
+    case 'crash':
+      return { bucket: 'reprovados', motivo: 'comando quebrado (crash): ' + core.detail };
+    case 'noop':
+      return { bucket: 'alertas', motivo: 'oráculo pode ser no-op (contagem ingênua): ' + core.detail };
+    default:
+      break;
+  }
+
+  // core.kind === 'assertion'
+  if (ac.guarda && ac.guarda.forma === 'citacao') {
+    return { bucket: 'citacoes', motivo: 'citação de fato pré-existente, não prova de trabalho' };
+  }
+  if (ctx.statusSuspends && core.assertionTrue === true) {
+    return { bucket: 'naoDeterminados', causa: 'nasce-verde-pos-trabalho', motivo: 'não decido nasce-verde depois de o trabalho existir' };
+  }
+  if (core.assertionTrue === false) {
+    return { bucket: 'ok' };
+  }
+  // assertionTrue === true, status decidável
+  if (!ac.guarda) {
+    return { bucket: 'reprovados', motivo: 'nasce verde: a asserção já é verdadeira hoje, sem pareamento (prova de trabalho)' };
+  }
+  if (ac.guarda.forma === 'prova') {
+    const target = ctx.coreById[ac.guarda.provaId];
+    const targetRaw = target && target.kind === 'assertion' && target.assertionTrue === true;
+    if (targetRaw) {
+      return { bucket: 'reprovados', motivo: 'cadeia guarda→guarda proibida: prova (' + ac.guarda.provaId + ') também é nasce-verde' };
+    }
+    return { bucket: 'ok' };
+  }
+  // forma 'sem-irmao' (já validada estruturalmente)
+  return { bucket: 'ok' };
+}
+
+function classifyAc(ac, options) {
+  const opts = options || {};
+  const ctx = {
+    cwd: opts.cwd || REPO_ROOT,
+    timeoutMs: opts.timeoutMs,
+    reentrant: !!opts.reentrant,
+    statusSuspends: !!opts.statusSuspends,
+    acIds: opts.acIds || new Set(ac.guarda && ac.guarda.provaId ? [ac.guarda.provaId] : []),
+    coreById: opts.coreById || {},
+  };
+  const core = computeCore(ac, ctx);
+  return finalizeAc(ac, core, ctx);
+}
+
+function currentDepth() {
+  const n = parseInt(process.env.VSA_DEPTH, 10);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function validateStory(content, options) {
+  const opts = options || {};
+  const cwd = opts.cwd || REPO_ROOT;
+  const timeoutMs = opts.timeoutMs;
+  const reentrant = currentDepth() >= 1;
+  const statusSuspends = statusSuspendsNasceVerde(content);
+
+  const acs = parseAcs(content);
+  const acIds = new Set(acs.map((a) => a.id));
+
+  const report = {
+    total: 0,
+    semOraculo: 0,
+    ok: [],
+    reprovados: [],
+    alertas: [],
+    citacoes: [],
+    naoDeterminados: [],
+  };
+
+  const ctxBase = { cwd, timeoutMs, reentrant, statusSuspends, acIds };
+
+  // Passo 1 — núcleo de cada AC (sem checagem de cadeia guarda→guarda ainda).
+  const coreById = {};
+  for (const ac of acs) {
+    coreById[ac.id] = computeCore(ac, ctxBase);
+  }
+
+  // Passo 2 — finalização (usa `coreById` para resolver `[Guarda] (prova: AC-M)`).
+  const ctx = Object.assign({}, ctxBase, { coreById });
+  let sawAnyOraculo = false;
+  for (const ac of acs) {
+    const core = coreById[ac.id];
+    const final = finalizeAc(ac, core, ctx);
+    if (final.bucket === 'semOraculo') {
+      report.semOraculo += 1;
+      continue;
+    }
+    sawAnyOraculo = true;
+    report.total += 1;
+    const entry = { id: ac.id, motivo: final.motivo };
+    if (final.bucket === 'naoDeterminados') entry.causa = final.causa;
+    report[final.bucket].push(entry);
+  }
+
+  // Arquivo com seção mas NENHUM AC declarou oráculo ⇒ o relatório FALA
+  // (B4/`ADR-031` Emenda 8 aplicada ao nível do arquivo) — "não consegui
+  // determinar", nunca silêncio de "tudo OK".
+  const hasSection = /^##[ \t]+Acceptance Criteria[ \t]*$/m.test(String(content || ''));
+  if (hasSection && !sawAnyOraculo) {
+    report.naoDeterminados.push({
+      id: null,
+      motivo: 'nenhum AC declarou oráculo — não pude medir',
+      causa: 'arquivo-sem-oraculo',
+    });
+  }
+
+  return report;
+}
+
+function validateStoryBatch(dirPath, options) {
+  const opts = options || {};
+  const files = fs.readdirSync(dirPath).filter((f) => f.endsWith('.story.md')).sort();
+  const aggregate = {
+    files: files.length,
+    total: 0,
+    semOraculo: 0,
+    ok: [],
+    reprovados: [],
+    alertas: [],
+    citacoes: [],
+    naoDeterminados: [],
+    perFile: {},
+  };
+  for (const f of files) {
+    const full = path.join(dirPath, f);
+    const content = fs.readFileSync(full, 'utf8');
+    const r = validateStory(content, opts);
+    aggregate.total += r.total;
+    aggregate.semOraculo += r.semOraculo;
+    aggregate.ok.push(...r.ok);
+    aggregate.reprovados.push(...r.reprovados);
+    aggregate.alertas.push(...r.alertas);
+    aggregate.citacoes.push(...r.citacoes);
+    aggregate.naoDeterminados.push(...r.naoDeterminados);
+    aggregate.perFile[f] = r;
+  }
+  return aggregate;
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function printReport(label, report) {
+  process.stdout.write('\n=== ' + label + ' ===\n');
+  process.stdout.write('total=' + report.total + ' semOraculo=' + report.semOraculo + '\n');
+  process.stdout.write('ok=' + report.ok.length + ' reprovados=' + report.reprovados.length + ' alertas=' + report.alertas.length + ' citacoes=' + report.citacoes.length + ' naoDeterminados=' + report.naoDeterminados.length + '\n');
+  for (const r of report.reprovados) process.stdout.write('  REPROVA ' + (r.id || '(arquivo)') + ': ' + r.motivo + '\n');
+  for (const a of report.alertas) process.stdout.write('  ALERTA  ' + a.id + ': ' + a.motivo + '\n');
+  for (const n of report.naoDeterminados) process.stdout.write('  ND      ' + (n.id || '(arquivo)') + ' [' + n.causa + ']: ' + n.motivo + '\n');
+}
+
+function main(argv) {
+  const args = (argv || process.argv).slice(2);
+  if (args.length === 0) {
+    process.stderr.write('uso: node validate-story-acs.cjs <story.md> | <diretorio de stories>\n');
+    process.exitCode = 2;
+    return;
+  }
+  const target = args[0];
+  let stat;
+  try {
+    stat = fs.statSync(target);
+  } catch (err) {
+    process.stderr.write('Erro: caminho não encontrado: ' + target + '\n');
+    process.exitCode = 2;
+    return;
+  }
+  try {
+    if (stat.isDirectory()) {
+      const report = validateStoryBatch(target, { cwd: REPO_ROOT });
+      printReport(target + ' (' + report.files + ' arquivos)', report);
+      process.exitCode = report.reprovados.length > 0 ? 1 : 0;
+    } else {
+      const content = fs.readFileSync(target, 'utf8');
+      const report = validateStory(content, { cwd: REPO_ROOT });
+      printReport(target, report);
+      process.exitCode = report.reprovados.length > 0 ? 1 : 0;
+    }
+  } catch (err) {
+    process.stderr.write('Erro ao validar ' + target + ': ' + (err && err.message ? err.message : String(err)) + '\n');
+    process.exitCode = 2;
+  }
+}
+
+if (require.main === module) {
+  main(process.argv);
+}
+
+module.exports = {
+  HEADER_ALLOWLIST,
+  GIT_SUB_ALLOWLIST,
+  NAO_DETERMINADOS_CAUSAS,
+  tokenizeCommand,
+  hasUnquotedMetachar,
+  wouldBeRefused,
+  runOracle,
+  evaluateAssertion,
+  parseEspera,
+  isCrash,
+  looksLikeNaiveCounting,
+  extractAcSection,
+  parseAcs,
+  parseGuarda,
+  classifyAc,
+  validateStory,
+  validateStoryBatch,
+  extractStatusSection,
+  normalizeStatusText,
+  readStoryStatus,
+  statusSuspendsNasceVerde,
+  main,
+};