@daniellins/power-claude 0.16.3

package/scripts/forge-harden-learning.cjs

@@ -0,0 +1,921 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * forge-harden-learning.cjs — `*harden-learning`: promove UMA heurística do consolidado
+ * de memória de um pod a FORMA CANÔNICA do pod — Story SF7.6, ADR-012 (Decisões 6 e 7);
+ * 2º alvo (knowledge) em SF10.10, ADR-012 Adendo SF10.10 (DF-SF10.10-1 a -6).
+ *
+ * DOIS ALVOS DE PROMOÇÃO (`--target-type`):
+ *   veto      (default) → veto.assertion no wf-*.yaml (enforcement do runner, SF7.6)
+ *   knowledge (SF10.10) → knowledge canônico do pod (prosa que o export recebe cru)
+ * + modo read-only `--list-candidates` (detecção, DF-SF10.10-3).
+ *
+ * Caso motivador (benchmark 4-braços, R5): a heurística "evitar travessões" foi injetada
+ * no brief via memória evolutiva e AINDA ASSIM regrediu — memória é sugestão, não
+ * enforcement. Este motor fecha o degrau aprender→impor: a heurística vira bloqueio
+ * físico do runner (veto existente `count_gte`/`field_matches`/... ou `command_check`
+ * blessed da SF7.2, ex.: lexical-check para travessões).
+ *
+ * FRONTEIRAS (vinculantes):
+ *  - A TRADUÇÃO heurística→forma de veto é JULGAMENTO HUMANO: a asserção entra como
+ *    ARGUMENTO (--assertion), nunca derivada de prosa por LLM (Escopo OUT da story).
+ *  - Aprovação do dono OBRIGATÓRIA: --approved-by <nome> (padrão migration-manifest);
+ *    sem ela a promoção NÃO aplica (exit 2 explícito, nunca silencioso).
+ *  - Regeneração via forge-generate `--additive` + owns (mecanismo provado por
+ *    *migrate-squad F2b): edita pod-spec.json (fonte declarada da verdade, ADR-005) e
+ *    reemite o workflow-alvo; `agents/` NUNCA é tocado (forge-generate não escreve lá).
+ *  - Prova de preservação: validate-pod-workflow + smoke 4/4 ANTES e DEPOIS; diff do wf
+ *    confinado à etapa-alvo — qualquer mudança fora dela ⇒ ROLLBACK + exit 2.
+ *  - Marcação append-only na memória: {type:"hardening", ref, target, approved_by,
+ *    timestamp} (pod-memory.appendHardening); consolidate anota 🔒 e DEMOVE do top-N
+ *    ativo (enforcement substitui injeção) — a heurística NUNCA é removida do log.
+ *
+ * ALVO `knowledge` (SF10.10) — FRONTEIRAS ADICIONAIS (vinculantes):
+ *  - A REDAÇÃO do knowledge é do dono: o conteúdo novo entra por `--content <arquivo>`
+ *    (proposto/revisado por humano). Este motor NUNCA gera prosa.
+ *  - Prova de PRESERVAÇÃO (DF-SF10.10-2): baseline antes (validate + smoke 4/4);
+ *    CONFINAMENTO de escrita a 3 paths (knowledge/<file>, memory/learnings.jsonl,
+ *    memory/learnings.consolidated.md) com rollback fora deles; scanClone (regras 1-3)
+ *    verde sobre o alvo depois; paridade de `per_file_sha` via pod-export-compile
+ *    quando o pod é export-capaz (senão `export_check: n/a`, declarado).
+ *  - SEM smoke "depois": omitido POR DECISÃO e com o motivo registrado — nenhum
+ *    caminho de runtime lê `knowledge/*.md` (zero ocorrência em smoke-pod-workflow.cjs
+ *    e pc-run-pod.cjs), logo o smoke é VERDE POR CONSTRUÇÃO para este alvo; mantê-lo
+ *    seria gate que não pode falhar (ilusão de cobertura).
+ *  - Prova de QUALIDADE: NÃO EXISTE em máquina. Nenhum gate deste mecanismo julga se a
+ *    prosa ficou melhor. O único portão de qualidade é `--approved-by`.
+ *
+ * Uso:
+ *   # alvo veto (SF7.6)
+ *   node scripts/forge-harden-learning.cjs <podDir> \
+ *     --learning <id-da-entrada-no-learnings.jsonl> \
+ *     --step <stepId-do-workflow> \
+ *     --assertion '<json da veto.assertion>' \
+ *     --approved-by <nome> \
+ *     [--workflow <workflowId>]   (default: workflowId do pod-spec.json)
+ *
+ *   # alvo knowledge (SF10.10)
+ *   node scripts/forge-harden-learning.cjs <podDir> --target-type knowledge \
+ *     --learning <id> --file <knowledge/arquivo.md> --content <arquivo-novo.md> \
+ *     --approved-by <nome> [--pins <pins.json>]
+ *
+ *   # detecção (read-only, exit 0 sempre)
+ *   node scripts/forge-harden-learning.cjs <podDir> --list-candidates
+ *
+ * Exit: 0 promoção aplicada e provada (ou listagem) · 2 recusa (aprovação ausente,
+ *       learning/step/arquivo inexistente, asserção inválida, knowledge não declarado
+ *       no wf, baseline vermelho, pós-gate vermelho→rollback, diff fora do alvo→
+ *       rollback, budget estourado→rollback, já endurecida) · 1 erro de uso/interno.
+ *
+ * Node >= 18, sem dependências externas.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+const podMemory = require('./pod-memory.cjs');
+const { generatePod, stepsFromSpec, slug } = require('./forge-generate.cjs');
+const { VETO_TYPES, parseYaml } = require('./validate-pod-workflow.cjs');
+const { scanClone, deriveDenylist } = require('./validate-no-clone.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const VETO_CHECKS_ROOT = path.join(REPO_ROOT, 'scripts', 'veto-checks');
+
+// DF-SF10.10-2 item 6 — dito com todas as letras no --help, na SAÍDA do comando e no
+// doc de mecanismo. Não há eufemismo aqui: a máquina prova confinamento, o humano
+// prova qualidade, e nenhum dos dois finge ser o outro.
+const QUALITY_NOTICE =
+  'Nenhum gate deste mecanismo julga se a prosa ficou melhor. O único portão de qualidade ' +
+  'é a revisão humana registrada em `--approved-by` sobre o diff proposto.';
+
+// DF-SF10.10-2 item 2 — o motivo da AUSÊNCIA do smoke "depois", impresso no relatório
+// (omissão declarada, nunca silenciosa).
+const NO_SMOKE_AFTER_NOTICE =
+  'sem smoke "depois": omitido POR DECISÃO (DF-SF10.10-2) — nenhum caminho de runtime lê ' +
+  'knowledge/*.md (zero ocorrência em smoke-pod-workflow.cjs/pc-run-pod.cjs), logo seria ' +
+  'VERDE POR CONSTRUÇÃO: prova vacuosa não é prova.';
+
+const USAGE_LINES = [
+  'Uso:',
+  '  # alvo veto (SF7.6) — promove heurística a enforcement físico do runner',
+  '  node scripts/forge-harden-learning.cjs <podDir> --learning <id> --step <stepId> \\',
+  "      --assertion '<json>' --approved-by <nome> [--workflow <id>]",
+  '',
+  '  # alvo knowledge (SF10.10) — promove heurística a knowledge canônico do pod',
+  '  node scripts/forge-harden-learning.cjs <podDir> --target-type knowledge \\',
+  '      --learning <id> --file <knowledge/arquivo.md> --content <arquivo-com-o-conteudo-novo> \\',
+  '      --approved-by <nome> [--pins <pins.json>]',
+  '',
+  '  # detecção de candidatos (read-only, exit 0 sempre, nunca promove)',
+  '  node scripts/forge-harden-learning.cjs <podDir> --list-candidates',
+  '',
+  `QUALIDADE (alvo knowledge): ${QUALITY_NOTICE}`,
+];
+
+function usage(msg) {
+  if (msg) console.error(`[erro] ${msg}`);
+  for (const l of USAGE_LINES) console.error(l);
+  process.exit(1);
+}
+
+function help() {
+  for (const l of USAGE_LINES) console.log(l);
+}
+
+function refuse(msg) {
+  console.error(`[recusa] ${msg}`);
+  process.exit(2);
+}
+
+function argVal(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+function run(cmdArgs, label) {
+  // O 1º argumento é sempre um script DESTE repo: resolve contra REPO_ROOT em vez do
+  // cwd — o pod-alvo pode viver em outro repositório (cross-repo por path, padrão D6
+  // do ADR-018) e o motor precisa achar os próprios gates de qualquer cwd.
+  const [script, ...rest] = cmdArgs;
+  const abs = path.isAbsolute(script) ? script : path.join(REPO_ROOT, script);
+  const r = spawnSync(process.execPath, [abs, ...rest], { encoding: 'utf8' });
+  return { label, status: r.status, out: `${r.stdout || ''}${r.stderr || ''}` };
+}
+
+/** Valida a FORMA da asserção proposta (o conteúdo é julgamento humano revisado). */
+function checkAssertionShape(assertion) {
+  if (!assertion || typeof assertion !== 'object' || Array.isArray(assertion)) {
+    refuse('--assertion deve ser um objeto JSON (a veto.assertion proposta pelo dono)');
+  }
+  const required = VETO_TYPES[assertion.type];
+  if (!required) {
+    refuse(
+      `--assertion type "${assertion.type}" não é uma forma suportada (${Object.keys(VETO_TYPES).join(', ')})`,
+    );
+  }
+  for (const k of required) {
+    if (!(k in assertion)) refuse(`--assertion (${assertion.type}) exige o campo "${k}"`);
+  }
+  if (assertion.type === 'command_check') {
+    const cmd = String(assertion.command || '');
+    if (/[\\/]/.test(cmd) || cmd.includes('..') || !/\.(cjs|js)$/.test(cmd)) {
+      refuse(`command_check: "${cmd}" não é nome simples de script blessed (.cjs/.js sob scripts/veto-checks/)`);
+    }
+    if (!fs.existsSync(path.join(VETO_CHECKS_ROOT, cmd))) {
+      refuse(`command_check: script blessed inexistente: scripts/veto-checks/${cmd}`);
+    }
+    if ('args' in assertion) {
+      if (!Array.isArray(assertion.args) || assertion.args.some((a) => typeof a !== 'string')) {
+        refuse('command_check: "args" deve ser um array de strings literais');
+      }
+      if (assertion.args.some((a) => /[`$]|\{\{|\$\(/.test(a))) {
+        refuse('command_check: "args" não pode conter template/interpolação/shell');
+      }
+    }
+  }
+}
+
+/** Assinatura estável de uma asserção (dedup — ignora _sources). */
+function assertionSig(a) {
+  const clean = {};
+  for (const k of Object.keys(a).sort()) {
+    if (k.startsWith('_')) continue;
+    clean[k] = a[k];
+  }
+  return JSON.stringify(clean);
+}
+
+/** Quebra o texto do wf em { header, blocks: Map<stepId, texto> } (blocos `- id:`). */
+function splitWfBlocks(text) {
+  const lines = String(text).split('\n');
+  const header = [];
+  const blocks = new Map();
+  let cur = null;
+  for (const line of lines) {
+    const m = line.match(/^  - id:\s*(\S+)\s*$/);
+    if (m) {
+      cur = m[1];
+      blocks.set(cur, [line]);
+      continue;
+    }
+    if (cur) blocks.get(cur).push(line);
+    else header.push(line);
+  }
+  return { header: header.join('\n'), blocks };
+}
+
+// ── comum aos dois alvos: localizar a heurística e exigi-la no consolidado ───
+/**
+ * Acha a entrada-fonte no log cru, consolida ANTES (estado curado fresco) e recusa se
+ * a heurística já está endurecida (🔒) ou não está no consolidado curado. Idêntico
+ * para os dois alvos: promoção é sempre DE uma heurística consolidada.
+ */
+function resolveLearning(pod, podDir, learningId) {
+  const memPaths = podMemory.memoryPaths(pod, { podDir });
+  if (!fs.existsSync(memPaths.raw)) refuse(`memória não encontrada: ${memPaths.raw}`);
+  const rawLines = fs.readFileSync(memPaths.raw, 'utf8').split('\n').filter(Boolean);
+  const entries = rawLines.map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  const entry = entries.find((e) => e.id === learningId && e.type !== podMemory.TYPE_HARDENING);
+  if (!entry) refuse(`learning "${learningId}" não encontrado em ${memPaths.raw}`);
+  const ref = podMemory.dedupKey(entry);
+
+  // consolida ANTES para decidir sobre o estado curado atual (top-N fresco)
+  podMemory.consolidate(pod, { podDir });
+  // SF11.4/ADR-022 (DF-SF11.4-5) — as duas checagens abaixo passam a ler DADO
+  // ESTRUTURADO (o mesmo conjunto curado que o motor acabou de escrever), não string do
+  // artefato RENDERIZADO. Duas razões, nesta ordem:
+  //   1. OBRIGATÓRIO junto de DF-SF11.4-1: a seção 🔒 virou referência AGREGADA, então
+  //      a string antiga (`🔒 **[trigger]**`) não existe mais no consolidado — mantê-la
+  //      seria regressão SILENCIOSA (a mesma heurística promovida duas vezes sem recusa).
+  //   2. RESTRIÇÃO NÃO-DOCUMENTADA REMOVIDA: a checagem antiga era por `trigger`
+  //      APENAS, então DUAS heurísticas legítimas e distintas com o mesmo trigger não
+  //      podiam ambas ser promovidas — a segunda era recusada mesmo sendo conteúdo novo.
+  //      Isso bloqueou uma promoção real (2026-08-01/02) e foi contornado RENOMEANDO o
+  //      trigger da segunda ("compor a capa" → "titular capa") — gambiarra de
+  //      nomenclatura, registrada como achado lateral 1 da Story SF11.4. A chave correta
+  //      é `dedupKey` (trigger + recommendation), a MESMA que o motor usa para dedup e
+  //      para casar registro de hardening ↔ heurística.
+  const { pins, ranked, hardenedRefs } = podMemory.computeConsolidation(pod, { podDir });
+  if (hardenedRefs.has(ref)) {
+    refuse(`learning "${learningId}" já está endurecido (registro 🔒 com ref "${ref}") — nada a promover`);
+  }
+  const curated = new Set([...pins, ...ranked].map((m) => podMemory.dedupKey(m)));
+  if (!curated.has(ref)) {
+    refuse(`learning "${learningId}" não está no consolidado curado (top-N/pinado) — o hardening promove heurística DO CONSOLIDADO (story SF7.6); consolide/cure antes`);
+  }
+  return { entry, ref, memPaths };
+}
+
+// ── ALVO `knowledge` (SF10.10) — helpers ─────────────────────────────────────
+
+function sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/** Identidade do pod para os dois alvos: spec quando existe, basename como fallback. */
+function podIdentity(podDir, args) {
+  const specPath = path.join(podDir, 'pod-spec.json');
+  let spec = null;
+  if (fs.existsSync(specPath)) {
+    try {
+      spec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+    } catch (e) {
+      refuse(`pod-spec.json inválido: ${e.message}`);
+    }
+  }
+  const pod = (spec && spec.pod) || path.basename(path.resolve(podDir));
+  const workflowId = slug(argVal(args, '--workflow') || (spec && (spec.workflowId || spec.pod)) || pod);
+  return { spec, pod, workflowId };
+}
+
+/**
+ * Normaliza `--file` para o NOME SIMPLES sob `knowledge/` e recusa qualquer forma que
+ * escape do diretório (path traversal, path absoluto, subdiretório). 1ª barreira do
+ * confinamento — a 2ª é a verificação de escrita pós-aplicação.
+ */
+function normalizeKnowledgeFile(raw) {
+  let f = String(raw == null ? '' : raw).trim().replace(/\\/g, '/');
+  if (f.startsWith('./')) f = f.slice(2);
+  if (f.startsWith('knowledge/')) f = f.slice('knowledge/'.length);
+  if (!f) refuse('--file <arquivo> é obrigatório no alvo knowledge (nome sob knowledge/, ex.: slides-html.md)');
+  if (path.isAbsolute(f) || f.includes('/') || f.includes('..')) {
+    refuse(
+      `--file ${JSON.stringify(String(raw))} deve ser um nome SIMPLES sob knowledge/ (sem path, sem "..") — ` +
+        'o alvo knowledge escreve EXCLUSIVAMENTE dentro de <podDir>/knowledge/',
+    );
+  }
+  if (!/\.md$/i.test(f)) refuse(`--file "${f}": o alvo knowledge só edita arquivos .md declarados no wf`);
+  return f;
+}
+
+/** Nomes de knowledge DECLARADOS no wf (knowledge: de qualquer etapa + knowledge_exclude:). */
+function declaredKnowledge(wfPath) {
+  let doc;
+  try {
+    doc = parseYaml(fs.readFileSync(wfPath, 'utf8'));
+  } catch (e) {
+    refuse(`workflow ilegível (${wfPath}): ${e.message}`);
+  }
+  const declared = new Set();
+  for (const k of Array.isArray(doc.knowledge_exclude) ? doc.knowledge_exclude : []) declared.add(String(k));
+  for (const step of Array.isArray(doc.steps) ? doc.steps : []) {
+    for (const k of Array.isArray(step.knowledge) ? step.knowledge : []) declared.add(String(k));
+  }
+  return declared;
+}
+
+/**
+ * CONTAINMENT POR REALPATH — mesmo padrão do Guard B de `command_check`
+ * (`pc-run-pod.cjs`) e do `confineToRunDir` de `pod-export-ui.cjs` (SF10.9): o guard
+ * lexical (`path.resolve`) NÃO enxerga symlink. Quando o caminho — ou o ancestral
+ * existente mais próximo — resolve em disco, o realpath TEM que permanecer sob o
+ * realpath da raiz; senão RECUSA antes de qualquer escrita.
+ */
+function assertRealpathUnder(realRoot, abs, label) {
+  let probe = path.resolve(abs);
+  for (;;) {
+    let real;
+    try {
+      real = fs.realpathSync(probe);
+    } catch {
+      const parent = path.dirname(probe);
+      if (parent === probe || parent.length < realRoot.length) return; // nada existe ainda
+      probe = parent;
+      continue;
+    }
+    if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+      refuse(
+        `${label}: "${abs}" resolve (realpath) para FORA de ${realRoot} — symlink/traversal para "${real}". ` +
+          'A escrita cairia fora do pod e o diff de confinamento seria CEGO (Dirent de symlink não é isFile()).',
+      );
+    }
+    return;
+  }
+}
+
+/**
+ * Snapshot recursivo (relpath posix → conteúdo) — base do confinamento e do rollback.
+ * Symlinks são REGISTRADOS (tipo + destino), não ignorados: um Dirent de link não é
+ * `isFile()`, e pulá-lo tornava o diff cego a link criado/alterado/removido sob o
+ * podDir. Registrado, qualquer mexida em link vira violação como qualquer outra.
+ * (O guard que impede ESCRITA ATRAVÉS de um link pré-existente é `assertRealpathUnder`,
+ * aplicado aos 3 paths deste modo ANTES de escrever — este snapshot não substitui aquele.)
+ */
+function snapshotDir(root) {
+  const out = new Map();
+  const walk = (dir) => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+      const abs = path.join(dir, e.name);
+      const rel = path.relative(root, abs).split(path.sep).join('/');
+      if (e.isSymbolicLink()) out.set(rel, Buffer.from(`symlink → ${fs.readlinkSync(abs)}`));
+      else if (e.isDirectory()) walk(abs);
+      else if (e.isFile()) out.set(rel, fs.readFileSync(abs));
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * PURA (testável isoladamente): caminhos criados/alterados/removidos entre dois
+ * snapshots que NÃO estão no conjunto permitido. Este é o análogo real, para o alvo
+ * knowledge, do "diff confinado à etapa-alvo" do alvo veto (DF-SF10.10-2 item 3).
+ * @returns {string[]} ex.: ['~ workflows/wf-x.yaml', '+ templates/novo.md']
+ */
+function confinementViolations(before, after, allowedRels) {
+  const allowed = new Set(allowedRels);
+  const changed = [];
+  for (const [rel, buf] of after) {
+    const prev = before.get(rel);
+    if (prev == null) changed.push(`+ ${rel}`);
+    else if (!prev.equals(buf)) changed.push(`~ ${rel}`);
+  }
+  for (const rel of before.keys()) if (!after.has(rel)) changed.push(`- ${rel}`);
+  return changed.filter((c) => !allowed.has(c.slice(2))).sort();
+}
+
+/** Restaura o diretório ao estado do snapshot (bytes idênticos; extras removidos). */
+function restoreSnapshot(root, snap) {
+  const now = snapshotDir(root);
+  for (const rel of now.keys()) {
+    if (!snap.has(rel)) fs.rmSync(path.join(root, rel), { force: true });
+  }
+  for (const [rel, buf] of snap) {
+    const abs = path.join(root, rel);
+    const cur = now.get(rel);
+    if (cur == null || !cur.equals(buf)) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, buf);
+    }
+  }
+}
+
+/**
+ * Pins do pod (export-capacidade). Ordem: `--pins` explícito, `<podDir>/pins.json`,
+ * `exports/<pod>/pins.json` (local canônico que o compilador usa). Ausente ⇒ null,
+ * e o relatório grava `export_check: "n/a"` — DECLARADO, nunca pulado em silêncio.
+ */
+function findPins(podDir, podName, args) {
+  const explicit = argVal(args, '--pins');
+  if (explicit) {
+    const abs = path.resolve(explicit);
+    if (!fs.existsSync(abs)) refuse(`--pins não encontrado: ${abs}`);
+    return abs;
+  }
+  const inPod = path.join(podDir, 'pins.json');
+  if (fs.existsSync(inPod)) return inPod;
+  const canonical = path.join(REPO_ROOT, 'exports', podName, 'pins.json');
+  return fs.existsSync(canonical) ? canonical : null;
+}
+
+/** Compila o pod em diretório temporário e devolve o lock (sem tocar exports/ real). */
+function compileLock(podDir, pinsPath, label) {
+  const outRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harden-compile-'));
+  const lockPath = path.join(outRoot, 'export.lock.json');
+  const r = run([
+    'scripts/pod-export-compile.cjs', 'compile', path.resolve(podDir),
+    '--no-endpoint-check', '--pins', pinsPath,
+    '--out', path.join(outRoot, 'bundle'), '--lock-out', lockPath,
+  ], label);
+  let lock = null;
+  if (fs.existsSync(lockPath)) lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  fs.rmSync(outRoot, { recursive: true, force: true });
+  return { ...r, lock };
+}
+
+/** PURA: chaves de per_file_sha que diferem entre dois locks (criadas/removidas/alteradas). */
+function perFileShaDiff(lockBefore, lockAfter) {
+  const a = (lockBefore && lockBefore.per_file_sha) || {};
+  const b = (lockAfter && lockAfter.per_file_sha) || {};
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  return [...keys].filter((k) => a[k] !== b[k]).sort();
+}
+
+// ── ALVO `knowledge` (SF10.10) — promoção ────────────────────────────────────
+function hardenKnowledge(args) {
+  const podDir = args[0];
+  const learningId = argVal(args, '--learning');
+  const fileArg = argVal(args, '--file');
+  const contentArg = argVal(args, '--content');
+  const approvedBy = argVal(args, '--approved-by');
+
+  if (!learningId) usage('--learning <id> é obrigatório (id da entrada no learnings.jsonl)');
+  if (!fileArg || fileArg.startsWith('--')) usage('--file <arquivo> é obrigatório (knowledge-alvo, ex.: slides-html.md)');
+  if (!contentArg || contentArg.startsWith('--')) {
+    usage('--content <arquivo> é obrigatório — o conteúdo NOVO do knowledge é proposto/revisado pelo HUMANO; ' +
+      'este motor nunca gera prosa (ADR-012 §Escopo OUT)');
+  }
+  // aprovação do dono OBRIGATÓRIA — recusa explícita, nunca aplica sem ela.
+  if (!approvedBy || approvedBy.startsWith('--')) {
+    refuse('promoção exige --approved-by <nome> (aprovação humana registrada — padrão migration-manifest); sem ela NADA é aplicado. ' +
+      QUALITY_NOTICE);
+  }
+
+  const file = normalizeKnowledgeFile(fileArg);
+  const { pod, workflowId } = podIdentity(podDir, args);
+  const wfPath = path.join(podDir, 'workflows', `wf-${workflowId}.yaml`);
+  if (!fs.existsSync(wfPath)) refuse(`workflow-alvo não encontrado: ${wfPath}`);
+  const smokePath = wfPath.replace(/\.ya?ml$/, '.smoke.json');
+  if (!fs.existsSync(smokePath)) {
+    refuse(`cenário de smoke não encontrado: ${smokePath} — o BASELINE do alvo knowledge é validate + smoke 4/4 verdes (guarda de pod quebrado, DF-SF10.10-2 item 1); autore o sidecar primeiro`);
+  }
+
+  // ── (AC9/DF-SF10.10-5) knowledge DECLARADO no wf — precondição barata, lida
+  // direto do wf. v1 só EDITA knowledge já declarado; CRIAR é outro raio de
+  // explosão (arrasta wf/spec + regeneração) e está fora de escopo (DEBT-SF10.10-C).
+  const declared = declaredKnowledge(wfPath);
+  if (!declared.has(file)) {
+    refuse(
+      `"${file}" não está declarado em knowledge:/knowledge_exclude: de nenhuma etapa de ${path.relative(process.cwd(), wfPath)} ` +
+        `(declarados: ${[...declared].sort().join(', ') || 'nenhum'}). O alvo knowledge v1 só EDITA knowledge já declarado — ` +
+        'criar knowledge novo exige editar o wf/spec e regenerar (fora de escopo, DEBT-SF10.10-C).',
+    );
+  }
+
+  const targetAbs = path.join(podDir, 'knowledge', file);
+  // Guard LEXICAL (1ª camada): mesmo com --file já normalizado, o path resolvido tem que
+  // ser exatamente <podDir>/knowledge/<file>. Isto NÃO cobre symlink — `path.resolve`
+  // não resolve link; a 2ª camada (realpath, logo abaixo) é quem cobre.
+  const knowledgeRoot = path.resolve(podDir, 'knowledge');
+  if (path.resolve(targetAbs) !== path.join(knowledgeRoot, file)) {
+    refuse(`--file "${fileArg}" resolveu para fora de ${knowledgeRoot}`);
+  }
+  if (!fs.existsSync(targetAbs)) {
+    refuse(`knowledge-alvo inexistente: ${targetAbs} — o alvo v1 só EDITA arquivo existente (criar é DEBT-SF10.10-C)`);
+  }
+  // Guard REALPATH (2ª camada — QA SF10.10/F1): o alvo tem que SER o arquivo real sob
+  // knowledge/, e os outros 2 paths que este modo escreve têm que resolver sob a raiz
+  // real do pod. Sem isto, um `knowledge/<file>` que fosse symlink para fora do pod
+  // escreveria FORA do podDir com o diff de confinamento cego (Dirent de link não é
+  // isFile()) — e o relatório ainda diria "confinamento OK". Padrão idêntico ao Guard B
+  // de `command_check` (pc-run-pod.cjs) e ao `confineToRunDir` (pod-export-ui.cjs, SF10.9).
+  const realPodRoot = fs.realpathSync(path.resolve(podDir));
+  const realTarget = fs.realpathSync(targetAbs);
+  if (realTarget !== path.join(fs.realpathSync(knowledgeRoot), file)) {
+    refuse(
+      `knowledge/${file} resolve (realpath) para "${realTarget}" — não é o arquivo real sob ` +
+        `${fs.realpathSync(knowledgeRoot)}. Promover através de symlink escreveria FORA do pod e a prova de ` +
+        'confinamento seria cega (Dirent de symlink não é isFile()); a promoção é RECUSADA antes de qualquer escrita.',
+    );
+  }
+  for (const rel of ['memory/learnings.jsonl', 'memory/learnings.consolidated.md']) {
+    assertRealpathUnder(realPodRoot, path.join(podDir, rel), `memória do pod (${rel})`);
+  }
+  const contentPath = path.resolve(contentArg);
+  if (!fs.existsSync(contentPath)) refuse(`--content não encontrado: ${contentPath}`);
+  const newContent = fs.readFileSync(contentPath);
+  const oldContent = fs.readFileSync(targetAbs);
+  if (oldContent.equals(newContent)) {
+    refuse(`--content é BYTE-IDÊNTICO a knowledge/${file} — não há promoção a registrar (registro de hardening marca uma MUDANÇA)`);
+  }
+  const shaBefore = sha256(oldContent);
+  const shaAfter = sha256(newContent);
+
+  // ── heurística-fonte: existe, está no consolidado, ainda não endurecida ─────
+  const { entry, ref, memPaths } = resolveLearning(pod, podDir, learningId);
+
+  // ── BASELINE (antes): estático + smoke 4/4 verdes (guarda de pod quebrado) ──
+  const staticBefore = run(['scripts/validate-pod-workflow.cjs', wfPath], 'validate-pod-workflow (antes)');
+  if (staticBefore.status !== 0) {
+    refuse(`baseline vermelho — ${staticBefore.label} exit ${staticBefore.status}:\n${staticBefore.out}`);
+  }
+  const smokeBefore = run(['scripts/smoke-pod-workflow.cjs', wfPath, '--scenario', smokePath], 'smoke 4/4 (antes)');
+  if (smokeBefore.status !== 0) {
+    refuse(`baseline vermelho — ${smokeBefore.label} exit ${smokeBefore.status}:\n${smokeBefore.out}`);
+  }
+
+  // ── PARIDADE DE COMPILAÇÃO (antes), quando o pod é export-capaz ─────────────
+  const pinsPath = findPins(podDir, pod, args);
+  let lockBefore = null;
+  if (pinsPath) {
+    const cb = compileLock(podDir, pinsPath, 'pod-export-compile (antes)');
+    if (cb.status !== 0 || !cb.lock) {
+      refuse(`baseline vermelho — ${cb.label} exit ${cb.status}:\n${cb.out}`);
+    }
+    lockBefore = cb.lock;
+  }
+
+  // ── snapshot p/ CONFINAMENTO + rollback (pós-consolidate do baseline) ───────
+  const snapshot = snapshotDir(path.resolve(podDir));
+  const ALLOWED = [
+    `knowledge/${file}`,
+    'memory/learnings.jsonl',
+    'memory/learnings.consolidated.md',
+    // SF11.4/ADR-022 (DF-SF11.4-1/-6): a trilha auditável das endurecidas é escrita por
+    // `consolidate` — sem ela no ALLOWED, a própria promoção reprovaria por violação de
+    // confinamento contra si mesma. Fica no repositório do pod; NÃO viaja no bundle.
+    podMemory.HARDENED_DETAIL_REL,
+  ];
+  const rollback = (why) => {
+    restoreSnapshot(path.resolve(podDir), snapshot);
+    refuse(`${why} — ROLLBACK aplicado (pod restaurado byte a byte ao estado anterior à promoção)`);
+  };
+
+  // ── aplicar o conteúdo proposto pelo humano ────────────────────────────────
+  const timestamp = new Date().toISOString();
+  fs.writeFileSync(targetAbs, newContent);
+
+  // ── marcação append-only + consolidação (demoção do top-N) ─────────────────
+  let record;
+  let consolidateResult;
+  try {
+    ({ record } = podMemory.appendHardening(pod, {
+      ref,
+      target: { pod, kind: 'knowledge', file, sha_before: shaBefore, sha_after: shaAfter },
+      approved_by: approvedBy,
+      timestamp,
+    }, { podDir }));
+    consolidateResult = podMemory.consolidate(pod, { podDir });
+  } catch (e) {
+    rollback(`marcação/consolidação falhou: ${e.message}`);
+  }
+
+  // ── (DF-SF11.4-4, SUPERSEDE DF-SF10.10-6) o gate mede a CAUSA, não o sintoma que a
+  // poda já apagou. O gate anterior comparava `consolidateResult.tokens > TOKEN_BUDGET`
+  // — grandeza que `computeConsolidation` NORMALIZA antes de qualquer chamador vê-la
+  // (o `while` de poda só termina com tokens ≤ BUDGET ou `ranked` VAZIO). Consequência
+  // provada em ADR-022 §C4: ele só era alcançável com `ranked.length === 0`, ou seja,
+  // depois que 100% da memória ativa do pod já tinha sido apagada em silêncio (8
+  // promoções seguidas zeram o `hn-carousel` sem um único sinal). Agora recusa quando a
+  // promoção CAUSOU eviction — fato binário observável, sem limiar novo (DF4-5).
+  //
+  // SF11.4b/ADR-023 (DF-SF11.4b-1): com a ADMISSÃO ÚNICA, `evicted` passou a carregar
+  // TAMBÉM o corte por teto de atenção (`reason: 'top_n'`). O GATE continua medindo só
+  // `reason: 'budget'` — e isso não é afrouxamento: promover REMOVE a heurística do pool
+  // que compete por slot (endurecida sai do top-N ativo), então uma promoção nunca CAUSA
+  // corte por TOP_N; recusar por ele puniria o dono por um fato pré-existente e
+  // independente do ato. O RELATO, ao contrário, é sempre o TOTAL (ledger do motor):
+  // recusar por uma causa e relatar por outra é o defeito de C2 pela porta dos fundos.
+  const evicted = Array.isArray(consolidateResult.evicted) ? consolidateResult.evicted : [];
+  const evictedByBudget = evicted.filter((e) => e.reason === 'budget');
+  const ledger = podMemory.formatEvictionLedger(pod, consolidateResult);
+  if (evictedByBudget.length > 0) {
+    rollback(
+      `promoção DESCARTARIA ${evictedByBudget.length} heurística(s) do consolidado por ` +
+        `${consolidateResult.memoryCost ? 'alvo' : 'teto'} de custo (${consolidateResult.tokenBudget} tok): ` +
+        `${evictedByBudget.map((e) => `"${e.trigger}"`).join(', ')}. ` +
+        'Nenhum aprendizado sai da memória ativa em silêncio para abrir espaço a outro: cure o consolidado ' +
+        `(marque redundância como obsolete) e promova de novo.\n${ledger}`,
+    );
+  } else if (ledger) {
+    // sem eviction por custo, mas o pool excede o teto de ATENÇÃO: a promoção segue
+    // (ela não causou o corte), e o corte deixa de ser mudo mesmo neste caminho.
+    console.error(ledger);
+  }
+
+  // ── CONFINAMENTO: só os 3 paths permitidos mudaram sob o podDir ────────────
+  const after = snapshotDir(path.resolve(podDir));
+  const violations = confinementViolations(snapshot, after, ALLOWED);
+  if (violations.length > 0) {
+    rollback(`escrita FORA do confinamento permitido (${ALLOWED.join(', ')}): ${violations.join(', ')}`);
+  }
+
+  // ── PROVENIÊNCIA/IDENTIDADE: scanClone (regras 1-3) verde sobre o alvo ─────
+  // Determinístico, sem limiar: prosa nova que encarne um mind ou cite token de
+  // squad sem citação reprova. (A regra 4, knowledge-sem-fonte, fica FORA por
+  // decisão — DF-SF10.10-2.1: reprova 4/5 knowledge reais, inclusive o caso motivador.)
+  const cloneViolations = scanClone(targetAbs, deriveDenylist(null));
+  if (cloneViolations.length > 0) {
+    const detail = cloneViolations.slice(0, 5)
+      .map((v) => `${v.rule} (linha ${v.line}): "${v.term}" — ${v.text}`).join('; ');
+    rollback(`validate-no-clone: ${cloneViolations.length} violação(ões) no knowledge promovido: ${detail}`);
+  }
+
+  // ── PARIDADE DE COMPILAÇÃO (depois) ────────────────────────────────────────
+  let exportCheck = 'n/a';
+  let exportDetail = `nenhum pins.json encontrado (nem <podDir>/pins.json, nem exports/${pod}/pins.json) — pod NÃO é export-capaz (DEBT-SF10.10-E: prova mais fraca, declarada)`;
+  if (pinsPath) {
+    const ca = compileLock(podDir, pinsPath, 'pod-export-compile (depois)');
+    if (ca.status !== 0 || !ca.lock) {
+      rollback(`pós-gate vermelho — ${ca.label} exit ${ca.status}:\n${ca.out}`);
+    }
+    const diverged = perFileShaDiff(lockBefore, ca.lock);
+    const expected = [`knowledge/${file}`, 'memory/learnings.consolidated.md'].sort();
+    const unexpected = diverged.filter((k) => !expected.includes(k));
+    if (unexpected.length > 0) {
+      rollback(`per_file_sha divergiu FORA do alvo (esperado só ${expected.join(', ')}): ${unexpected.join(', ')}`);
+    }
+    if (!diverged.includes(`knowledge/${file}`)) {
+      rollback(`per_file_sha NÃO registrou mudança em knowledge/${file} — o compilador não vê o arquivo promovido (knowledge órfão/não anexado?)`);
+    }
+    exportCheck = 'ok';
+    exportDetail = `per_file_sha divergiu SOMENTE em ${diverged.join(', ')}; pod_sha ${lockBefore.pod_sha.slice(0, 12)} → ${ca.lock.pod_sha.slice(0, 12)} ` +
+      '(muda ⇒ pod-export-release --if-changed detecta-e-bloqueia o selo antigo, DF4-4)';
+  }
+
+  // ── relatório ──────────────────────────────────────────────────────────────
+  console.log('# forge-harden-learning — promoção de KNOWLEDGE aplicada e provada');
+  console.log(`pod: ${pod} · alvo: knowledge/${file}`);
+  console.log(`learning: ${learningId} ("${entry.trigger}", ref: ${ref})`);
+  console.log(`aprovado por: ${approvedBy} em ${timestamp}`);
+  console.log(`sha_before: ${shaBefore}`);
+  console.log(`sha_after : ${shaAfter}`);
+  console.log(`gates: baseline validate+smoke 4/4 exit 0 · confinamento OK (${ALLOWED.join(', ')}) · ` +
+    `scanClone 0 violação(ões) · export_check: ${exportCheck}`);
+  console.log(`export_check(${exportCheck}): ${exportDetail}`);
+  console.log(NO_SMOKE_AFTER_NOTICE);
+  console.log(`QUALIDADE: ${QUALITY_NOTICE}`);
+  console.log(`diff: NÃO embutido no registro (DF-SF10.10-1) — revise com \`git diff -- ${path.join(podDir, 'knowledge', file)}\``);
+  console.log(`memória: registro hardening append-only gravado (${record.timestamp}) em ${memPaths.raw}; ` +
+    `consolidado: ${consolidateResult.hardenedCount} endurecida(s) 🔒 (referência agregada; detalhe íntegro em ` +
+    `${podMemory.HARDENED_DETAIL_REL}), top-N ativo: ${consolidateResult.topNCount}, ` +
+    `${consolidateResult.tokens}/${podMemory.TOKEN_BUDGET} tokens, 0 heurística descartada por orçamento`);
+  process.exit(0);
+}
+
+// ── DETECÇÃO (DF-SF10.10-3) — read-only, exit 0 SEMPRE, nunca promove ────────
+function listCandidatesMode(args) {
+  const podDir = args[0];
+  const { pod } = podIdentity(podDir, args);
+  const candidates = podMemory.listCandidates(pod, { podDir });
+
+  console.log(`# candidatos a endurecimento — pod "${pod}"`);
+  console.log('Heurísticas do consolidado CURADO sem registro de hardening (diferença de conjuntos).');
+  console.log('Esta lista NÃO classifica "de conteúdo" vs "mecanizável": não há oráculo para isso — a');
+  console.log('tradução heurística→forma (veto ou knowledge) é julgamento HUMANO (ADR-012 §Escopo OUT).');
+  console.log('');
+  if (candidates.length === 0) {
+    console.log('_Nenhum candidato: toda heurística do consolidado já tem registro de hardening (ou o consolidado está vazio)._');
+  } else {
+    for (const c of candidates) {
+      console.log(`- [${c.section}] **[${c.trigger}]** ${c.recommendation} _(x${c.occurrences})_`);
+      console.log(`    --learning ${c.last_id}`);
+    }
+  }
+  console.log('');
+  console.log(`${candidates.length} candidato(s). Read-only: nada foi promovido, nada foi escrito.`);
+  console.log('Disciplina de PRÉ-RELEASE (nunca gate): rode antes de `pod-export-release.cjs` e decida o que promover.');
+  process.exit(0);
+}
+
+// ── ALVO `veto` (SF7.6) — fluxo original, inalterado ─────────────────────────
+function hardenVeto(args) {
+  const podDir = args[0];
+
+  const learningId = argVal(args, '--learning');
+  const stepId = argVal(args, '--step');
+  const assertionJson = argVal(args, '--assertion');
+  const approvedBy = argVal(args, '--approved-by');
+
+  if (!learningId) usage('--learning <id> é obrigatório (id da entrada no learnings.jsonl)');
+  if (!stepId) usage('--step <stepId> é obrigatório (etapa-alvo do workflow)');
+  if (!assertionJson) usage("--assertion '<json>' é obrigatório (a forma de veto proposta — julgamento humano)");
+  // (b) aprovação do dono OBRIGATÓRIA — recusa explícita, nunca aplica sem ela.
+  if (!approvedBy || approvedBy.startsWith('--')) {
+    refuse('promoção exige --approved-by <nome> (aprovação humana registrada — padrão migration-manifest); sem ela NADA é aplicado');
+  }
+
+  let assertion;
+  try {
+    assertion = JSON.parse(assertionJson);
+  } catch (e) {
+    refuse(`--assertion não é JSON válido: ${e.message}`);
+  }
+  checkAssertionShape(assertion);
+
+  // ── pod-spec.json = fonte declarada da verdade (ADR-005) ────────────────────
+  const specPath = path.join(podDir, 'pod-spec.json');
+  if (!fs.existsSync(specPath)) {
+    refuse(`pod-spec.json não encontrado em ${podDir} — o hardening edita a SPEC (fonte da verdade, ADR-005) e regenera o wf; sem spec declarada não há o que promover`);
+  }
+  const specTextBefore = fs.readFileSync(specPath, 'utf8');
+  let spec;
+  try {
+    spec = JSON.parse(specTextBefore);
+  } catch (e) {
+    refuse(`pod-spec.json inválido: ${e.message}`);
+  }
+
+  const pod = spec.pod || path.basename(path.resolve(podDir));
+  const workflowId = slug(argVal(args, '--workflow') || spec.workflowId || spec.pod || 'main');
+  const wfRel = path.join('workflows', `wf-${workflowId}.yaml`);
+  const wfPath = path.join(podDir, wfRel);
+  if (!fs.existsSync(wfPath)) refuse(`workflow-alvo não encontrado: ${wfPath}`);
+  const smokePath = wfPath.replace(/\.ya?ml$/, '.smoke.json');
+  if (!fs.existsSync(smokePath)) {
+    refuse(`cenário de smoke não encontrado: ${smokePath} — sem ele não há prova 4/4 antes/depois (AC5); autore o sidecar primeiro`);
+  }
+
+  // ── localizar a heurística no log cru e exigir presença no consolidado ──────
+  const { entry, ref } = resolveLearning(pod, podDir, learningId);
+
+  // ── localizar a etapa-alvo na spec ──────────────────────────────────────────
+  const steps = stepsFromSpec(spec);
+  const stepIdx = steps.findIndex((s) => s.id === slug(stepId));
+  if (stepIdx < 0) {
+    refuse(`etapa "${stepId}" não existe na spec (etapas: ${steps.map((s) => s.id).join(', ')})`);
+  }
+  const agentEntry = spec.agents[stepIdx];
+  if (typeof agentEntry === 'string') {
+    refuse(`agents[${stepIdx}] da spec é string simples — hardening exige entrada-objeto para declarar veto[] (edite a spec para a forma objeto antes)`);
+  }
+
+  // dedup: mesma asserção já declarada na etapa ⇒ recusa (idempotência explícita)
+  const existing = Array.isArray(agentEntry.veto) ? agentEntry.veto : [];
+  const sig = assertionSig(assertion);
+  if (existing.some((a) => assertionSig(a) === sig)) {
+    refuse(`a etapa "${stepId}" já declara esta exata asserção — promoção repetida não aplica`);
+  }
+
+  // ── BASELINE (antes): estático + smoke 4/4 têm que estar verdes ─────────────
+  const staticBefore = run(['scripts/validate-pod-workflow.cjs', wfPath], 'validate-pod-workflow (antes)');
+  if (staticBefore.status !== 0) {
+    refuse(`baseline vermelho — ${staticBefore.label} exit ${staticBefore.status}:\n${staticBefore.out}`);
+  }
+  const smokeBefore = run(['scripts/smoke-pod-workflow.cjs', wfPath, '--scenario', smokePath], 'smoke 4/4 (antes)');
+  if (smokeBefore.status !== 0) {
+    refuse(`baseline vermelho — ${smokeBefore.label} exit ${smokeBefore.status}:\n${smokeBefore.out}`);
+  }
+
+  // snapshots p/ rollback e p/ diff de preservação
+  const wfBefore = fs.readFileSync(wfPath, 'utf8');
+  const ownedTemplates = steps.map((s) => path.join('templates', `${s.id}-tmpl.md`));
+  const tmplBefore = new Map(ownedTemplates.map((rel) => {
+    const abs = path.join(podDir, rel);
+    return [rel, fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null];
+  }));
+
+  // ── aplicar a asserção à SPEC (com rastreabilidade _sources) ────────────────
+  const timestamp = new Date().toISOString();
+  // sem veto declarado, o gerador emitia o default (confianca) — preservá-lo
+  // explicitamente antes de somar a nova asserção (nenhuma regressão de veto).
+  if (!Array.isArray(agentEntry.veto) || agentEntry.veto.length === 0) {
+    agentEntry.veto = [{ type: 'field_matches', field: 'confianca', pattern: '^(alta|media|baixa)$' }];
+  }
+  agentEntry.veto.push({
+    ...assertion,
+    _sources: `hardening SF7.6: learning ${learningId} ("${entry.trigger}") promovido a enforcement por ${approvedBy} em ${timestamp} (forge-harden-learning.cjs)`,
+  });
+
+  const rollback = (why) => {
+    fs.writeFileSync(specPath, specTextBefore);
+    fs.writeFileSync(wfPath, wfBefore);
+    for (const [rel, content] of tmplBefore) {
+      if (content != null) fs.writeFileSync(path.join(podDir, rel), content);
+    }
+    refuse(`${why} — ROLLBACK aplicado (spec, wf e templates restaurados; memória intocada)`);
+  };
+
+  fs.writeFileSync(specPath, `${JSON.stringify(spec, null, 2)}\n`);
+
+  // ── regenerar SÓ o alvo via mecanismo provado (--additive + owns) ───────────
+  try {
+    generatePod(spec, path.resolve(podDir), {
+      additive: true,
+      owns: [wfRel, ...ownedTemplates],
+      // SF12.4a/ADR-030 Bloco O (AC48/Emenda 1) — `*harden-learning` reemite a partir da
+      // spec PRÉ-EXISTENTE (re-emitida, não autorada agora): sempre 'derived'.
+      specOrigin: 'derived',
+    });
+  } catch (e) {
+    rollback(`forge-generate --additive falhou: ${e.message}`);
+  }
+
+  // ── prova de preservação: diff confinado à etapa-alvo ───────────────────────
+  const wfAfter = fs.readFileSync(wfPath, 'utf8');
+  const before = splitWfBlocks(wfBefore);
+  const after = splitWfBlocks(wfAfter);
+  if (before.header !== after.header) rollback('regeneração alterou o cabeçalho do wf (fora da etapa-alvo)');
+  const ids = new Set([...before.blocks.keys(), ...after.blocks.keys()]);
+  const changedSteps = [];
+  for (const id of ids) {
+    const b = (before.blocks.get(id) || []).join('\n');
+    const a = (after.blocks.get(id) || []).join('\n');
+    if (b !== a) changedSteps.push(id);
+  }
+  if (changedSteps.length !== 1 || changedSteps[0] !== slug(stepId)) {
+    rollback(`regeneração mudou etapas além da alvo (mudadas: ${changedSteps.join(', ') || 'nenhuma'})`);
+  }
+  const changedTemplates = ownedTemplates.filter((rel) => {
+    const abs = path.join(podDir, rel);
+    const now = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+    return now !== tmplBefore.get(rel);
+  });
+  if (changedTemplates.some((rel) => rel !== path.join('templates', `${slug(stepId)}-tmpl.md`))) {
+    rollback(`regeneração mudou template de etapa não-alvo (${changedTemplates.join(', ')})`);
+  }
+
+  // ── DEPOIS: estático + smoke 4/4 sobre o wf regenerado ──────────────────────
+  const staticAfter = run(['scripts/validate-pod-workflow.cjs', wfPath], 'validate-pod-workflow (depois)');
+  if (staticAfter.status !== 0) rollback(`pós-gate vermelho — ${staticAfter.label} exit ${staticAfter.status}:\n${staticAfter.out}`);
+  const smokeAfter = run(['scripts/smoke-pod-workflow.cjs', wfPath, '--scenario', smokePath], 'smoke 4/4 (depois)');
+  if (smokeAfter.status !== 0) rollback(`pós-gate vermelho — ${smokeAfter.label} exit ${smokeAfter.status}:\n${smokeAfter.out}`);
+
+  // ── marcação append-only + demoção do top-N (pod-memory, ADR-012) ───────────
+  const { record } = podMemory.appendHardening(pod, {
+    ref,
+    target: { pod, workflowId, step: slug(stepId), assertion },
+    approved_by: approvedBy,
+    timestamp,
+  }, { podDir });
+  const consolidateResult = podMemory.consolidate(pod, { podDir });
+
+  // diff textual do wf (linhas adicionadas na etapa-alvo) p/ o registro
+  const beforeLines = new Set(wfBefore.split('\n'));
+  const addedLines = wfAfter.split('\n').filter((l) => !beforeLines.has(l));
+
+  console.log(`# forge-harden-learning — promoção aplicada e provada`);
+  console.log(`pod: ${pod} · workflow: wf-${workflowId} · etapa-alvo: ${slug(stepId)}`);
+  console.log(`learning: ${learningId} (ref: ${ref})`);
+  console.log(`aprovado por: ${approvedBy} em ${timestamp}`);
+  console.log(`asserção promovida: ${assertionSig(assertion)}`);
+  console.log(`gates: estático antes/depois exit 0 · smoke 4/4 antes/depois exit 0`);
+  console.log(`diff do wf confinado à etapa-alvo (${addedLines.length} linha(s) adicionada(s)):`);
+  for (const l of addedLines) console.log(`  + ${l}`);
+  // SF11.4/DF-SF11.4-2: poda nunca é silenciosa — o alvo `veto` não tem rollback de
+  // memória (a marcação é o último passo, depois dos gates), então o canal aqui é o
+  // LEDGER nomeado em stderr, nunca o silêncio.
+  // SF11.4b/DF-SF11.4b-1: a mensagem vem do motor (fonte única) e reporta o TOTAL das
+  // duas vias — este emissor não monta contador próprio nem cita só uma causa.
+  const evictedVeto = Array.isArray(consolidateResult.evicted) ? consolidateResult.evicted : [];
+  const ledgerVeto = podMemory.formatEvictionLedger(pod, consolidateResult);
+  if (ledgerVeto) console.error(ledgerVeto);
+  const evictedBreakdown = `${evictedVeto.length} NÃO admitida(s) ` +
+    `(${evictedVeto.filter((e) => e.reason === 'top_n').length} por teto de atenção · ` +
+    `${evictedVeto.filter((e) => e.reason === 'budget').length} por custo)`;
+  console.log(`memória: registro hardening append-only gravado (${record.timestamp}); ` +
+    `consolidado: ${consolidateResult.hardenedCount} endurecida(s) 🔒 (referência agregada; detalhe em ` +
+    `${podMemory.HARDENED_DETAIL_REL}), top-N ativo: ${consolidateResult.topNCount}, ` +
+    `${evictedBreakdown}`);
+  process.exit(0);
+}
+
+// ── despacho por MODO ────────────────────────────────────────────────────────
+function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    help();
+    process.exit(0);
+  }
+  const podDir = args[0];
+  if (!podDir || podDir.startsWith('--')) usage('informe o <podDir>');
+  if (!fs.existsSync(podDir)) usage(`podDir não encontrado: ${podDir}`);
+
+  if (args.includes('--list-candidates')) return listCandidatesMode(args);
+
+  const targetType = argVal(args, '--target-type') || podMemory.HARDEN_KIND_VETO;
+  if (targetType === podMemory.HARDEN_KIND_KNOWLEDGE) return hardenKnowledge(args);
+  if (targetType !== podMemory.HARDEN_KIND_VETO) {
+    usage(`--target-type "${targetType}" desconhecido (use "veto" — default — ou "knowledge")`);
+  }
+  return hardenVeto(args);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  splitWfBlocks,
+  assertionSig,
+  checkAssertionShape,
+  // SF10.10 — invariantes do alvo knowledge, exportados para teste hermético
+  confinementViolations,
+  perFileShaDiff,
+  snapshotDir,
+  declaredKnowledge,
+  QUALITY_NOTICE,
+};