@daniellins/power-claude 0.16.3

package/scripts/forge-generate.cjs

@@ -0,0 +1,1303 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * forge-generate.cjs — geração proporcional de artefatos de pod (Story SF1.4).
+ *
+ * Consome o veredito de `forge-assess-tier.cjs` (ADR-004) e gera, DISCO-FIRST
+ * (M2 — grava em disco antes de qualquer outra ação, sem rede/vault), os
+ * artefatos proporcionais ao tier:
+ *
+ *   SIMPLE          → no máximo 1 workflow mínimo + templates das 1–2 saídas.
+ *                     SEM squad-io.yaml, SEM veto-engine obrigatório, SEM memória.
+ *   STANDARD/COMPLEX→ workflows/wf-<id>.yaml (DAG+checkpoints+veto de máquina, no
+ *                     schema da SF1.1) a partir de templates/workflow-tmpl.yaml,
+ *                     1 template por etapa, squad-io.yaml (contrato de handoff) e
+ *                     scaffold de memória (learnings.jsonl vazio +
+ *                     learnings.consolidated.md só com cabeçalho — SEM lifecycle).
+ *
+ * O `wf-<id>.yaml` gerado passa `scripts/validate-pod-workflow.cjs` sem ajuste
+ * manual (AC4): DAG linear, cada etapa com agent+template(em disco)+outputs+veto,
+ * handoffs fechados (output de cada etapa consumido pela seguinte; última = sink).
+ *
+ * Uso:
+ *   node scripts/forge-generate.cjs <pod-spec.json> --out <podDir>
+ *
+ * Spec: { pod, agents:[{name, step, output}], workflowId?, dna?, critical?,
+ *         handoffs?, outputs?:[...] }. `agents` ordenados = etapas do DAG.
+ *
+ * Node >= 18, sem dependências externas.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { classifyTier, TIER_SIMPLE } = require('./forge-assess-tier.cjs');
+const podMemory = require('./pod-memory.cjs');
+// SF12.6/ADR-030 Bloco C/D — a auto-validação (AC25) e o guard por classe (AC11-AC20) INVOCAM
+// o validador estático já existente, nunca duplicam a regra (juiz único: checkCheckpoint).
+const { parseYaml: parseWfYaml, checkCheckpoint } = require('./validate-pod-workflow.cjs');
+
+function slug(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+// ---------------------------------------------------------------------------
+// MODO ADITIVO (Decisão C.2, SF3.1). Preserva o validado; adiciona o novo; RECUSA
+// (exit 2) colisão de artefato validado fora de owns[]. `owns[]` = paths que a
+// linha corrente É DONA (planejados no open-line do manifest) — regenerados
+// deterministicamente (retomada idempotente), nunca tratados como colisão.
+// ---------------------------------------------------------------------------
+class AdditiveCollisionError extends Error {
+  constructor(relPath, kind) {
+    super(`colisão aditiva: ${kind} "${relPath}" já existe e NÃO pertence a esta linha (owns[]) — ` +
+      `modo aditivo recusa editar/sobrescrever artefato validado (isso é evolução do pod, ciclo próprio).`);
+    this.name = 'AdditiveCollisionError';
+    this.exitCode = 2;
+    this.collision = { path: relPath, kind };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Forma STANDARD-interface (ADR-004 adendo 2026-07-25, caso de fronteira SF6.2).
+// `interface: true` suprime wf-*.yaml + squad-io.yaml (zero handoff artefato-a-artefato
+// entre os agentes do pod). É VÁLIDA SOMENTE com `handoffs: 0` — com handoff declarado
+// há processo real e o pod deve gerar workflow. Fail-loud (exit 2) contra fabricação.
+// ---------------------------------------------------------------------------
+class InterfaceContractError extends Error {
+  constructor(handoffs) {
+    super(`pod-interface inválido: interface:true exige handoffs:0 (recebido handoffs:${handoffs}). ` +
+      `A forma STANDARD-interface (ADR-004 adendo 2026-07-25) suprime wf/squad-io SOMENTE onde há zero ` +
+      `handoff interno; com handoff real o pod tem processo e deve gerar workflow/contrato — não pode declarar-se interface.`);
+    this.name = 'InterfaceContractError';
+    this.exitCode = 2;
+    this.handoffs = handoffs;
+  }
+}
+
+/** Extrai os handoffs (from/to/artifact) de um texto squad-io.yaml. */
+function extractHandoffTriples(text) {
+  const lines = String(text).split(/\r?\n/);
+  const triples = [];
+  let cur = null;
+  for (const line of lines) {
+    const from = line.match(/^\s*-\s*from:\s*(.+?)\s*$/);
+    if (from) { if (cur) triples.push(cur); cur = { from: from[1], to: '', artifact: '' }; continue; }
+    if (cur) {
+      const to = line.match(/^\s*to:\s*(.+?)\s*$/);
+      const art = line.match(/^\s*artifact:\s*(.+?)\s*$/);
+      if (to) cur.to = to[1];
+      else if (art) cur.artifact = art[1];
+    }
+  }
+  if (cur) triples.push(cur);
+  return triples.filter((t) => t.from && t.to);
+}
+
+/** Quebra um squad-io.yaml em preâmbulo (comentários) + seções de topo (`key:`). */
+function splitTopSections(text) {
+  const lines = String(text).split(/\r?\n/);
+  const preamble = [];
+  const sections = [];
+  let cur = null;
+  for (const line of lines) {
+    const isTop = /^[A-Za-z_][\w-]*:\s*(.*)$/.test(line) && !/^\s/.test(line);
+    if (isTop) { if (cur) sections.push(cur); cur = { key: line.match(/^([A-Za-z_][\w-]*):/)[1], lines: [line] }; }
+    else if (cur) cur.lines.push(line);
+    else preamble.push(line);
+  }
+  if (cur) sections.push(cur);
+  return { preamble, sections };
+}
+
+/**
+ * MERGE POR SEÇÃO do squad-io.yaml (Decisão C.2). Preserva TODAS as seções
+ * pré-existentes (inclusive customizadas fora do gerador) e faz UNIÃO dos handoffs
+ * (dedup por from|to|artifact). Não sobrescreve conteúdo validado — só adiciona.
+ */
+function mergeSquadIo(existing, generated) {
+  const ex = splitTopSections(existing);
+  const gen = splitTopSections(generated);
+  const exKeys = new Set(ex.sections.map((s) => s.key));
+  const union = [];
+  const seen = new Set();
+  for (const h of [...extractHandoffTriples(existing), ...extractHandoffTriples(generated)]) {
+    const k = `${h.from}|${h.to}|${h.artifact}`;
+    if (!seen.has(k)) { seen.add(k); union.push(h); }
+  }
+  const handoffLines = ['handoffs:'];
+  for (const h of union) handoffLines.push(`  - from: ${h.from}`, `    to: ${h.to}`, `    artifact: ${h.artifact}`);
+  const out = [];
+  if (ex.preamble.some((l) => l.trim())) out.push(...ex.preamble);
+  for (const s of ex.sections) {
+    if (s.key === 'handoffs') out.push(...handoffLines);
+    else out.push(...s.lines);
+  }
+  for (const s of gen.sections) {
+    if (exKeys.has(s.key)) continue;
+    if (s.key === 'handoffs') { out.push(...handoffLines); continue; }
+    out.push(...s.lines);
+  }
+  return `${out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '')}\n`;
+}
+
+/** Escreve arquivo criando os diretórios pais. Disco-first, síncrono. */
+function writeDisk(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+// ---------------------------------------------------------------------------
+// SF12.4a/ADR-030 Bloco O (`DF-SF12.4-11`, Emenda 1) — `opts.specOrigin`, OBRIGATÓRIO,
+// SEM DEFAULT. Substitui a leitura ambígua de `opts.additive` (acerta 0 de 4 chamadores,
+// anti-correlacionado em 2 — ver `*review` da SF12.4a). 3 call sites reais:
+//   forge-generate.cjs main()/CLI            → 'authored'  (incondicional — *new E
+//                                               *migrate-squad F2b, `--additive` NÃO muda isto)
+//   forge-upgrade-pod.cjs                    → 'derived'
+//   forge-harden-learning.cjs                → 'derived'
+// Sem default: um consumidor novo que esquecer o parâmetro PARA na hora, nomeando a
+// ausência — a mesma doutrina da Decisão 3 (Bloco C) aplicada à própria API do gerador.
+// ---------------------------------------------------------------------------
+const SPEC_ORIGINS = new Set(['authored', 'derived']);
+
+class SpecOriginError extends Error {
+  constructor(value) {
+    super(`generatePod: opts.specOrigin é OBRIGATÓRIO e deve ser "authored" ou "derived" (recebido: ${JSON.stringify(value)}). ` +
+      `"authored" = spec autorada fresca (*new, *migrate-squad F2b) — aciona a recusa fail-loud dos campos canônicos (Bloco C). ` +
+      `"derived" = spec sintetizada de um pod já em disco (*upgrade-pod, *harden-learning) — preserva o comportamento atual e reporta ` +
+      `os campos canônicos ausentes (ADR-030 Emenda 1, DF-SF12.4-11). Sem default: nomeie a escolha.`);
+    this.name = 'SpecOriginError';
+    this.exitCode = 2;
+  }
+}
+
+function validateSpecOrigin(value) {
+  if (!SPEC_ORIGINS.has(value)) throw new SpecOriginError(value);
+}
+
+// ---------------------------------------------------------------------------
+// SF12.6/ADR-030 Bloco C (Decisão 7) — guard POR CLASSE de artefato. Escopo:
+// `specOrigin: 'derived'` (regeneração a partir de um pod já em disco — *upgrade-pod,
+// *harden-learning) E o path NÃO pertencer a `opts.owns[]` (harden-learning já usa
+// --additive + owns para regenerar deterministicamente o SEU alvo; essa é uma
+// autoridade de escrita PRÉ-EXISTENTE e mais estreita — o guard novo não a reabre,
+// só protege o que NINGUÉM declarou possuir). Três classes:
+//   wf            → recusa fail-loud (Decisão 7.1), leniência POR PATH (Decisão 7.2).
+//   templates/*   → preserva-por-default (reporta em preserved[], nunca lança).
+//   squad-io.yaml → sempre-merge (mergeSquadIo, incondicional — ver bloco (3) abaixo).
+//   pod-spec.json / memory/ → FORA, explicitamente (AC16) — já são write-once/merge
+//   por outros mecanismos pré-existentes (guarda de existência, consolidate()).
+// ---------------------------------------------------------------------------
+class DivergentRegenerationError extends Error {
+  constructor(relPath, diskLen, genLen, firstDiffLine) {
+    super(
+      `recusa fail-loud (ADR-030 Decisão 7.1, guard por classe): "${relPath}" (classe wf — fail-loud) ` +
+      `diverge do que a spec regeneraria — bytes disco×gerado: ${diskLen}×${genLen}; 1ª linha divergente: ` +
+      `${JSON.stringify(firstDiffLine)}. A causa: a spec está atrás do artefato — alguém editou o wf ` +
+      'diretamente sem levar a mudança para pod-spec.json (ADR-030 Emenda 3: o wf é DERIVADO da spec, ' +
+      'nunca o contrário). Duas saídas, NESTA ordem: (1) declarar na spec o que falta, para a próxima ' +
+      'regeneração já bater — fecha o vão de verdade; (2) se a perda for aceitável, nomeie o path ' +
+      `explicitamente: --allow-divergent-overwrite ${relPath} (ADR-030 Decisão 7.2 — a leniência é ` +
+      'sempre POR PATH, nunca "sim para tudo").',
+    );
+    this.name = 'DivergentRegenerationError';
+    this.exitCode = 2;
+    this.path = relPath;
+  }
+}
+
+class AllowDivergentOverwriteError extends Error {
+  constructor(value) {
+    super(`generatePod: opts.allowDivergentOverwrite deve ser um array de paths (recebido ` +
+      `${JSON.stringify(value)}) — a leniência é SEMPRE por path, nunca "sim para tudo" (ADR-030 ` +
+      'Decisão 7.2). Ex.: allowDivergentOverwrite: ["workflows/wf-x.yaml"].');
+    this.name = 'AllowDivergentOverwriteError';
+    this.exitCode = 2;
+  }
+}
+
+/** Forma nua (`true`/qualquer não-array) é RECUSADA (Decisão 7.2). Ausente ⇒ []. */
+function validateAllowDivergentOverwrite(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new AllowDivergentOverwriteError(value);
+  return value.map(String);
+}
+
+/** 1ª linha em que `a`/`b` divergem (para a mensagem de recusa, Decisão 7.3). */
+function firstDivergentLine(a, b) {
+  const la = String(a).split(/\r?\n/);
+  const lb = String(b).split(/\r?\n/);
+  const n = Math.max(la.length, lb.length);
+  for (let i = 0; i < n; i++) {
+    if (la[i] !== lb[i]) return lb[i] !== undefined ? lb[i] : la[i];
+  }
+  return '';
+}
+
+/**
+ * SF12.6/ADR-030 Bloco D (AC25/DEBT-SF12.6-E) — generatePod valida a PRÓPRIA saída ANTES
+ * de escrever: parseYaml(wfContent) → checkCheckpoint. INVOCA o validador estático já
+ * existente (validate-pod-workflow.cjs) — nunca duplica a regra de DF-SF11.10-3. Recusa
+ * (não escreve nada) se a saída violaria o invariante do gate humano.
+ */
+class CheckpointInvariantError extends Error {
+  constructor(wfRelPath, cause) {
+    super(`generatePod: recusa escrever "${wfRelPath}" — a saída violaria o invariante do gate ` +
+      'humano (ADR-024 DF-SF11.10-3), auto-validado via checkCheckpoint ANTES de qualquer escrita ' +
+      `(ADR-030 Bloco D, DEBT-SF12.6-E): ${cause}`);
+    this.name = 'CheckpointInvariantError';
+    this.exitCode = 2;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SF12.4a/ADR-030 Bloco C (`DF-SF12.4-3`, Decisão 3) — os 3 padrões DECLARADOS-OU-
+// RECUSADOS (`ritmo`, `contrato_entrada`, `entregavel`, Bloco A/AC2). Três estados,
+// nunca dois: declarado com conteúdo (emite o mecanismo, Blocos E/G/H); recusado —
+// `nao_se_aplica: true` + `razao` + `respondido_por` não-vazios (emite nada, registra a
+// recusa); ausente (recusa fail-loud SOB `specOrigin: 'authored'` — Bloco O/AC48b). A
+// máquina confere FORMA (campo existe? razão não-vazia? atribuição presente?), nunca
+// julga se a razão é boa (fronteira ADR-002, `DEBT-SF12.4-A`).
+// ---------------------------------------------------------------------------
+const CANONICAL_FIELDS = ['ritmo', 'contrato_entrada', 'entregavel'];
+
+class CanonicalFieldError extends Error {
+  constructor(field, reason) {
+    super(`campo canônico "${field}" ${reason} — declare com conteúdo ou registre ` +
+      `{ nao_se_aplica: true, razao: "<motivo>", respondido_por: "<quem>" } (ADR-030 Decisão 3, DF-SF12.4-3).`);
+    this.name = 'CanonicalFieldError';
+    this.exitCode = 2;
+    this.field = field;
+  }
+}
+
+/** Referência de etapa (AC21/AC24) — mesma disciplina de `anti_path.mechanized_by`. */
+function validateCanonicalStepRef(field, stepId, steps) {
+  if (!steps.some((s) => s.id === stepId)) {
+    throw new CanonicalFieldError(field, `referencia a etapa "${stepId}" que não existe entre os ids de ` +
+      `stepsFromSpec(spec) — ids válidos: ${steps.map((s) => s.id).join(', ') || '(nenhuma etapa)'}`);
+  }
+}
+
+/**
+ * Lê e valida (FORMA, não semântica) UM campo canônico da spec — usado sob
+ * `specOrigin: 'authored'` (fail-loud, Bloco C/AC7-AC10/AC42-AC44). Retorna
+ * `{ mode: 'declared', value }` ou `{ mode: 'refused', razao, respondido_por }`;
+ * nunca retorna para o caso "ausente" — lança CanonicalFieldError.
+ */
+function readCanonicalField(spec, field, steps) {
+  const raw = spec[field];
+  if (raw == null) {
+    throw new CanonicalFieldError(field, 'ausente na spec');
+  }
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new CanonicalFieldError(field, 'deve ser um objeto — declarado com conteúdo OU recusa (ver AC2)');
+  }
+  if (raw.nao_se_aplica === true) {
+    // AC9 — a recusa TEM forma exigida: razão e atribuição não-vazias. Mensagem
+    // DIFERENTE da de "ausente" (AC44) — quem lê o erro sabe qual dos dois corrigir.
+    const razaoOk = typeof raw.razao === 'string' && raw.razao.trim() !== '';
+    const respOk = typeof raw.respondido_por === 'string' && raw.respondido_por.trim() !== '';
+    if (!razaoOk || !respOk) {
+      const falta = !razaoOk ? 'razao' : 'respondido_por';
+      throw new CanonicalFieldError(field, `tem recusa MALFORMADA — "${falta}" ausente ou vazio ` +
+        `(nao_se_aplica exige razao E respondido_por não-vazios)`);
+    }
+    return { mode: 'refused', razao: raw.razao, respondido_por: raw.respondido_por };
+  }
+  // Conteúdo declarado — forma exata por campo (AC2).
+  if (field === 'ritmo') {
+    if (typeof raw.step !== 'string' || raw.step.trim() === ''
+      || !Array.isArray(raw.skip_modes) || raw.skip_modes.length === 0
+      || !raw.skip_modes.every((m) => typeof m === 'string' && m.trim() !== '')) {
+      throw new CanonicalFieldError(field, 'tem conteúdo malformado — esperado { step: <id>, skip_modes: [<modo...>] } (≥1 modo)');
+    }
+    // SF12.6/ADR-030 AC21c — mesma disciplina que contrato_entrada/entregavel já aplicam:
+    // referência a etapa inexistente RECUSA, nunca retorna `declared` em silêncio.
+    validateCanonicalStepRef(field, raw.step, steps);
+  } else if (field === 'contrato_entrada') {
+    if (typeof raw.step !== 'string' || raw.step.trim() === ''
+      || !Array.isArray(raw.valores) || raw.valores.length < 2
+      || !raw.valores.every((v) => typeof v === 'string' && v.trim() !== '')) {
+      throw new CanonicalFieldError(field, 'tem conteúdo malformado — esperado { step: <id>, valores: [<≥2 strings>] }');
+    }
+    validateCanonicalStepRef(field, raw.step, steps);
+  } else if (field === 'entregavel') {
+    if (typeof raw.step !== 'string' || raw.step.trim() === '') {
+      throw new CanonicalFieldError(field, 'tem conteúdo malformado — esperado { step: <id> }');
+    }
+    validateCanonicalStepRef(field, raw.step, steps);
+  }
+  return { mode: 'declared', value: raw };
+}
+
+/**
+ * Estado dos 3 campos canônicos, best-effort (nunca lança) — usado para persistência
+ * (Bloco F/AC18-19), relato do modo `derived` (Bloco O/AC48c) e o anúncio do ritmo
+ * (Bloco E/AC15), independente de `specOrigin`.
+ */
+function computeCanonicalStatus(spec) {
+  const out = {};
+  for (const field of CANONICAL_FIELDS) {
+    const raw = spec[field];
+    if (raw == null) {
+      out[field] = { mode: 'ausente' };
+    } else if (raw && typeof raw === 'object' && !Array.isArray(raw) && raw.nao_se_aplica === true) {
+      out[field] = { mode: 'refused', razao: raw.razao, respondido_por: raw.respondido_por };
+    } else if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+      out[field] = { mode: 'declared', ...raw };
+    } else {
+      out[field] = { mode: 'malformed', value: raw };
+    }
+  }
+  return out;
+}
+
+/**
+ * Template de saída de uma etapa.
+ * FORMA = as seções `##` (verificadas por checkTemplateConformance no runner).
+ * VETO ORTOGONAL (ADR-005 Decisão A): o template SEMPRE termina com um campo de
+ * máquina NÃO-heading — a linha `confianca: <alta|media|baixa>`, cujo placeholder
+ * NÃO casa o pattern do veto default (força preenchimento real). Nunca se usa
+ * `section_exists` de uma seção do próprio template como veto (seria implicado pela
+ * conformidade de forma — a classe degenerada que o piloto expôs).
+ */
+/**
+ * Nota de semântica contável do veto `count_gte` (débito #1 do gate SF1.5, finding
+ * id:1). O piloto expôs que 2/5 runs formataram uma seção contável como TABELA e o
+ * contador (bullets-only, à época) contou 0 → fix evitável. Agora o template GERADO
+ * PRESCREVE a forma contável junto à seção-alvo, para o agente de etapa saber, ANTES
+ * de escrever, o que conta. Casa a semântica real de countListItemsInSection (SF2.3):
+ * bullets, lista numerada e linhas de tabela contam; prosa não.
+ */
+function countGteNote(field) {
+  return `<!-- count_gte "${field}": conte itens de lista sob este heading — bullets (\`- \`/\`* \`), ` +
+    `linhas numeradas (\`1.\` \`2.\` ...) OU linhas de tabela (\`| ... |\`, o separador \`|---|---|\` NÃO conta). ` +
+    `Prosa corrida NÃO conta. -->`;
+}
+
+/** Índice case-insensitive dos vetos count_gte por campo (mesma regra de contains do contador). */
+function countGteFields(veto) {
+  const out = [];
+  if (Array.isArray(veto)) {
+    for (const a of veto) {
+      if (a && a.type === 'count_gte' && a.field != null) out.push({ field: String(a.field), n: a.n });
+    }
+  }
+  return out;
+}
+
+/**
+ * SF12.4a/ADR-030 Blocos G/H (AC20a/AC23a) — campos de máquina extras dos padrões
+ * `contrato_entrada`/`entregavel`, quando declarados. Emitidos ANTES de `confianca`
+ * (mesma zona ortogonal fora dos headings — ADR-005 Decisão A). `extraFields`:
+ * `[{ field, placeholder }]`.
+ */
+function stepTemplate(stepId, agent, output, sections, veto, extraFields) {
+  const secs = Array.isArray(sections) && sections.length ? sections : ['## Contexto', '## Output'];
+  const cg = countGteFields(veto);
+  const body = secs
+    .map((s) => {
+      const label = String(s).replace(/^#+\s*/, '').trim();
+      // Anexa a nota de forma contável quando a seção casa o field de um count_gte
+      // (mesma semântica CONTAINS/case-insensitive do contador do runner).
+      const match = cg.find((c) => label.toLowerCase().includes(c.field.toLowerCase())
+        || c.field.toLowerCase().includes(label.toLowerCase()));
+      const note = match ? `${countGteNote(match.field)}\n` : '';
+      return `${s}\n${note}<!-- preencher: conteúdo de "${label}" -->\n`;
+    })
+    .join('\n');
+  const extras = (Array.isArray(extraFields) && extraFields.length)
+    ? `${extraFields.map((e) => `${e.field}: <${e.placeholder}>`).join('\n')}\n`
+    : '';
+  return `# Template de saída — etapa \`${stepId}\` (agente \`${agent}\`, artefato \`${output}\`)
+
+> Gerado por forge-generate.cjs (SF1.4 + ADR-005). Preencher com o artefato real da etapa.
+> FORMA (seções \`##\`) verificada por checkTemplateConformance; VETO ORTOGONAL via o
+> campo de máquina \`confianca\` abaixo (fora dos headings — ADR-005 Decisão A).
+
+${body}
+<!-- Campo(s) de máquina do(s) padrão(ões) declarado(s) (SF12.4a/ADR-030 Blocos G/H), quando aplicável — NÃO é heading. -->
+${extras}<!-- Campo de máquina do veto default (ADR-005) — NÃO é heading. Troque o placeholder por alta|media|baixa. -->
+confianca: <alta|media|baixa>
+`;
+}
+
+/** Serializa UMA veto.assertion para o flow-map inline do contrato wf-*.yaml. */
+function serializeAssertion(a) {
+  // SF7.2: enc RECURSIVO — arrays viram flow-list `[..]` e objetos viram flow-map `{..}`,
+  // para emitir corretamente `command_check.args` (lista) e `json_schema_valid.extract`
+  // (mapa). Antes, String(array)="a,b" e String(obj)="[object Object]" corrompiam a emissão.
+  const enc = (v) => {
+    if (v === null || v === undefined) return 'null';
+    if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+    if (Array.isArray(v)) return `[${v.map(enc).join(', ')}]`;
+    if (typeof v === 'object') {
+      return `{ ${Object.entries(v).map(([k, val]) => `${k}: ${enc(val)}`).join(', ')} }`;
+    }
+    const s = String(v);
+    // SF7.6: string PURAMENTE numérica é emitida QUOTADA — sem aspas o parser YAML-lite
+    // a releria como number e corromperia o tipo (ex.: command_check.args ["--max","0"]
+    // viraria [--max, 0] e o validador estático recusa "args" não-string). Round-trip
+    // fiel: string entra, string sai.
+    return /^[A-Za-z0-9_]+$/.test(s) && !/^\d+$/.test(s) ? s : JSON.stringify(s);
+  };
+  const parts = [`type: ${a.type}`];
+  for (const [k, v] of Object.entries(a)) {
+    if (k === 'type') continue;
+    parts.push(`${k}: ${enc(v)}`);
+  }
+  return `- { ${parts.join(', ')} }`;
+}
+
+/** Constrói o texto YAML do wf-<id>.yaml a partir das etapas (schema SF1.1). */
+/**
+ * Serializa um checkpoint por-etapa declarado na spec para o flow-map inline do
+ * wf-*.yaml. Preserva `blocking` e `criteria` (fonte do legado citada na spec).
+ * SF3.4/finding F2: sem isto o checkpoint mid-DAG autorado era DROPADO — degradando
+ * fidelidade E mascarando o gatilho checkpoint:mid do feature-diff (computeFeatureSet
+ * lê step.checkpoint.blocking). Newlines viram espaço (o flow-map é single-line).
+ */
+function serializeCheckpoint(cp) {
+  const blocking = cp.blocking === true ? 'true' : 'false';
+  const criteria = String(cp.criteria == null ? '' : cp.criteria)
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"');
+  // SF12.6/ADR-030 Bloco D (AC22) — skip_modes, quando presente (INJETADO por `ritmo`, nunca
+  // lido de agents[i].checkpoint.skip_modes diretamente — ver injeção em generatePod), é
+  // emitido ANTES de `criteria` (mesma ordem do wf hand-authored — fecha o AC23).
+  const skipModes = (Array.isArray(cp.skip_modes) && cp.skip_modes.length)
+    ? `skip_modes: [${cp.skip_modes.join(', ')}], `
+    : '';
+  return `{ blocking: ${blocking}, ${skipModes}criteria: "${criteria}" }`;
+}
+
+function buildWorkflowYaml(workflowId, steps) {
+  const lines = [];
+  lines.push(`# wf-${workflowId}.yaml — gerado por forge-generate.cjs (SF1.4).`);
+  lines.push(`# Contrato: templates/workflow-tmpl.yaml. Validador: scripts/validate-pod-workflow.cjs.`);
+  lines.push('');
+  lines.push('state_machine:');
+  lines.push('  states: [init, running, review, complete, failed]');
+  lines.push('  initial: init');
+  lines.push('  terminal: [complete, failed]');
+  lines.push('');
+  lines.push('steps:');
+  steps.forEach((step, i) => {
+    const inputs = i === 0 ? '[brief]' : `[${steps[i - 1].output}]`;
+    const dependsOn = i === 0 ? '[]' : `[${steps[i - 1].id}]`;
+    // Checkpoint por-etapa: se a spec declarou `step.checkpoint` (mid ou final),
+    // PROPAGA-o conforme declarado (blocking/criteria). Senão, mantém o default:
+    // última etapa ganha checkpoint bloqueante genérico; demais, null.
+    const isLast = i === steps.length - 1;
+    const checkpoint = (step.checkpoint && typeof step.checkpoint === 'object')
+      ? serializeCheckpoint(step.checkpoint)
+      : (isLast ? '{ blocking: true, criteria: "revisão da etapa final aprovada" }' : 'null');
+    lines.push(`  - id: ${step.id}`);
+    lines.push(`    agent: ${step.agent}`);
+    lines.push(`    template: templates/${step.id}-tmpl.md`);
+    lines.push(`    inputs: ${inputs}`);
+    lines.push(`    outputs: [${step.output}]`);
+    // SF12.4a/ADR-030 Bloco D (AC12) — mecanismo 1 (`requiredReading`, primitiva EMITIDA):
+    // `knowledge:` por etapa, MESMA forma já validada por validate-pod-workflow.cjs
+    // (bloco SF10.1/ADR-018 D2). Etapa sem `knowledge` na spec: nada emitido (AC14 —
+    // retrocompat byte-idêntica, não é caso de recusa do Bloco C).
+    if (Array.isArray(step.knowledge) && step.knowledge.length) {
+      lines.push(`    knowledge: [${step.knowledge.join(', ')}]`);
+    }
+    lines.push(`    depends_on: ${dependsOn}`);
+    lines.push(`    checkpoint: ${checkpoint}`);
+    lines.push('    veto:');
+    lines.push('      assertions:');
+    // Veto ORTOGONAL ao template (ADR-005): default = asserção de conteúdo declarado
+    // (campo de máquina `confianca` fora dos headings). Vetos de domínio declarados na
+    // spec (step.veto[]) SUBSTITUEM o default (sempre ≥1). Nunca section_exists de
+    // seção do próprio template (implicado pela conformidade de forma).
+    const assertions = (Array.isArray(step.veto) && step.veto.length)
+      ? step.veto
+      : [{ type: 'field_matches', field: 'confianca', pattern: '^(alta|media|baixa)$' }];
+    for (const a of assertions) lines.push(`        ${serializeAssertion(a)}`);
+    // SF7.3/ADR-016 — emissão OPT-IN de anti_path: só quando a spec da etapa o declara
+    // (ausente por padrão — diferente de `confianca`, que é default por ortogonalidade).
+    if (Array.isArray(step.anti_path) && step.anti_path.length) {
+      lines.push('    anti_path:');
+      for (const it of step.anti_path) {
+        const mb = (it.mechanized_by == null) ? 'null' : encAntiScalar(it.mechanized_by);
+        lines.push(`      - { rule: ${encAntiScalar(it.rule)}, mechanized_by: ${mb} }`);
+      }
+    }
+    lines.push('');
+  });
+  return lines.join('\n');
+}
+
+/** Escalar do anti_path para o flow-map inline (aspas só quando não é token simples). */
+function encAntiScalar(v) {
+  const s = String(v);
+  return /^[A-Za-z0-9_-]+$/.test(s) ? s : JSON.stringify(s);
+}
+
+/** squad-io.yaml — contrato de handoff do pod (inputs↔outputs entre etapas). */
+function buildSquadIo(pod, steps) {
+  const lines = [];
+  lines.push(`# squad-io.yaml — contrato de handoff do pod \`${pod}\` (SF1.4).`);
+  lines.push(`# Cada handoff liga o output de uma etapa ao input da etapa a jusante.`);
+  lines.push(`pod: ${pod}`);
+  lines.push('handoffs:');
+  for (let i = 1; i < steps.length; i++) {
+    lines.push(`  - from: ${steps[i - 1].id}`);
+    lines.push(`    to: ${steps[i].id}`);
+    lines.push(`    artifact: ${steps[i - 1].output}`);
+  }
+  if (steps.length < 2) lines.push('  [] # pod de etapa única — sem handoff interno');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** Normaliza a lista de etapas a partir da spec (agents ordenados = etapas). */
+function stepsFromSpec(spec) {
+  const agents = Array.isArray(spec.agents) ? spec.agents : [];
+  const steps = agents.map((a, i) => {
+    const name = typeof a === 'string' ? a : a.name;
+    const id = slug((typeof a === 'object' && a.step) || name || `step-${i + 1}`);
+    const output = (typeof a === 'object' && a.output) || `${id}-artifact`;
+    // ADR-005: propaga as seções do template e o veto de domínio declarados na spec.
+    const sections = (typeof a === 'object' && Array.isArray(a.sections)) ? a.sections : undefined;
+    const veto = (typeof a === 'object' && Array.isArray(a.veto)) ? a.veto : undefined;
+    // ADR-005/SF3.4: propaga o checkpoint por-etapa declarado na spec (mid ou final).
+    const checkpoint = (typeof a === 'object' && a.checkpoint && typeof a.checkpoint === 'object') ? a.checkpoint : undefined;
+    // SF7.3/ADR-016: propaga anti_path da etapa da spec (opt-in). A emissão pelo
+    // buildWorkflowYaml só é ALCANÇÁVEL pela rota real (generatePod→stepsFromSpec) se o
+    // campo for propagado aqui — antes era descartado (CONCERNS-1). Valida a forma na
+    // ENTRADA da spec (fail-loud, coerente com o estático): item malformado ou mechanized_by
+    // sem id correspondente no veto da etapa recusa a geração.
+    const anti_path = (typeof a === 'object' && Array.isArray(a.anti_path))
+      ? validateSpecAntiPath(a.anti_path, veto, id)
+      : undefined;
+    // SF12.4a/ADR-030 Bloco D (AC11) — propaga agents[i].knowledge (opcional, retro-
+    // compat: ausente ⇒ undefined ⇒ nenhuma chave `knowledge:` emitida, AC14).
+    const knowledge = (typeof a === 'object' && Array.isArray(a.knowledge))
+      ? a.knowledge.map(String)
+      : undefined;
+    return { id, agent: name, output, sections, veto, checkpoint, anti_path, knowledge };
+  });
+  return injectRitmoSkipModes(spec, steps);
+}
+
+/**
+ * SF12.6/ADR-030 Bloco D (Decisão 6.1-6.5) — `ritmo` INJETA checkpoint.skip_modes sobre um
+ * checkpoint JÁ AUTORADO (mesmo padrão de contrato_entrada/entregavel, Blocos G/H — mas
+ * aplicado AQUI, em `stepsFromSpec`, não em `generatePod`: a emissão precisa ser alcançável
+ * também pela rota direta `stepsFromSpec → buildWorkflowYaml`, sem passar por `generatePod`
+ * — AC23). NUNCA fabrica `criteria` (Decisão 1): RECUSA quando a etapa-alvo não tem
+ * checkpoint autorado — inclusive quando o único "checkpoint" seria só o DEFAULT sintetizado
+ * por `buildWorkflowYaml` na última etapa (nunca aparece aqui: esse default só é aplicado
+ * DEPOIS, dentro de `buildWorkflowYaml` — Decisão 6.5, `DEBT-SF12.6-F`, sem AC próprio).
+ * Muta `steps` em memória (array recém-construído por este mesmo `stepsFromSpec`) — nunca a
+ * spec de entrada. Mutação silenciosa quando `ritmo` está ausente/recusado/malformado: a
+ * disciplina de FORMA (fail-loud sob `specOrigin:'authored'`) é do Bloco C/`readCanonicalField`,
+ * não deste ponto — aqui só se decide SE a injeção é POSSÍVEL sobre o alvo referenciado.
+ */
+function injectRitmoSkipModes(spec, steps) {
+  const ritmo = spec && spec.ritmo;
+  const isCandidate = ritmo && typeof ritmo === 'object' && !Array.isArray(ritmo) && ritmo.nao_se_aplica !== true
+    && typeof ritmo.step === 'string' && ritmo.step.trim() !== ''
+    && Array.isArray(ritmo.skip_modes) && ritmo.skip_modes.length
+    && ritmo.skip_modes.every((m) => typeof m === 'string' && m.trim() !== '');
+  if (!isCandidate) return steps;
+  validateCanonicalStepRef('ritmo', ritmo.step, steps); // AC21c — referência a etapa inexistente RECUSA.
+  const idx = steps.findIndex((s) => s.id === ritmo.step);
+  const targetCp = steps[idx].checkpoint;
+  if (!targetCp || typeof targetCp !== 'object' || typeof targetCp.criteria !== 'string' || targetCp.criteria.trim() === '') {
+    throw new CanonicalFieldError('ritmo', `aponta para a etapa "${ritmo.step}" que NÃO tem checkpoint ` +
+      'autorado (blocking+criteria escritos por humano) — "ritmo" só INJETA skip_modes sobre um gate que já ' +
+      'existe; a máquina NUNCA fabrica criteria (ADR-030 Decisão 1/6.1/6.5, AC21b/DEBT-SF12.6-F).');
+  }
+  steps[idx] = { ...steps[idx], checkpoint: { ...targetCp, skip_modes: ritmo.skip_modes } };
+  return steps;
+}
+
+/** Valida a forma do anti_path na entrada da spec (fail-loud). Retorna o array validado. */
+function validateSpecAntiPath(ap, veto, stepId) {
+  const ids = new Set((Array.isArray(veto) ? veto : [])
+    .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)) {
+      throw new Error(`anti_path[${i}] da etapa "${stepId}" deve ser um mapa { rule, mechanized_by }`);
+    }
+    if (typeof item.rule !== 'string' || item.rule.trim() === '') {
+      throw new Error(`anti_path[${i}].rule da etapa "${stepId}" ausente ou vazio`);
+    }
+    if (item.mechanized_by != null) {
+      if (typeof item.mechanized_by !== 'string' || !ids.has(item.mechanized_by)) {
+        throw new Error(`anti_path[${i}].mechanized_by "${item.mechanized_by}" da etapa "${stepId}" não referencia o id de nenhuma veto.assertion declarada na spec desta etapa`);
+      }
+    }
+  });
+  return ap;
+}
+
+/**
+ * Gera os artefatos do pod em `podDir`, proporcionais ao tier.
+ * Retorna { tier, written[], skipped[] } — written = paths criados (disco-first).
+ */
+// ---------------------------------------------------------------------------
+// SF12.4a/ADR-030 Bloco I — o preço do L1: stub de agente + sidecar `.smoke.json`
+// sintetizado. Síntese ESTRUTURAL (satisfaz a FORMA das veto.assertions declaradas),
+// nunca redação de conteúdo — mesma fronteira ADR-002 do resto do framework.
+// ---------------------------------------------------------------------------
+
+class KnowledgeFileMissingError extends Error {
+  constructor(stepId, file) {
+    super(`etapa "${stepId}": knowledge declarado "${file}" não existe em <podDir>/knowledge/${file} — ` +
+      `o gerador CONFERE existência, não cria (pipeline.md Fase 3: knowledge é autorado ANTES de invocar ` +
+      `forge-generate.cjs). AC13/ADR-030 Bloco D.`);
+    this.name = 'KnowledgeFileMissingError';
+    this.exitCode = 2;
+  }
+}
+
+/** AC13 — pré-condição que o motor verifica no dispatch, conferida NA GERAÇÃO. */
+function assertKnowledgeExists(steps, podDir) {
+  for (const step of steps) {
+    if (!Array.isArray(step.knowledge)) continue;
+    for (const k of step.knowledge) {
+      const abs = path.join(podDir, 'knowledge', k);
+      if (!fs.existsSync(abs)) throw new KnowledgeFileMissingError(step.id, k);
+    }
+  }
+}
+
+class UnsynthesizableVetoError extends Error {
+  constructor(stepId, assertion) {
+    const extra = assertion.type === 'field_matches'
+      ? ` com pattern "${assertion.pattern}" (o sintetizador só deriva alternação simples "^(a|b|c)$" ou literal puro)`
+      : '';
+    super(`sidecar de smoke (Bloco I): a etapa "${stepId}" declara veto.assertions do tipo "${assertion.type}"${extra} ` +
+      `que o sintetizador não sabe satisfazer — RECUSA fail-loud (não gera .smoke.json/cenário inválido; ` +
+      `um sidecar que não prova nada seria pior que ausente — mesma doutrina do Bloco C, AC28).`);
+    this.name = 'UnsynthesizableVetoError';
+    this.exitCode = 2;
+    this.stepId = stepId;
+    this.assertionType = assertion.type;
+  }
+}
+
+const SYNTHESIZABLE_VETO_TYPES = new Set(['field_matches', 'count_gte', 'file_referenced_exists', 'section_exists']);
+
+/** Deriva um valor literal que CASA o pattern — só alternação simples "^(a|b|c)$" ou literal puro. Senão, null. */
+function deriveFieldMatchesValue(pattern) {
+  let p = String(pattern == null ? '' : pattern);
+  if (p.startsWith('^')) p = p.slice(1);
+  if (p.endsWith('$')) p = p.slice(0, -1);
+  const alt = p.match(/^\(([^()]+)\)$/);
+  if (alt) {
+    const first = alt[1].split('|')[0];
+    if (first && !/[\\.*+?[\]{}^$]/.test(first)) return first;
+    return null;
+  }
+  if (p && !/[\\.*+?()[\]{}^$|]/.test(p)) return p;
+  return null;
+}
+
+/** Escapa um literal para uso seguro dentro de uma alternação de regex `(a|b|c)`. */
+function escapeRegexAlt(v) {
+  return String(v).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function stepAssertions(step) {
+  return (Array.isArray(step.veto) && step.veto.length)
+    ? step.veto
+    : [{ type: 'field_matches', field: 'confianca', pattern: '^(alta|media|baixa)$' }];
+}
+
+function stepSections(step) {
+  return Array.isArray(step.sections) && step.sections.length ? step.sections : ['## Contexto', '## Output'];
+}
+
+/** AC28 — recusa fail-loud ANTES de qualquer escrita se algum veto declarado não é sintetizável. */
+function assertSynthesizableVeto(steps) {
+  for (const step of steps) {
+    for (const a of stepAssertions(step)) {
+      if (!SYNTHESIZABLE_VETO_TYPES.has(a.type)) throw new UnsynthesizableVetoError(step.id, a);
+      if (a.type === 'field_matches' && deriveFieldMatchesValue(a.pattern) == null) {
+        throw new UnsynthesizableVetoError(step.id, a);
+      }
+    }
+  }
+}
+
+/**
+ * Sintetiza o texto de UM artefato de etapa: `{}` = conforme (caminho feliz);
+ * `{ dropFirstSection: true }` = quebra de FORMA (template_violation, AC27);
+ * `{ breakAssertion: <assertion> }` = quebra de UMA assertion nomeada (veto_violation,
+ * AC27/AC27b — nunca uma assertion genérica/arbitrária).
+ */
+function synthesizeArtifactText(step, opts = {}) {
+  const sections = stepSections(step);
+  const useSections = opts.dropFirstSection ? sections.slice(1) : sections;
+  const assertions = stepAssertions(step);
+  const countGte = assertions.filter((a) => a.type === 'count_gte');
+
+  const body = useSections.map((s) => {
+    const label = String(s).replace(/^#+\s*/, '').trim();
+    const cg = countGte.find((c) => label.toLowerCase().includes(String(c.field).toLowerCase())
+      || String(c.field).toLowerCase().includes(label.toLowerCase()));
+    if (cg) {
+      const broken = opts.breakAssertion === cg;
+      const n = broken ? 0 : Math.max(1, Number(cg.n) || 1);
+      const items = Array.from({ length: n }, (_, i) => `- item de canário ${i + 1}`).join('\n');
+      return `${s}\n${items ? `${items}\n` : ''}`;
+    }
+    return `${s}\nConteúdo de canário (sintetizado por forge-generate.cjs, ADR-030 Bloco I — síntese ESTRUTURAL, não redação).\n`;
+  }).join('\n');
+
+  const fieldLines = [];
+  const seen = new Set();
+  for (const a of assertions) {
+    if (a.type === 'field_matches') {
+      const val = deriveFieldMatchesValue(a.pattern);
+      const broken = opts.breakAssertion === a;
+      fieldLines.push(`${a.field}: ${broken ? `${val}--quebrado-pelo-smoke` : val}`);
+      seen.add(a.field);
+    } else if (a.type === 'file_referenced_exists') {
+      const broken = opts.breakAssertion === a;
+      // O agente-stub do AC26 garante existência real de agents/<agent>.md sob podRoot
+      // (base de resolução confirmada pelo `*review` — pc-run-pod.cjs:466).
+      fieldLines.push(`${a.field}: ${broken ? 'arquivo-inexistente-smoke.md' : `agents/${step.agent}.md`}`);
+      seen.add(a.field);
+    }
+  }
+  if (!seen.has('confianca')) fieldLines.push('confianca: alta');
+
+  return `${body}\n${fieldLines.join('\n')}\n`;
+}
+
+/**
+ * Monta UM sidecar `.smoke.json` (schema medido em `wf-forge.smoke.json` — Contexto (f)
+ * da story): `artifacts` conforme por etapa (TODAS as etapas do wf); `template_violation`/
+ * `veto_violation` da etapa-alvo. `breakField`, quando dado, nomeia a assertion a quebrar
+ * (AC27b — mecanismo específico); default: a 1ª assertion da etapa-alvo (AC27 — base).
+ */
+function buildSmokeSidecar(steps, targetStepId, breakField) {
+  const artifacts = {};
+  for (const step of steps) artifacts[step.id] = synthesizeArtifactText(step);
+  const targetStep = steps.find((s) => s.id === targetStepId);
+  const templateViolation = synthesizeArtifactText(targetStep, { dropFirstSection: true });
+  const assertions = stepAssertions(targetStep);
+  const breakAssertion = (breakField && assertions.find((a) => a.field === breakField)) || assertions[0];
+  const vetoViolation = synthesizeArtifactText(targetStep, { breakAssertion });
+  return {
+    _comment: 'Cenário de smoke SINTETIZADO por forge-generate.cjs (SF12.4a/ADR-030 Bloco I) — canário ' +
+      'ESTRUTURAL (satisfaz a forma das veto.assertions declaradas), não redação de conteúdo (fronteira ADR-002). ' +
+      `target_step="${targetStepId}"${breakField ? ` — cenário do mecanismo "${breakField}" (AC27b)` : ' — sidecar BASE (AC27)'}.`,
+    target_step: targetStepId,
+    artifacts,
+    template_violation: templateViolation,
+    veto_violation: vetoViolation,
+  };
+}
+
+/** AC26 — frontmatter + 3 blocos mínimos (Papel/Comandos/Regras de ouro), dentro do teto de validate-budgets.js. */
+function agentStubContent(name) {
+  return `---
+name: ${name}
+description: "Stub gerado por forge-generate.cjs (SF12.4a/ADR-030 Bloco I). Use para: pod executável até o forge-chief preencher o conteúdo real."
+model: sonnet
+budget_tokens: 400
+---
+
+# Papel
+
+Stub gerado automaticamente para que o pod seja EXECUTÁVEL pelo motor real (o runner
+exige \`agents/<nome>.md\` — ADR-030 M2/DF-SF12.4-1). Conteúdo REAL é autoria do
+\`forge-chief\` em prosa (\`DEBT-SF12.4-F\`) — este stub não é bom, é estruturalmente válido.
+
+## Comandos
+
+- *comando-exemplo: preencher com os comandos reais deste agente.
+
+## Regras de ouro
+
+- Preencher com as regras de ouro reais deste agente antes de considerar o pod pronto para uso.
+`;
+}
+
+// ---------------------------------------------------------------------------
+// SF12.4a/ADR-030 Bloco J (`DF-SF12.4-5`/`-6`) — camada do dono, SÓ PLACEHOLDER. Nunca
+// escreve instância (`dono.yaml`); emite `knowledge/dono.example.yaml` com sentinela
+// `pc:placeholder`, no MESMO formato estrutural de `content-carousel/knowledge/dono.example.yaml`
+// (generalizado — sem os campos específicos de carrossel/CTA).
+// ---------------------------------------------------------------------------
+const ESCADA_DE_VOZ_VALUES = new Set(['sem_voz', 'guia_de_estilo', 'dna_completo']);
+
+function donoExampleContent(pod) {
+  return `# dono.example.yaml — forma declarada da configuração de dono do pod \`${pod}\` (ADR-010 + ADR-013).
+# O template NUNCA distribui dado pessoal real: este arquivo é o placeholder.
+# pc:placeholder   <- SENTINELA (ADR-027): enquanto esta marca existir, o arquivo
+#                     ainda NÃO foi personalizado. Apague-a ao preencher de verdade.
+#                     É ela que o oráculo de contenção do framework exige de todo
+#                     arquivo da camada do dono que entra no pacote.
+# Na instância: copie para \`knowledge/dono.yaml\` e preencha. Se \`dono.yaml\` estiver
+# ausente ou ainda igual a este placeholder, o agente ELICITA os dados na 1ª ativação.
+#
+# Gerado por forge-generate.cjs (SF12.4a/ADR-030 Bloco J) — SÓ emissão de placeholder,
+# NUNCA escrita de instância (\`DF-SF12.4-6\`, vinculante).
+dono:
+  nome: "<Nome do Dono>"        # quem assina a peça (nome civil ou de marca)
+  handle: "<@handle>"           # handle do perfil onde a peça é publicada
+  autoridade: "<uma linha factual de enquadramento de autoridade, sem persona nem promessa que o conteúdo não sustente>"
+  # Guia de estilo do dono (ADR-013) — degrau intermediário da escada de voz
+  # (sem voz / GUIA DE ESTILO / DNA completo do dono). Machine-readable.
+  voz:
+    pessoa: "primeira"          # o dono é o AUTOR; NUNCA citado em 3ª pessoa como fonte externa
+    lexico_proibido: ["—", "–"]  # PISO do framework (classe P) — subir é livre, descer exige atribuição explícita
+    tom: "<uma linha: registro e energia da voz do dono, ex.: direto, técnico sem jargão, sem hype>"
+`;
+}
+
+function generatePod(spec, podDir, opts = {}) {
+  // SF12.4a/ADR-030 Bloco O (AC48) — PRIMEIRA checagem, antes de qualquer outra.
+  validateSpecOrigin(opts.specOrigin);
+  const specOrigin = opts.specOrigin;
+  // C.1/SF3.1 — tierOverride INTERCEPTA a classificação: com override presente,
+  // NÃO re-classifica pela spec isolada (que ignoraria o pod existente). O modo
+  // aditivo e o upgrade-in-place SEMPRE passam o tier AGREGADO do disco. Sem
+  // override, comportamento SF1.4 inalterado (classifica pela spec recebida).
+  const tier = opts.tierOverride != null ? opts.tierOverride : classifyTier(spec).tier;
+  const steps = stepsFromSpec(spec);
+  const workflowId = slug(spec.workflowId || spec.pod || 'main');
+  const written = [];
+  const skipped = [];
+
+  // dry-run (SF6.2): computa o PLANO (written[]/skipped[] preenchidos) sem tocar disco.
+  // Requisito da diretiva ADR-004 §2: forge-upgrade-pod em dry-run = zero escrita.
+  const dryRun = Boolean(opts.dryRun);
+  const emit = (file, content) => { if (!dryRun) writeDisk(file, content); };
+
+  // Forma STANDARD-interface (ADR-004 adendo): `interface:true` só é válido com zero
+  // handoff interno. Fail-loud ANTES de qualquer escrita (vale também em dry-run).
+  const isInterface = spec.interface === true;
+  if (isInterface && Number(spec.handoffs || 0) !== 0) {
+    throw new InterfaceContractError(Number(spec.handoffs || 0));
+  }
+  // Memória em SIMPLE é OPCIONAL (SPEC §G2 tabela — "memória opcional", não proibida):
+  // habilitada só sob pedido explícito via flag CLI `--with-memory` (opts.withMemory)
+  // ou campo `spec.memoryOpt: true`. STANDARD/COMPLEX sempre recebe.
+  const withMemory = Boolean(opts.withMemory) || spec.memoryOpt === true;
+
+  // Modo aditivo: `owns[]` (resolvidos a absoluto) são os paths que ESTA linha
+  // possui — regeneráveis; qualquer outro artefato pré-existente é intocável.
+  const additive = Boolean(opts.additive);
+  const ownsSet = new Set((opts.owns || []).map((p) => path.resolve(podDir, p)));
+  const merged = [];
+
+  // SF12.6/ADR-030 Bloco C — leniência POR PATH (Decisão 7.2), forma nua recusada.
+  const allowDivergentOverwrite = validateAllowDivergentOverwrite(opts.allowDivergentOverwrite);
+  const allowSet = new Set(allowDivergentOverwrite.map((p) => path.resolve(p)));
+  const divergent = [];
+  const preserved = [];
+  // Guarda aditiva: existe + não-owned ⇒ colisão (exit 2). Existe + owned ⇒ regenera.
+  const guardCollision = (abs, kind) => {
+    if (!additive) return;
+    if (!fs.existsSync(abs)) return;
+    if (ownsSet.has(path.resolve(abs))) return; // owned → retomada idempotente (regenera determinístico)
+    throw new AdditiveCollisionError(path.relative(podDir, abs), kind);
+  };
+
+  // SF12.4a/ADR-030 Bloco D (AC13) — pré-condição de knowledge ANTES de qualquer escrita.
+  assertKnowledgeExists(steps, podDir);
+
+  // SF12.4a/ADR-030 Blocos C/E/G/H/O (AC7-AC25, AC42-AC44, AC48b/AC48c) — os 3 campos
+  // canônicos (ritmo, contrato_entrada, entregavel). `specOrigin: 'authored'` ⇒ recusa
+  // fail-loud de campo AUSENTE ou malformado, ANTES de qualquer escrita; `'derived'` ⇒
+  // preserva o comportamento atual e reporta o que falta (leniência que FALA).
+  if (specOrigin === 'authored') {
+    for (const field of CANONICAL_FIELDS) readCanonicalField(spec, field, steps);
+  }
+  const canonicalStatus = computeCanonicalStatus(spec);
+
+  // stepExtraFields: stepId -> [{ field, placeholder }] — campos de máquina extras
+  // (Blocos G/H) a injetar no template da etapa-alvo, ANTES de `confianca`.
+  const stepExtraFields = new Map();
+
+  // Bloco G (AC20-22) — contrato_entrada declarado: campo de máquina + veto field_matches.
+  if (canonicalStatus.contrato_entrada.mode === 'declared'
+    && typeof canonicalStatus.contrato_entrada.step === 'string'
+    && Array.isArray(canonicalStatus.contrato_entrada.valores) && canonicalStatus.contrato_entrada.valores.length >= 2) {
+    const { step: targetId, valores } = canonicalStatus.contrato_entrada;
+    const idx = steps.findIndex((s) => s.id === targetId);
+    if (idx === -1) {
+      throw new CanonicalFieldError('contrato_entrada', `referencia a etapa "${targetId}" que não existe entre os ids de stepsFromSpec(spec)`);
+    }
+    const pattern = `^(${valores.map(escapeRegexAlt).join('|')})$`;
+    const baseVeto = (Array.isArray(steps[idx].veto) && steps[idx].veto.length)
+      ? steps[idx].veto
+      : [{ type: 'field_matches', field: 'confianca', pattern: '^(alta|media|baixa)$' }];
+    steps[idx] = {
+      ...steps[idx],
+      veto: [...baseVeto, {
+        type: 'field_matches', field: 'contrato_entrada', pattern,
+        _sources: 'ADR-030 Bloco G (DF-SF12.4-1) — âncora de MÁQUINA do padrão contrato_entrada, declarado na spec (mesma forma de content-carousel/workflows/wf-content-carousel.yaml).',
+      }],
+    };
+    stepExtraFields.set(targetId, [...(stepExtraFields.get(targetId) || []), { field: 'contrato_entrada', placeholder: valores.join('|') }]);
+  }
+
+  // Bloco H (AC23-25) — entregavel declarado: campo de máquina + veto file_referenced_exists.
+  if (canonicalStatus.entregavel.mode === 'declared' && typeof canonicalStatus.entregavel.step === 'string') {
+    const targetId = canonicalStatus.entregavel.step;
+    const idx = steps.findIndex((s) => s.id === targetId);
+    if (idx === -1) {
+      throw new CanonicalFieldError('entregavel', `referencia a etapa "${targetId}" que não existe entre os ids de stepsFromSpec(spec)`);
+    }
+    const baseVeto = (Array.isArray(steps[idx].veto) && steps[idx].veto.length)
+      ? steps[idx].veto
+      : [{ type: 'field_matches', field: 'confianca', pattern: '^(alta|media|baixa)$' }];
+    steps[idx] = {
+      ...steps[idx],
+      veto: [...baseVeto, {
+        type: 'file_referenced_exists', field: 'entregavel',
+        _sources: 'ADR-030 Bloco H (DF-SF12.4-1) — forma GENÉRICA já em produção (automation/wf-n8n-build.yaml:64), declarada na spec.',
+      }],
+    };
+    stepExtraFields.set(targetId, [...(stepExtraFields.get(targetId) || []), { field: 'entregavel', placeholder: 'path/relativo/ao/entregável' }]);
+  }
+
+  // wf — SIMPLE: no máx. 1 workflow mínimo (só se ≥2 etapas; comando/agente único ⇒
+  // nenhum). STANDARD/COMPLEX: sempre. EXCEÇÃO (ADR-004 adendo): pod-interface (zero
+  // handoff interno) NÃO fabrica workflow nem squad-io. Calculado AQUI (hoisted) porque
+  // o Bloco D (injeção de ritmo) e o Bloco I (AC28) precisam dele ANTES de qualquer escrita.
+  const wantsWorkflow = !isInterface && (tier !== TIER_SIMPLE || steps.length >= 2);
+
+  // SF12.6/ADR-030 Bloco D (Decisão 6.3) — a INJEÇÃO de fato (mutação de `steps[idx].checkpoint`
+  // + recusa quando a etapa-alvo não tem checkpoint autorado) já aconteceu dentro de
+  // `stepsFromSpec` (função `injectRitmoSkipModes`, acima) — precisa ser alcançável também
+  // pela rota direta `stepsFromSpec → buildWorkflowYaml`, sem passar por `generatePod` (AC23).
+  // Se chegamos aqui com `canonicalStatus.ritmo.mode === 'declared'` e forma válida, a injeção
+  // JÁ teve sucesso (senão `stepsFromSpec`, chamado no topo desta função, já teria lançado) —
+  // este bloco só ANUNCIA (nunca duplica a regra).
+  const ritmoAnnouncement = (canonicalStatus.ritmo.mode === 'declared'
+    && typeof canonicalStatus.ritmo.step === 'string'
+    && Array.isArray(canonicalStatus.ritmo.skip_modes) && canonicalStatus.ritmo.skip_modes.length)
+    ? `[ritmo] etapa "${canonicalStatus.ritmo.step}" declarou checkpoint.skip_modes ` +
+      `${JSON.stringify(canonicalStatus.ritmo.skip_modes)} — EMITIDO no wf gerado, injetado sobre o ` +
+      'checkpoint JÁ AUTORADO (ADR-030 Bloco D, Decisão 6.3). Registrado em pod-spec.json._canonical_status.ritmo.'
+    : null;
+  if (ritmoAnnouncement) console.log(ritmoAnnouncement);
+
+  // Bloco O (AC48c) — modo `derived`: leniência que FALA, nos 2 modos (dry-run e --apply,
+  // ambos passam por aqui — a checagem não depende de `dryRun`) e mesmo sem pod-spec.json
+  // pré-existente (a spec RECEBIDA é a fonte, nunca leitura de arquivo em disco). SF12.6/
+  // AC27/`DEBT-SF12.5b-B`: quando `spec._<campo>_deferido` está presente (marcador irmão
+  // inerte, mesmo que o campo canônico fique ausente), a mensagem DISCRIMINA "deferido por X"
+  // de "ausente, legado" — não é a mesma frase genérica para os dois casos.
+  if (specOrigin === 'derived') {
+    for (const field of CANONICAL_FIELDS) {
+      if (canonicalStatus[field].mode === 'ausente') {
+        const deferido = spec[`_${field}_deferido`];
+        const razaoOk = deferido && typeof deferido === 'object' && typeof deferido.razao === 'string' && deferido.razao.trim() !== '';
+        if (razaoOk) {
+          console.log(`[specOrigin:derived] campo canônico "${field}" AUSENTE, mas deferido-com-registro: ` +
+            `${deferido.razao}` +
+            (typeof deferido.respondido_por === 'string' && deferido.respondido_por.trim() ? ` (respondido por ${deferido.respondido_por})` : '') +
+            ' — não é esquecimento, é decisão registrada (ADR-030, paga DEBT-SF12.5b-B).');
+        } else {
+          console.log(`[specOrigin:derived] campo canônico ausente no pod pré-existente: "${field}" ` +
+            '(DEBT-SF12.4-B — pod anterior à forma canônica; declare ou recuse quando levá-lo à forma canônica, ADR-030 Emenda 1).');
+        }
+      }
+    }
+  }
+
+  // SF12.4a/ADR-030 Bloco I (AC28) — recusa fail-loud ANTES de qualquer escrita, se algum
+  // veto declarado não é sintetizável (mesma disciplina do Bloco C: um artefato inválido
+  // seria pior que ausente). Só quando o Bloco I de fato vai rodar (`specOrigin:'authored'`
+  // + workflow) — nunca penaliza specs `derived`/sem workflow por um tipo de veto que o
+  // sintetizador não precisa satisfazer.
+  if (specOrigin === 'authored' && wantsWorkflow && steps.length >= 1) {
+    assertSynthesizableVeto(steps);
+  }
+
+  // SF12.6/ADR-030 Bloco C+D — o `wf` é computado UMA VEZ aqui (reusado no write real do
+  // passo (2) abaixo) para poder: (i) auto-validar a PRÓPRIA saída via checkCheckpoint
+  // (AC25/DEBT-SF12.6-E) e (ii) recusar fail-loud ANTES de escrever QUALQUER arquivo do pod
+  // se divergir do disco (AC11) — nem os templates que não divergiam (por isso este bloco
+  // roda ANTES do passo (1)/templates, não junto do passo (2)/workflow).
+  let wfContent = null;
+  const wfPath = (wantsWorkflow && steps.length >= 1)
+    ? path.join(podDir, 'workflows', `wf-${workflowId}.yaml`)
+    : null;
+  if (wfPath) {
+    wfContent = buildWorkflowYaml(workflowId, steps);
+    try {
+      checkCheckpoint(parseWfYaml(wfContent));
+    } catch (e) {
+      throw new CheckpointInvariantError(path.relative(podDir, wfPath), e.message);
+    }
+    // Guard por classe (Decisão 7.1): só sob `specOrigin:'derived'` (regeneração de um pod
+    // já em disco) E path NÃO owned (harden-learning já tem autoridade de escrita mais
+    // estreita e pré-existente via --additive + owns — o guard novo não a reabre).
+    if (specOrigin === 'derived' && !ownsSet.has(path.resolve(wfPath)) && fs.existsSync(wfPath)) {
+      const diskWf = fs.readFileSync(wfPath, 'utf8');
+      if (diskWf !== wfContent) {
+        divergent.push(wfPath);
+        if (!allowSet.has(path.resolve(wfPath)) && !dryRun) {
+          const diskLen = Buffer.byteLength(diskWf, 'utf8');
+          const genLen = Buffer.byteLength(wfContent, 'utf8');
+          throw new DivergentRegenerationError(path.relative(podDir, wfPath), diskLen, genLen, firstDivergentLine(diskWf, wfContent));
+        }
+      }
+    }
+  }
+
+  // (1) templates por etapa — SEMPRE (SIMPLE gera só das 1–2 saídas; a spec já limita a
+  // contagem de agentes de um SIMPLE a ≤2). Disco-first. SF12.6/ADR-030 Bloco C: sob
+  // `specOrigin:'derived'` (e path NÃO owned), um template pré-existente cujo conteúdo
+  // diverge do que seria gerado é PRESERVADO por default (preserved[]) — nunca sobrescrito
+  // numa regeneração (write-once, mesmo regime que generatePod já pratica em 5 outros
+  // lugares — stub de agente, sidecar de smoke, sidecar de cenário, dono.example, README).
+  for (const step of steps) {
+    const tpl = path.join(podDir, 'templates', `${step.id}-tmpl.md`);
+    const tplContent = stepTemplate(step.id, step.agent, step.output, step.sections, step.veto, stepExtraFields.get(step.id));
+    if (specOrigin === 'derived' && !ownsSet.has(path.resolve(tpl)) && fs.existsSync(tpl)) {
+      const diskTpl = fs.readFileSync(tpl, 'utf8');
+      if (diskTpl !== tplContent) {
+        preserved.push(tpl);
+        continue; // preserva-por-default — não sobrescreve conteúdo curado.
+      }
+    }
+    guardCollision(tpl, 'template/step-id'); // colisão de step-id/output fora de owns[] ⇒ exit 2
+    emit(tpl, tplContent);
+    written.push(tpl);
+  }
+
+  // (2) workflow — `wfPath`/`wfContent` já computados acima (hoisted para o Bloco C/D/I).
+  if (wfPath) {
+    guardCollision(wfPath, 'workflowId'); // colisão de workflowId fora de owns[] ⇒ exit 2
+    emit(wfPath, wfContent);
+    written.push(wfPath);
+  } else if (isInterface) {
+    skipped.push('wf/squad-io (pod-interface: zero handoff interno; enforcement do crítico no ciclo pc-*)');
+  } else {
+    skipped.push('workflow (comando/agente único no caminho SIMPLE)');
+  }
+
+  // SF12.4a/ADR-030 Bloco I — o preço do L1: stub de agente (AC26) + sidecar de smoke
+  // sintetizado (AC27/AC27b/AC28). Só quando o pod TEM workflow (é o motor que consome
+  // leitura obrigatória + smoke) E `specOrigin: 'authored'` (Decisão 7/Emenda 1: os
+  // caminhos `derived` — `*upgrade-pod`/`*harden-learning` — PRESERVAM o comportamento
+  // atual; impor a obrigação nova do L1 sobre um pod pré-existente regenerado é
+  // exatamente o risco de regressão que a Decisão 7 existe para evitar — AC49/AC50).
+  // Nunca sobrescreve artefato já existente (mesma guarda do README de memória) —
+  // hand-authored (`*migrate-squad` F2a, `wf-forge.smoke.json`) ou já gerado antes,
+  // preservado byte-a-byte.
+  if (specOrigin === 'authored' && wantsWorkflow && steps.length >= 1) {
+    const distinctAgents = [...new Set(steps.map((s) => s.agent))];
+    for (const agentName of distinctAgents) {
+      const agentPath = path.join(podDir, 'agents', `${agentName}.md`);
+      if (!fs.existsSync(agentPath)) {
+        emit(agentPath, agentStubContent(agentName));
+        written.push(agentPath);
+      }
+    }
+
+    const lastStep = steps[steps.length - 1];
+    const basePath = path.join(podDir, 'workflows', `wf-${workflowId}.smoke.json`);
+    if (!fs.existsSync(basePath)) {
+      // AC28 já foi checado ANTES de qualquer escrita (ver acima, hoisted com `wantsWorkflow`).
+      emit(basePath, `${JSON.stringify(buildSmokeSidecar(steps, lastStep.id), null, 2)}\n`);
+      written.push(basePath);
+    }
+
+    // AC27b — 1 cenário adicional por mecanismo EMITIDO (contrato_entrada/entregavel),
+    // SEMPRE — inclusive quando a etapa-alvo É a última: o sidecar BASE (AC27) quebra a
+    // 1ª assertion da etapa por padrão (âncora L1 genérica), que pode NÃO ser a do
+    // mecanismo; o cenário nomeado do AC27b é o único que GARANTE nomear a assertion do
+    // mecanismo especificamente (AC39/AC40 dependem disso, `target_step` escalar único,
+    // `smoke-pod-workflow.cjs:219`).
+    const mechanismSteps = [];
+    if (canonicalStatus.contrato_entrada.mode === 'declared' && canonicalStatus.contrato_entrada.step) {
+      mechanismSteps.push({ field: 'contrato_entrada', stepId: canonicalStatus.contrato_entrada.step });
+    }
+    if (canonicalStatus.entregavel.mode === 'declared' && canonicalStatus.entregavel.step) {
+      mechanismSteps.push({ field: 'entregavel', stepId: canonicalStatus.entregavel.step });
+    }
+    for (const m of mechanismSteps) {
+      if (!steps.some((s) => s.id === m.stepId)) continue;
+      const scenarioPath = path.join(podDir, 'workflows', `wf-${workflowId}.${m.stepId}.smoke.json`);
+      if (!fs.existsSync(scenarioPath)) {
+        emit(scenarioPath, `${JSON.stringify(buildSmokeSidecar(steps, m.stepId, m.field), null, 2)}\n`);
+        written.push(scenarioPath);
+      }
+    }
+  }
+
+  // (3) squad-io.yaml — SÓ STANDARD/COMPLEX NÃO-interface (SIMPLE e interface não
+  // recebem contrato de handoff). SF12.6/ADR-030 Bloco C (Decisão 7.1, classe
+  // squad-io.yaml → sempre-merge): squad-io pré-existente NUNCA é colisão nem
+  // sobrescrita — SEMPRE faz MERGE por seção (C.2) quando o arquivo já existe, em
+  // QUALQUER modo (a exigência de `additive:true` foi removida — `*upgrade-pod` nunca
+  // passava `additive`, e por isso squad-io era sobrescrito incondicionalmente numa
+  // regeneração, AC15).
+  if (tier !== TIER_SIMPLE && !isInterface) {
+    const io = path.join(podDir, 'squad-io.yaml');
+    const content = buildSquadIo(spec.pod || workflowId, steps);
+    // squad-io é POD-GLOBAL (agrega handoffs de TODOS os workflows). Merge é idempotente
+    // (união dedup), seguro na retomada — nunca perde os handoffs/seções de outros workflows
+    // nem conteúdo customizado hand-authored fora do gerador.
+    if (fs.existsSync(io)) {
+      emit(io, mergeSquadIo(fs.readFileSync(io, 'utf8'), content));
+      merged.push(io);
+    } else {
+      emit(io, content);
+      written.push(io);
+    }
+  } else if (!isInterface) {
+    skipped.push('squad-io.yaml (SIMPLE não recebe contrato de handoff)');
+  } // isInterface: wf+squad-io já cobertos pela mensagem combinada em (2).
+
+  // (4) MEMÓRIA OPERANTE proporcional ao tier (SF2.3, SPEC §G1/§G2). Substitui o
+  // scaffold morto da SF1.4: a fábrica INSTALA a memória usando o MOTOR REAL
+  // (pod-memory.cjs, SF2.1) — não hand-escreve um cabeçalho. O pod NASCE cabeado ao
+  // mecanismo que o runner (SF2.2) consome: o consolidado fica no path canônico
+  // (`memory/learnings.consolidated.md`, lido por getConsolidatedForBrief) e o log cru
+  // (`memory/learnings.jsonl`) já existe para o append da run. "Operância" = o pod está
+  // corretamente ligado ao motor pronto — nenhuma ação manual entre gerar e rodar.
+  //   STANDARD/COMPLEX → sempre. SIMPLE → só sob pedido explícito (withMemory).
+  if (tier !== TIER_SIMPLE || withMemory) {
+    written.push(...installMemory(spec.pod || workflowId, podDir, tier, { additive, dryRun }));
+  } else {
+    skipped.push('memória (SIMPLE sem --with-memory/spec.memoryOpt — opcional, não gerada)');
+  }
+
+  // SF12.4a/ADR-030 Bloco J (AC29-32) — camada do dono, SÓ placeholder, quando
+  // `escada_de_voz` indica pod de CONTEÚDO (qualquer valor ≠ "sem_voz"/ausente).
+  // NUNCA escreve instância (`dono.yaml`) — `DF-SF12.4-6`, vinculante.
+  const escadaDeVoz = ESCADA_DE_VOZ_VALUES.has(spec.escada_de_voz) ? spec.escada_de_voz : 'sem_voz';
+  if (escadaDeVoz !== 'sem_voz') {
+    const donoPath = path.join(podDir, 'knowledge', 'dono.example.yaml');
+    if (!fs.existsSync(donoPath)) {
+      emit(donoPath, donoExampleContent(spec.pod || workflowId));
+      written.push(donoPath);
+    }
+  }
+
+  // SF12.4a/ADR-030 Bloco F (AC18-19) — pod-spec.json persistido na raiz do pod (fonte
+  // da verdade, ADR-005; generalização da persistência que `*harden-learning` já fazia).
+  // `_canonical_status` torna a recusa/anúncio/relato AUDITÁVEL por grep no artefato.
+  if (!dryRun) {
+    const specDest = path.join(podDir, 'pod-spec.json');
+    const persisted = { ...spec, _canonical_status: canonicalStatus };
+    emit(specDest, `${JSON.stringify(persisted, null, 2)}\n`);
+    written.push(specDest);
+  }
+
+  return { tier, workflowId, steps, written, skipped, merged, divergent, preserved, canonicalStatus, ritmoAnnouncement };
+}
+
+/**
+ * Instala a memória OPERANTE do pod usando o motor real pod-memory.cjs (SF2.1).
+ * Cria o log cru vazio e materializa o consolidado canônico via `consolidate()` — o
+ * mesmo caminho que o lifecycle usa em produção, provando que o pod está cabeado ao
+ * motor (não a um cabeçalho morto). Idempotente. Retorna os paths gravados.
+ */
+function installMemory(pod, podDir, tier, opts = {}) {
+  const additive = Boolean(opts.additive);
+  const dryRun = Boolean(opts.dryRun);
+  const paths = podMemory.memoryPaths(pod, { podDir });
+  const readme = path.join(paths.dir, 'README.md');
+  // dry-run (SF6.2): retorna o PLANO (paths que SERIAM gravados) sem tocar disco.
+  if (dryRun) return [paths.raw, paths.consolidated, readme];
+  fs.mkdirSync(paths.dir, { recursive: true });
+  // Log cru vazio (append-only, alimentado pelo runner). Não sobrescreve se já existir
+  // (upgrade-in-place preserva histórico da SF2.1 — o runner é o único escritor).
+  if (!fs.existsSync(paths.raw)) fs.writeFileSync(paths.raw, '');
+  // Consolidado canônico via o MOTOR. No modo aditivo, um consolidado JÁ EXISTENTE é
+  // PRESERVADO byte-a-byte (a migração NUNCA escreve na memória do pod destino, ADR-006
+  // §F; o critério de integridade compara sha256 de learnings.jsonl+.consolidated.md).
+  if (!(additive && fs.existsSync(paths.consolidated))) podMemory.consolidate(pod, { podDir });
+  // Marcador de cabeamento. GUARD DE EXISTÊNCIA (M2, fecha o furo do sobrescrever
+  // incondicional): README pré-existente NÃO é sobrescrito — preserva conteúdo curado.
+  if (!fs.existsSync(readme)) fs.writeFileSync(readme, memoryWiringNote(pod, tier));
+  return [paths.raw, paths.consolidated, readme];
+}
+
+/** Nota de cabeamento da memória — prova documental de operância (SF2.3). */
+function memoryWiringNote(pod, tier) {
+  return `# Memória do pod \`${pod}\` — OPERANTE (SF2.3)
+
+> Instalada por forge-generate.cjs via o motor \`scripts/pod-memory.cjs\` (SF2.1).
+> Tier: ${tier}. Esta memória NÃO é scaffold morto: nasce cabeada ao lifecycle.
+
+## Cabeamento (nenhuma ação manual necessária)
+
+- \`learnings.jsonl\` — log cru append-only. O runner (\`pc-run-pod\`, SF2.2) faz \`append()\`
+  ao fim de cada etapa/run. O AGENTE NUNCA lê este arquivo (auditoria apenas).
+- \`learnings.consolidated.md\` — top-N curado (\`consolidate()\`), no path canônico que
+  \`getConsolidatedForBrief()\` entrega ao brief da run. É o ÚNICO que o agente lê.
+- Auditoria de aderência por run: \`config/heuristic-watcher-rubric.yaml\` +
+  \`scripts/watcher-audit.cjs\` (executado pelo \`pod-critic\`).
+
+Assim que este pod rodar via \`pc-run-pod\`, injeção do consolidado no brief e append de
+learnings funcionam sem qualquer passo manual — a operância é o cabeamento ao motor pronto.
+`;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  let out = null;
+  let withMemory = false;
+  let additive = false;
+  const owns = [];
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--out') out = args[++i];
+    else if (args[i] === '--with-memory') withMemory = true;
+    else if (args[i] === '--additive') additive = true;
+    else if (args[i] === '--owns') owns.push(...String(args[++i]).split(','));
+    else rest.push(args[i]);
+  }
+  if (!rest[0] || !out) {
+    console.error('Uso: node scripts/forge-generate.cjs <pod-spec.json> --out <podDir> [--with-memory] [--additive] [--owns p1,p2]');
+    process.exit(2);
+  }
+  const spec = JSON.parse(fs.readFileSync(rest[0], 'utf8'));
+  let r;
+  try {
+    // SF12.4a/ADR-030 Bloco O (AC48) — o CLI é SEMPRE 'authored', incondicional: serve
+    // `*new` (sem flag) E `*migrate-squad` F2b (`--additive`). `--additive` governa só a
+    // guarda de colisão (ortogonal) — NÃO muda `specOrigin`.
+    r = generatePod(spec, path.resolve(out), { withMemory, additive, owns, specOrigin: 'authored' });
+  } catch (e) {
+    console.error(`[erro] ${e.message}`);
+    process.exit(e && e.exitCode ? e.exitCode : 1);
+  }
+  console.log(`tier: ${r.tier}`);
+  console.log('artefatos gravados (disco-first):');
+  for (const w of r.written) console.log(`  + ${path.relative(process.cwd(), w)}`);
+  if (r.merged && r.merged.length) {
+    console.log('merge aditivo (seções preservadas + novas):');
+    for (const m of r.merged) console.log(`  ~ ${path.relative(process.cwd(), m)}`);
+  }
+  if (r.skipped.length) {
+    console.log('não gerados (proporcionalidade):');
+    for (const s of r.skipped) console.log(`  - ${s}`);
+  }
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  generatePod, installMemory, stepsFromSpec, buildWorkflowYaml, buildSquadIo, slug, stepTemplate,
+  countGteNote, countGteFields, serializeAssertion, serializeCheckpoint, mergeSquadIo,
+  extractHandoffTriples, splitTopSections, AdditiveCollisionError, InterfaceContractError,
+  // SF12.4a/ADR-030
+  SpecOriginError, CanonicalFieldError, KnowledgeFileMissingError, UnsynthesizableVetoError,
+  validateSpecOrigin, readCanonicalField, computeCanonicalStatus, CANONICAL_FIELDS,
+  deriveFieldMatchesValue, synthesizeArtifactText, buildSmokeSidecar, agentStubContent,
+  donoExampleContent, ESCADA_DE_VOZ_VALUES, assertKnowledgeExists, assertSynthesizableVeto,
+  // SF12.6/ADR-030 Bloco C/D
+  DivergentRegenerationError, AllowDivergentOverwriteError, CheckpointInvariantError,
+  validateAllowDivergentOverwrite, validateCanonicalStepRef, firstDivergentLine,
+};