@daniellins/power-claude 0.16.3

package/scripts/forge-upgrade-pod.cjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * forge-upgrade-pod.cjs — formaliza um pod EXISTENTE em v0.3 (Story SF1.4, item e).
+ *
+ * upgrade-in-place (SPEC §G4): NÃO regenera do zero. Preserva os agentes já
+ * validados, gera os artefatos ausentes proporcionais ao tier, e aplica a
+ * RECONCILIAÇÃO WORKFLOW-AWARE BOUNDED (v4) sobre cada agente preservado.
+ *
+ * Pipeline: (1) *assess de tier sobre o pod existente → (2) gera artefatos
+ * ausentes (forge-generate.cjs, preservando agentes) → (3) reconciliação bounded
+ * → (4) valida estático (validate-pod-workflow.cjs) → (5) smoke dinâmico (SF1.3,
+ * quando disponível) → (6) pod-critic *review (gate G6) → (7) registro.
+ * Passos 5–6 são despachados FORA deste script (agente/QA); ele cobre 1–4 e a
+ * reconciliação, e SINALIZA quando um agente excede o bound (recomenda *new).
+ *
+ * Bound da reconciliação (v4) — APENAS:
+ *   (i)  remover auto-sequenciamento / auto-chamada a outro agente;
+ *   (ii) escopar a saída do agente ao artefato da etapa (nota workflow-aware).
+ * Qualquer coisa além disso (reescrever papel, refazer comandos, redividir
+ * responsabilidades — ex.: agente que DECIDE sozinho entre caminhos do processo)
+ * EXCEDE o bound ⇒ o comando reporta e recomenda `*new` para aquele agente,
+ * sem forçar a reconciliação (Risco 2).
+ *
+ * Uso:
+ *   node scripts/forge-upgrade-pod.cjs <podDir> [--critical] [--handoffs N] [--apply]
+ *   (sem --apply: dry-run, não escreve nos agentes; imprime o plano)
+ *
+ * Node >= 18, sem dependências externas.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { classifyTier } = require('./forge-assess-tier.cjs');
+const { generatePod } = require('./forge-generate.cjs');
+
+// ---------------------------------------------------------------------------
+// Padrões de reconciliação (v4). Auditáveis e num único lugar.
+// ---------------------------------------------------------------------------
+
+// (i) Auto-sequenciamento: o agente chama/invoca/despacha OUTRO agente por conta
+// própria (o runner passa a orquestrar, não o agente). Casável por linha.
+const AUTO_SEQUENCING = [
+  /\bdepois\s+(disso|de\s+\w+)[^.]*\b(chame|invoque|acione|despache|passe\s+para|delegue)\b/i,
+  /\b(chame|invoque|acione|despache|delegue)\s+(o\s+)?(agente|subagente)\b/i,
+  /\bem\s+seguida[^.]*\b(chame|invoque|acione|despache)\b/i,
+  /\bpassa?\s+(a\s+bola|o\s+bastão)\s+(para|ao)\b/i,
+];
+
+// (ii) Fora do bound: o agente ORQUESTRA/DECIDE o fluxo — escolhe sozinho entre
+// caminhos do processo, não apenas produz um artefato. Isso é cirurgia de
+// capacidade, não ajuste de prosa ⇒ recomenda *new.
+//
+// [SF6.1 fix round — CONCERNS-1] O 3º regex era `/orquestr[ao]\b[^.]*\b(...agentes)\b/`:
+// o `[^.]*` GULOSO (inclui newlines) casava "Orquestra a criação de novos pods,
+// AGENTES" (papel-de-domínio: `agentes` é OBJETO DA CRIAÇÃO, não alvo de orquestração
+// de fluxo) como se fosse auto-sequenciamento em runtime — falso-positivo em QUALQUER
+// agente orquestrador. Refino: a palavra-de-processo tem de ser o OBJETO DIRETO (near)
+// de "orquestra" — só artigos/quantificadores entre elas —, distinguindo "orquestra
+// AS ETAPAS / OS AGENTES" (fluxo/dispatch, out-of-bound) de "orquestra A CRIAÇÃO DE
+// agentes" (domínio: um substantivo de criação governa o objeto → não casa). Sem `[^.]*`.
+const OUT_OF_BOUND = [
+  /\bdecid[ei]\s+(sozinho\s+)?(entre|qual)\b[^.]*\bcaminho/i,
+  /\bescolhe\s+(o\s+)?(caminho|fluxo|rota|pipeline)\b/i,
+  /\borquestr[ao]\s+(?:(?:o|a|os|as|todo|toda|todos|todas)\s+)*(?:fases?|etapas?|pipelines?|fluxos?|agentes?|processos?)\b/i,
+  /\bramifica\s+(o\s+)?(fluxo|processo)\s+entre\b/i,
+];
+
+/**
+ * Reconcilia o texto de UM agente dentro do bound.
+ * Retorna { status, text, removed[], reason }.
+ *   status 'recommend-new' ⇒ excede o bound; text inalterado, reason preenchido.
+ *   status 'reconciled'    ⇒ dentro do bound; text ajustado, removed[] lista as
+ *                            linhas de auto-sequenciamento retiradas.
+ *   status 'clean'         ⇒ nada a reconciliar.
+ */
+function reconcileAgent(text) {
+  // Detecção de excesso de bound PRIMEIRO — nunca "forçar" preservação.
+  for (const re of OUT_OF_BOUND) {
+    const m = text.match(re);
+    if (m) {
+      return {
+        status: 'recommend-new',
+        text,
+        removed: [],
+        reason: `agente decide/orquestra o fluxo ("${m[0].trim()}") — excede o bound (reescrever papel), recomenda *new`,
+      };
+    }
+  }
+
+  const lines = text.split(/\r?\n/);
+  const removed = [];
+  const kept = [];
+  for (const line of lines) {
+    if (AUTO_SEQUENCING.some((re) => re.test(line))) {
+      removed.push(line.trim());
+      continue; // (i) remove a auto-chamada — o runner orquestra.
+    }
+    kept.push(line);
+  }
+
+  if (removed.length === 0) {
+    return { status: 'clean', text, removed: [], reason: null };
+  }
+
+  // (ii) escopar output à etapa: nota workflow-aware, sem reescrever o papel.
+  let out = kept.join('\n');
+  const scopeNote =
+    '\n> [reconciliação v0.3] Este agente é invocado POR ETAPA pelo runner ' +
+    '(`pc-run-pod`): produz apenas o artefato da sua etapa, a partir do template, ' +
+    'e NÃO se auto-sequencia — a orquestração é do runner.\n';
+  if (!out.includes('[reconciliação v0.3]')) out += scopeNote;
+
+  return { status: 'reconciled', text: out, removed, reason: null };
+}
+
+/** Lê os agentes do pod (arquivos .md em agents/, exceto README). */
+function readAgents(podDir) {
+  const dir = path.join(podDir, 'agents');
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.md') && f !== 'README.md')
+    .map((f) => ({ name: f.replace(/\.md$/, ''), file: path.join(dir, f) }));
+}
+
+/** Erro de fail-loud: ordem do DAG não declarada (ADR-005 Decisão B → exit 2). */
+class SpecRequiredError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SpecRequiredError';
+    this.exitCode = 2;
+  }
+}
+
+/** Carrega a spec de ordem: `--spec <file>` OU `pods/<pod>/pod-spec.json`. */
+function loadSpec(podDir, opts) {
+  const specPath = opts.spec ? path.resolve(opts.spec) : path.join(podDir, 'pod-spec.json');
+  if (!fs.existsSync(specPath)) return null;
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+  } catch (e) {
+    throw new Error(`pod-spec.json inválido (${path.relative(process.cwd(), specPath)}): ${e.message}`);
+  }
+  return { path: specPath, data };
+}
+
+/** Fontes candidatas para AUTORAR a spec (README do pod; wf-*.yaml de squad legado). */
+function specSourceCandidates(podDir) {
+  const out = [];
+  const readme = path.join(podDir, 'README.md');
+  if (fs.existsSync(readme)) out.push(`${path.relative(process.cwd(), readme)} (fluxo descrito na prosa do pod)`);
+  // squad legado correlato: <repo>/squads/<base>/workflows, base = nome do pod sem sufixo "-method".
+  const base = path.basename(podDir).replace(/-method$/, '');
+  const legacyWf = path.resolve(podDir, '..', '..', 'squads', base, 'workflows');
+  if (fs.existsSync(legacyWf)) {
+    for (const f of fs.readdirSync(legacyWf).filter((n) => /^wf-.*\.ya?ml$/.test(n))) {
+      out.push(`${path.relative(process.cwd(), path.join(legacyWf, f))} (workflow legado — evidência de reconciliação, ADR-005 §B4)`);
+    }
+  }
+  if (out.length === 0) out.push('(nenhuma fonte auto-detectada; autore pod-spec.json a partir do domínio)');
+  return out;
+}
+
+/**
+ * Executa o upgrade-in-place sobre um pod existente.
+ * A ORDEM DO DAG é DADO DECLARADO (ADR-005 Decisão B): exige `pods/<pod>/pod-spec.json`
+ * ou `--spec <file>`. Sem declaração ⇒ SpecRequiredError (exit 2). NUNCA readdir/alfabético.
+ * apply=false ⇒ dry-run (não escreve nos agentes). Retorna um relatório estruturado.
+ */
+function upgradePod(podDir, opts = {}) {
+  const apply = Boolean(opts.apply);
+  const agents = readAgents(podDir); // TODOS os agentes do pod (reconciliação + tier).
+  if (agents.length === 0) throw new Error(`nenhum agente em ${podDir}/agents/`);
+
+  // (0) Fonte da ordem do DAG — obrigatória (ADR-005 Decisão B). Fail-loud sem ela.
+  const loaded = loadSpec(podDir, opts);
+  if (!loaded) {
+    const candidates = specSourceCandidates(podDir);
+    throw new SpecRequiredError(
+      `ordem do DAG não declarada para o pod "${path.basename(podDir)}". ` +
+      `Crie pods/${path.basename(podDir)}/pod-spec.json (ou passe --spec <file>): ` +
+      `spec.agents[] ORDENADO = ordem topológica do DAG (ADR-005 — a ordem é dado declarado, ` +
+      `nunca readdir/alfabético).\nFontes candidatas para AUTORAR a spec:\n` +
+      candidates.map((c) => `  - ${c}`).join('\n'),
+    );
+  }
+  const spec = loaded.data;
+  const specAgents = Array.isArray(spec.agents) ? spec.agents : [];
+  if (specAgents.length === 0) throw new Error(`spec sem agents[] ordenado (${path.relative(process.cwd(), loaded.path)})`);
+
+  // (1) Valida a spec contra o disco. Agente na spec sem arquivo ⇒ erro.
+  const diskNames = new Set(agents.map((a) => a.name));
+  const workflowNames = new Set();
+  for (const sa of specAgents) {
+    const nm = typeof sa === 'string' ? sa : sa.name;
+    if (!nm) throw new Error(`entrada de agents[] na spec sem "name"`);
+    if (!diskNames.has(nm)) throw new Error(`agente "${nm}" declarado na spec sem arquivo em agents/${nm}.md`);
+    workflowNames.add(nm);
+  }
+
+  // (2) *assess de tier sobre TODOS os agentes do pod (ADR-005 §B3), não só os do workflow.
+  const assessment = classifyTier({
+    pod: spec.pod || path.basename(podDir),
+    agents: agents.map((a) => a.name),
+    workflows: fs.existsSync(path.join(podDir, 'workflows'))
+      ? fs.readdirSync(path.join(podDir, 'workflows')).filter((f) => /^wf-.*\.ya?ml$/.test(f)).length
+      : 0,
+    handoffs: Number(opts.handoffs || spec.handoffs || 0),
+    dna: Boolean(opts.dna || spec.dna),
+    critical: Boolean(opts.critical || spec.critical),
+  });
+
+  // (3) gera artefatos na ORDEM DA SPEC (agents[] ordenado = etapas do DAG). O generator
+  // só escreve em workflows/ templates/ squad-io.yaml memory/, nunca em agents/ (AC6).
+  const genSpec = {
+    pod: spec.pod || path.basename(podDir),
+    workflowId: spec.workflowId,
+    agents: specAgents, // ORDEM = declaração da spec (com sections/veto por etapa).
+    handoffs: Number(opts.handoffs || spec.handoffs || 0),
+    dna: Boolean(opts.dna || spec.dna),
+    critical: Boolean(opts.critical || spec.critical),
+    // Forma STANDARD-interface (ADR-004 adendo): propaga `interface` da spec — suprime
+    // wf/squad-io fabricados (validado contra handoffs:0 dentro de generatePod).
+    interface: spec.interface === true,
+    // Memória em SIMPLE segue opcional no upgrade (SPEC §G2): mesma flag da geração.
+    memoryOpt: Boolean(opts.withMemory) || spec.memoryOpt === true,
+    // SF12.4a/ADR-030 — propaga os 3 campos canônicos + escada_de_voz da spec CARREGADA
+    // (`--spec`/`pod-spec.json`) para a spec EFETIVAMENTE RECEBIDA por generatePod
+    // (AC48c cláusula 1: o relato de `derived` é sobre ESTE objeto, não sobre disco).
+    // Ausentes na spec carregada ⇒ ausentes aqui também ⇒ generatePod reporta (AC48c).
+    ritmo: spec.ritmo,
+    contrato_entrada: spec.contrato_entrada,
+    entregavel: spec.entregavel,
+    escada_de_voz: spec.escada_de_voz,
+  };
+  // STANDARD/COMPLEX recebe/mantém a memória operante; SIMPLE só sob --with-memory.
+  // C.1/SF3.1 (fecha G1): repassa o `assessment.tier` AGREGADO — computado acima sobre
+  // TODOS os agentes+workflows do pod (linhas ~195-204) mas até aqui IGNORADO — como
+  // tierOverride. Antes, generatePod re-classificava pela spec isolada (só os agentes
+  // do workflow), rebaixando silenciosamente um pod COMPLEX a SIMPLE e pulando
+  // squad-io/memória. Agora o aparato proporcional ao pod inteiro é gerado.
+  // Bug real (ADR-004 §2, confirmado na branch SF6.2): generatePod era chamado
+  // INCONDICIONALMENTE — até o dry-run escrevia no pod. Fix: dry-run repassa
+  // dryRun=true → generatePod computa o PLANO (written[]/skipped[]) SEM tocar disco.
+  // Toda escrita (generatePod + reconciliação §245 + spec §250) fica sob --apply.
+  const gen = generatePod(genSpec, podDir, {
+    withMemory: Boolean(opts.withMemory) || spec.memoryOpt === true,
+    tierOverride: assessment.tier,
+    dryRun: !apply,
+    // SF12.4a/ADR-030 Bloco O (AC48/Emenda 1) — `*upgrade-pod` é sempre 'derived': a spec
+    // é SINTETIZADA de um pod já em disco, nunca autorada fresca. Preserva o comportamento
+    // atual (campo ausente nunca para o processo) e reporta o que falta (AC48c).
+    specOrigin: 'derived',
+    // SF12.6/ADR-030 Bloco C (Decisão 7.2) — leniência POR PATH para o guard novo (`wf`
+    // fail-loud). `opts.allowDivergentOverwrite` (repetível via `--allow-divergent-overwrite
+    // <path>`) chega como array de strings relativas ao cwd — resolvidas a absoluto aqui
+    // (generatePod compara por path.resolve). Ausente ⇒ [] (leniência SEMPRE por path,
+    // nunca "sim para tudo" — AC12).
+    allowDivergentOverwrite: (opts.allowDivergentOverwrite || []).map((p) => path.resolve(p)),
+  });
+
+  // (4) reconciliação bounded sobre CADA agente do pod (inclui os fora do workflow).
+  const reconciliation = [];
+  for (const a of agents) {
+    const before = fs.readFileSync(a.file, 'utf8');
+    const r = reconcileAgent(before);
+    const inWorkflow = workflowNames.has(a.name);
+    reconciliation.push({ agent: a.name, status: r.status, removed: r.removed, reason: r.reason, inWorkflow });
+    if (apply && r.status === 'reconciled') fs.writeFileSync(a.file, r.text);
+    // status 'recommend-new' e 'clean' NÃO alteram o arquivo (preservação).
+  }
+
+  // (5) persiste a spec COM o pod quando aplicada via --spec (fonte da verdade em git).
+  if (apply && opts.spec) {
+    const dest = path.join(podDir, 'pod-spec.json');
+    if (path.resolve(opts.spec) !== path.resolve(dest)) {
+      fs.writeFileSync(dest, JSON.stringify(spec, null, 2) + '\n');
+    }
+  }
+
+  const recommendNew = reconciliation.filter((r) => r.status === 'recommend-new').map((r) => r.agent);
+  const notInWorkflow = reconciliation.filter((r) => !r.inWorkflow).map((r) => r.agent);
+
+  return {
+    tier: assessment.tier,
+    assessment,
+    generated: gen.written,
+    skipped: gen.skipped,
+    // SF12.6/ADR-030 Bloco C — repassa o relato por classe do guard novo (merged[] já
+    // existia; divergent[]/preserved[] são novos — AC11-AC15).
+    merged: gen.merged,
+    divergent: gen.divergent,
+    preserved: gen.preserved,
+    reconciliation,
+    recommendNew,
+    notInWorkflow,
+    applied: apply,
+    specPath: loaded.path,
+  };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  let podDir = null;
+  const opts = { allowDivergentOverwrite: [] };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--apply') opts.apply = true;
+    else if (args[i] === '--critical') opts.critical = true;
+    else if (args[i] === '--dna') opts.dna = true;
+    else if (args[i] === '--with-memory') opts.withMemory = true;
+    else if (args[i] === '--handoffs') opts.handoffs = Number(args[++i]);
+    else if (args[i] === '--spec') opts.spec = args[++i];
+    // SF12.6/ADR-030 Bloco C (AC18, Decisão 7.2) — repetível; forma nua (sem valor) é um erro
+    // de uso comum, não a leniência global proibida (essa é sobre a FORMA do dado dentro de
+    // generatePod — aqui é só coleta de path por path).
+    else if (args[i] === '--allow-divergent-overwrite') opts.allowDivergentOverwrite.push(args[++i]);
+    else podDir = args[i];
+  }
+  if (!podDir) {
+    console.error('Uso: node scripts/forge-upgrade-pod.cjs <podDir> [--spec <file>] [--critical] [--dna] ' +
+      '[--with-memory] [--handoffs N] [--allow-divergent-overwrite <path>]... [--apply]');
+    process.exit(2);
+  }
+  let r;
+  try {
+    r = upgradePod(path.resolve(podDir), opts);
+  } catch (e) {
+    console.error(`[erro] ${e.message}`);
+    process.exit(e && e.exitCode ? e.exitCode : 1);
+  }
+  console.log(`tier: ${r.tier}${r.applied ? '' : '  (dry-run — use --apply para gravar a reconciliação)'}`);
+  console.log(`ordem do DAG: declarada em ${path.relative(process.cwd(), r.specPath)}`);
+  console.log('artefatos gerados (ausentes):');
+  for (const w of r.generated) console.log(`  + ${path.relative(process.cwd(), w)}`);
+  if (r.merged && r.merged.length) {
+    console.log('merge (squad-io.yaml — seções preservadas + novas):');
+    for (const m of r.merged) console.log(`  ~ ${path.relative(process.cwd(), m)}`);
+  }
+  if (r.preserved && r.preserved.length) {
+    console.log('templates PRESERVADOS (divergem do que seria gerado — write-once, ADR-030 Decisão 7.1):');
+    for (const p of r.preserved) console.log(`  = ${path.relative(process.cwd(), p)}`);
+  }
+  if (r.divergent && r.divergent.length) {
+    console.log('artefatos DIVERGENTES da spec (guard por classe, ADR-030 Bloco C):');
+    for (const d of r.divergent) console.log(`  ! ${path.relative(process.cwd(), d)}`);
+  }
+  console.log('reconciliação por agente (bounded):');
+  for (const rec of r.reconciliation) {
+    const wf = rec.inWorkflow ? '' : ' [not-in-workflow]';
+    const detail = rec.status === 'recommend-new' ? ` — ${rec.reason}`
+      : rec.status === 'reconciled' ? ` — ${rec.removed.length} auto-sequenciamento(s) removido(s)` : '';
+    console.log(`  · ${rec.agent}: ${rec.status}${wf}${detail}`);
+  }
+  if (r.notInWorkflow.length) {
+    console.log(`\n·· fora deste workflow (preservados no pod): ${r.notInWorkflow.join(', ')}`);
+  }
+  if (r.recommendNew.length) {
+    console.log(`\n>> RECOMENDA *new para: ${r.recommendNew.join(', ')} (excedem o bound — não foram forçados).`);
+  }
+  console.log('\nPróximo: validate-pod-workflow.cjs (estático) → smoke (SF1.3) → pod-critic *review (G6) → registro.');
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = { upgradePod, reconcileAgent, readAgents, loadSpec, specSourceCandidates, SpecRequiredError, AUTO_SEQUENCING, OUT_OF_BOUND };