@daniellins/power-claude 0.16.3

package/scripts/validate-pod-workflow.cjs

@@ -0,0 +1,878 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * validate-pod-workflow.cjs — validador estático do contrato `wf-*.yaml` de pod.
+ *
+ * Prova, SEM EXECUTAR NADA, que um workflow de pod está BEM-FORMADO (não que
+ * funciona — isso é o smoke dinâmico, SF1.3; fronteira do ADR-002). Porta o
+ * padrão --strict --fail-on-warnings / stop-on-first-failure. Exit 0 = contrato
+ * bem-formado; exit != 0 = primeira violação nomeada (arquivo, etapa, campo).
+ *
+ * Uso:
+ *   node scripts/validate-pod-workflow.cjs <wf.yaml> [<wf.yaml> ...] [--pod-root <dir>]
+ *   node scripts/validate-pod-workflow.cjs --glob template/pods            (varre **\/workflows/*.yaml)
+ *
+ * Verificações (Escopo IN c da Story SF1.1; SPEC §B2a; ADR-002), em ordem,
+ * stop-on-first-failure por arquivo:
+ *   1. Schema        — state_machine (com `failed` terminal) + steps[] tipados.
+ *   2. Etapa completa — toda etapa tem agent + template + outputs + veto.
+ *   3. Veto de máquina — veto.assertions[] reduz a uma das 5 formas (ADR-002).
+ *   4. DAG acíclico  — depends_on referencia ids válidos e não forma ciclo.
+ *   5. Fix-loop      — `fix_cycle` (opcional) referencia etapa A MONTANTE; é a
+ *                       ÚNICA aresta para trás permitida (SPEC §B2a "exceto o
+ *                       fix-loop explícito"). Aresta para trás via `depends_on`
+ *                       continua sendo ciclo → FALHA (débito herdado da SF1.1).
+ *   6. Templates      — todo template: existe em disco (path resolvido do pod).
+ *   7. Handoffs fechados — todo output é consumido a jusante ou é artefato final.
+ *   8. Checkpoint     — (SF11.10/ADR-024) forma de `checkpoint` (blocking/criteria/skip_modes,
+ *                       chaves fechadas) + INVARIANTE: nenhum modo do conjunto fechado fica sem
+ *                       um gate bloqueante não-pulável. Primeiro enforcement de MÁQUINA da
+ *                       proibição do ADR-020 ("o modo autônomo JAMAIS aprova").
+ *
+ * Node >= 18, sem dependências externas (parser YAML-lite embutido — ver abaixo).
+ * Exporta `parseYaml`, `validateWorkflow`, `podRootFor`, `topoOrder`, `VETO_TYPES`,
+ * `Fail` para reuso pelo runner `pc-run-pod.cjs` (fonte única do contrato — Risco 2
+ * da Story SF1.2: preflight do runner não reimplementa o schema/DAG).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const VETO_TYPES = {
+  section_exists: ['section'],
+  field_matches: ['field', 'pattern'],
+  file_referenced_exists: ['field'],
+  count_gte: ['field', 'n'],
+  json_schema_valid: ['schema'],
+  // SF7.2/ADR-011 — 6ª forma: executa um script BLESSED (só sob scripts/veto-checks/).
+  command_check: ['command'],
+};
+// Raiz BLESSED de execução (ADR-011 Decisão 2): o runner NUNCA executa código de pod —
+// só scripts autorados/code-reviewed do framework sob este diretório.
+const VETO_CHECKS_ROOT = path.join(REPO_ROOT, 'scripts', 'veto-checks');
+
+/**
+ * SF11.10/ADR-024 `DF-SF11.10-5` — CONJUNTO FECHADO de ritmos de run. Emenda explícita ao
+ * ADR-020 `DF-SF10.21-12` ("`--mode` é rótulo inerte"): a partir daqui o modo PRODUZ
+ * diferença estrutural (`checkpoint.skip_modes`), e um rótulo não pode fazer isso. Mora
+ * AQUI, e não no motor, porque este arquivo é a FONTE ÚNICA do contrato (o motor o importa,
+ * Risco 2 da SF1.2): o validador estático e o runtime têm que concordar sobre o conjunto por
+ * construção, nunca por duas listas que alguém sincroniza à mão.
+ */
+const RUN_MODES = ['interactive', 'yolo'];
+
+/**
+ * SF11.10/ADR-024 `DF-SF11.10-2`/`-6` — chaves CONHECIDAS sob `checkpoint` de uma etapa.
+ * Lista fechada: chave fora dela é contrato de um motor mais novo (ou typo) e vira falha
+ * estática aqui + gap nomeado em `capabilityGaps` (pc-run-pod.cjs) — nunca degradação muda.
+ */
+const CHECKPOINT_KEYS = ['blocking', 'criteria', 'skip_modes'];
+
+/**
+ * Validação ESTÁTICA de segurança de um `command_check` (ADR-011 Decisão 2), ANTES de
+ * qualquer execução: (1) `command` é nome de arquivo simples (sem `/`, sem `..`) → sem
+ * path traversal; (2) resolve DENTRO de scripts/veto-checks/; (3) extensão .cjs/.js;
+ * (4) existe em disco; (5) consta no manifesto ADR-007; (6) `args` (se houver) é array de
+ * strings LITERAIS, nunca template/interpolação. Qualquer violação → Fail (exit 1).
+ */
+function checkCommandCheckSafety(assertion) {
+  const cmd = assertion.command;
+  if (typeof cmd !== 'string' || cmd.trim() === '') fail('command_check: "command" ausente ou não-string');
+  if (/[\\/]/.test(cmd) || cmd.includes('..')) {
+    fail(`command_check: "command" deve ser um nome de arquivo simples sob scripts/veto-checks/ (sem caminho nem traversal): "${cmd}"`);
+  }
+  if (!/\.(cjs|js)$/.test(cmd)) fail(`command_check: extensão não permitida em "${cmd}" (esperado .cjs/.js)`);
+  const resolved = path.resolve(VETO_CHECKS_ROOT, cmd);
+  if (path.dirname(resolved) !== VETO_CHECKS_ROOT) {
+    fail(`command_check: "${cmd}" resolve fora da raiz blessed scripts/veto-checks/ — recusado`);
+  }
+  if (!fs.existsSync(resolved)) fail(`command_check: script blessed inexistente: scripts/veto-checks/${cmd}`);
+  const rel = `scripts/veto-checks/${cmd}`;
+  let inManifest = true;
+  try {
+    const { motorRels } = require(path.join(REPO_ROOT, 'installer', 'motor-scripts.js'));
+    inManifest = motorRels().includes(rel);
+  } catch { /* manifesto indisponível na instalação — a raiz blessed + existência já barram */ }
+  if (!inManifest) fail(`command_check: "${rel}" não está classificado em installer/motor-scripts.json (ADR-007)`);
+  if ('args' in assertion) {
+    if (!Array.isArray(assertion.args)) fail('command_check: "args" deve ser um array de strings literais');
+    for (const a of assertion.args) {
+      if (typeof a !== 'string') fail(`command_check: "args" só aceita strings literais (recebeu ${typeof a})`);
+      if (/[`$]|\{\{|\$\(/.test(a)) fail(`command_check: "args" não pode conter template/interpolação/shell: "${a}"`);
+    }
+  }
+  if ('timeout_ms' in assertion && (!Number.isInteger(assertion.timeout_ms) || assertion.timeout_ms <= 0)) {
+    fail(`command_check: "timeout_ms" deve ser inteiro > 0 (recebeu ${JSON.stringify(assertion.timeout_ms)})`);
+  }
+}
+
+/** Valida o shape do `extract:{section,fence}` opcional do json_schema_valid (ADR-011 Decisão 1). */
+function checkJsonSchemaExtract(assertion) {
+  if (!('extract' in assertion) || assertion.extract == null) return;
+  const ex = assertion.extract;
+  if (typeof ex !== 'object' || Array.isArray(ex)) fail('json_schema_valid.extract deve ser um mapa {section, fence?}');
+  if (typeof ex.section !== 'string' || ex.section.trim() === '') fail('json_schema_valid.extract.section ausente (string)');
+  if ('fence' in ex && (typeof ex.fence !== 'string' || ex.fence.trim() === '')) fail('json_schema_valid.extract.fence deve ser string não-vazia');
+}
+
+// ---------------------------------------------------------------------------
+// YAML-lite: parser de indentação para o subconjunto do contrato wf-*.yaml.
+// Decisão do @dev (Story SF1.1): o repo tem ZERO dependências (sem node_modules,
+// sem js-yaml declarado) e `scripts/` é publicado no pacote (files[]). Adicionar
+// js-yaml como dep de produção pesa no npm pack sem ganho — o contrato é
+// estruturalmente simples (mapas/listas/escalares). Parser próprio, determinístico.
+// Suporta: mapas aninhados por indentação, listas de bloco (`- `), listas/mapas
+// em flow (`[a, b]`, `{k: v}`), escalares (string/int/bool/null), comentários.
+// NÃO suporta: âncoras, tags, escalares multi-linha (não usados pelo contrato).
+// ---------------------------------------------------------------------------
+
+function stripComment(line) {
+  let inS = false;
+  let inD = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (c === "'" && !inD) inS = !inS;
+    else if (c === '"' && !inS) inD = !inD;
+    else if (c === '#' && !inS && !inD && (i === 0 || /\s/.test(line[i - 1]))) {
+      return line.slice(0, i);
+    }
+  }
+  return line;
+}
+
+function splitTopLevel(str, sep) {
+  const out = [];
+  let depth = 0;
+  let inS = false;
+  let inD = false;
+  let cur = '';
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    if (c === "'" && !inD) inS = !inS;
+    else if (c === '"' && !inS) inD = !inD;
+    if (!inS && !inD) {
+      if (c === '[' || c === '{') depth++;
+      else if (c === ']' || c === '}') depth--;
+      else if (c === sep && depth === 0) {
+        out.push(cur);
+        cur = '';
+        continue;
+      }
+    }
+    cur += c;
+  }
+  out.push(cur);
+  return out;
+}
+
+function parseScalar(raw) {
+  const s = raw.trim();
+  if (s === '' || s === '~' || s === 'null') return null;
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (/^-?\d+$/.test(s)) return Number.parseInt(s, 10);
+  if (/^-?\d+\.\d+$/.test(s)) return Number.parseFloat(s);
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  if (s.startsWith('[') && s.endsWith(']')) {
+    const body = s.slice(1, -1).trim();
+    if (body === '') return [];
+    return splitTopLevel(body, ',').map((e) => parseScalar(e));
+  }
+  if (s.startsWith('{') && s.endsWith('}')) {
+    const body = s.slice(1, -1).trim();
+    const obj = {};
+    if (body === '') return obj;
+    for (const entry of splitTopLevel(body, ',')) {
+      const [k, ...rest] = splitTopLevel(entry, ':');
+      obj[parseScalar(k)] = parseScalar(rest.join(':'));
+    }
+    return obj;
+  }
+  return s;
+}
+
+function isMapEntry(content) {
+  // Uma entrada de mapa tem um ':' de topo seguido de espaço ou fim de linha,
+  // e não é um item de sequência de bloco, nem um flow list/map inteiro.
+  if (content.startsWith('- ') || content === '-') return false;
+  if ((content.startsWith('[') && content.endsWith(']')) ||
+      (content.startsWith('{') && content.endsWith('}'))) return false;
+  let inS = false;
+  let inD = false;
+  let depth = 0;
+  for (let i = 0; i < content.length; i++) {
+    const c = content[i];
+    if (c === "'" && !inD) inS = !inS;
+    else if (c === '"' && !inS) inD = !inD;
+    else if (!inS && !inD) {
+      if (c === '[' || c === '{') depth++;
+      else if (c === ']' || c === '}') depth--;
+      else if (c === ':' && depth === 0 && (i === content.length - 1 || content[i + 1] === ' ')) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function splitEntry(content) {
+  let inS = false;
+  let inD = false;
+  let depth = 0;
+  for (let i = 0; i < content.length; i++) {
+    const c = content[i];
+    if (c === "'" && !inD) inS = !inS;
+    else if (c === '"' && !inS) inD = !inD;
+    else if (!inS && !inD) {
+      if (c === '[' || c === '{') depth++;
+      else if (c === ']' || c === '}') depth--;
+      else if (c === ':' && depth === 0 && (i === content.length - 1 || content[i + 1] === ' ')) {
+        return { key: content.slice(0, i).trim(), val: content.slice(i + 1).trim() };
+      }
+    }
+  }
+  return { key: content.trim(), val: '' };
+}
+
+function parseYaml(text) {
+  const lines = [];
+  text.split(/\r?\n/).forEach((rawLine, idx) => {
+    const noComment = stripComment(rawLine);
+    if (noComment.trim() === '') return;
+    lines.push({
+      indent: noComment.length - noComment.trimStart().length,
+      content: noComment.trim(),
+      n: idx + 1,
+    });
+  });
+
+  let i = 0;
+
+  function parseValue(indent) {
+    if (i >= lines.length) return null;
+    const c = lines[i].content;
+    if (c.startsWith('- ') || c === '-') return parseSeq(indent);
+    return parseMap(indent);
+  }
+
+  function parseSeq(indent) {
+    const arr = [];
+    while (i < lines.length && lines[i].indent === indent &&
+           (lines[i].content.startsWith('- ') || lines[i].content === '-')) {
+      const line = lines[i];
+      const rest = line.content === '-' ? '' : line.content.slice(2).trim();
+      if (rest === '') {
+        i++;
+        if (i < lines.length && lines[i].indent > indent) arr.push(parseValue(lines[i].indent));
+        else arr.push(null);
+      } else if (isMapEntry(rest)) {
+        const childIndent = indent + 2;
+        // Reescreve a linha corrente como entrada de mapa em childIndent e
+        // deixa parseMap consumir a semente + entradas irmãs alinhadas.
+        lines[i] = { indent: childIndent, content: rest, n: line.n };
+        arr.push(parseMap(childIndent));
+      } else {
+        arr.push(parseScalar(rest));
+        i++;
+      }
+    }
+    return arr;
+  }
+
+  function parseMap(indent) {
+    const obj = {};
+    while (i < lines.length && lines[i].indent === indent && isMapEntry(lines[i].content)) {
+      const { key, val } = splitEntry(lines[i].content);
+      if (val === '') {
+        i++;
+        if (i < lines.length && lines[i].indent > indent) {
+          obj[key] = parseValue(lines[i].indent);
+        } else if (i < lines.length && lines[i].indent === indent &&
+                   (lines[i].content.startsWith('- ') || lines[i].content === '-')) {
+          obj[key] = parseSeq(indent);
+        } else {
+          obj[key] = null;
+        }
+      } else {
+        obj[key] = parseScalar(val);
+        i++;
+      }
+    }
+    return obj;
+  }
+
+  return parseValue(lines.length ? lines[0].indent : 0);
+}
+
+// ---------------------------------------------------------------------------
+// Validação do contrato.
+// ---------------------------------------------------------------------------
+
+class Fail extends Error {}
+function fail(msg) {
+  throw new Fail(msg);
+}
+
+function podRootFor(workflowPath, override) {
+  if (override) return path.resolve(override);
+  const dir = path.dirname(workflowPath);
+  // Convenção: <pod>/workflows/wf-*.yaml → raiz do pod é o pai de workflows/.
+  if (path.basename(dir) === 'workflows') return path.dirname(dir);
+  return dir;
+}
+
+function checkSchema(doc) {
+  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+    fail('raiz do documento não é um mapa YAML');
+  }
+  const sm = doc.state_machine;
+  if (!sm || typeof sm !== 'object') fail('campo obrigatório ausente: state_machine');
+  if (!Array.isArray(sm.states) || sm.states.length === 0) {
+    fail('state_machine.states ausente ou vazio (esperado lista de estados)');
+  }
+  for (const req of ['init', 'complete', 'failed']) {
+    if (!sm.states.includes(req)) fail(`state_machine.states não contém o estado obrigatório "${req}"`);
+  }
+  const terminal = Array.isArray(sm.terminal) ? sm.terminal : [];
+  if (!terminal.includes('failed')) fail('state_machine.terminal deve incluir "failed" (estado terminal)');
+  if (!Array.isArray(doc.steps) || doc.steps.length === 0) {
+    fail('campo obrigatório ausente: steps[] (esperado lista não-vazia)');
+  }
+  doc.steps.forEach((step, idx) => {
+    if (!step || typeof step !== 'object' || Array.isArray(step)) {
+      fail(`steps[${idx}] não é um mapa`);
+    }
+    if (typeof step.id !== 'string' || step.id.trim() === '') {
+      fail(`steps[${idx}] sem campo obrigatório "id"`);
+    }
+  });
+  const seen = new Set();
+  for (const step of doc.steps) {
+    if (seen.has(step.id)) fail(`id de etapa duplicado: "${step.id}"`);
+    seen.add(step.id);
+  }
+}
+
+function checkStepCompleteness(doc) {
+  // AC2/AC4: toda etapa tem agent + template + outputs (não-vazio) + veto.
+  for (const step of doc.steps) {
+    const id = step.id;
+    if (typeof step.agent !== 'string' || step.agent.trim() === '') {
+      fail(`etapa "${id}": campo obrigatório ausente: agent`);
+    }
+    if (typeof step.template !== 'string' || step.template.trim() === '') {
+      fail(`etapa "${id}": campo obrigatório ausente: template`);
+    }
+    if (!Array.isArray(step.outputs) || step.outputs.length === 0) {
+      fail(`etapa "${id}": campo obrigatório ausente ou vazio: outputs (artefato declarado)`);
+    }
+    if (!step.veto || typeof step.veto !== 'object') {
+      fail(`etapa "${id}": campo obrigatório ausente: veto`);
+    }
+  }
+}
+
+function checkVetoMachineEvaluable(doc) {
+  // AC7 / ADR-002: veto.assertions[] reduz a uma das 5 formas estruturadas.
+  for (const step of doc.steps) {
+    const id = step.id;
+    const assertions = step.veto.assertions;
+    if (!Array.isArray(assertions) || assertions.length === 0) {
+      fail(`etapa "${id}": veto.assertions ausente ou vazio (ADR-002: veto deve ser asserção de máquina, não prosa)`);
+    }
+    assertions.forEach((a, ai) => {
+      if (typeof a === 'string' || a === null || typeof a !== 'object' || Array.isArray(a)) {
+        fail(`etapa "${id}": veto.assertions[${ai}] é prosa/valor livre, não asserção estruturada — proibido por ADR-002 (formas válidas: ${Object.keys(VETO_TYPES).join(', ')})`);
+      }
+      if (typeof a.type !== 'string' || !(a.type in VETO_TYPES)) {
+        fail(`etapa "${id}": veto.assertions[${ai}].type inválido ("${a.type}") — não redutível a asserção de máquina (ADR-002; formas válidas: ${Object.keys(VETO_TYPES).join(', ')})`);
+      }
+      for (const req of VETO_TYPES[a.type]) {
+        if (!(req in a) || a[req] === null || a[req] === '') {
+          fail(`etapa "${id}": veto.assertions[${ai}] (type=${a.type}) sem campo obrigatório "${req}"`);
+        }
+      }
+      if (a.type === 'field_matches') {
+        try {
+          new RegExp(String(a.pattern));
+        } catch (e) {
+          fail(`etapa "${id}": veto.assertions[${ai}] field_matches com regex inválida: ${e.message}`);
+        }
+      }
+      if (a.type === 'command_check') {
+        try {
+          checkCommandCheckSafety(a);
+        } catch (e) {
+          fail(`etapa "${id}": veto.assertions[${ai}] ${e.message}`);
+        }
+      }
+      if (a.type === 'json_schema_valid') {
+        try {
+          checkJsonSchemaExtract(a);
+        } catch (e) {
+          fail(`etapa "${id}": veto.assertions[${ai}] ${e.message}`);
+        }
+      }
+    });
+  }
+}
+
+/**
+ * SF7.3/ADR-016 — valida a FORMA do campo OPCIONAL `anti_path` por etapa (instrução
+ * negativa escopo-de-etapa). Ausente = no-op (retrocompat byte-idêntica). Quando presente:
+ * array de `{ rule: string não-vazio, mechanized_by: null | <id de uma veto.assertion da
+ * MESMA etapa> }`. `mechanized_by` que não referencia um id real de asserção da etapa =
+ * FAIL estático (deriva vira erro, não passa a runtime). A enforcement dos itens mecanizados
+ * é a da própria asserção pareada (runner genérico); a injeção do não-mecanizado é advisory.
+ */
+function checkAntiPath(doc) {
+  for (const step of doc.steps) {
+    if (step.anti_path == null) continue; // OPCIONAL — só valida quando presente
+    const ap = step.anti_path;
+    if (!Array.isArray(ap)) fail(`etapa "${step.id}": anti_path deve ser um array (ou ausente)`);
+    const assertions = (step.veto && Array.isArray(step.veto.assertions)) ? step.veto.assertions : [];
+    const ids = new Set(assertions.filter((a) => a && typeof a.id === 'string' && a.id.trim()).map((a) => a.id));
+    ap.forEach((item, i) => {
+      if (!item || typeof item !== 'object' || Array.isArray(item)) {
+        fail(`etapa "${step.id}": anti_path[${i}] deve ser um mapa { rule, mechanized_by }`);
+      }
+      if (typeof item.rule !== 'string' || item.rule.trim() === '') {
+        fail(`etapa "${step.id}": anti_path[${i}].rule ausente ou vazio (instrução negativa obrigatória)`);
+      }
+      if ('mechanized_by' in item && item.mechanized_by !== null) {
+        if (typeof item.mechanized_by !== 'string') {
+          fail(`etapa "${step.id}": anti_path[${i}].mechanized_by deve ser null ou o id (string) de uma veto.assertion da etapa`);
+        }
+        if (!ids.has(item.mechanized_by)) {
+          fail(`etapa "${step.id}": anti_path[${i}].mechanized_by "${item.mechanized_by}" não referencia nenhuma veto.assertion com esse id nesta etapa (item mecanizável sem veto que o enforça)`);
+        }
+      }
+    });
+  }
+}
+
+/**
+ * SF10.1/ADR-018 D2 — valida a FORMA do campo OPCIONAL `knowledge:` por etapa (lista ordenada
+ * de knowledge/*.md citados pela fase) e do `knowledge_exclude:` opcional no topo. Ausente =
+ * no-op (retrocompat byte-idêntica — precedente `anti_path`). Aqui só a FORMA: QUANDO declarado,
+ * o campo é uma lista de strings não-vazias. [SF11.2/DF-SF11.2-4] A EXISTÊNCIA em disco passou a
+ * ser checada por `checkKnowledgeExists` (paridade com `pod-export-compile.cjs:236`); as
+ * demais semânticas (superconjunto das citações, órfãos) seguem só no COMPILADOR de export.
+ */
+function checkKnowledge(doc) {
+  if (doc.knowledge_exclude != null) {
+    if (!Array.isArray(doc.knowledge_exclude)) fail('knowledge_exclude (topo) deve ser um array de strings (ou ausente)');
+    doc.knowledge_exclude.forEach((k, i) => {
+      if (typeof k !== 'string' || k.trim() === '') fail(`knowledge_exclude[${i}] deve ser string não-vazia`);
+    });
+  }
+  for (const step of doc.steps) {
+    if (step.knowledge == null) continue; // OPCIONAL — só valida quando presente
+    if (!Array.isArray(step.knowledge)) fail(`etapa "${step.id}": knowledge deve ser um array de strings (ou ausente)`);
+    step.knowledge.forEach((k, i) => {
+      if (typeof k !== 'string' || k.trim() === '') fail(`etapa "${step.id}": knowledge[${i}] deve ser string não-vazia (nome de arquivo knowledge/*.md)`);
+    });
+  }
+}
+
+/**
+ * SF11.10/ADR-024 `DF-SF11.10-3` — valida o `checkpoint` por etapa: FORMA + o INVARIANTE do
+ * gate humano. Até esta story o validador não olhava NADA sob `checkpoint` (zero ocorrências
+ * da palavra no arquivo) — a proibição do ADR-020 ("o modo autônomo JAMAIS aprova") era 100%
+ * prosa. Aqui ela vira máquina pela primeira vez.
+ *
+ * FORMA (ausente/`null` = no-op, retrocompat byte-idêntica — precedente `anti_path`/`knowledge`):
+ *   - `blocking` booleano obrigatório quando o mapa existe;
+ *   - chave desconhecida sob `checkpoint` = FALHA (o campo é contrato, não saco de extras);
+ *   - `criteria` string não-vazia quando `blocking: true` (gate sem critério é gate mudo), e
+ *     NUNCA um sigilo de escalar de bloco (`DF-SF11.10-17`: o parser descartaria o texto);
+ *   - `skip_modes` (opcional) = array de modos do conjunto fechado, e só faz sentido com
+ *     `blocking: true`. AUSENTE ⇒ bloqueia em TODO modo; modo NÃO listado ⇒ bloqueia
+ *     (enumeração NEGATIVA de propósito: `blocking_in:` falharia ABERTO num modo com typo).
+ *
+ * INVARIANTE: se o `wf` declara ao menos um checkpoint bloqueante, então para CADA modo do
+ * conjunto fechado existe ≥1 bloqueante que NÃO o pula. Um `wf` cujo único gate é pulável em
+ * algum modo faria aquele modo rodar SEM NENHUM gate humano — o oposto do que a `skip_modes`
+ * existe para permitir (pular UM gate, nunca ficar sem gate).
+ *
+ * Escopo declarado, não escondido: um `wf` com ZERO checkpoint bloqueante NÃO é reprovado
+ * aqui. Ele já existia antes desta story (`wf-criacao-redteam`, `wf-materiais-revisao` usam
+ * `blocking: false`), e "todo pod precisa de gate humano" é uma decisão de produto que este
+ * ADR não tomou. O invariante desta story é mais estreito e verdadeiro: **`skip_modes` nunca
+ * pode ser o motivo de um modo perder o gate**.
+ */
+function checkCheckpoint(doc) {
+  const blockingPerMode = new Map(RUN_MODES.map((m) => [m, 0]));
+  let anyBlocking = false;
+
+  for (const step of doc.steps) {
+    const cp = step.checkpoint;
+    if (cp == null) continue; // OPCIONAL — só valida quando presente.
+    if (typeof cp !== 'object' || Array.isArray(cp)) {
+      fail(`etapa "${step.id}": checkpoint deve ser um mapa {blocking, criteria?, skip_modes?} (ou null/ausente)`);
+    }
+    for (const k of Object.keys(cp)) {
+      if (!CHECKPOINT_KEYS.includes(k)) {
+        fail(`etapa "${step.id}": checkpoint.${k} é chave desconhecida — chaves válidas: ${CHECKPOINT_KEYS.join(', ')} ` +
+          `(chave de um motor mais novo? rode "update --scope motor")`);
+      }
+    }
+    if (typeof cp.blocking !== 'boolean') {
+      fail(`etapa "${step.id}": checkpoint.blocking deve ser booleano (recebeu ${JSON.stringify(cp.blocking)})`);
+    }
+    if (cp.skip_modes != null) {
+      if (!Array.isArray(cp.skip_modes)) {
+        fail(`etapa "${step.id}": checkpoint.skip_modes deve ser um array de modos (ou ausente) — modos válidos: ${RUN_MODES.join(', ')}`);
+      }
+      cp.skip_modes.forEach((m, i) => {
+        if (typeof m !== 'string' || !RUN_MODES.includes(m)) {
+          fail(`etapa "${step.id}": checkpoint.skip_modes[${i}] = ${JSON.stringify(m)} não é um modo de run válido ` +
+            `(conjunto fechado: ${RUN_MODES.join(', ')})`);
+        }
+      });
+      if (cp.blocking !== true) {
+        fail(`etapa "${step.id}": checkpoint.skip_modes só faz sentido com blocking: true ` +
+          `(um checkpoint não-bloqueante não para em modo nenhum — nada a pular)`);
+      }
+    }
+    if (cp.blocking !== true) continue;
+    if (typeof cp.criteria !== 'string' || cp.criteria.trim() === '') {
+      fail(`etapa "${step.id}": checkpoint.criteria ausente ou vazio com blocking: true — ` +
+        `um gate humano sem critério escrito não é gate, é pausa (ADR-002: o critério é o que o humano julga)`);
+    }
+    // SF11.10/ADR-024 `DF-SF11.10-17` — o parser YAML-lite NÃO suporta escalar de bloco e falha
+    // em SILÊNCIO: `criteria: |` vira a string "|" e as linhas seguintes são DESCARTADAS. Sem
+    // esta recusa, a checagem de "não-vazia" acima aceita ("|" é não-vazia) e o gate nasce mudo
+    // pelo idioma YAML mais natural para texto longo. Recusa com causa nomeada > aceite mudo.
+    // (Causa-raiz — o parser ignorar o sigilo em QUALQUER campo — é do épico do motor.)
+    if (/^[|>][0-9+-]*$/.test(cp.criteria.trim())) {
+      fail(`etapa "${step.id}": checkpoint.criteria = ${JSON.stringify(cp.criteria.trim())} é sigilo de escalar ` +
+        `de bloco YAML (| |- |+ > >- >+), e o parser do POWER CLAUDE NÃO suporta essa forma: as linhas ` +
+        `indentadas abaixo dele são DESCARTADAS em silêncio e o gate nasceria mudo. Escreva o critério ` +
+        `em UMA linha física, entre aspas — ex.: criteria: "o humano confirma X; rejeita se Y" ` +
+        `(ADR-024 DF-SF11.10-17)`);
+    }
+    anyBlocking = true;
+    const skip = new Set(Array.isArray(cp.skip_modes) ? cp.skip_modes : []);
+    for (const m of RUN_MODES) {
+      if (!skip.has(m)) blockingPerMode.set(m, blockingPerMode.get(m) + 1);
+    }
+  }
+
+  if (!anyBlocking) return; // wf sem gate humano nenhum: pré-existente, fora deste invariante.
+  for (const m of RUN_MODES) {
+    if (blockingPerMode.get(m) === 0) {
+      fail(`invariante do gate humano violado (ADR-024 DF-SF11.10-3): o modo "${m}" ficaria SEM ` +
+        `nenhum checkpoint bloqueante — todo checkpoint com blocking: true deste workflow o lista ` +
+        `em skip_modes. Cada modo do conjunto fechado (${RUN_MODES.join(', ')}) precisa de ao menos ` +
+        `um gate NÃO-pulável; pular um gate é permitido, ficar sem gate não é (ADR-020: o modo ` +
+        `autônomo JAMAIS aprova — se não há gate, não há o que ele espere)`);
+    }
+  }
+}
+
+function checkDag(doc) {
+  // AC3: depends_on referencia ids válidos; grafo acíclico (fluxo unidirecional).
+  const ids = new Set(doc.steps.map((s) => s.id));
+  const edges = new Map(); // step -> [deps]
+  for (const step of doc.steps) {
+    const deps = Array.isArray(step.depends_on) ? step.depends_on : [];
+    for (const d of deps) {
+      if (!ids.has(d)) fail(`etapa "${step.id}": depends_on referencia etapa inexistente "${d}"`);
+    }
+    edges.set(step.id, deps);
+  }
+  // DFS com detecção de ciclo, reportando o ciclo.
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map(doc.steps.map((s) => [s.id, WHITE]));
+  const stack = [];
+  function visit(node) {
+    color.set(node, GRAY);
+    stack.push(node);
+    for (const dep of edges.get(node)) {
+      if (color.get(dep) === GRAY) {
+        const cycleStart = stack.indexOf(dep);
+        const cycle = stack.slice(cycleStart).concat(dep);
+        fail(`ciclo no DAG (depends_on não é acíclico): ${cycle.join(' -> ')}`);
+      }
+      if (color.get(dep) === WHITE) visit(dep);
+    }
+    stack.pop();
+    color.set(node, BLACK);
+  }
+  for (const step of doc.steps) {
+    if (color.get(step.id) === WHITE) visit(step.id);
+  }
+}
+
+function ancestorsOf(doc, id) {
+  // Conjunto de todas as etapas alcançáveis para trás por `depends_on` a partir de `id`.
+  const dep = new Map(doc.steps.map((s) => [s.id, Array.isArray(s.depends_on) ? s.depends_on : []]));
+  const seen = new Set();
+  const stack = [...(dep.get(id) || [])];
+  while (stack.length > 0) {
+    const n = stack.pop();
+    if (seen.has(n)) continue;
+    seen.add(n);
+    for (const d of (dep.get(n) || [])) stack.push(d);
+  }
+  return seen;
+}
+
+function checkFixCycle(doc) {
+  // Débito herdado da SF1.1 (gate sf1.1 finding #1; SPEC §B2a linha 72 / linha 85):
+  // o fix-loop explícito é a ÚNICA aresta para trás permitida. Ele NÃO é `depends_on`
+  // (isso seria ciclo, reprovado por checkDag) — é um campo dedicado `fix_cycle` que
+  // aponta para uma etapa a MONTANTE e é isento da checagem de aciclicidade. Uma
+  // aresta para trás disfarçada de `depends_on` continua sendo ciclo → FALHA.
+  const ids = new Set(doc.steps.map((s) => s.id));
+  for (const step of doc.steps) {
+    if (step.fix_cycle == null) continue;
+    const fc = step.fix_cycle;
+    if (typeof fc !== 'object' || Array.isArray(fc)) {
+      fail(`etapa "${step.id}": fix_cycle deve ser um mapa {to, max_iterations}`);
+    }
+    if (typeof fc.to !== 'string' || !ids.has(fc.to)) {
+      fail(`etapa "${step.id}": fix_cycle.to referencia etapa inexistente "${fc.to}"`);
+    }
+    if (fc.to === step.id) {
+      fail(`etapa "${step.id}": fix_cycle.to não pode apontar para a própria etapa`);
+    }
+    if ('max_iterations' in fc && fc.max_iterations != null &&
+        (!Number.isInteger(fc.max_iterations) || fc.max_iterations < 1)) {
+      fail(`etapa "${step.id}": fix_cycle.max_iterations deve ser inteiro >= 1`);
+    }
+    if (!ancestorsOf(doc, step.id).has(fc.to)) {
+      fail(`etapa "${step.id}": fix_cycle.to "${fc.to}" deve ser uma etapa A MONTANTE ` +
+        `(ancestral via depends_on) — o fix-loop volta para trás, nunca para frente; ` +
+        `aresta para trás disfarçada de depends_on é ciclo (proibida)`);
+    }
+  }
+}
+
+function topoOrder(doc) {
+  // Ordenação topológica determinística: a cada passo, escolhe a PRIMEIRA etapa (na
+  // ordem de declaração) cujas dependências já foram emitidas. Empates resolvidos pela
+  // ordem do arquivo → saída reprodutível. Assume DAG acíclico (checkDag rodou antes).
+  const ids = doc.steps.map((s) => s.id);
+  const dep = new Map(doc.steps.map((s) => [s.id, Array.isArray(s.depends_on) ? s.depends_on : []]));
+  const order = [];
+  const done = new Set();
+  while (order.length < ids.length) {
+    const next = ids.find((id) => !done.has(id) && dep.get(id).every((d) => done.has(d)));
+    if (!next) fail('topoOrder: ciclo residual (checkDag deveria ter reprovado antes)');
+    order.push(next);
+    done.add(next);
+  }
+  return order;
+}
+
+function checkTemplatesExist(doc, podRoot) {
+  // AC5: todo template: existe em disco (path resolvido a partir da raiz do pod).
+  for (const step of doc.steps) {
+    const resolved = path.resolve(podRoot, step.template);
+    if (!fs.existsSync(resolved)) {
+      fail(`etapa "${step.id}": template inexistente em disco — ${path.relative(REPO_ROOT, resolved)}`);
+    }
+  }
+}
+
+/**
+ * SF11.2/ADR-021 `DF-SF11.2-4` (item 2) — paridade estática de EXISTÊNCIA do `knowledge:`
+ * declarado por etapa. Antes, aqui só a FORMA do campo era checada (`checkKnowledge`),
+ * enquanto o compilador de export já falhava pela existência (`pod-export-compile.cjs:236`)
+ * sobre o MESMO `wf`: o driver de dev era mais frouxo que o export. Agora o runner também
+ * BLOQUEIA o despacho pela mesma causa (`pc-run-pod.cjs`, `requiredReading`); este check é a
+ * versão estática, para o defeito aparecer no `validate` e não só na hora de rodar.
+ *
+ * `knowledge:` segue OPCIONAL aqui (o export o EXIGE, D2) — etapa sem o campo é no-op.
+ * Retrocompat, `DF-SF11.2-10`.
+ *
+ * [AUTO-DECISION SF11.2] A existência do AGENTE (`agents/<step.agent>.md`) NÃO é checada
+ * aqui, embora o runner a exija antes de despachar e o export a exija para compilar
+ * (`pod-export-compile.cjs:214`). Motivo MEDIDO, não preferência: `forge-generate.cjs`
+ * escreve `workflows/wf-*.yaml`, `templates/` e `squad-io.yaml`, mas NÃO escreve
+ * `agents/*.md` — os agentes são autorados depois, pela skill do forge. Um `wf` recém-gerado
+ * é um estado intermediário LEGÍTIMO em que o agente ainda não existe, e o próprio contrato
+ * do forge exige que esse `wf` passe neste validador (`scripts/forge.test.cjs`, AC4).
+ * Exigir o agente aqui reprovaria todo pod no instante seguinte à geração. O gate de agente
+ * vive onde a premissa "o pod está pronto" é verdadeira: no DESPACHO (runner) e no EXPORT.
+ */
+function checkKnowledgeExists(doc, podRoot) {
+  for (const step of doc.steps) {
+    if (step.knowledge == null) continue; // campo OPCIONAL — retrocompat
+    for (const k of step.knowledge) {
+      const kRel = path.join('knowledge', String(k));
+      const abs = path.resolve(podRoot, kRel);
+      const root = path.resolve(podRoot);
+      // Confinamento: mesma régua do runner (`pc-run-pod.cjs`, `requiredReading`) — knowledge
+      // que escapa da raiz do pod é recusado ainda que o arquivo exista lá fora.
+      if (!(abs === root || abs.startsWith(root + path.sep))) {
+        fail(`etapa "${step.id}": knowledge declarado escapa da raiz do pod — ${kRel} ` +
+          `(leitura obrigatória da etapa: só arquivos sob a raiz do pod podem ser declarados)`);
+      }
+      if (!fs.existsSync(abs)) {
+        fail(`etapa "${step.id}": knowledge declarado inexistente em disco — ${kRel} ` +
+          `(leitura obrigatória da etapa: o runner recusa despachar e o export recusa compilar)`);
+      }
+    }
+  }
+}
+
+function checkVetoOrthogonality(doc, podRoot) {
+  // ADR-005 Decisão A (enforcement): um veto `section_exists` cuja seção coincide com
+  // um heading `##+` do template DA ETAPA é logicamente IMPLICADO pela conformidade de
+  // template (o runner roda checkTemplateConformance antes das asserções) — não existe
+  // artefato que viole só o veto sem violar a forma, tornando a Prova 3b do smoke
+  // inconstruível. Essa classe degenerada vira ERRO ESTÁTICO aqui. Régua dos headings
+  // idêntica à de checkTemplateConformance no runner: linha trimada casando /^#{2,6}\s+\S/.
+  const templateHeadings = (t) =>
+    new Set(t.split(/\r?\n/).map((l) => l.trim()).filter((l) => /^#{2,6}\s+\S/.test(l)));
+  for (const step of doc.steps) {
+    const assertions = (step.veto && Array.isArray(step.veto.assertions)) ? step.veto.assertions : [];
+    const hasSectionExists = assertions.some((a) => a && a.type === 'section_exists');
+    if (!hasSectionExists) continue;
+    const tmplPath = path.resolve(podRoot, step.template);
+    const wanted = templateHeadings(fs.readFileSync(tmplPath, 'utf8'));
+    for (const a of assertions) {
+      if (a && a.type === 'section_exists' && wanted.has(String(a.section).trim())) {
+        fail(`etapa "${step.id}": veto não-ortogonal — section_exists "${String(a.section).trim()}" ` +
+          `duplica a conformidade de template (ADR-005); use asserção de conteúdo ` +
+          `(field_matches/count_gte/file_referenced_exists/json_schema_valid)`);
+      }
+    }
+  }
+}
+
+function checkClosedHandoffs(doc) {
+  // AC6: todo output é consumido por um input a jusante OU é artefato final
+  // (produzido por um passo-sumidouro — etapa da qual nenhuma outra depende).
+  const consumed = new Set();
+  for (const step of doc.steps) {
+    const inputs = Array.isArray(step.inputs) ? step.inputs : [];
+    for (const inp of inputs) consumed.add(inp);
+  }
+  const hasDependent = new Set();
+  for (const step of doc.steps) {
+    for (const d of (Array.isArray(step.depends_on) ? step.depends_on : [])) hasDependent.add(d);
+  }
+  for (const step of doc.steps) {
+    const isSink = !hasDependent.has(step.id);
+    const outputs = Array.isArray(step.outputs) ? step.outputs : [];
+    for (const out of outputs) {
+      if (!consumed.has(out) && !isSink) {
+        fail(`handoff aberto: output "${out}" da etapa "${step.id}" não é consumido por nenhuma etapa a jusante nem é artefato final`);
+      }
+    }
+  }
+}
+
+function validateWorkflow(workflowPath, podRootOverride) {
+  let doc;
+  try {
+    doc = parseYaml(fs.readFileSync(workflowPath, 'utf8'));
+  } catch (e) {
+    fail(`YAML malformado: ${e.message}`);
+  }
+  checkSchema(doc);
+  checkStepCompleteness(doc);
+  checkVetoMachineEvaluable(doc);
+  checkAntiPath(doc); // SF7.3 — no-op quando nenhuma etapa declara anti_path (retrocompat)
+  checkKnowledge(doc); // SF10.1/D2 — no-op quando nenhuma etapa declara knowledge (retrocompat)
+  checkCheckpoint(doc); // SF11.10/DF-SF11.10-3 — forma do checkpoint + invariante do gate humano
+  checkDag(doc);
+  checkFixCycle(doc);
+  const podRoot = podRootFor(workflowPath, podRootOverride);
+  checkTemplatesExist(doc, podRoot);
+  checkKnowledgeExists(doc, podRoot); // SF11.2/DF-SF11.2-4: paridade de existência com o export.
+  checkVetoOrthogonality(doc, podRoot); // ADR-005: depois de garantir template em disco.
+  checkClosedHandoffs(doc);
+}
+
+function collectGlob(root) {
+  const out = [];
+  const stack = [path.resolve(root)];
+  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()) stack.push(p);
+      else if (entry.isFile() && path.basename(dir) === 'workflows' &&
+               /^wf-.*\.ya?ml$/.test(entry.name)) {
+        out.push(p);
+      }
+    }
+  }
+  return out.sort();
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  let podRootOverride = null;
+  const targets = [];
+  for (let a = 0; a < args.length; a++) {
+    if (args[a] === '--pod-root') {
+      podRootOverride = args[++a];
+    } else if (args[a] === '--glob') {
+      targets.push(...collectGlob(args[++a]));
+    } else {
+      targets.push(args[a]);
+    }
+  }
+
+  if (targets.length === 0) {
+    console.error('Uso: node scripts/validate-pod-workflow.cjs <wf.yaml> [...] [--pod-root <dir>] [--glob <dir>]');
+    process.exit(2);
+  }
+
+  let ok = 0;
+  for (const t of targets) {
+    const rel = path.relative(REPO_ROOT, path.resolve(t));
+    if (!fs.existsSync(t)) {
+      console.error(`[FALHA] ${rel}: arquivo não encontrado`);
+      process.exit(1);
+    }
+    try {
+      validateWorkflow(t, podRootOverride);
+      console.log(`[OK   ] ${rel}`);
+      ok++;
+    } catch (e) {
+      if (e instanceof Fail) {
+        console.error(`[FALHA] ${rel}: ${e.message}`);
+        process.exit(1);
+      }
+      throw e;
+    }
+  }
+  console.log(`\n${ok} workflow(s) validado(s). Contrato bem-formado.`);
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  parseYaml,
+  validateWorkflow,
+  podRootFor,
+  topoOrder,
+  ancestorsOf,
+  VETO_TYPES,
+  VETO_CHECKS_ROOT,
+  RUN_MODES,          // SF11.10/DF-SF11.10-5 — conjunto fechado de ritmos (fonte única).
+  CHECKPOINT_KEYS,    // SF11.10/DF-SF11.10-6 — chaves conhecidas sob `checkpoint`.
+  checkCommandCheckSafety,
+  checkJsonSchemaExtract,
+  checkAntiPath,
+  checkKnowledge,
+  checkCheckpoint,
+  checkKnowledgeExists,
+  Fail,
+};