@daniellins/power-claude 0.16.3

package/scripts/owner-layer.test.cjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * owner-layer.test.cjs — ORÁCULO DA FRONTEIRA DO PUBLICÁVEL (Story SF12.1).
+ * AC1 · AC2 · AC3 · AC4 · AC9 · AC12. Fonte de desenho: ADR-027 (Decisões 1, 3, 8).
+ *
+ * O QUE ESTE TESTE PROVA — e o que ele NÃO prova. Declarado aqui porque um AC (ou
+ * um teste) que promete mais que o instrumento é a classe de defeito que o SF11
+ * pagou nove vezes:
+ *
+ *  ✓ CONTENÇÃO (AC12): nenhum arquivo do TARBALL REAL dentro da camada declarada
+ *    em `owner-layer.cjs` é publicado sem ser um placeholder `*.example.*` com
+ *    sentinela — ou um não-`.example.` explicitamente permitido por path, com a
+ *    sua regra verificada. Pega dado NÃO ENUMERADO dentro da camada, inclusive
+ *    DNA de terceiro extraído pelo `mind-extractor`.
+ *    ✗ NÃO pega nada FORA da camada.
+ *
+ *  ✓ ENUMERAÇÃO (AC1/AC9): nenhum dos padrões JÁ CLASSIFICADOS em
+ *    `owner-layer.cjs` aparece em qualquer arquivo do tarball fora da allowlist
+ *    por path exato.
+ *    ✗ NÃO prova ausência de "qualquer dado pessoal": a régua do dono é
+ *      ENUMERÁVEL POR DESENHO. Dado pessoal não tem gramática sintática (um nome
+ *      próprio, um cargo ou uma tese editorial não têm forma reconhecível, ao
+ *      contrário de `sk-`/`AKIA`/`ghp_`). Uma varredura heurística ("parece nome
+ *      próprio?") foi REJEITADA por doutrina no ADR-027 Decisão 3, por ser
+ *      impossível declarar seu alcance honestamente.
+ *
+ *  ✗ LACUNA RESIDUAL, SEM INSTRUMENTO: dado pessoal NÃO ENUMERADO e FORA da
+ *    camada. `DEBT-SF12.1-B`. Nenhum AC da SF12.1 afirma cobri-la. Só leitura
+ *    humana a pega; centralizar (mover o dado para dentro da camada) é o que a
+ *    encolhe.
+ *
+ * MÉTODO: `npm pack` de VERDADE (nunca `--dry-run` — precisamos do CONTEÚDO de
+ * cada arquivo, não da lista de nomes), extração para diretório temporário,
+ * varredura do conteúdo extraído. É o tarball que vai para o registry, não uma
+ * simulação da árvore de trabalho.
+ *
+ * KILL-TESTS (AC2 e AC12): um oráculo verde só no caminho feliz não prova nada.
+ * As injeções abaixo passam pelas MESMAS funções (`scanEnumeration`/
+ * `scanContainment`) e sobre os MESMOS arquivos reais do tarball, acrescidos de
+ * uma entrada violadora — não sobre um conjunto sintético que poderia divergir do
+ * caminho real.
+ *
+ * Node >= 18, zero dependências. Exit 0/1.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const OL = require('./owner-layer.cjs');
+const { parseYaml } = require('./validate-pod-workflow.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+// ---------------------------------------------------------------------------
+// Este arquivo de teste é PUBLICADO (`scripts/` está em package.json.files) e NÃO
+// está na allowlist do AC2 — por desenho: acrescentá-lo alargaria a fronteira que
+// a story existe para estreitar. Consequência: o teste NUNCA escreve os literais
+// perigosos. Ele os obtém por PAPEL (`patternByRole`) e verifica o manifesto
+// contra uma fonte independente e já isenta — o campo `author` de `package.json`.
+// Efeito colateral desejado: se o manifesto divergir do dono real do pacote, o
+// teste falha alto em vez de proteger a pessoa errada em silêncio.
+// ---------------------------------------------------------------------------
+const PKG = require('../package.json');
+const NOME_CIVIL = PKG.author;
+const SLUG = String(PKG.author).toLowerCase().replace(/\s+/g, '-');
+
+let passed = 0;
+const failures = [];
+function ok(cond, label) {
+  if (cond) { passed++; console.log(`[OK   ] ${label}`); }
+  else { failures.push(label); console.log(`[FALHA] ${label}`); }
+}
+
+function fmtEnum(v) {
+  return v.map((x) => `    ${x.path}:${x.line} → "${x.pattern}"  | ${x.excerpt}`).join('\n');
+}
+function fmtCont(v) {
+  return v.map((x) => `    ${x.path}  [camada ${x.layer}] → ${x.reason}`).join('\n');
+}
+
+// ===========================================================================
+// Setup — `npm pack` real + extração.
+// ===========================================================================
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-owner-layer-'));
+let tarball;
+try {
+  const out = execFileSync('npm', ['pack', '--pack-destination', tmp, '--silent'], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'inherit'],
+  });
+  tarball = path.join(tmp, out.trim().split(/\r?\n/).filter(Boolean).pop());
+} catch (e) {
+  console.error('[FATAL] `npm pack` falhou — sem tarball não há oráculo.', e.message);
+  process.exit(1);
+}
+const extractDir = path.join(tmp, 'x');
+fs.mkdirSync(extractDir);
+execFileSync('tar', ['-xzf', tarball, '-C', extractDir], { stdio: 'inherit' });
+
+/** Lê todo arquivo extraído como { path (lógico, sem `package/`), content }. */
+function collect(dir, base = '') {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    const rel = base ? `${base}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...collect(abs, rel));
+    else if (entry.isFile()) {
+      const buf = fs.readFileSync(abs);
+      // Guarda de binário: um arquivo com NUL não é varrível por string.
+      const binary = buf.subarray(0, 8000).includes(0);
+      out.push({ path: OL.stripPackagePrefix(rel), content: binary ? '' : buf.toString('utf8'), binary });
+    }
+  }
+  return out;
+}
+const files = collect(extractDir);
+console.log(`\n[info ] tarball: ${path.basename(tarball)} — ${files.length} arquivos publicados`);
+console.log(`[info ] binários (não varridos por string): ${files.filter((f) => f.binary).length}`);
+
+ok(files.length > 100, `tarball extraído tem conteúdo real (${files.length} arquivos)`);
+
+// ===========================================================================
+// AC1 + AC9 — ENUMERAÇÃO sobre o tarball real: zero fora da allowlist.
+// ===========================================================================
+const enumViolations = OL.scanEnumeration(files);
+if (enumViolations.length > 0) {
+  console.log('  Ocorrências de dado pessoal ENUMERADO fora da allowlist:');
+  console.log(fmtEnum(enumViolations));
+}
+ok(enumViolations.length === 0,
+  `AC1/AC9 — enumeração: zero ocorrências dos ${OL.patterns.length} padrões fora da allowlist de ${OL.enumerationAllowlist.length} paths`);
+
+// Cada padrão declarado tem os 3 campos exigidos pelo AC1.
+ok(OL.patterns.every((p) => p.pattern && p.description && p.origin),
+  'AC1 — todo padrão declara pattern/description/origin (proveniência do achado)');
+// Os 3 padrões mínimos do AC1, verificados SEM escrever os literais:
+//   • nome civil  → tem de bater com `package.json.author` (fonte independente);
+//   • slug        → tem de ser a slugificação desse mesmo nome;
+//   • path de máquina → tem de ser um path `/Users/<usuário>` não-degenerado.
+ok(OL.patternByRole('nome-civil') === NOME_CIVIL,
+  'AC1 — padrão de NOME CIVIL declarado e igual ao `author` de package.json (fonte independente)');
+ok(OL.patternByRole('slug') === SLUG,
+  'AC1 — padrão de SLUG hifenizado declarado e derivado do mesmo nome (cobre nome de arquivo)');
+const pathPat = OL.patternByRole('path-maquina');
+ok(pathPat.startsWith('/Users/') && pathPat.length > '/Users/'.length + 3,
+  'AC1 — padrão de PATH DE MÁQUINA pessoal declarado (`/Users/<usuário>`, não-degenerado)');
+
+// ===========================================================================
+// AC2 — KILL-TEST da enumeração: a allowlist é restrita, não escotilha.
+// ===========================================================================
+const killEnumFiles = files.concat([
+  { path: 'scripts/__killtest__.md', content: `Escrito por ${NOME_CIVIL} em 2026.\n` },
+]);
+// Como nos kill-tests de contenção: a asserção é sobre a INJEÇÃO, não sobre a
+// contagem global — a limpeza da linha de base é a asserção AC1/AC9 acima.
+const killEnum = OL.scanEnumeration(killEnumFiles);
+ok(killEnum.some((v) => v.path === 'scripts/__killtest__.md'),
+  'AC2 kill-test — arquivo NOVO fora da allowlist contendo o nome civil do dono é PEGO (oráculo não é decorativo)');
+
+// A allowlist casa por path EXATO: um vizinho de nome parecido não herda a isenção.
+const killNear = OL.scanEnumeration(files.concat([
+  { path: 'scripts/owner-layer.cjs.bak', content: `pattern: "${NOME_CIVIL}"\n` },
+  { path: 'template/README.md', content: `Copyright ${NOME_CIVIL}\n` },
+]));
+ok(['scripts/owner-layer.cjs.bak', 'template/README.md'].every((p) => killNear.some((v) => v.path === p)),
+  'AC2 kill-test — allowlist é por PATH EXATO: `scripts/owner-layer.cjs.bak` e `template/README.md` NÃO herdam isenção');
+
+// E o oráculo se protege de si mesmo: o arquivo de declaração É publicado e ESTÁ isento.
+const declInTarball = files.find((f) => f.path === 'scripts/owner-layer.cjs');
+ok(!!declInTarball, 'AC2 — o manifesto `scripts/owner-layer.cjs` é publicado (está em package.json.files)');
+ok(!!declInTarball && OL.patterns.every((p) => declInTarball.content.includes(p.pattern)),
+  'AC2 — o manifesto contém, de fato, todos os literais perigosos (é a lista deles) — a isenção não é teórica');
+
+// ===========================================================================
+// AC12 — CONTENÇÃO sobre o tarball real.
+// ===========================================================================
+const inLayer = files.filter((f) => OL.layerOf(f.path));
+console.log(`[info ] arquivos do tarball dentro da camada do dono: ${inLayer.length}`);
+for (const f of inLayer) console.log(`         · ${f.path}  [${OL.layerOf(f.path).id}]`);
+
+const contViolations = OL.scanContainment(files);
+if (contViolations.length > 0) {
+  console.log('  Violações de contenção:');
+  console.log(fmtCont(contViolations));
+}
+ok(contViolations.length === 0,
+  `AC12 — contenção: os ${inLayer.length} arquivos da camada são placeholder com sentinela ou não-example permitido com regra verificada`);
+ok(inLayer.length > 0, 'AC12 — a camada declarada de fato alcança arquivos do tarball (manifesto não é letra morta)');
+// GUARDA DE REGRESSÃO DO MANIFESTO (AC17c). Igualdade de CONJUNTO, não `>=`: uma
+// camada removida do manifesto reabriria o canal correspondente **com a suíte verde**,
+// e os kill-tests abaixo não pegariam isso — eles provam o estado atual, não que a
+// declaração continua existindo. O acoplamento é de propósito nos DOIS sentidos:
+// remover uma camada falha aqui, e ACRESCENTAR uma também — camada nova sem kill-test
+// próprio é exatamente o defeito que esta asserção existe para impedir.
+const CAMADAS_EXIGIDAS = ['voice-dna', 'dono-do-pod', 'exemplos-do-pod', 'memoria-do-pod'];
+const idsDeclarados = OL.layers.map((l) => l.id).sort();
+const idsExigidos = CAMADAS_EXIGIDAS.slice().sort();
+ok(idsDeclarados.length === idsExigidos.length && idsDeclarados.every((id, i) => id === idsExigidos[i]),
+  `AC12/AC17c — o manifesto declara EXATAMENTE as ${CAMADAS_EXIGIDAS.length} camadas com kill-test próprio\n` +
+  `         exigidas: ${idsExigidos.join(', ')}\n         declaradas: ${idsDeclarados.join(', ')}`);
+// E cada camada exigida precisa ter kill-test — conferido por construção logo abaixo.
+
+// KILL-TESTS da contenção — cada um sobre os arquivos REAIS + uma injeção.
+const OLD_DNA_PATH = `template/knowledge/voice-dna/${SLUG}-voice-dna.yaml`;
+const killCont = [
+  {
+    label: 'AC12 kill-test (a) — DNA real do dono de volta na camada (sem `.example.`) é PEGO',
+    inject: { path: OLD_DNA_PATH, content: 'meta:\n  owner: "alguem"\n' },
+  },
+  {
+    label: 'AC12 kill-test (b) — DNA de TERCEIRO extraído pelo mind-extractor é PEGO sem enumerar nada',
+    inject: { path: 'template/knowledge/voice-dna/fulano-de-tal-dna.yaml', content: 'meta:\n  owner: "Fulano de Tal"\n' },
+  },
+  {
+    label: 'AC12 kill-test (c) — `.example.` SEM sentinela é PEGO (a sentinela é exigida, não sugerida)',
+    inject: { path: 'template/knowledge/voice-dna/outro.example.yaml', content: 'meta:\n  owner: "x"\n' },
+  },
+  {
+    label: 'AC12 kill-test (d) — `learnings.jsonl` NÃO vazio (memória de instância no pacote) é PEGO',
+    inject: { path: 'template/pods/dev-ia/memory/learnings.jsonl', content: '{"trigger":"x","recommendation":"y"}\n' },
+  },
+  {
+    label: 'AC12 kill-test (e) — consolidado COM heurística (conhecimento de instância) é PEGO',
+    inject: {
+      path: 'template/pods/dev-ia/memory/learnings.consolidated.md',
+      content: '# Memória consolidada — dev-ia\n\n## Heurísticas (top-N)\n- **[ao migrar]** faça assim _(x3)_\n',
+    },
+  },
+  {
+    label: 'AC12 kill-test (f) — `learnings.hardened.md` real chegando ao template é PEGO',
+    inject: { path: 'template/pods/dev-ia/memory/learnings.hardened.md', content: '# Endurecidas\n' },
+  },
+  {
+    // AC17c — achado da PRÓPRIA guarda de regressão nesta rodada: a camada `dono-do-pod`
+    // também estava sem kill-test. O vazamento realista é o `dono.yaml` de INSTÂNCIA
+    // (já preenchido) sendo publicado no lugar do `.example.`.
+    label: 'AC12/AC17c kill-test (h) — `dono.yaml` de INSTÂNCIA (preenchido) no template é PEGO',
+    inject: {
+      path: 'template/pods/content-carousel/knowledge/dono.yaml',
+      content: 'dono:\n  nome: "Nome Real"\n  handle: "@handle.real"\n',
+    },
+  },
+  {
+    // AC17c — o canal `exemplos-do-pod`. Um `examples/` AUTORADO é por onde opinião e
+    // posicionamento do dono chegavam à instalação de terceiros: o agente lê o exemplo
+    // como referência de padrão e imita o ASSUNTO junto com a FORMA.
+    label: 'AC12/AC17c kill-test (g) — exemplo AUTORADO (peça pronta, não esqueleto) em `examples/` é PEGO',
+    inject: {
+      path: 'template/pods/academy/examples/palestra-tema-do-dono.md',
+      camada: 'exemplos-do-pod',
+      content: '# Palestra: "<tese do dono sobre o assunto dele>"\n\nTese: <posicionamento autoral>.\n',
+    },
+  },
+];
+// Cada kill-test afirma que a INJEÇÃO é pega — não que ela é a única violação do
+// conjunto. A limpeza da linha de base já é uma asserção independente (acima);
+// acoplar as duas produziria 6 falhas em cascata para um único defeito plantado,
+// que é ruído de diagnóstico, não sinal.
+const camadasComKillTest = new Set();
+for (const t of killCont) {
+  const base = files.filter((f) => f.path !== t.inject.path);
+  const v = OL.scanContainment(base.concat([t.inject]));
+  const hit = v.filter((x) => x.path === t.inject.path);
+  ok(hit.length === 1, `${t.label}${hit.length ? ` → ${hit[0].reason.slice(0, 70)}…` : ''}`);
+  if (hit.length === 1) camadasComKillTest.add(hit[0].layer);
+}
+
+// AC17c — nenhuma camada declarada pode ficar sem kill-test. Sem esta asserção, uma
+// camada nova entra no manifesto sem prova de que reprova o que promete reprovar, e a
+// suíte segue verde: foi exatamente o buraco que `exemplos-do-pod` abriu ao nascer.
+const semKillTest = CAMADAS_EXIGIDAS.filter((id) => !camadasComKillTest.has(id));
+ok(semKillTest.length === 0,
+  `AC17c — toda camada declarada é exercida por kill-test próprio${semKillTest.length ? ` — SEM prova: ${semKillTest.join(', ')}` : ` (${[...camadasComKillTest].sort().join(', ')})`}`);
+
+// AC17c(iii) — A ASSIMETRIA VIRA ASSERÇÃO, não comentário. A MESMA injeção que a
+// contenção pega precisa dar ZERO na enumeração. É isto que sustenta, por execução, a
+// frase que o AC17 declara: o mecanismo **fecha o canal**, ele **não detecta opinião**
+// (opinião não tem gramática sintática). Se algum dia a enumeração passar a pegar esta
+// injeção, a frase do AC virou mentira e esta asserção falha antes de alguém publicá-la.
+const injecaoOpiniao = killCont.find((t) => t.inject.camada === 'exemplos-do-pod').inject;
+const contOpiniao = OL.scanContainment(files.concat([injecaoOpiniao])).filter((x) => x.path === injecaoOpiniao.path);
+const enumOpiniao = OL.scanEnumeration([injecaoOpiniao]);
+ok(contOpiniao.length === 1 && enumOpiniao.length === 0,
+  `AC17c(iii) — alcance DISJUNTO na mesma injeção: contenção ${contOpiniao.length} (pega) × enumeração ${enumOpiniao.length} (não pega) — fecha o canal, não detecta opinião`);
+
+// Contraprova de simetria: injeção CONFORME não gera violação PRÓPRIA (o oráculo
+// discrimina em vez de reprovar por atacado).
+const CONFORME_PATH = 'template/knowledge/voice-dna/outro.example.yaml';
+const conforme = OL.scanContainment(files.concat([
+  { path: CONFORME_PATH, content: '# pc:placeholder\nmeta:\n  owner: "<preencha>"\n' },
+]));
+ok(conforme.filter((x) => x.path === CONFORME_PATH).length === 0,
+  'AC12 contraprova — `.example.` COM sentinela passa: o oráculo discrimina, não reprova por atacado');
+
+// ===========================================================================
+// AC3 — o dado real do dono não existe mais no pacote publicado.
+// ===========================================================================
+ok(!files.some((f) => f.path === OLD_DNA_PATH),
+  `AC3 — o DNA autoral (\`${OLD_DNA_PATH}\`) NÃO está no tarball`);
+ok(!fs.existsSync(path.join(REPO_ROOT, OLD_DNA_PATH)),
+  'AC3 — o arquivo também não existe mais no repositório (test -f falso)');
+
+// ===========================================================================
+// AC4 — `voice-dna.example.yaml`: paridade de FORMA + sentinela.
+// ===========================================================================
+const EXPECTED_TOP_KEYS = [
+  'meta', 'identity', 'tone', 'structures', 'hooks',
+  'vocabulary', 'argumentation', 'signatures', 'anti_patterns', 'gaps_e_limitacoes',
+];
+const example = files.find((f) => f.path === 'template/knowledge/voice-dna/voice-dna.example.yaml');
+ok(!!example, 'AC4 — `voice-dna.example.yaml` está no tarball');
+if (example) {
+  let parsed = null;
+  let parseErr = null;
+  try { parsed = parseYaml(example.content); } catch (e) { parseErr = e; }
+  ok(parsed && typeof parsed === 'object', `AC4 — parse YAML válido${parseErr ? ` (erro: ${parseErr.message})` : ''}`);
+  if (parsed) {
+    const got = Object.keys(parsed).sort();
+    const want = EXPECTED_TOP_KEYS.slice().sort();
+    ok(got.length === want.length && got.every((k, i) => k === want[i]),
+      `AC4 — paridade de chaves de topo (igualdade de conjunto, 10 chaves)\n         esperado: ${want.join(', ')}\n         obtido:   ${got.join(', ')}`);
+    ok(parsed.meta && parsed.meta.placeholder === true,
+      'AC4 — sentinela `meta.placeholder: true` presente (consumida pelo oráculo E pelo agente)');
+  }
+  // Alcance declarado: isto prova FORMA. Que os placeholders façam sentido
+  // semântico como exemplo é revisão humana — sem oráculo de máquina (ADR-002).
+}
+
+// ===========================================================================
+// AC6 — nenhum ponteiro para o nome de arquivo antigo sobrou no pacote.
+// ===========================================================================
+const OLD_DNA_BASENAME = `${SLUG}-voice-dna`;
+const oldRefs = files.filter((f) => f.content.includes(OLD_DNA_BASENAME));
+ok(oldRefs.length === 0,
+  `AC6 — zero referências ao nome de arquivo antigo no tarball${oldRefs.length ? ` (${oldRefs.map((f) => f.path).join(', ')})` : ''}`);
+
+// A instância declarada pelo manifesto é a que as referências cruzadas usam.
+const voiceLayer = OL.layers.find((l) => l.id === 'voice-dna');
+ok(voiceLayer.instancePath === 'knowledge/voice-dna/voice-dna.yaml',
+  'AC6 — o manifesto declara o path de INSTÂNCIA (ADR-027 Decisão 8), fonte única das referências cruzadas');
+
+// ===========================================================================
+// AC8 — a identidade fictícia canônica é única e está declarada no manifesto.
+// ===========================================================================
+ok(OL.FICTIONAL_IDENTITY.nome === 'Alexa Exemplo' && OL.FICTIONAL_IDENTITY.handle === '@alexa.exemplo',
+  'AC8 — identidade fictícia canônica declarada no manifesto (uma só no repo, DF-SF12.1-6)');
+
+// ===========================================================================
+console.log(`\n${failures.length === 0 ? 'PASS' : 'FAIL'} — ${passed} asserções OK, ${failures.length} falha(s)`);
+if (failures.length > 0) {
+  for (const f of failures) console.error(`  ✗ ${f}`);
+}
+try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* tmp */ }
+process.exit(failures.length === 0 ? 0 : 1);

package/scripts/pc-run-pipeline.cjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * pc-run-pipeline.cjs — MOTOR SUPERVISOR do maestro cross-pod (Story SF9.1/ADR-017).
+ *
+ * DUAS máquinas de estado. A do run-filho (`pc-run-pod`) é dirigida pelo OPERADOR (executa
+ * os steps, agente a agente). Esta — a do PIPELINE — é 100% determinística e SUPERVISORA:
+ * dá `start` no run-filho da fase, DETECTA `done` LENDO o state.json do filho, impõe o
+ * BASELINE (run done + artefato de output existente EM DISCO), aplica o PORTÃO binário
+ * GO/NO-GO (veto de máquina reusando evalVeto; checkpoint humano = PARADA explícita), e só
+ * então libera a fase seguinte — passando o output da fase N por REFERÊNCIA (path resolvido,
+ * verificado em disco, via --task-ref; sem cópia). NUNCA executa LLM/etapa. NUNCA pula fase.
+ * NUNCA avança sem evidência em disco. "O eletricista não começa antes da parede aprovada."
+ *
+ * Comandos: init <pipeline.yaml> | status <id> | advance <id> | approve <id> [--note ..] | reject <id>
+ * Flags: --pods-root <dir> (onde vivem os pods; default pods/), --state-root <dir> (default .power-claude).
+ * Exit 0 = ação concluída; exit 1 = fail-loud (fase sem run, run não-done, artefato ausente,
+ * portão NO-GO, contrato inválido). Node >= 18, zero-dep.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { parseYaml } = require('./validate-pod-workflow.cjs');
+const { evalVeto, startRun, readState, runDirFor, statePathFor } = require('./pc-run-pod.cjs');
+const { validatePipeline } = require('./validate-pipeline.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+class PipelineError extends Error {}
+function fail(msg) { throw new PipelineError(msg); }
+function nowISO() { return new Date().toISOString(); }
+
+function podsRootFor(o) { return o ? path.resolve(o) : path.join(process.cwd(), 'pods'); }
+function stateRootFor(o) { return o ? path.resolve(o) : path.join(process.cwd(), '.power-claude'); }
+function pipelineDir(stateRoot, id) { return path.join(stateRoot, 'pipeline', id); }
+function pipelineStatePath(stateRoot, id) { return path.join(pipelineDir(stateRoot, id), 'state.json'); }
+
+function saveState(sp, state) {
+  state.updated_at = nowISO();
+  fs.mkdirSync(path.dirname(sp), { recursive: true });
+  const tmp = `${sp}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, sp);
+}
+function loadPipelineState(stateRoot, id) {
+  const sp = pipelineStatePath(stateRoot, id);
+  if (!fs.existsSync(sp)) fail(`pipeline "${id}" não inicializado (${path.relative(REPO_ROOT, sp)} não existe) — rode 'init'`);
+  try { return JSON.parse(fs.readFileSync(sp, 'utf8')); }
+  catch (e) { fail(`state.json do pipeline "${id}" corrompido: ${e.message}`); }
+}
+
+// ---------------------------------------------------------------------------
+// init — valida o contrato e cria o state (todas as fases pending).
+// ---------------------------------------------------------------------------
+function init(pipelinePath, { podsRoot, stateRoot } = {}) {
+  const pr = podsRootFor(podsRoot);
+  validatePipeline(pipelinePath, pr); // fail-loud se o contrato for inválido (Fail → propaga)
+  const doc = parseYaml(fs.readFileSync(pipelinePath, 'utf8'));
+  const sr = stateRootFor(stateRoot);
+  const sp = pipelineStatePath(sr, doc.id);
+  if (fs.existsSync(sp)) fail(`pipeline "${doc.id}" já iniciado (${path.relative(REPO_ROOT, sp)}) — use 'status'/'advance' (retomada) ou remova o state para recomeçar`);
+  const phases = {};
+  const order = [];
+  for (const ph of doc.phases) {
+    order.push(ph.id);
+    phases[ph.id] = {
+      status: 'pending', pod: ph.pod, workflow: ph.workflow,
+      outputs: ph.outputs, inputs: ph.inputs || null, gate: ph.gate || null,
+      run_id: null, run_dir: null, outputs_resolved: null, note: null,
+      started_at: null, completed_at: null,
+    };
+  }
+  const state = {
+    pipeline: doc.id, deliverable: doc.deliverable,
+    contract_path: path.resolve(pipelinePath), pods_root: pr,
+    runs_root: path.join(pipelineDir(sr, doc.id), 'runs'),
+    order, phases, updated_at: nowISO(),
+  };
+  saveState(sp, state);
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers do supervisor.
+// ---------------------------------------------------------------------------
+function currentPhaseId(state) {
+  return state.order.find((id) => state.phases[id].status !== 'completed') || null;
+}
+function childStatePathOf(state, ph) {
+  return statePathFor(state.runs_root, ph.pod, ph.workflow, ph.run_id);
+}
+function childDone(childState) {
+  const steps = childState && childState.steps ? Object.values(childState.steps) : [];
+  return steps.length > 0 && steps.every((s) => s.status === 'done');
+}
+function resolveOutputs(state, ph) {
+  const runDir = ph.run_dir;
+  const out = {};
+  for (const [name, rel] of Object.entries(ph.outputs)) out[name] = path.resolve(runDir, rel);
+  return out;
+}
+/** Resolve os inputs da fase a partir dos outputs JÁ RESOLVIDOS de fases anteriores, verificando EM DISCO. */
+function resolveInputs(state, ph) {
+  const resolved = {};
+  if (!ph.inputs) return resolved;
+  for (const [local, refRaw] of Object.entries(ph.inputs)) {
+    const ref = String(refRaw).replace(/^\s*<-\s*/, '').trim();
+    const dot = ref.indexOf('.');
+    const srcPhase = ref.slice(0, dot);
+    const srcOut = ref.slice(dot + 1);
+    const src = state.phases[srcPhase];
+    if (!src || src.status !== 'completed' || !src.outputs_resolved || !(srcOut in src.outputs_resolved)) {
+      fail(`input "${local}": fase-fonte "${srcPhase}" não concluída ou output "${srcOut}" não resolvido`);
+    }
+    const abs = src.outputs_resolved[srcOut];
+    if (!fs.existsSync(abs)) fail(`input "${local}": artefato de referência ausente EM DISCO — ${abs} (nunca por relato)`);
+    resolved[local] = abs;
+  }
+  return resolved;
+}
+
+/** Avalia o portão de máquina da fase sobre o PRIMEIRO output declarado. GO/NO-GO. */
+function evalGateVeto(state, ph) {
+  const g = ph.gate;
+  if (!g || !Array.isArray(g.veto) || g.veto.length === 0) return { go: true };
+  const [firstName] = Object.keys(ph.outputs);
+  const artPath = ph.outputs_resolved[firstName];
+  const text = fs.readFileSync(artPath, 'utf8');
+  const roots = { podRoot: path.join(state.pods_root, ph.pod), runDir: ph.run_dir };
+  for (const a of g.veto) {
+    const r = evalVeto(a, text, artPath, roots);
+    if (!r.ok) return { go: false, reason: `${a.type}: ${r.reason}` };
+  }
+  return { go: true };
+}
+
+// ---------------------------------------------------------------------------
+// advance — UMA transição do supervisor. Nunca executa a fase; só supervisiona.
+// ---------------------------------------------------------------------------
+function advance(id, { stateRoot } = {}) {
+  const sr = stateRootFor(stateRoot);
+  const sp = pipelineStatePath(sr, id);
+  const state = loadPipelineState(sr, id);
+  const cur = currentPhaseId(state);
+  if (cur === null) return { status: 'complete', message: `pipeline "${id}" COMPLETO — todas as fases concluídas.` };
+  const ph = state.phases[cur];
+
+  if (ph.status === 'failed') fail(`fase "${cur}" FALHOU — pipeline travado (fail-loud; sem pular fase). Corrija e reinicie a fase.`);
+  if (ph.status === 'blocked') fail(`fase "${cur}" aguarda decisão HUMANA do checkpoint — rode 'approve ${id}' (GO) ou 'reject ${id}' (NO-GO).`);
+
+  if (ph.status === 'pending') {
+    // START do run-filho (o SUPERVISOR só cria o run; o OPERADOR executa os steps depois).
+    const inputs = resolveInputs(state, ph); // verifica os inputs EM DISCO (fail-loud)
+    const taskRef = Object.keys(inputs).length
+      ? `Inputs cross-pod (por REFERÊNCIA, verificados em disco): ${Object.entries(inputs).map(([k, v]) => `${k}=${v}`).join('; ')}`
+      : null;
+    const podRoot = path.join(state.pods_root, ph.pod);
+    const workflowPath = path.join(podRoot, 'workflows', `${ph.workflow}.yaml`);
+    // Roteamento de memória do run gravado no state do filho (SF9.2 CONCERNS-1): o start
+    // isola em tmp E o `next` do operador honra o mesmo dir (lido do state) — sem vazar
+    // learnings do pipeline para o memory REAL do pod.
+    const { result } = startRun({
+      workflowPath, podRootOverride: podRoot, pod: ph.pod, workflow: ph.workflow,
+      taskRef, runsRoot: state.runs_root, runId: cur, memoryPodDir: fs.mkdtempSync(path.join(os.tmpdir(), 'pc-pipe-mem-')),
+    });
+    ph.run_id = cur;
+    ph.run_dir = runDirFor(state.runs_root, ph.pod, ph.workflow, cur);
+    ph.status = 'running';
+    ph.started_at = nowISO();
+    ph.task_ref = taskRef;
+    saveState(sp, state);
+    // Aspereza #1: expõe o BRIEF da 1ª etapa (o operador precisa dele para executar a fase).
+    const firstBrief = result && result.brief ? result.brief : null;
+    return { status: 'started', phase: cur, run_dir: ph.run_dir, task_ref: taskRef, brief: firstBrief,
+      message: `fase "${cur}" iniciada (run-filho em ${ph.run_dir}).\n` + // aspereza #3: path absoluto, sem ../../.. cosmético
+        (firstBrief ? `--- BRIEF DA 1ª ETAPA (execute-a via pc-run-pod; o pipeline NÃO executa) ---\n${firstBrief}\n--- fim do brief ---\n` : '') +
+        `O OPERADOR completa o run via 'pc-run-pod next/approve'; depois rode 'advance ${id}' de novo.` };
+  }
+
+  if (ph.status === 'running') {
+    // DETECTA done LENDO o state do filho — nunca executa os steps.
+    const csp = childStatePathOf(state, ph);
+    if (!fs.existsSync(csp)) fail(`fase "${cur}": state.json do run-filho ausente (${path.relative(REPO_ROOT, csp)})`);
+    const child = readState(csp);
+    if (!childDone(child)) {
+      const pend = Object.entries(child.steps).filter(([, s]) => s.status !== 'done').map(([k, s]) => `${k}:${s.status}`);
+      fail(`fase "${cur}": run-filho NÃO está done (steps: ${pend.join(', ')}). O pipeline é SUPERVISOR — quem executa a fase é o operador via pc-run-pod. Complete o run e rode advance de novo.`);
+    }
+    // BASELINE: outputs declarados existem EM DISCO (nunca por relato do state.json).
+    ph.outputs_resolved = resolveOutputs(state, ph);
+    for (const [name, abs] of Object.entries(ph.outputs_resolved)) {
+      if (!fs.existsSync(abs)) { ph.status = 'failed'; saveState(sp, state); fail(`fase "${cur}": output "${name}" declarado mas AUSENTE em disco (${abs}) — baseline reprovado.`); }
+    }
+    // PORTÃO de máquina (binário GO/NO-GO).
+    const gv = evalGateVeto(state, ph);
+    if (!gv.go) { ph.status = 'failed'; saveState(sp, state); fail(`fase "${cur}": PORTÃO NO-GO (veto de máquina) — ${gv.reason}. Fase seguinte NÃO dispara.`); }
+    // PORTÃO humano = PARADA explícita (nunca auto-avanço).
+    if (ph.gate && ph.gate.checkpoint) {
+      ph.status = 'blocked';
+      saveState(sp, state);
+      return { status: 'blocked', phase: cur, message: `fase "${cur}": run done + baseline + veto GO, MAS há checkpoint HUMANO (${ph.gate.checkpoint.criteria}). Decisão explícita: 'approve ${id}' (GO) ou 'reject ${id}' (NO-GO). Sem auto-avanço.` };
+    }
+    // GO automático (só baseline/veto).
+    ph.status = 'completed';
+    ph.completed_at = nowISO();
+    saveState(sp, state);
+    return { status: 'phase-complete', phase: cur, message: `fase "${cur}" CONCLUÍDA (GO). Rode 'advance ${id}' para iniciar a próxima.` };
+  }
+
+  fail(`fase "${cur}": status desconhecido "${ph.status}"`);
+  return undefined;
+}
+
+function approve(id, { stateRoot, note } = {}) {
+  const sr = stateRootFor(stateRoot);
+  const sp = pipelineStatePath(sr, id);
+  const state = loadPipelineState(sr, id);
+  const cur = currentPhaseId(state);
+  const ph = cur && state.phases[cur];
+  if (!ph || ph.status !== 'blocked') fail(`nenhuma fase aguardando decisão humana em "${id}" (use advance).`);
+  ph.status = 'completed';
+  ph.completed_at = nowISO();
+  ph.note = note || null; // ressalvas como TEXTO LIVRE num GO (nunca 3º estado de fluxo)
+  saveState(sp, state);
+  return { status: 'phase-complete', phase: cur, message: `fase "${cur}" GO humano${note ? ` (ressalva: ${note})` : ''}. Rode 'advance ${id}'.` };
+}
+
+function reject(id, { stateRoot } = {}) {
+  const sr = stateRootFor(stateRoot);
+  const sp = pipelineStatePath(sr, id);
+  const state = loadPipelineState(sr, id);
+  const cur = currentPhaseId(state);
+  const ph = cur && state.phases[cur];
+  if (!ph || ph.status !== 'blocked') fail(`nenhuma fase aguardando decisão humana em "${id}".`);
+  ph.status = 'failed';
+  saveState(sp, state);
+  fail(`fase "${cur}": NO-GO humano — pipeline travado. Fase seguinte NÃO dispara.`);
+}
+
+function statusSummary(id, { stateRoot } = {}) {
+  const state = loadPipelineState(stateRootFor(stateRoot), id);
+  const lines = state.order.map((pid) => `  ${pid}: ${state.phases[pid].status}`);
+  return `pipeline "${id}" (${state.deliverable})\n${lines.join('\n')}`;
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+function argVal(args, flag) { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : null; }
+
+function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+  const podsRoot = argVal(args, '--pods-root');
+  const stateRoot = argVal(args, '--state-root');
+  const note = argVal(args, '--note');
+  try {
+    if (cmd === 'init') {
+      const s = init(args[1], { podsRoot, stateRoot });
+      console.log(`[OK] pipeline "${s.pipeline}" iniciado — ${s.order.length} fase(s): ${s.order.join(' → ')}`);
+    } else if (cmd === 'status') {
+      console.log(statusSummary(args[1], { stateRoot }));
+    } else if (cmd === 'advance') {
+      const r = advance(args[1], { stateRoot });
+      console.log(`[${r.status}] ${r.message}`);
+    } else if (cmd === 'approve') {
+      const r = approve(args[1], { stateRoot, note });
+      console.log(`[${r.status}] ${r.message}`);
+    } else if (cmd === 'reject') {
+      reject(args[1], { stateRoot });
+    } else {
+      console.error('Uso: node scripts/pc-run-pipeline.cjs <init|status|advance|approve|reject> <pipeline.yaml|id> [--pods-root <dir>] [--state-root <dir>] [--note "..."]');
+      process.exit(2);
+    }
+    process.exit(0);
+  } catch (e) {
+    if (e instanceof PipelineError || e.constructor.name === 'Fail') { console.error(`[FALHA] ${e.message}`); process.exit(1); }
+    throw e;
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  init, advance, approve, reject, statusSummary, loadPipelineState,
+  currentPhaseId, childDone, resolveInputs, evalGateVeto,
+  pipelineStatePath, pipelineDir, PipelineError,
+};