@daniellins/power-claude 0.16.3

package/scripts/pc-run-pod.cjs

@@ -0,0 +1,1355 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * pc-run-pod.cjs — motor determinístico da skill `pc-run-pod` (Story SF1.2).
+ *
+ * Executa um `wf-*.yaml` de pod POR ETAPA, forçando o processo por CÓDIGO — nunca
+ * pela confiança no relato do subagente (mesma regra "do not fake green" do
+ * `pc-full-cycle`). É irmão de `pc-full-cycle`: a story é dado / a skill é motor;
+ * aqui o pod é dado / este runner é motor, na granularidade "passo do DAG".
+ *
+ * Garantia central (SPEC §B1, ADR-001, AC4/DoD 1b): uma etapa só vira `done` quando
+ * a VERIFICAÇÃO EM DISCO passa — o artefato existe, casa estruturalmente com o
+ * template, e TODAS as `veto.assertions` passam. Enquanto isso não ocorre, o runner
+ * RECUSA avançar: a etapa seguinte nunca roda. O agente não escreve o `state.json`.
+ *
+ * Fonte única do contrato (Risco 2): parse/schema/DAG/fix_cycle vêm de
+ * `validate-pod-workflow.cjs` (SF1.1) — o preflight do runner NÃO reimplementa o
+ * schema; reusa `validateWorkflow` + `parseYaml` + `topoOrder`.
+ *
+ * State durável (retomável): `.power-claude/pod-runs/{pod}/{workflow}/{run-id}/state.json`,
+ * schema exato da SPEC §B1. Comandos: start/resume/next/status/approve/revise/abort.
+ *
+ * Status de etapa: `pending` → `running` → `done` (SPEC). Extensões documentadas do
+ * runner: `awaiting_approval` (checkpoint.blocking verificado, aguardando gate humano),
+ * `failed` (aborto). O relato do subagente nunca decide a transição.
+ *
+ * SF11.10/ADR-024: o gate é condicionado ao RITMO (`checkpoint.skip_modes`, conjunto fechado
+ * `RUN_MODES`). Um ritmo listado PULA o gate — e pular NÃO é aprovar: `approve()` não é
+ * chamado, a etapa nunca entra em `awaiting_approval` e o `state.json` grava `checkpoint:
+ * null` ali. A proibição do ADR-020 (o modo autônomo JAMAIS aprova) segue inteira.
+ *
+ * Node >= 18, sem dependências externas. Exporta a API para a suíte própria (DoD 1b).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process'); // SF7.2 — command_check (execução blessed)
+
+const {
+  parseYaml,
+  validateWorkflow,
+  podRootFor,
+  topoOrder,
+  VETO_TYPES,
+  // SF11.10/ADR-024 — conjunto fechado de ritmos e chaves conhecidas de `checkpoint`. Vêm do
+  // validador (fonte única do contrato, Risco 2 da SF1.2): estático e runtime NUNCA divergem.
+  RUN_MODES,
+  CHECKPOINT_KEYS,
+} = require('./validate-pod-workflow.cjs');
+
+// SF7.2/ADR-011 — raiz BLESSED de execução, ANCORADA no diretório do runner (robusto ao
+// path de instalação). Defesa em profundidade: o runner re-valida esta raiz em runtime,
+// nunca confia que o validador estático rodou.
+const VETO_CHECKS_ROOT = path.join(__dirname, 'veto-checks');
+const COMMAND_CHECK_TIMEOUT_MS = 15000;
+
+// Conjunto BLESSED de runtime (paridade com o estático): repo-rel paths sob
+// scripts/veto-checks/ classificados em installer/motor-scripts.json (ADR-007). Cacheado.
+let _blessedVetoRels = null;
+function blessedVetoRels() {
+  if (_blessedVetoRels) return _blessedVetoRels;
+  _blessedVetoRels = new Set();
+  try {
+    const { motorRels } = require(path.join(__dirname, '..', 'installer', 'motor-scripts.js'));
+    for (const rel of motorRels()) if (rel.startsWith('scripts/veto-checks/')) _blessedVetoRels.add(rel);
+  } catch { /* manifesto indisponível — realpath + existência ainda barram o vetor externo */ }
+  return _blessedVetoRels;
+}
+
+/** Extrai o conteúdo do 1º bloco cercado ```<fence>``` sob uma seção declarada. */
+function extractFencedBlock(text, section, fence) {
+  const lines = text.split(/\r?\n/);
+  const want = String(section).trim();
+  let i = 0;
+  if (want) {
+    i = lines.findIndex((l) => l.trim() === want);
+    if (i < 0) return null;
+    i += 1;
+  }
+  const open = new RegExp('^\\s*```' + (fence ? fence : '[A-Za-z0-9_-]*') + '\\s*$');
+  let start = -1;
+  for (; i < lines.length; i++) {
+    if (open.test(lines[i])) { start = i + 1; break; }
+    // Não atravessa para a próxima seção (heading ##) se estávamos ancorados numa seção.
+    if (want && /^#{1,6}\s+\S/.test(lines[i].trim())) return null;
+  }
+  if (start < 0) return null;
+  const body = [];
+  for (let j = start; j < lines.length; j++) {
+    if (/^\s*```\s*$/.test(lines[j])) return body.join('\n');
+    body.push(lines[j]);
+  }
+  return null; // sem fechamento
+}
+
+// Motor de memória do pod (Story SF2.1) — biblioteca já testada (suíte própria).
+// SF2.2 CONSOME esta API (append/consolidate/getConsolidatedForBrief); nunca
+// reimplementa retenção/curadoria. O runner é o CALLER da cadência de consolidação.
+const podMemory = require('./pod-memory.cjs');
+
+// ---------------------------------------------------------------------------
+// Utilidades de estado e tempo.
+// ---------------------------------------------------------------------------
+
+function nowISO() {
+  return new Date().toISOString();
+}
+
+let __runIdSeq = 0;
+/**
+ * run-id = timestamp ISO sanitizado (prefixo legível, padrão da SPEC
+ * 2026-07-24T18-00-00Z) + sufixo de unicidade `-<pid>-<seq>`.
+ *
+ * [SF1.2 finding #1 — débito resolvido na SF1.3] O timestamp tem granularidade de
+ * segundo: dois `start` no MESMO segundo (ex.: um harness que dispara vários runs)
+ * gerariam o mesmo run-id → o mesmo path de state.json → um run sobrescrevendo o
+ * outro. O sufixo `<pid>-<seq>` garante unicidade dentro do processo (seq monotônico)
+ * e entre processos (pid), sem perder a legibilidade do timestamp. Callers que
+ * passam `--run-id`/`runId` explícito continuam no controle (não passam por aqui).
+ */
+function makeRunId(date) {
+  const iso = (date || new Date()).toISOString(); // 2026-07-24T18:00:00.000Z
+  const base = iso.replace(/\.\d+Z$/, 'Z').replace(/:/g, '-');
+  const suffix = `${process.pid.toString(36)}-${(__runIdSeq++).toString(36)}`;
+  return `${base}-${suffix}`;
+}
+
+function runDirFor(runsRoot, pod, workflow, runId) {
+  return path.join(runsRoot, pod, workflow, runId);
+}
+
+function statePathFor(runsRoot, pod, workflow, runId) {
+  return path.join(runDirFor(runsRoot, pod, workflow, runId), 'state.json');
+}
+
+function readState(statePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(statePath, 'utf8');
+  } catch (e) {
+    throw new Error(`state.json não encontrado: ${statePath}`);
+  }
+  let state;
+  try {
+    state = JSON.parse(raw);
+  } catch (e) {
+    // Risco 4: state corrompido nunca é "consertado" silenciosamente — HALT explícito.
+    throw new Error(`state.json corrompido (JSON inválido) em ${statePath}: ${e.message}`);
+  }
+  validateStateSchema(state, statePath);
+  return state;
+}
+
+function validateStateSchema(state, where) {
+  // Risco 4: valida o schema antes de qualquer decisão de retomada.
+  const req = ['pod', 'workflow', 'run_id', 'mode', 'steps', 'updated_at'];
+  for (const k of req) {
+    if (!(k in state)) throw new Error(`state.json inválido (campo "${k}" ausente) em ${where}`);
+  }
+  if (!state.steps || typeof state.steps !== 'object' || Array.isArray(state.steps)) {
+    throw new Error(`state.json inválido (steps não é um mapa) em ${where}`);
+  }
+  const VALID = new Set(['pending', 'running', 'awaiting_approval', 'done', 'failed']);
+  for (const [id, s] of Object.entries(state.steps)) {
+    if (!VALID.has(s.status)) {
+      throw new Error(`state.json inválido: etapa "${id}" com status desconhecido "${s.status}" em ${where}`);
+    }
+  }
+}
+
+/** Escrita atômica: grava em tmp e renomeia (nunca deixa um state.json parcial). */
+function writeState(statePath, state) {
+  state.updated_at = nowISO();
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  const tmp = `${statePath}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, statePath);
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Carga do contrato (fonte única — SF1.1).
+// ---------------------------------------------------------------------------
+
+/**
+ * SF10.20/ADR-019 `DF-SF10.20-2` — deriva, do `wf` JÁ ESTRUTURADO, as CAPACIDADES que
+ * ele exige e que ESTE motor (o do repo em que este arquivo está instalado) não tem.
+ * Não há campo novo no `wf` e não há comparação de versão: a capacidade é o FATO,
+ * a versão seria só um proxy dela (e um proxy que mente exatamente quando alguém
+ * copia scripts à mão — que é a causa-raiz desta família de defeito).
+ *
+ * Três classes, todas derivadas de campos que o schema já tem:
+ *   (a) `veto.assertions[].type` que não consta em VETO_TYPES deste motor;
+ *   (b) `command_check.command` cujo script blessed não existe sob scripts/veto-checks/;
+ *   (c) [SF11.10/ADR-024 `DF-SF11.10-6`] chave sob `step.checkpoint` que não consta em
+ *       CHECKPOINT_KEYS deste motor. ADR-021 `DF-SF11.2-7` registrou como PERDA que o gate
+ *       de capacidade não sabia expressar a capacidade da vez; esta sabe, e barato. Sem ela,
+ *       motor antigo + `wf` novo degrada SEGURO (o gate bloqueia também no ritmo autônomo,
+ *       nada é aprovado sem humano) porém OBSCURO: a run estaciona sem causa nomeada.
+ *
+ * Best-effort e SEM efeito colateral: nunca lança, nunca decide se algo falha —
+ * só explica uma falha que o preflight já produziu.
+ */
+function capabilityGaps(workflowPath) {
+  const gaps = [];
+  let doc;
+  try {
+    doc = parseYaml(fs.readFileSync(workflowPath, 'utf8'));
+  } catch {
+    return gaps; // wf ilegível: a falha é outra, não de capacidade.
+  }
+  const steps = doc && Array.isArray(doc.steps) ? doc.steps : [];
+  for (const step of steps) {
+    // (c) SF11.10 — chave de `checkpoint` que este motor não conhece.
+    const cp = step && step.checkpoint;
+    if (cp && typeof cp === 'object' && !Array.isArray(cp)) {
+      for (const k of Object.keys(cp)) {
+        if (!CHECKPOINT_KEYS.includes(k)) {
+          gaps.push(`etapa "${step.id}" · checkpoint.${k}: chave de checkpoint "${k}" não existe neste motor`);
+        }
+      }
+    }
+    const assertions = step && step.veto && Array.isArray(step.veto.assertions) ? step.veto.assertions : [];
+    for (let i = 0; i < assertions.length; i++) {
+      const a = assertions[i];
+      if (!a || typeof a.type !== 'string') continue;
+      const where = `etapa "${step.id}" · veto.assertions[${i}]`;
+      if (!Object.prototype.hasOwnProperty.call(VETO_TYPES, a.type)) {
+        gaps.push(`${where}: tipo de veto "${a.type}" não existe neste motor`);
+        continue;
+      }
+      if (a.type === 'command_check' && typeof a.command === 'string' && /^[\w.-]+$/.test(a.command)) {
+        if (!fs.existsSync(path.join(VETO_CHECKS_ROOT, a.command))) {
+          gaps.push(`${where}: script blessed "scripts/veto-checks/${a.command}" não está instalado neste motor`);
+        }
+      }
+    }
+  }
+  return gaps;
+}
+
+/** Manifest da instalação, ou null. Best-effort: nunca lança, nunca é condição de falha. */
+function readInstallManifest() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, '..', '.power-claude', 'manifest.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * SF10.20/ADR-019 `DF-SF10.20-3` — única frase honesta disponível sobre a instalação.
+ * O manifest é registro de distribuição/integridade, NÃO o oráculo do bloqueio.
+ */
+function installationLabel() {
+  const m = readInstallManifest();
+  if (!m) return 'SEM manifest em .power-claude/ — instalação não rastreada (nunca passou por install/adopt/update)';
+  return `versão ${m.version} registrada em .power-claude/manifest.json`;
+}
+
+/**
+ * SF10.20 — o comando de correção, VERIFICADO antes de ser impresso.
+ *
+ * Por que não `npx power-claude`: uma instalação não tem `package.json` nem
+ * `node_modules` do framework, e o binário não está no PATH — `npx` resolveria pelo
+ * REGISTRY PÚBLICO, onde o nome `power-claude` pertence a um pacote de TERCEIRO. A
+ * mensagem mandaria o dono, já em estado quebrado, baixar e executar código de
+ * estranho dentro do repo de uso diário. Um comando que não corrige e ainda abre
+ * superfície de supply-chain é pior do que não imprimir comando nenhum.
+ *
+ * O caminho do framework vem do `frameworkRoot` que o próprio instalador carimbou no
+ * manifest (ele roda a partir do framework, então sabe). Como é registro e não
+ * oráculo — o framework pode ter sido movido ou apagado depois —, aqui se CONFERE a
+ * existência do `bin/cli.js` antes de imprimir. Sem confirmação, degrada para
+ * instrução com placeholder explícito: menos cômodo, mas nunca perigoso e nunca falso.
+ *
+ * @returns {{lines: string[], resolved: boolean}}
+ */
+function correctionCommand() {
+  const m = readInstallManifest();
+  const root = m && typeof m.frameworkRoot === 'string' ? m.frameworkRoot : null;
+  const cli = root ? path.join(root, 'bin', 'cli.js') : null;
+  if (cli && fs.existsSync(cli)) {
+    return {
+      resolved: true,
+      lines: [
+        `          Corrija:  node ${cli} adopt \\`,
+        `                 && node ${cli} update --scope motor`,
+      ],
+    };
+  }
+  return {
+    resolved: false,
+    lines: [
+      '          Corrija a partir do repositório do POWER CLAUDE (troque o caminho pelo real):',
+      '                    node <repo-power-claude>/bin/cli.js adopt \\',
+      '                 && node <repo-power-claude>/bin/cli.js update --scope motor',
+      root
+        ? `          (o manifest aponta "${root}", mas não há bin/cli.js lá — o framework foi movido?)`
+        : '          (esta instalação não registra o caminho do framework; rode install/adopt de lá)',
+      '          NÃO use "npx power-claude": esse nome no registry público é de terceiro.',
+    ],
+  };
+}
+
+/**
+ * SF10.20/ADR-019 `DF-SF10.20-4` — ATRIBUIÇÃO. O preflight já falhava alto e cedo; o que
+ * faltava era dizer de QUEM é a culpa. A mensagem do validador acusa o `wf` ("type
+ * inválido", "proibido por ADR-002") — e o `wf` pode estar perfeitamente certo, com a
+ * INSTALAÇÃO velha. Aqui a exceção original é reaproveitada (mesma classe, mesmo exit
+ * code, zero mudança de comportamento — só texto), acrescida da hipótese de skew.
+ *
+ * Fica em `loadWorkflow` e NÃO no validador de propósito: `validate-pod-workflow.cjs`
+ * também é linter estático puro (CI, forge-*, pod-export-compile), onde "sua instalação
+ * está defasada" seria ruído falso. A hipótese só é verdadeira quando alguém tenta RODAR.
+ *
+ * Declara DUAS causas porque, de dentro do motor defasado, é logicamente impossível
+ * decidir a direção do skew: um `type` desconhecido é indistinguível de um `type`
+ * inventado. Apontar uma causa só seria adivinhação com cara de diagnóstico.
+ */
+function annotateCapabilitySkew(error, workflowPath) {
+  try {
+    const gaps = capabilityGaps(workflowPath);
+    if (gaps.length === 0) return error; // falha de contrato comum: mensagem intacta.
+    error.capabilityGaps = gaps;
+    error.message = [
+      error.message,
+      '',
+      '  ↑ ATRIBUIÇÃO: esta falha é da INSTALAÇÃO, não necessariamente do wf.',
+      `     Motor:      ${path.join(__dirname, path.basename(__filename))}`,
+      `     Instalação: ${installationLabel()}`,
+      '     Capacidade(s) que o wf exige e este motor NÃO tem:',
+      ...gaps.map((g) => `       - ${g}`),
+      '     Duas causas possíveis, nesta ordem de probabilidade:',
+      '       1. INSTALAÇÃO DEFASADA — o wf usa capacidade de um motor mais novo que o instalado.',
+      ...correctionCommand().lines,
+      '       2. o wf declara capacidade que não existe em nenhuma versão do motor',
+      '          (só nesse caso o defeito é do wf).',
+    ].join('\n');
+  } catch { /* atribuição é enfeite: jamais pode substituir a falha original */ }
+  return error;
+}
+
+function loadWorkflow(workflowPath, podRootOverride) {
+  // Preflight de contrato reusando o validador estático da SF1.1 (Risco 2): se o
+  // wf-*.yaml não é bem-formado, o runner nem começa. Lança em caso de contrato inválido.
+  // SF10.20: a falha ganha ATRIBUIÇÃO quando é skew de capacidade (ADR-019 DF-SF10.20-4).
+  try {
+    validateWorkflow(workflowPath, podRootOverride);
+  } catch (error) {
+    throw annotateCapabilitySkew(error, workflowPath);
+  }
+  const doc = parseYaml(fs.readFileSync(workflowPath, 'utf8'));
+  const podRoot = podRootFor(workflowPath, podRootOverride);
+  const order = topoOrder(doc);
+  return { doc, podRoot, order };
+}
+
+function stepById(doc, id) {
+  return doc.steps.find((s) => s.id === id);
+}
+
+/**
+ * SF11.10/ADR-024 `DF-SF11.10-2` — o checkpoint bloqueia NESTE ritmo?
+ *
+ * `skip_modes` é enumeração NEGATIVA de propósito: o modo passado só escapa do gate se
+ * estiver LISTADO. Ausente, `undefined`, typo, modo futuro ⇒ **bloqueia** (fail-closed).
+ * A enumeração positiva (`blocking_in: [interactive]`) foi avaliada e recusada: um modo
+ * desconhecido cairia em "não bloqueia" — falha ABERTA no único gate humano do sistema.
+ *
+ * PULAR NÃO É APROVAR: quando esta função devolve `false`, o motor segue o caminho comum
+ * (`done`) e o `state.json` grava `checkpoint: null` para a etapa — ninguém, em lugar
+ * nenhum, chama `approve()` em nome do dono. A proibição inegociável do ADR-020 fica
+ * INTEIRA; o que muda é ONDE existe gate, nunca QUEM o resolve.
+ */
+function isBlocking(step, mode) {
+  if (!step || !step.checkpoint || step.checkpoint.blocking !== true) return false;
+  const skip = Array.isArray(step.checkpoint.skip_modes) ? step.checkpoint.skip_modes : [];
+  return !skip.includes(mode);
+}
+
+// ---------------------------------------------------------------------------
+// Verificação pós-etapa EM DISCO (o coração do não-fake-green).
+// ---------------------------------------------------------------------------
+
+function extractHeadings(text) {
+  return text
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => /^#{1,6}\s+\S/.test(l));
+}
+
+function extractField(text, field) {
+  // Aceita `field: valor`, `**field**: valor`, `- field: valor`, `field = valor`.
+  const esc = field.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`^\\s*(?:[-*]\\s+)?(?:\\*\\*)?${esc}(?:\\*\\*)?\\s*[:=]\\s*(.*)$`, 'i');
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.match(re);
+    if (m) return m[1].trim();
+  }
+  return null;
+}
+
+// Débito #2 do gate sf1.5-piloto-hormozi-g5.yaml (finding id:1, segunda metade):
+// o contador só reconhecia bullets `-`/`*` — 2/5 runs do piloto formataram o Value
+// Stack como TABELA e count_gte contou 0 (< n) → fix evitável (~40% das runs). Aqui o
+// contador passa a reconhecer as 3 formas contáveis de item de lista sob um heading:
+//   (a) bullets       `- item` / `* item`   (comportamento SF1.1 — INALTERADO)
+//   (b) lista numerada `1. item` / `2. item`
+//   (c) linha de tabela `| ... |`           (EXCLUINDO a linha separadora `|---|---|`)
+// Prosa corrida NUNCA conta (nenhuma das 3 formas casa uma linha de prosa). É ADIÇÃO
+// pura: bullets contam exatamente como antes; numeradas/tabela só SOMAM (nunca reduzem
+// a contagem de um artefato pré-existente) — sem afrouxar a semântica do veto.
+const RE_BULLET = /^\s*[-*]\s+\S/;
+const RE_NUMBERED = /^\s*\d+\.\s+\S/;
+const RE_TABLE_ROW = /^\s*\|.+\|\s*$/;
+// separador de tabela markdown: célula só com `-`, `:`, espaços (ex.: `|---|:--:|`).
+const RE_TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/;
+
+function countListItemsInSection(text, sectionField) {
+  // Conta itens de lista sob a seção cujo heading CONTÉM `sectionField`.
+  const lines = text.split(/\r?\n/);
+  let inSection = false;
+  let count = 0;
+  for (const line of lines) {
+    if (/^#{1,6}\s+\S/.test(line.trim())) {
+      inSection = line.toLowerCase().includes(String(sectionField).toLowerCase());
+      continue;
+    }
+    if (!inSection) continue;
+    if (RE_BULLET.test(line)) count++;                                  // (a) bullets — inalterado
+    else if (RE_NUMBERED.test(line)) count++;                          // (b) lista numerada
+    else if (RE_TABLE_ROW.test(line) && !RE_TABLE_SEPARATOR.test(line)) count++; // (c) tabela (exclui separador)
+  }
+  return count;
+}
+
+/**
+ * Avalia UMA veto.assertion contra o texto do artefato. Resultado binário e
+ * determinístico (SPEC §B1: veto é avaliável por máquina, proibido julgamento LLM).
+ * As 5 formas são as mesmas validadas na FORMA pela SF1.1 (VETO_TYPES).
+ */
+function evalVeto(assertion, text, artifactPath, roots) {
+  const ok = () => ({ ok: true });
+  const no = (reason) => ({ ok: false, reason });
+  switch (assertion.type) {
+    case 'section_exists': {
+      const want = String(assertion.section).trim();
+      const has = text.split(/\r?\n/).some((l) => l.trim() === want);
+      return has ? ok() : no(`seção "${want}" ausente`);
+    }
+    case 'field_matches': {
+      const val = extractField(text, assertion.field);
+      if (val === null) return no(`campo "${assertion.field}" ausente`);
+      let re;
+      try {
+        re = new RegExp(String(assertion.pattern));
+      } catch (e) {
+        return no(`regex inválida: ${e.message}`);
+      }
+      return re.test(val) ? ok() : no(`campo "${assertion.field}"="${val}" não casa /${assertion.pattern}/`);
+    }
+    case 'file_referenced_exists': {
+      const ref = extractField(text, assertion.field);
+      if (ref === null) return no(`campo "${assertion.field}" ausente`);
+      const bases = [path.dirname(artifactPath), roots.runDir, roots.podRoot].filter(Boolean);
+      const found = bases.some((b) => fs.existsSync(path.resolve(b, ref)));
+      return found ? ok() : no(`arquivo referenciado por "${assertion.field}" ("${ref}") não existe`);
+    }
+    case 'count_gte': {
+      // M-r2-5 (SF3.1): campo auto-declarado NUNCA satisfaz count_gte — a contagem
+      // REAL de itens de lista sob o heading é a ÚNICA fonte. O caminho `extractField`
+      // (número declarado) foi REMOVIDO de propósito: era um bypass de green ("Value
+      // Stack: 99" sem nenhum item passava o veto). Agora `Value Stack: 99` sem itens
+      // bloqueia (declaração não compra prova); heading ausente ⇒ contagem 0 ⇒ bloqueia.
+      const n = Number(assertion.n);
+      const c = countListItemsInSection(text, assertion.field);
+      return c >= n ? ok() : no(`contagem ${c} < ${n} para "${assertion.field}"`);
+    }
+    case 'json_schema_valid': {
+      // SF7.2/ADR-011 Decisão 1: com `extract:{section,fence}`, valida o BLOCO fenced de uma
+      // seção declarada (não o artefato inteiro) — fecha o CONCERNS-1 de SF6.3 (JSON.parse do
+      // .md colidia com checkTemplateConformance). Sem `extract`, comportamento legado (artefato = JSON).
+      let jsonText = text;
+      if (assertion.extract && typeof assertion.extract === 'object') {
+        const fence = assertion.extract.fence || 'json';
+        const block = extractFencedBlock(text, assertion.extract.section, fence);
+        if (block === null) {
+          return no(`bloco \`\`\`${fence}\`\`\` não encontrado na seção "${assertion.extract.section}"`);
+        }
+        jsonText = block;
+      }
+      let obj;
+      try {
+        obj = JSON.parse(jsonText);
+      } catch (e) {
+        return no(`${assertion.extract ? 'bloco extraído' : 'artefato'} não é JSON válido: ${e.message}`);
+      }
+      let required = [];
+      const sc = assertion.schema;
+      if (Array.isArray(sc)) required = sc;
+      else if (sc && typeof sc === 'object' && Array.isArray(sc.required)) required = sc.required;
+      else if (typeof sc === 'string') {
+        const scPath = path.resolve(roots.podRoot, sc);
+        if (fs.existsSync(scPath)) {
+          try {
+            const parsed = JSON.parse(fs.readFileSync(scPath, 'utf8'));
+            required = Array.isArray(parsed) ? parsed : (parsed.required || []);
+          } catch (e) {
+            return no(`schema "${sc}" ilegível: ${e.message}`);
+          }
+        } else {
+          required = String(sc).split(',').map((s) => s.trim()).filter(Boolean);
+        }
+      }
+      const missing = required.filter((k) => !(k in obj));
+      return missing.length === 0 ? ok() : no(`chaves obrigatórias ausentes: ${missing.join(', ')}`);
+    }
+    case 'command_check': {
+      // SF7.2/ADR-011 Decisão 2 — executa SÓ script BLESSED sob scripts/veto-checks/.
+      // Defesa em profundidade: re-valida a raiz blessed em runtime (nunca confia que o
+      // validador estático rodou). execFileSync SEM shell, args literais, timeout. Exit 0 =
+      // ok; não-zero (inclui fail-loud de dependência ausente) = no() → etapa BLOQUEADA.
+      const cmd = String(assertion.command || '');
+      if (/[\\/]/.test(cmd) || cmd.includes('..') || !/\.(cjs|js)$/.test(cmd)) {
+        return no(`command_check recusado: "${cmd}" não é nome simples de script blessed`);
+      }
+      // Guard B (defesa em profundidade endurecida, SF7.2 CONCERNS-1): o nome DEVE ser blessed
+      // no manifesto (paridade com o estático — barra arquivo estranho no dir), E o path
+      // RESOLVIDO POR realpathSync tem que ficar sob o realpath da raiz blessed (um symlink
+      // dentro de veto-checks/ apontando para fora NÃO fura mais: o check lexical anterior
+      // seguia o link; o realpath expõe o alvo externo e RECUSA sem executar).
+      const blessed = blessedVetoRels();
+      if (blessed.size > 0 && !blessed.has(`scripts/veto-checks/${cmd}`)) {
+        return no(`command_check recusado: "${cmd}" não é blessed no manifesto (ADR-007)`);
+      }
+      const scriptPath = path.resolve(VETO_CHECKS_ROOT, cmd);
+      let realScript;
+      let realRoot;
+      try {
+        realRoot = fs.realpathSync(VETO_CHECKS_ROOT);
+        realScript = fs.realpathSync(scriptPath);
+      } catch {
+        return no(`command_check recusado: "${cmd}" não resolve em disco sob scripts/veto-checks/`);
+      }
+      if (path.dirname(realScript) !== realRoot) {
+        return no(`command_check recusado: "${cmd}" resolve (realpath) FORA de scripts/veto-checks/ — symlink/traversal para "${realScript}"`);
+      }
+      const extraArgs = Array.isArray(assertion.args) ? assertion.args.map(String) : [];
+      const timeout = Number.isInteger(assertion.timeout_ms) && assertion.timeout_ms > 0
+        ? assertion.timeout_ms : COMMAND_CHECK_TIMEOUT_MS;
+      try {
+        execFileSync(process.execPath, [scriptPath, artifactPath, ...extraArgs], {
+          timeout, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return ok();
+      } catch (e) {
+        if (e.code === 'ETIMEDOUT' || e.signal === 'SIGTERM') {
+          return no(`command_check "${cmd}" excedeu o timeout de ${timeout}ms`);
+        }
+        const out = `${e.stderr || ''}${e.stdout || ''}`.trim().split('\n').pop() || e.message;
+        return no(`command_check "${cmd}" bloqueou (exit ${e.status ?? '?'}): ${out.slice(0, 200)}`);
+      }
+    }
+    default:
+      return no(`tipo de veto desconhecido: ${assertion.type}`);
+  }
+}
+
+/**
+ * Conformidade estrutural ao template: o artefato contém toda SEÇÃO do template.
+ * "Seção" = heading de nível 2+ (`##`…); o título H1 do template é descritivo, não
+ * uma seção obrigatória do artefato produzido. Regra determinística e documentada.
+ */
+function checkTemplateConformance(ctx, step, artifactText) {
+  const tmplPath = path.resolve(ctx.podRoot, step.template);
+  if (!fs.existsSync(tmplPath)) {
+    return { ok: false, failures: [`template ausente em disco: ${step.template}`] };
+  }
+  const sections = (t) => extractHeadings(t).filter((h) => /^#{2,6}\s+\S/.test(h));
+  const wanted = sections(fs.readFileSync(tmplPath, 'utf8'));
+  const have = new Set(sections(artifactText));
+  const failures = [];
+  for (const h of wanted) {
+    if (!have.has(h)) failures.push(`seção obrigatória do template ausente no artefato: "${h}"`);
+  }
+  return { ok: failures.length === 0, failures };
+}
+
+/**
+ * Verificação pós-etapa completa. Retorna { ok, failures[] }. NÃO muta o state — a
+ * decisão de transição é do `advance`. Ordem: artefato existe → template conforme →
+ * TODAS as veto.assertions. Reúne todas as falhas (diagnóstico rico no relatório).
+ */
+function verifyStep(ctx, stepId) {
+  const step = stepById(ctx.doc, stepId);
+  const artRel = ctx.state.steps[stepId].artifact;
+  if (!artRel) return { ok: false, failures: ['artefato não atribuído à etapa'] };
+  const artPath = path.resolve(ctx.runDir, artRel);
+  if (!fs.existsSync(artPath)) {
+    return { ok: false, failures: [`artefato ausente em disco: ${artRel}`] };
+  }
+  const text = fs.readFileSync(artPath, 'utf8');
+  const failures = [];
+  const tconf = checkTemplateConformance(ctx, step, text);
+  if (!tconf.ok) failures.push(...tconf.failures);
+  const assertions = (step.veto && Array.isArray(step.veto.assertions)) ? step.veto.assertions : [];
+  assertions.forEach((a, i) => {
+    const r = evalVeto(a, text, artPath, ctx);
+    if (!r.ok) failures.push(`veto.assertions[${i}] (${a.type}) falhou: ${r.reason}`);
+  });
+  return { ok: failures.length === 0, failures };
+}
+
+// ---------------------------------------------------------------------------
+// Brief do subagente FRESCO (AC3): leitura obrigatória (SF11.2), paths, contrato de saída,
+// veto (sem `_sources`, SF11.2), retorno ≤15.
+// ---------------------------------------------------------------------------
+
+function artifactRelFor(stepId) {
+  return path.join('artifacts', `${stepId}.md`);
+}
+
+/**
+ * SF7.3/ADR-016 — linhas do brief para o `anti_path` da etapa. Separa ENFORÇADOS (item
+ * com `mechanized_by` → aponta o veto pareado que MORDE) de ADVISORY (`mechanized_by: null`
+ * → orientação rotulada NÃO-enforcement). Etapa sem anti_path = array vazio (nada injetado).
+ */
+function antiPathBriefLines(step) {
+  const ap = Array.isArray(step.anti_path) ? step.anti_path : [];
+  if (ap.length === 0) return [];
+  const enforced = ap.filter((it) => it && it.mechanized_by != null);
+  const advisory = ap.filter((it) => it && it.mechanized_by == null);
+  const out = [];
+  if (enforced.length > 0) {
+    out.push('', '## Anti-padrões desta etapa — ENFORÇADOS por veto (bloqueiam de verdade)');
+    for (const it of enforced) out.push(`- ${it.rule} → enforçado pela veto.assertion id="${it.mechanized_by}" (o runner bloqueia se violado).`);
+  }
+  if (advisory.length > 0) {
+    out.push('', '## Anti-padrões desta etapa (orientação — NÃO enforcement)');
+    out.push('_Sugestões escopo-de-etapa; o runner NÃO as verifica em disco — não são gate. Siga-as, mas nada bloqueia se não seguir._');
+    for (const it of advisory) out.push(`- ${it.rule}`);
+  }
+  return out;
+}
+
+/**
+ * SF11.2/ADR-021 `DF-SF11.2-2` — o MESMO motor roda sobre dois transportes do mesmo `wf`:
+ * a raiz de POD em disco (driver de dev) e a raiz de BUNDLE COMPILADO (export server-side,
+ * `pod-export-executor.cjs` dirige `advance` com `podRootOverride: bundleRoot`). No bundle
+ * NÃO existe `agents/<a>.md`: o agente + golden rules + knowledge (na ordem declarada) já
+ * foram compilados POR VALOR em `phases/<step>/system.md` (`pod-export-compile.cjs:249-262,298`)
+ * e o brief nem é consumido nesse caminho (`pod-export-executor.cjs:241,339`).
+ *
+ * Marcador POSITIVO do transporte (nunca a AUSÊNCIA de `agents/`, que é justamente o defeito
+ * que o gate existe para pegar): `bundle.json` na raiz — escrito só pelo compilador de export
+ * (`pod-export-compile.cjs:355`) — mais o diretório `phases/`.
+ */
+function isExportBundle(podRoot) {
+  return fs.existsSync(path.join(podRoot, 'bundle.json')) && fs.existsSync(path.join(podRoot, 'phases'));
+}
+
+/**
+ * SF11.2/ADR-021 `DF-SF11.2-1`/`-4` — LEITURA OBRIGATÓRIA da etapa, resolvida a partir do
+ * `wf`: `agents/<step.agent>.md` seguido de cada `knowledge/<k>` NA ORDEM DECLARADA. Mesma
+ * convenção de path do OUTRO runtime do mesmo `wf` (`pod-export-compile.cjs:213,234`), que já
+ * compila esses arquivos POR VALOR e já falha quando um deles não existe em disco — aqui a
+ * renderização é POR REFERÊNCIA VERIFICADA (`DF-SF11.2-2`): o motor **não abre nem lê** o
+ * conteúdo, só resolve o path, confere existência e exibe.
+ *
+ * Etapa sem `knowledge:` → lista SÓ o arquivo do agente (o campo é OPCIONAL no schema,
+ * `validate-pod-workflow.cjs:451`; retrocompat explícita, `DF-SF11.2-10`). Raiz de BUNDLE de
+ * export → a leitura obrigatória da fase é o `phases/<id>/system.md` compilado (ver
+ * `isExportBundle`): a MESMA fonte de verdade do `wf`, renderizada POR VALOR (`DF-SF11.2-2`).
+ *
+ * Confinamento (`DF-SF11.2` / segurança do ADR): todo path é resolvido sob `ctx.podRoot`; o
+ * que escapar da raiz do pod é tratado como AUSENTE (fail-closed), nunca exibido no brief.
+ *
+ * Retorna `{ files: [{ kind, rel, abs }], missing: [string] }` — `missing` traz a descrição
+ * legível do que falta (path relativo ao pod + causa), pronta para virar `failures`.
+ */
+function requiredReading(ctx, step) {
+  const podRoot = path.resolve(ctx.podRoot);
+  const declared = isExportBundle(podRoot)
+    ? [{ kind: 'phase-system', rel: path.posix.join('phases', String(step.id), 'system.md') }]
+    : [
+      { kind: 'agent', rel: path.posix.join('agents', `${step.agent}.md`) },
+      ...(Array.isArray(step.knowledge) ? step.knowledge : []).map((k) => ({
+        kind: 'knowledge',
+        rel: path.posix.join('knowledge', String(k)),
+      })),
+    ];
+  const files = [];
+  const missing = [];
+  for (const d of declared) {
+    const abs = path.resolve(podRoot, d.rel);
+    const inside = abs === podRoot || abs.startsWith(podRoot + path.sep);
+    if (!inside) {
+      missing.push(`${d.rel} (leitura obrigatória ${d.kind}: path escapa da raiz do pod ${podRoot})`);
+      continue;
+    }
+    if (!fs.existsSync(abs)) {
+      missing.push(`${d.rel} (leitura obrigatória ${d.kind}: inexistente em disco — ${abs})`);
+      continue;
+    }
+    files.push({ kind: d.kind, rel: d.rel, abs });
+  }
+  return { files, missing };
+}
+
+/**
+ * SF11.2/ADR-021 `DF-SF11.2-1`/`-6` — seção de leitura obrigatória do brief. Vem ANTES de
+ * `## Veto` (na verdade, antes de tudo que não é cabeçalho): a precedência de layout é parte
+ * da decisão, não estética — o agravante medido pelo QA (gate SF10.21, finding 2) era a
+ * ASSIMETRIA "a resposta que faz passar aparece, a regra que manda recusar não".
+ *
+ * Honestidade do rótulo (mesma família de `antiPathBriefLines`, ADR-016): o motor declara o
+ * ESTATUTO do que injeta. Aqui: os arquivos existem (verificado em disco) e a `## Veto` é
+ * verificação POSTERIOR. O ato de LER e OBEDECER continua sendo disciplina do agente — este
+ * canal garante alcançabilidade e declaração, não obediência (`DF-SF11.2-3`).
+ */
+function requiredReadingBriefLines(files) {
+  return [
+    '## Leitura obrigatória ANTES de agir (declarada no workflow desta etapa)',
+    '_O runner verificou que cada arquivo abaixo existe em disco. Leia-os na ordem, integralmente, antes de qualquer ação. Se algum não abrir, HALTE e reporte._',
+    ...files.map((f) => `- ${f.abs}`),
+    '_A seção "Veto" abaixo é a verificação POSTERIOR do runner sobre o artefato — não é a especificação da tarefa e não substitui a leitura acima._',
+    '',
+  ];
+}
+
+/**
+ * SF11.2/ADR-021 `DF-SF11.2-5` — projeção da `veto.assertion` para o brief: tudo, MENOS
+ * `_sources`. `_sources` é metadado de MANUTENÇÃO por inspeção (cita IDs de ADR/story,
+ * obrigações de sidecar/smoke, achados de `extractField`) — endereçado a quem mantém o `wf`,
+ * nada nele é acionável pelo agente, e ele era 85% do bloco de veto da `digest`.
+ *
+ * Omissão GENÉRICA por construção: vale para toda assertion de todo pod. Sem classificação
+ * por `type`/`field`/`id`, sem lista de exceções, sem nome de pod, sem campo novo no `wf`.
+ * Todo o resto (`type`, `field`, `pattern`, `n`, `command`, `args`, `timeout_ms`, `id`,
+ * `section`, ...) segue no brief verbatim — o caso honesto não perde nada.
+ */
+function vetoAssertionForBrief(a) {
+  if (!a || typeof a !== 'object' || Array.isArray(a)) return a;
+  const out = {};
+  for (const k of Object.keys(a)) {
+    if (k === '_sources') continue;
+    out[k] = a[k];
+  }
+  return out;
+}
+
+function buildBrief(ctx, stepId) {
+  const step = stepById(ctx.doc, stepId);
+  const artRel = ctx.state.steps[stepId].artifact || artifactRelFor(stepId);
+  const artAbs = path.resolve(ctx.runDir, artRel);
+  const tmplAbs = path.resolve(ctx.podRoot, step.template);
+  // SF11.2/DF-SF11.2-4: nenhum brief é emitido com referência morta. `advance` já bloqueia
+  // antes de chegar aqui; este throw fecha o invariante para QUALQUER outro chamador.
+  const rr = requiredReading(ctx, step);
+  if (rr.missing.length > 0) {
+    throw new Error(`leitura_obrigatoria_ausente na etapa "${stepId}": ${rr.missing.join(' | ')}`);
+  }
+  const assertions = (step.veto && Array.isArray(step.veto.assertions)) ? step.veto.assertions : [];
+  const vetoLines = assertions.map((a, i) => `  ${i + 1}. ${JSON.stringify(vetoAssertionForBrief(a))}`).join('\n');
+  const mem = memorySection(ctx); // ADR-003: SOMENTE o consolidado, nunca o log cru.
+  return [
+    `# Brief — etapa "${stepId}" (agente: ${step.agent})`,
+    `Pod: ${ctx.state.pod} · Workflow: ${ctx.state.workflow} · Run: ${ctx.state.run_id}`,
+    ctx.state.task_ref ? `Tarefa: ${ctx.state.task_ref}` : null,
+    '',
+    ...requiredReadingBriefLines(rr.files),
+    '## Contrato de saída (obrigatório)',
+    `- Escreva o artefato EXATAMENTE em: ${artAbs}`,
+    `- Siga o template: ${tmplAbs} (todas as seções/headings do template devem constar).`,
+    '',
+    '## Veto (o runner verifica em disco; nenhuma passa por confiança no relato)',
+    vetoLines || '  (sem asserções declaradas)',
+    // SF7.3/ADR-016 — anti_path da etapa: os mecanizados são ENFORÇADOS pelo veto pareado
+    // (bloqueiam de verdade); os não-mecanizados são ADVISORY, rotulados explicitamente como
+    // NÃO-enforcement (honestidade SF7.6: injeção é sugestão, nunca gate).
+    ...antiPathBriefLines(step),
+    mem ? '' : null,
+    mem, // bloco condicional: omitido inteiramente quando não há memória consolidada real.
+    '',
+    '## Autoridade e retorno',
+    '- Você NÃO marca a etapa concluída; o runner decide pela verificação em disco.',
+    '- Sem git push / PR (exclusivo devops).',
+    '- Relatório final ≤15 linhas: o que produziu e onde; detalhes vão no artefato.',
+  ].filter((l) => l !== null).join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle de memória do pod (SF2.2): appending determinístico + injeção do
+// consolidado + cadência de consolidação. Consome o motor SF2.1 via `podMemory`.
+// Contrato inegociável (ADR-003 / AC3-AC4): o agente lê SOMENTE o consolidado
+// curado; NENHUM caminho do brief lê nem referencia o log cru `learnings.jsonl`.
+// ---------------------------------------------------------------------------
+
+function memOptsFor(ctx) {
+  // A memória vive em `<pod>/memory/` (ADR-003). O runner conhece o dir do pod
+  // (ctx.podRoot); `memoryPodDir` permite redirecionar em teste sem tocar produção.
+  return { podDir: ctx.memoryPodDir || ctx.podRoot };
+}
+
+/**
+ * Extrai APENAS o corpo substantivo do consolidado (das seções `##` em diante:
+ * CRITICAL pinado + Heurísticas top-N), descartando o título H1 e o cabeçalho de
+ * disclaimer que o motor gera. [AUTO-DECISION SF2.2] Esse disclaimer contém a string
+ * literal "learnings.jsonl" (pod-memory.cjs renderConsolidated) — injetá-lo cru
+ * violaria AC4 ("brief nunca menciona o log cru"). Descartar o cabeçalho preserva a
+ * arquitetura (injeta só o consolidado) e satisfaz o teste negativo. É formatação de
+ * injeção, não duplicação da lógica de consolidação (que segue inteira na SF2.1).
+ */
+function extractInjectable(md) {
+  if (!md) return '';
+  const lines = md.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^##\s+\S/.test(l));
+  if (start === -1) return '';
+  return lines.slice(start).join('\n').trim();
+}
+
+/**
+ * Bloco de memória para o brief (AC3/AC4). Retorna a seção pronta SOMENTE se o
+ * consolidado existe e tem conteúdo real (ao menos uma heurística/pin, não só
+ * cabeçalho); caso contrário `null` (seção omitida, sem placeholder vazio).
+ */
+function memorySection(ctx) {
+  let md = '';
+  try {
+    md = podMemory.getConsolidatedForBrief(ctx.state.pod, memOptsFor(ctx));
+  } catch {
+    return null; // ausência/erro de leitura do consolidado nunca quebra o brief.
+  }
+  const body = extractInjectable(md);
+  // conteúdo real = ao menos um item de heurística/pin (`- **[...]**`). Scaffold
+  // vazio ("_Nenhuma heurística consolidada ainda._") não casa → seção omitida.
+  if (!/^\s*-\s+\*\*\[/m.test(body)) return null;
+  return `## Memória consolidada (aplique estas heurísticas)\n${body}`;
+}
+
+/** Conta appends acumulados no log cru (fonte única de verdade da cadência K). */
+function rawAppendCount(ctx) {
+  const rawPath = podMemory.memoryPaths(ctx.state.pod, memOptsFor(ctx)).raw;
+  if (!fs.existsSync(rawPath)) return 0;
+  return fs.readFileSync(rawPath, 'utf8').split('\n').filter((l) => l.trim()).length;
+}
+
+/**
+ * Appenda UMA entrada de aprendizado ao motor (SF2.1) e decide a cadência de
+ * consolidação (AC5/AC6): consolida SEMPRE no fechamento (`forceConsolidate`) e/ou a
+ * cada K=20 appends acumulados no log cru — o que ocorrer primeiro. Memória é auxiliar
+ * ao enforcement: um erro de I/O de memória é reportado (nunca suprimido) mas NÃO
+ * derruba a transição da máquina de estados (o núcleo não-fake-green é intocado).
+ */
+function recordLearning(ctx, entry, { forceConsolidate = false } = {}) {
+  const memOpts = memOptsFor(ctx);
+  const pod = ctx.state.pod;
+  try {
+    podMemory.append(pod, entry, memOpts);
+    const n = rawAppendCount(ctx);
+    if (forceConsolidate || (n > 0 && n % podMemory.CONSOLIDATE_K === 0)) {
+      // SF11.4/ADR-022 (DF-SF11.4-2): o retorno de consolidate() PARA DE SER DESCARTADO.
+      // Poda nunca é silenciosa — mesmo padrão "surface, não suprime" do catch abaixo.
+      // O aviso nomeia o que saiu: quem lê o consolidado da próxima rodada precisa saber
+      // que uma heurística real deixou de ser injetada (a substância continua no log cru,
+      // que o agente nunca lê — só curadoria a recupera).
+      //
+      // SF11.4b/ADR-023 (DF-SF11.4b-1): a mensagem vem do LEDGER do motor, fonte única —
+      // este emissor não monta contador próprio. Era exatamente assim que o número
+      // errado nascia: a mensagem falava só do cano do orçamento e omitia o corte por
+      // TOP_N, anunciando "1" com 13 heurísticas fora do brief (ADR-023 §C2).
+      const res = podMemory.consolidate(pod, memOpts);
+      const ledger = podMemory.formatEvictionLedger(pod, res);
+      if (ledger) console.error(ledger);
+    }
+  } catch (e) {
+    // Surface, não suprime: aviso em stderr, run continua (memória ≠ enforcement).
+    console.error(`[memory] aviso: falha ao registrar aprendizado do pod "${pod}": ${e.message}`);
+  }
+}
+
+/**
+ * Candidato a aprendizado a partir de um bloqueio `verification_failed` (AC1). O
+ * `trigger`/`recommendation`/`evidence` são montados DETERMINISTICAMENTE a partir dos
+ * campos estruturados de `failures` (retornados por verifyStep/evalVeto) — nunca por
+ * julgamento de LLM. `tier: 'normal'` SEMPRE (o runner jamais decide critical: trava ii).
+ */
+function buildFailureLearning(ctx, stepId, failures) {
+  const list = Array.isArray(failures) ? failures : [];
+  return {
+    trigger: `etapa "${stepId}" bloqueada por verification_failed`,
+    recommendation: `corrigir antes de reexecutar: ${list.join(' | ')}`,
+    evidence: { step: stepId, veto: list, causa: `${list.length} verificação(ões) de veto/template falharam` },
+    tier: 'normal',
+    source_run_id: ctx.state.run_id,
+  };
+}
+
+/**
+ * Registro de padrão-ok a partir de um fechamento limpo (`complete`, AC2). Registra
+ * que a sequência completou sem bloqueio. `tier: 'normal'` SEMPRE.
+ * SF8.3: marcado NA ORIGEM com `type: ok_pattern` (constante do pod-memory) — vai
+ * ao log cru como trilha de auditoria de estabilidade, mas a consolidação o exclui
+ * do ranking do top-N (auto-referência não é heurística; ver splitRaw/isOkPattern).
+ */
+function buildOkLearning(ctx) {
+  const done = ctx.order.filter((id) => ctx.state.steps[id].status === 'done').length;
+  return {
+    type: podMemory.TYPE_OK_PATTERN,
+    trigger: `workflow "${ctx.state.workflow}" completou sem bloqueio`,
+    recommendation: `caminho seguido (${done} etapa(s) verificadas em disco) é válido; repetir a sequência`,
+    evidence: { steps_done: done, run_id: ctx.state.run_id },
+    tier: 'normal',
+    source_run_id: ctx.state.run_id,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Máquina de estados: transições decididas por CÓDIGO.
+// ---------------------------------------------------------------------------
+
+function depsDone(ctx, stepId) {
+  const step = stepById(ctx.doc, stepId);
+  const deps = Array.isArray(step.depends_on) ? step.depends_on : [];
+  return deps.every((d) => ctx.state.steps[d].status === 'done');
+}
+
+function firstNonDone(ctx) {
+  return ctx.order.find((id) => ctx.state.steps[id].status !== 'done') || null;
+}
+
+function dispatchStep(ctx, stepId) {
+  const st = ctx.state.steps[stepId];
+  st.status = 'running';
+  st.started_at = nowISO();
+  st.verified_at = null;
+  st.artifact = artifactRelFor(stepId);
+  fs.mkdirSync(path.resolve(ctx.runDir, 'artifacts'), { recursive: true });
+}
+
+function resetStep(ctx, stepId) {
+  const st = ctx.state.steps[stepId];
+  st.status = 'pending';
+  st.started_at = null;
+  st.verified_at = null;
+  st.artifact = null;
+}
+
+/**
+ * Avança a máquina por EXATAMENTE uma transição determinística. Nunca "fabrica verde":
+ * um passo running só vira done se verifyStep passar. Persiste o state a cada mudança.
+ * Retorna { action, step?, brief?, reason?, failures? }.
+ *   dispatch | blocked | awaiting_approval | complete
+ */
+function advance(ctx) {
+  const { state, order } = ctx;
+
+  // (1) Há passo running? → verifica em disco antes de qualquer avanço.
+  const running = order.find((id) => state.steps[id].status === 'running');
+  if (running) {
+    const v = verifyStep(ctx, running);
+    if (!v.ok) {
+      // AC1: todo bloqueio por verification_failed vira candidato a aprendizado
+      // (etapa + veto violado + causa), montado dos campos estruturados de v.failures.
+      recordLearning(ctx, buildFailureLearning(ctx, running, v.failures));
+      // NÃO avança: a etapa seguinte não roda. O passo permanece running.
+      return { action: 'blocked', step: running, reason: 'verification_failed', failures: v.failures };
+    }
+    state.steps[running].verified_at = nowISO();
+    const step = stepById(ctx.doc, running);
+    // SF11.10: o gate é condicionado ao RITMO da run, lido do state (nunca re-derivado).
+    if (isBlocking(step, state.mode)) {
+      state.steps[running].status = 'awaiting_approval';
+      writeState(ctx.statePath, state);
+      return { action: 'awaiting_approval', step: running };
+    }
+    state.steps[running].status = 'done';
+    writeState(ctx.statePath, state);
+    // segue para despachar o próximo (abaixo)
+  }
+
+  // (2) Há passo aguardando aprovação? → só approve/revise destravam.
+  const awaiting = order.find((id) => state.steps[id].status === 'awaiting_approval');
+  if (awaiting) {
+    return { action: 'awaiting_approval', step: awaiting };
+  }
+
+  // (3) Próximo pendente na ordem topológica com dependências satisfeitas.
+  const next = order.find((id) => state.steps[id].status === 'pending' && depsDone(ctx, id));
+  if (!next) {
+    const anyPending = order.some((id) => state.steps[id].status === 'pending');
+    if (!anyPending) {
+      writeState(ctx.statePath, state);
+      // AC2 + AC5: fechamento limpo appenda padrão-ok e SEMPRE dispara consolidate
+      // (após o append), consolidando o aprendizado acumulado do run.
+      recordLearning(ctx, buildOkLearning(ctx), { forceConsolidate: true });
+      return { action: 'complete' };
+    }
+    return { action: 'blocked', reason: 'deps_unmet' };
+  }
+  // (3b) SF11.2/ADR-021 `DF-SF11.2-4` — leitura obrigatória da etapa resolvida e VERIFICADA
+  // em disco ANTES do despacho. Referência morta (agente ou knowledge declarado que não
+  // existe, ou path que escapa da raiz do pod) BLOQUEIA: a etapa NÃO é despachada (segue
+  // `pending`) e NENHUM brief é emitido. Paridade com o compilador de export, que já falha
+  // pela mesma causa (`pod-export-compile.cjs:214,236`) sobre o MESMO `wf`.
+  // Não gera aprendizado de memória de propósito: isto é defeito de CONFIGURAÇÃO do pod em
+  // disco (o operador conserta o `wf`/arquivo), não aprendizado de execução do run.
+  const rr = requiredReading(ctx, stepById(ctx.doc, next));
+  if (rr.missing.length > 0) {
+    return { action: 'blocked', step: next, reason: 'leitura_obrigatoria_ausente', failures: rr.missing };
+  }
+  dispatchStep(ctx, next);
+  const brief = buildBrief(ctx, next);
+  writeState(ctx.statePath, state);
+  return { action: 'dispatch', step: next, brief };
+}
+
+function approve(ctx, stepId) {
+  const { state, order } = ctx;
+  const target = stepId || order.find((id) => state.steps[id].status === 'awaiting_approval');
+  if (!target || state.steps[target].status !== 'awaiting_approval') {
+    return { action: 'noop', reason: 'nenhuma etapa aguardando aprovação' };
+  }
+  state.steps[target].status = 'done';
+  writeState(ctx.statePath, state);
+  // libera o próximo passo
+  const nxt = advance(ctx);
+  return { action: 'approved', step: target, next: nxt };
+}
+
+function revise(ctx, stepId) {
+  const { state, order, doc } = ctx;
+  const target = stepId || order.find((id) => state.steps[id].status === 'awaiting_approval');
+  if (!target) return { action: 'noop', reason: 'nenhuma etapa para revisar' };
+  const step = stepById(doc, target);
+
+  // Fix-loop explícito (SPEC §B2a): revise honra `fix_cycle` devolvendo o alcance
+  // [fix_cycle.to .. target] a pending para reexecução, sob max_iterations.
+  if (step.fix_cycle) {
+    const to = step.fix_cycle.to;
+    const max = step.fix_cycle.max_iterations || Infinity;
+    const st = state.steps[target];
+    st.fix_iterations = (st.fix_iterations || 0) + 1;
+    if (st.fix_iterations > max) {
+      state.steps[target].status = 'failed';
+      writeState(ctx.statePath, state);
+      return { action: 'halt', step: target, reason: `fix_cycle max_iterations (${max}) excedido` };
+    }
+    const iTo = order.indexOf(to);
+    const iTarget = order.indexOf(target);
+    for (let k = iTo; k <= iTarget; k++) {
+      const keep = state.steps[order[k]].fix_iterations; // preserva contador do owner
+      resetStep(ctx, order[k]);
+      if (order[k] === target) state.steps[target].fix_iterations = keep;
+    }
+    writeState(ctx.statePath, state);
+    const nxt = advance(ctx);
+    return { action: 'revised', step: target, loop_to: to, iteration: st.fix_iterations, next: nxt };
+  }
+
+  // Sem fix_cycle: apenas a própria etapa volta a pending para reexecução.
+  resetStep(ctx, target);
+  writeState(ctx.statePath, state);
+  const nxt = advance(ctx);
+  return { action: 'revised', step: target, next: nxt };
+}
+
+function abort(ctx) {
+  ctx.state.mode_aborted = true;
+  for (const id of ctx.order) {
+    if (['pending', 'running', 'awaiting_approval'].includes(ctx.state.steps[id].status)) {
+      ctx.state.steps[id].status = 'failed';
+    }
+  }
+  writeState(ctx.statePath, ctx.state);
+  return { action: 'aborted' };
+}
+
+function statusSummary(ctx) {
+  const rows = ctx.order.map((id) => `  ${id}: ${ctx.state.steps[id].status}`);
+  const next = firstNonDone(ctx);
+  return [
+    `Run ${ctx.state.run_id} · ${ctx.state.pod}/${ctx.state.workflow} · mode=${ctx.state.mode}`,
+    ...rows,
+    `próximo não-done: ${next || '(nenhum — completo)'}`,
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Construção de contexto e start.
+// ---------------------------------------------------------------------------
+
+function buildContext({ workflowPath, podRootOverride, statePath, state, memoryPodDir }) {
+  const { doc, podRoot, order } = loadWorkflow(workflowPath, podRootOverride);
+  return {
+    doc,
+    podRoot,
+    order,
+    statePath,
+    runDir: path.dirname(statePath),
+    workflowPath,
+    state,
+    // Dir do pod p/ o lifecycle de memória (SF2.2). Precedência (SF9.2 CONCERNS-1):
+    // (1) override explícito; (2) roteamento GRAVADO no state do run (`memory_pod_dir`,
+    // escrito no start — o operador que dirige next/approve o honra sem re-derivar);
+    // (3) default = raiz do pod (produção grava em `<pod>/memory/`). Ausente = retrocompat.
+    memoryPodDir: memoryPodDir || (state && state.memory_pod_dir) || podRoot,
+  };
+}
+
+/**
+ * start: cria o state.json (schema exato SPEC §B1, todos os passos pending) e faz o
+ * primeiro dispatch. Retorna { ctx, result }.
+ */
+function startRun(opts) {
+  const {
+    workflowPath,
+    podRootOverride,
+    pod,
+    workflow,
+    mode = 'interactive',
+    taskRef = null,
+    runsRoot,
+    runId = makeRunId(),
+    date,
+  } = opts;
+  // SF11.10/ADR-024 `DF-SF11.10-5` — `mode` deixa de ser rótulo inerte (emenda ao ADR-020
+  // `DF-SF10.21-12`) e passa a ser CONJUNTO FECHADO, validado aqui, no único ponto de entrada
+  // que o cria. Sem este fechamento, `--mode YOLO` (maiúscula) não casaria `skip_modes` e
+  // travaria a rodada autônoma em `awaiting_approval` esperando um humano que a proibição do
+  // ADR-020 impede o comando de substituir — deadlock obscuro. Aqui vira erro imediato e
+  // legível. Breaking change DECLARADO: antes qualquer string era aceita.
+  if (!RUN_MODES.includes(mode)) {
+    throw new Error(`modo de run inválido: ${JSON.stringify(mode)} — valores aceitos: ${RUN_MODES.join(', ')} ` +
+      '(o modo agora decide quais checkpoints bloqueiam, via checkpoint.skip_modes; um rótulo livre ' +
+      'travaria a run num gate que ninguém pode destravar)');
+  }
+  const rid = opts.runId || makeRunId(date);
+  const { doc, podRoot, order } = loadWorkflow(workflowPath, podRootOverride);
+  const statePath = statePathFor(runsRoot, pod, workflow, rid);
+
+  const steps = {};
+  for (const step of doc.steps) {
+    steps[step.id] = {
+      status: 'pending',
+      agent: step.agent,
+      artifact: null,
+      template: step.template,
+      // SF11.10/DF-SF11.10-2: materialização HONESTA. Numa run que pula o gate, isto grava
+      // `null` — a auditoria diz "esta rodada não teve gate humano aqui", que é a verdade.
+      // Auto-aprovar escreveria a mentira oposta (done por veredito humano inexistente).
+      checkpoint: isBlocking(step, mode) ? 'blocking' : null,
+      started_at: null,
+      verified_at: null,
+    };
+  }
+  const state = {
+    pod,
+    workflow,
+    run_id: rid,
+    mode,
+    task_ref: taskRef,
+    // SF9.2 CONCERNS-1: grava o ROTEAMENTO de memória do run UMA vez, no start. Todo comando
+    // subsequente (next/approve/revise via openRun) o HONRA lendo do state — nunca re-deriva
+    // por default. Sem isso, o start do pipeline isolava em tmp mas o `next` do operador
+    // escrevia no memory REAL do pod (contaminação ativa). Ausente ⇒ retrocompat (podRoot).
+    ...(opts.memoryPodDir ? { memory_pod_dir: opts.memoryPodDir } : {}),
+    steps,
+    updated_at: nowISO(),
+  };
+  writeState(statePath, state);
+
+  const ctx = {
+    doc, podRoot, order, statePath, runDir: path.dirname(statePath), workflowPath, state,
+    memoryPodDir: opts.memoryPodDir || podRoot,
+  };
+  const result = advance(ctx); // primeiro dispatch
+  return { ctx, result };
+}
+
+/** Localiza o state.json de um run-id sob runsRoot (`.power-claude/pod-runs/**`). */
+function findStateByRunId(runsRoot, runId) {
+  const stack = [runsRoot];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === runId && fs.existsSync(path.join(p, 'state.json'))) {
+          return path.join(p, 'state.json');
+        }
+        stack.push(p);
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * resume/openRun: reconstrói o ctx a partir de um state.json em disco. SEMPRE lê o
+ * state primeiro (Sequence Lock / Risco 4). O workflowPath é derivado ou informado.
+ */
+function openRun({ statePath, workflowPath, podRootOverride, memoryPodDir }) {
+  const state = readState(statePath);
+  return buildContext({ workflowPath, podRootOverride, statePath, state, memoryPodDir });
+}
+
+// ---------------------------------------------------------------------------
+// CLI (a skill invoca; a suíte própria importa as funções acima).
+// ---------------------------------------------------------------------------
+
+function argVal(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+function deriveWorkflowPath(args, pod, workflow, runsRoot, statePath) {
+  const explicit = argVal(args, '--workflow-file');
+  if (explicit) return explicit;
+  const podRoot = argVal(args, '--pod-root');
+  if (podRoot && workflow) return path.join(podRoot, 'workflows', `${workflow}.yaml`);
+  throw new Error('informe --workflow-file <path> (ou --pod-root <dir> + workflow)');
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+  const runsRoot = argVal(args, '--runs-root') || path.join(process.cwd(), '.power-claude', 'pod-runs');
+  const podRootOverride = argVal(args, '--pod-root');
+
+  try {
+    if (cmd === 'start') {
+      const pod = args[1];
+      const workflow = args[2];
+      const taskRef = args[3] && !args[3].startsWith('--') ? args[3] : null;
+      const workflowPath = deriveWorkflowPath(args, pod, workflow);
+      const { ctx, result } = startRun({
+        workflowPath,
+        podRootOverride,
+        pod,
+        workflow,
+        mode: argVal(args, '--mode') || 'interactive',
+        taskRef: argVal(args, '--task-ref') || taskRef,
+        runsRoot,
+        runId: argVal(args, '--run-id'),
+      });
+      console.log(`[start] run ${ctx.state.run_id} → ${ctx.statePath}`);
+      printResult(result);
+      process.exit(0);
+    }
+
+    if (['resume', 'next', 'status', 'approve', 'revise', 'abort'].includes(cmd)) {
+      let statePath = argVal(args, '--state');
+      if (!statePath && cmd === 'resume') {
+        const runId = args[1];
+        statePath = findStateByRunId(runsRoot, runId);
+        if (!statePath) throw new Error(`run-id "${runId}" não encontrado sob ${runsRoot}`);
+      }
+      if (!statePath) throw new Error(`comando "${cmd}" exige --state <path> (ou resume <run-id>)`);
+      const workflowPath = deriveWorkflowPath(args);
+      const ctx = openRun({ statePath, workflowPath, podRootOverride });
+
+      if (cmd === 'status') {
+        console.log(statusSummary(ctx));
+        process.exit(0);
+      }
+      if (cmd === 'abort') {
+        printResult(abort(ctx));
+        process.exit(0);
+      }
+      if (cmd === 'approve') {
+        printResult(approve(ctx, argVal(args, '--step')));
+        process.exit(0);
+      }
+      if (cmd === 'revise') {
+        printResult(revise(ctx, argVal(args, '--step')));
+        process.exit(0);
+      }
+      // resume | next → uma transição
+      printResult(advance(ctx));
+      process.exit(0);
+    }
+
+    console.error('Uso: pc-run-pod.cjs <start|resume|next|status|approve|revise|abort> [args]');
+    console.error('  start <pod> <workflow> [task-ref] --workflow-file <wf.yaml> [--pod-root d] [--mode m] [--run-id id] [--runs-root d]');
+    console.error('  next|status|approve|revise|abort --state <state.json> --workflow-file <wf.yaml> [--pod-root d] [--step id]');
+    console.error('  resume <run-id> --workflow-file <wf.yaml> [--pod-root d] [--runs-root d]');
+    process.exit(2);
+  } catch (e) {
+    console.error(`[erro] ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function printResult(r) {
+  console.log(`[${r.action}]${r.step ? ` etapa=${r.step}` : ''}${r.reason ? ` motivo=${r.reason}` : ''}`);
+  if (r.failures && r.failures.length) {
+    for (const f of r.failures) console.log(`  - ${f}`);
+  }
+  if (r.brief) console.log(`\n--- BRIEF ---\n${r.brief}\n--- /BRIEF ---`);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  makeRunId,
+  runDirFor,
+  statePathFor,
+  readState,
+  writeState,
+  validateStateSchema,
+  loadWorkflow,
+  capabilityGaps,
+  annotateCapabilitySkew,
+  correctionCommand,
+  stepById,
+  isBlocking,
+  RUN_MODES, // SF11.10 — re-exportado do validador (fonte única) para consumidores do motor.
+  extractHeadings,
+  extractField,
+  countListItemsInSection,
+  evalVeto,
+  extractFencedBlock,
+  checkTemplateConformance,
+  verifyStep,
+  buildBrief,
+  antiPathBriefLines,
+  requiredReading,
+  requiredReadingBriefLines,
+  vetoAssertionForBrief,
+  memorySection,
+  extractInjectable,
+  recordLearning,
+  buildFailureLearning,
+  buildOkLearning,
+  rawAppendCount,
+  artifactRelFor,
+  depsDone,
+  firstNonDone,
+  dispatchStep,
+  resetStep,
+  advance,
+  approve,
+  revise,
+  abort,
+  statusSummary,
+  buildContext,
+  startRun,
+  findStateByRunId,
+  openRun,
+};