@daniellins/power-claude 0.16.3

package/scripts/pod-memory.cjs

@@ -0,0 +1,1252 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * pod-memory.cjs — motor determinístico do lifecycle de memória do pod (Story SF2.1).
+ *
+ * Implementa o modelo de DOIS NÍVEIS do ADR-003 / SPEC §G1, provado em código (não
+ * em prosa). É biblioteca standalone: SF2.2 (runner) e SF2.3 (fábrica) consomem via
+ * `require`; este motor NÃO integra com o runner nem com a fábrica.
+ *
+ *   NÍVEL 1 — log cru: `pods/<pod>/memory/learnings.jsonl`
+ *     append-only, uma linha JSON por evento. O AGENTE NUNCA LÊ ESTE ARQUIVO.
+ *     Rotaciona para `memory/archive/learnings-{ts}.jsonl` além de M=500 entradas.
+ *
+ *   NÍVEL 2 — consolidado curado: `pods/<pod>/memory/learnings.consolidated.md`
+ *     top-N=30 heurísticas rankeadas por frequência × recência × impacto, dentro de
+ *     um budget de ~1.500 tokens (bytes/4, mesma aproximação de validate-budgets.js).
+ *     É o ÚNICO que o agente lê (via `getConsolidatedForBrief`).
+ *
+ *   TRILHA AUDITÁVEL (SF11.4/ADR-022): `pods/<pod>/memory/learnings.hardened.md`
+ *     detalhe íntegro das endurecidas (🔒), append-only, sem poda e sem teto. FORA do
+ *     caminho de injeção — o agente NÃO lê este arquivo; o consolidado cita só uma
+ *     referência AGREGADA (contagem por alvo). Não viaja no bundle do export.
+ *
+ * GARANTIAS CATEGÓRICAS (provadas na suíte pod-memory.test.cjs, não-fake-green):
+ *   - O consolidado NUNCA excede top-N nem o budget de tokens.
+ *   - ADMISSÃO ÚNICA (SF11.4b/ADR-023): nenhuma heurística ativa fica fora do
+ *     consolidado sem entrar em `evicted` com `reason` — as DUAS vias de corte
+ *     (teto de atenção TOP_N e alvo/teto de custo) passam pelo mesmo registro, e
+ *     `evicted.length` é o TOTAL do que não foi injetado, nunca um subconjunto.
+ *   - CRITICAL pinado NUNCA é despejado por poda do top-N nem por rotação do log cru.
+ *   - Conflito é determinístico e reprodutível (mesmo input → mesmo vencedor).
+ *   - Teto de pins ≤10 NUNCA é ultrapassado silenciosamente (sinaliza needsCuration).
+ *   - `append` REJEITA `tier: "critical"` sem `attributed_by` válido.
+ *
+ * ── Anti-inflação do CRITICAL (v4, ADR-003 — as 3 travas, verificáveis em código) ──
+ *   (i)   CRITÉRIO ESTREITO — este motor NÃO decide se algo "é" critical. Critical =
+ *         dano irreversível / segurança (operação destrutiva, perda de dados,
+ *         vazamento, quebra de compliance), NUNCA "importante/útil/recorrente" (isso é
+ *         peso no ranking normal). A decisão de conteúdo é de quem chama `append`
+ *         (curadoria humana ou regra determinística upstream). O motor só valida a
+ *         FORMA da atribuição — validar semântica em código exigiria LLM, e veto por
+ *         LLM é proibido pela SPEC. Esta lista fechada é referência para o chamador.
+ *   (ii)  ATRIBUIÇÃO NÃO-DISCRICIONÁRIA — `attributed_by` é obrigatório e de enum
+ *         fechado (`"human"` | `"deterministic_rule"`) para toda entrada critical.
+ *         Nenhum caminho de código deixa o AGENTE em runtime marcar critical sem essa
+ *         atribuição: `append` rejeita a entrada (não a rebaixa silenciosamente).
+ *   (iii) TETO ≤10 — o conjunto pinado tem teto próprio; ao ultrapassar, `consolidate`
+ *         devolve `{ needsCuration: true, pinnedCount, overflow }` e o excedente NÃO é
+ *         escrito como pin permanente (fica retido no log cru + sinalizado, nunca
+ *         descartado), até curadoria explícita rebaixar/fundir um pin existente.
+ *
+ * Node >= 18, sem dependências externas. Exporta a API para a suíte própria.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ── Constantes do ADR-003 (decisão fechada; não reabrir nesta story) ─────────
+// SF11.4b/ADR-023 (DF-SF11.4b-1, §C5) — PROPÓSITO DECLARADO de TOP_N: é **teto de
+// ATENÇÃO**, não controle de custo. Custo se mede em BYTES e já é governado pelo
+// alvo/teto abaixo; controlar custo duas vezes, em duas unidades, seria redundante — e
+// foi essa ambiguidade que deixou o corte por TOP_N mudo por três ADRs. Medição que
+// sustenta a leitura (ADR-023 §C5): com heurísticas curtas cabem 30 itens em 938 tok e
+// caberiam >60 dentro do teto de 1.500 — uma lista que nenhum agente lê com proveito.
+// O que TOP_N protege é a leitura do agente; o que o orçamento protege é o bolso do dono.
+const TOP_N = 30;          // teto de ATENÇÃO do conjunto ranqueado (exclui pinados)
+const ROTATE_M = 500;      // rotação do log cru além de M entradas
+const CONSOLIDATE_K = 20;  // cadência (disparo é do CALLER/SF2.2; exportado p/ ref)
+const TOKEN_BUDGET = 1500; // TETO do framework p/ o consolidado (bytes/4) — ADR-003, intocado
+// SF11.4b/ADR-023 (DF-SF11.4b-2) — ALVO de custo por pod, OPT-IN, declarado no manifesto
+// que já existe (`pod-spec.json`). Não é limiar inventado: é a MEDIÇÃO do artefato no
+// instante em que o dono aceitou a economia, com atribuição (`acceptedBy`/`acceptedAt`),
+// versionada em git e reversível por ato explícito dele — o oráculo que DF4-5 (ADR-018)
+// exige. Pod que não declara se comporta EXATAMENTE como antes (teto 1.500).
+const POD_SPEC_FILE = 'pod-spec.json';
+const MEMORY_COST_FIELD = 'memoryCost';
+const PIN_CAP = 10;        // teto do conjunto CRITICAL pinado (trava iii)
+const DEFAULT_POD_ROOT = 'pods';
+
+const TIER_NORMAL = 'normal';
+const TIER_CRITICAL = 'critical';
+const VALID_ATTRIBUTION = new Set(['human', 'deterministic_rule']);
+// SF7.6/ADR-012 — registro de HARDENING: marca (append-only) que uma heurística foi
+// promovida a enforcement físico (veto.assertion no wf). Nunca remove a heurística do
+// log; `consolidate` a anota (🔒) e a EXCLUI do top-N ativo (orçamento de injeção é
+// finito — não re-sugerir o que virou regra física).
+const TYPE_HARDENING = 'hardening';
+// SF10.10/ADR-012 Adendo (DF-SF10.10-1) — o ALVO do registro de hardening é uma UNIÃO
+// DISCRIMINADA por `target.kind`:
+//   'veto'      → { pod, workflowId, step, assertion } (SF7.6, alvo original)
+//   'knowledge' → { pod, file, sha_before, sha_after } (2º alvo: knowledge canônico)
+// `kind` AUSENTE ⇒ 'veto': retrocompat dos registros JÁ EM DISCO, sem migração e sem
+// reescrita do log (mesmo precedente do OK_PATTERN_LEGACY_RE — reconhecer o legado por
+// convenção). `kind` DESCONHECIDO ⇒ fail-loud: nunca cai no ramo 'veto' por omissão.
+// O registro NÃO embute o diff (tamanho fixo: dois shas + um nome) — registros de
+// hardening nunca rotacionam e o consolidado alimenta um artefato orçado; o diff vive
+// no git, que já versiona o arquivo de knowledge.
+const HARDEN_KIND_VETO = 'veto';
+const HARDEN_KIND_KNOWLEDGE = 'knowledge';
+const HARDEN_KINDS = new Set([HARDEN_KIND_VETO, HARDEN_KIND_KNOWLEDGE]);
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+// SF11.4/ADR-022 (DF-SF11.4-1) — o DETALHE de cada endurecida sai do artefato INJETADO
+// e passa a viver aqui: append-only, sem poda, sem teto, fora do caminho de injeção
+// (o agente lê SOMENTE learnings.consolidated.md — getConsolidatedForBrief continua
+// lendo UM arquivo). No consolidado fica uma REFERÊNCIA AGREGADA nomeada e visível
+// (ADR-021 DF-SF11.2-3: orçamento decide INLINE × REFERÊNCIA, nunca MANTER × DESCARTAR).
+const HARDENED_DETAIL_FILE = 'learnings.hardened.md';
+const HARDENED_DETAIL_REL = `memory/${HARDENED_DETAIL_FILE}`;
+const HARDENED_DETAIL_BULLET = '- 🔒 ';
+
+/**
+ * Discriminante do alvo de um registro de hardening. Ausente ⇒ 'veto' (legado).
+ * Desconhecido ⇒ THROW (fail-loud): tratar um kind não suportado como 'veto' leria
+ * `target.assertion` inexistente e derrubaria `consolidate` — o exato defeito que
+ * DF-SF10.10-1 fecha.
+ */
+function hardeningKind(target) {
+  const kind = target && target.kind != null ? target.kind : HARDEN_KIND_VETO;
+  if (!HARDEN_KINDS.has(kind)) {
+    throw new Error(
+      `pod-memory: target.kind desconhecido ${JSON.stringify(kind)} — suportados: ${[...HARDEN_KINDS].join(', ')} ` +
+        '(ausente ⇒ "veto" por retrocompat; desconhecido NUNCA é tratado como "veto" — ADR-012 Adendo SF10.10/DF-SF10.10-1)',
+    );
+  }
+  return kind;
+}
+// SF8.3 — classe OK_PATTERN: auto-referência de fechamento limpo de workflow
+// (buildOkLearning do runner). Fica no LOG CRU como trilha de auditoria de
+// estabilidade, mas NUNCA compete por slot do top-N na consolidação — evidência
+// de campo (triagem 2026-07-29): 26/122 entradas, slot #1 dos 3 consolidados
+// com uso, crescendo a cada run limpo ("terminei e deu certo" não é heurística).
+const TYPE_OK_PATTERN = 'ok_pattern';
+// Reconhecimento LEGADO por assinatura estrutural: entradas de campo geradas antes
+// da marcação por tipo não têm `type` — casam pelo template EXATO e único do
+// produtor (pc-run-pod.cjs buildOkLearning). Complemento necessário para os
+// consolidados de campo existentes auto-resolverem na próxima consolidação; o
+// caminho canônico daqui em diante é o campo `type` (marcado na origem).
+const OK_PATTERN_LEGACY_RE = /^workflow ".+" completou sem bloqueio$/;
+
+/** Uma entrada é da classe ok_pattern? (tipo explícito OU assinatura legada.) */
+function isOkPattern(r) {
+  if (!r || typeof r !== 'object') return false;
+  if (r.type === TYPE_OK_PATTERN) return true;
+  return r.type == null && OK_PATTERN_LEGACY_RE.test(String(r.trigger || ''));
+}
+
+// Tokens de negação p/ detecção determinística de conflito (heurística simples,
+// documentada — NÃO NLP). Cobre PT-BR e EN. Ver detectConflict().
+// Nota: "no" (PT = em+o) é deliberadamente OMITIDO para evitar falso-positivo;
+// negação em EN usa "not"/"never"/"avoid".
+const NEGATION_TOKENS = new Set([
+  'não', 'nao', 'nunca', 'jamais', 'evite', 'evitar', 'sem',
+  'never', 'avoid', 'not',
+]);
+
+// ── Resolução de paths ───────────────────────────────────────────────────────
+// `pod` pode ser o nome do pod (resolvido contra opts.root ?? 'pods') OU o caminho
+// do diretório do pod (contém `memory/`). Isso mantém a assinatura da story
+// (`append(pod, entry)`) e ao mesmo tempo é testável com um root temporário.
+function podDirFor(pod, opts = {}) {
+  if (opts.podDir) return opts.podDir;
+  const root = opts.root || DEFAULT_POD_ROOT;
+  return path.join(root, pod);
+}
+
+function memoryPaths(pod, opts = {}) {
+  const base = path.join(podDirFor(pod, opts), 'memory');
+  const archiveDir = path.join(base, 'archive');
+  return {
+    dir: base,
+    raw: path.join(base, 'learnings.jsonl'),
+    consolidated: path.join(base, 'learnings.consolidated.md'),
+    // SF11.4/ADR-022 (DF-SF11.4-1): trilha auditável das endurecidas, FORA do caminho
+    // de injeção (o agente lê só o consolidado). Append-only, sem poda e sem teto.
+    hardenedDetail: path.join(base, HARDENED_DETAIL_FILE),
+    archiveDir,
+    conflicts: path.join(archiveDir, 'conflicts.jsonl'),
+    archivedEntries: path.join(archiveDir, 'archived-entries.jsonl'),
+  };
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+// ── Alvo de custo declarado pelo dono (SF11.4b/ADR-023 DF-SF11.4b-2) ─────────
+/**
+ * Lê `memoryCost` do `pod-spec.json` do pod. Retorna `null` quando o manifesto não
+ * existe ou não declara o campo — **a ausência não é defeito**: a trava é OPT-IN e
+ * inventar um número para quem não declarou é exatamente o que este desenho recusa.
+ *
+ * AUSÊNCIA TEM UMA SÓ FORMA: `ENOENT` (ADR-023 DF-SF11.4b-7, Emenda 1). Qualquer outro
+ * `errno` de leitura (EISDIR, EACCES, EIO, ELOOP…) significa "existe um manifesto e eu
+ * NÃO consegui lê-lo" — estado em que o alvo aceito pelo dono é DESCONHECIDO, não
+ * ausente — e LANÇA. Tratar falha de leitura como ausência devolvia o teto a
+ * `TOKEN_BUDGET` sem uma linha: o modo de falha que DF-SF11.4b-2 proíbe pelo nome.
+ *
+ * FAIL-LOUD DE FORMA: `memoryCost` PRESENTE e malformado LANÇA com mensagem acionável,
+ * nunca degrada em silêncio para `TOKEN_BUDGET`. Degradar seria reintroduzir "economia
+ * que evapora sem ninguém decidir" pela porta dos fundos (ADR-023 DF-SF11.4b-2).
+ * Mesmo padrão de `hardeningTargetLabel` (fail-loud de forma, DF-SF10.10-1).
+ *
+ * `acceptedBy` é EXIGIDO junto do número: o alvo só não é limiar arbitrário porque é
+ * uma medição ATRIBUÍDA a quem a aceitou (DF4-5/ADR-018 — "limiar sem oráculo é
+ * teatro"). Um `artifactTokens` sem dono é um número inventado com aparência de decisão.
+ */
+function readMemoryCost(pod, opts = {}) {
+  const specPath = path.join(podDirFor(pod, opts), POD_SPEC_FILE);
+  let text;
+  // Um único `readFileSync` (sem o par `existsSync` + read): uma syscall a menos e sem a
+  // janela TOCTOU — a ausência vem do próprio erro, discriminada por `errno`.
+  try {
+    text = fs.readFileSync(specPath, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return null; // manifesto não existe ⇒ o pod não optou
+    throw new Error(
+      `pod-memory: ${specPath} EXISTE mas não pôde ser lido (errno ${(e && e.code) || 'desconhecido'}: ${e && e.message}) — ` +
+        `o motor lê "${MEMORY_COST_FIELD}" deste manifesto para aplicar o alvo de custo da memória, e com o alvo ` +
+        `DESCONHECIDO o teto NUNCA volta em silêncio para ${TOKEN_BUDGET} tok. Corrija o acesso ao arquivo ` +
+        '(permissão, tipo do inode, path) — ausência legítima é o arquivo NÃO existir (ADR-023 DF-SF11.4b-7).',
+    );
+  }
+  let spec;
+  try {
+    spec = JSON.parse(text);
+  } catch (e) {
+    throw new Error(
+      `pod-memory: ${specPath} não é JSON válido (${e.message}) — o motor lê "${MEMORY_COST_FIELD}" ` +
+        'deste manifesto para aplicar o alvo de custo da memória; corrija o arquivo (ADR-023 DF-SF11.4b-2).',
+    );
+  }
+  const mc = spec && typeof spec === 'object' ? spec[MEMORY_COST_FIELD] : undefined;
+  if (mc == null) return null;
+  const where = `${specPath} → "${MEMORY_COST_FIELD}"`;
+  const bad = (why) => new Error(
+    `pod-memory: ${where} malformado — ${why}. O alvo de custo NUNCA degrada em silêncio para ` +
+      `${TOKEN_BUDGET} tok: corrija o manifesto ou remova o campo (a ausência é legítima e volta ao ` +
+      `teto do framework). Forma esperada: {"artifactTokens": <inteiro 1..${TOKEN_BUDGET}>, ` +
+      '"perRunTokens": <inteiro>, "steps": <inteiro>, "acceptedBy": "<quem aceitou>", ' +
+      '"acceptedAt": "<data>"} (ADR-023 DF-SF11.4b-2).',
+  );
+  if (typeof mc !== 'object' || Array.isArray(mc)) throw bad(`esperado objeto, recebido ${JSON.stringify(mc)}`);
+  const t = mc.artifactTokens;
+  if (typeof t !== 'number' || !Number.isInteger(t)) throw bad(`"artifactTokens" deve ser inteiro (recebido ${JSON.stringify(t)})`);
+  if (t <= 0) throw bad(`"artifactTokens" deve ser > 0 (recebido ${t})`);
+  if (t > TOKEN_BUDGET) throw bad(`"artifactTokens" (${t}) excede o teto do framework TOKEN_BUDGET=${TOKEN_BUDGET}`);
+  if (typeof mc.acceptedBy !== 'string' || mc.acceptedBy.trim() === '') {
+    throw bad('"acceptedBy" é obrigatório e não-vazio — o alvo é uma medição ACEITA e ATRIBUÍDA, ' +
+      'não um número escolhido (DF4-5: limiar sem oráculo é teatro)');
+  }
+  if (mc.steps != null && (!Number.isInteger(mc.steps) || mc.steps <= 0)) {
+    throw bad(`"steps" (opcional) deve ser inteiro > 0 quando presente (recebido ${JSON.stringify(mc.steps)})`);
+  }
+  return {
+    artifactTokens: t,
+    steps: mc.steps == null ? null : mc.steps,
+    acceptedBy: mc.acceptedBy,
+    acceptedAt: mc.acceptedAt == null ? null : String(mc.acceptedAt),
+    specPath,
+  };
+}
+
+/**
+ * Teto EFETIVO da etapa de admissão: `min(alvo declarado, TOKEN_BUDGET)`. O `min` é
+ * explícito (e não só a validação de forma) porque o teto do framework é piso de
+ * segurança do desenho: nenhum manifesto pode ampliar o orçamento do consolidado.
+ * @returns {{ tokens: number, target: object|null }}
+ */
+function effectiveTokenBudget(pod, opts = {}) {
+  const target = readMemoryCost(pod, opts);
+  if (!target) return { tokens: TOKEN_BUDGET, target: null };
+  return { tokens: Math.min(target.artifactTokens, TOKEN_BUDGET), target };
+}
+
+// ── Normalização (dedup, conflito) ───────────────────────────────────────────
+function normalizeText(s) {
+  return String(s == null ? '' : s)
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '') // remove acentos p/ casar 'nao'/'não'
+    .replace(/[^\w\s]/g, ' ')        // pontuação → espaço
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function evidenceCount(entry) {
+  const ev = entry.evidence;
+  if (ev == null) return 1;
+  if (typeof ev === 'number') return ev;
+  if (typeof ev.count === 'number') return ev.count;
+  return 1;
+}
+
+function impactOf(entry) {
+  return typeof entry.impact === 'number' && entry.impact > 0 ? entry.impact : 1;
+}
+
+// chave de dedup: mesmo trigger + mesma recomendação (normalizados) → mesma heurística
+function dedupKey(entry) {
+  return `${normalizeText(entry.trigger)}||${normalizeText(entry.recommendation)}`;
+}
+
+// chave de conflito: mesmo trigger, IGNORANDO polaridade da recomendação
+function conflictKey(entry) {
+  return `${normalizeText(entry.trigger)}||${stripNegation(entry.recommendation)}`;
+}
+
+// remove tokens de negação iniciais/internos p/ obter o "núcleo" da recomendação
+function stripNegation(rec) {
+  const words = normalizeText(rec).split(' ').filter(Boolean);
+  return words.filter((w) => !NEGATION_TOKENS.has(w)).join(' ');
+}
+
+function polarity(rec) {
+  // true = negativa (contém token de negação); false = afirmativa
+  return normalizeText(rec).split(' ').some((w) => NEGATION_TOKENS.has(w));
+}
+
+// ── (a) append — log cru append-only ─────────────────────────────────────────
+/**
+ * Grava UMA linha JSON no learnings.jsonl. Append-only: nunca reescreve linhas
+ * anteriores (rotação é operação SEPARADA e explícita — ver rotate()).
+ * Rejeita `tier: "critical"` sem `attributed_by` válido (travas i/ii).
+ * @returns {{ ok: true, entry }} ou lança Error em entrada inválida.
+ */
+function append(pod, entry, opts = {}) {
+  if (!entry || typeof entry !== 'object') {
+    throw new Error('pod-memory.append: entry deve ser um objeto');
+  }
+  if (!entry.trigger || !entry.recommendation) {
+    throw new Error('pod-memory.append: entry exige `trigger` e `recommendation`');
+  }
+  const tier = entry.tier || TIER_NORMAL;
+  if (tier !== TIER_NORMAL && tier !== TIER_CRITICAL) {
+    throw new Error(`pod-memory.append: tier inválido "${tier}" (use "normal"|"critical")`);
+  }
+  // Trava (ii): critical exige atribuição não-discricionária de enum fechado.
+  if (tier === TIER_CRITICAL && !VALID_ATTRIBUTION.has(entry.attributed_by)) {
+    throw new Error(
+      'pod-memory.append: tier "critical" REJEITADO — `attributed_by` deve ser ' +
+        '"human" ou "deterministic_rule" (anti-inflação v4, trava ii). ' +
+        'O agente em runtime não pode marcar critical sem atribuição.',
+    );
+  }
+  // SF8.3: `type` de classificação é PRESERVADO no registro (ex.: ok_pattern —
+  // marcado na origem pelo runner); "hardening" tem escritor próprio (appendHardening)
+  // e é rejeitado aqui para não fabricar marca de promoção sem ref/target/aprovação.
+  if (entry.type === TYPE_HARDENING) {
+    throw new Error('pod-memory.append: type "hardening" só via appendHardening (ADR-012)');
+  }
+
+  const record = {
+    id: entry.id || `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    ts: typeof entry.ts === 'number' ? entry.ts : Date.parse(entry.ts) || Date.now(),
+    trigger: entry.trigger,
+    recommendation: entry.recommendation,
+    evidence: entry.evidence != null ? entry.evidence : { count: 1 },
+    tier,
+    attributed_by: tier === TIER_CRITICAL ? entry.attributed_by : (entry.attributed_by || null),
+    source_run_id: entry.source_run_id || null,
+  };
+  if (entry.obsolete === true) record.obsolete = true;
+  if (entry.impact != null) record.impact = entry.impact;
+  if (entry.contradicts != null) record.contradicts = entry.contradicts;
+  if (entry.type != null) record.type = entry.type; // SF8.3 — classe preservada (ex.: ok_pattern)
+
+  const paths = memoryPaths(pod, opts);
+  ensureDir(paths.dir);
+  fs.appendFileSync(paths.raw, `${JSON.stringify(record)}\n`);
+  return { ok: true, entry: record };
+}
+
+// ── (SF7.6/ADR-012) appendHardening — marcação append-only de promoção ────────
+/**
+ * Grava UMA linha JSON `{type:"hardening", ref, target, approved_by, timestamp}` no
+ * learnings.jsonl (append-only — a heurística original NUNCA é editada/removida).
+ * `ref` = dedupKey da heurística promovida; `target` é uma UNIÃO DISCRIMINADA por
+ * `kind` (DF-SF10.10-1):
+ *   kind ausente/'veto' → { pod, workflowId, step, assertion:{type,...} } (ADR-012)
+ *   kind 'knowledge'    → { pod, file, sha_before, sha_after }  — sem diff embutido
+ * Rejeita (fail-loud) registro sem ref/target/approved_by válidos, e `kind`
+ * desconhecido (nunca degrada para o ramo 'veto').
+ * @returns {{ ok: true, record }}
+ */
+function appendHardening(pod, mark, opts = {}) {
+  if (!mark || typeof mark !== 'object') {
+    throw new Error('pod-memory.appendHardening: registro deve ser um objeto');
+  }
+  if (typeof mark.ref !== 'string' || mark.ref.trim() === '') {
+    throw new Error('pod-memory.appendHardening: `ref` (dedupKey da heurística) é obrigatório');
+  }
+  const t = mark.target;
+  if (!t || typeof t !== 'object' || Array.isArray(t)) {
+    throw new Error('pod-memory.appendHardening: `target` é obrigatório (objeto)');
+  }
+  const kind = hardeningKind(t); // fail-loud em kind desconhecido
+  let target;
+  if (kind === HARDEN_KIND_KNOWLEDGE) {
+    if (typeof t.file !== 'string' || t.file.trim() === '') {
+      throw new Error(
+        'pod-memory.appendHardening: target kind "knowledge" exige `file` (nome do arquivo sob knowledge/)',
+      );
+    }
+    if (/[\\/]/.test(t.file) || t.file.includes('..')) {
+      throw new Error(
+        `pod-memory.appendHardening: target.file ${JSON.stringify(t.file)} deve ser nome SIMPLES sob knowledge/ ` +
+          '(sem separador de path nem "..") — o registro é marca de auditoria, não caminho arbitrário',
+      );
+    }
+    for (const k of ['sha_before', 'sha_after']) {
+      if (!SHA256_HEX_RE.test(String(t[k] == null ? '' : t[k]))) {
+        throw new Error(
+          `pod-memory.appendHardening: target kind "knowledge" exige \`${k}\` sha256 hex de 64 ` +
+            `(recebido: ${JSON.stringify(t[k])}) — DF-SF10.10-1`,
+        );
+      }
+    }
+    target = {
+      pod: t.pod || pod,
+      kind: HARDEN_KIND_KNOWLEDGE,
+      file: t.file,
+      sha_before: t.sha_before,
+      sha_after: t.sha_after,
+    };
+  } else {
+    // Ramo 'veto' — validação IDÊNTICA à de SF7.6, byte a byte (zero mudança de
+    // comportamento no alvo já em produção).
+    if (!t.workflowId || !t.step ||
+        !t.assertion || typeof t.assertion !== 'object' || typeof t.assertion.type !== 'string') {
+      throw new Error(
+        'pod-memory.appendHardening: `target` exige { workflowId, step, assertion:{type,...} } (ADR-012)',
+      );
+    }
+    // `kind` só é MATERIALIZADO no registro quando veio explícito: o formato legado
+    // (sem `kind`) continua sendo o emitido por default — nada em disco muda de forma.
+    target = {
+      pod: t.pod || pod,
+      ...(t.kind != null ? { kind: HARDEN_KIND_VETO } : {}),
+      workflowId: t.workflowId,
+      step: t.step,
+      assertion: t.assertion,
+    };
+  }
+  if (typeof mark.approved_by !== 'string' || mark.approved_by.trim() === '') {
+    throw new Error(
+      'pod-memory.appendHardening: `approved_by` é obrigatório — promoção sem aprovação registrada não marca (padrão --approved-by)',
+    );
+  }
+  const record = {
+    type: TYPE_HARDENING,
+    ref: mark.ref,
+    target,
+    approved_by: mark.approved_by,
+    timestamp: mark.timestamp || new Date().toISOString(),
+  };
+  const paths = memoryPaths(pod, opts);
+  ensureDir(paths.dir);
+  fs.appendFileSync(paths.raw, `${JSON.stringify(record)}\n`);
+  return { ok: true, record };
+}
+
+/** Registros de hardening do log cru (ordenados; o último por ref vence). */
+function hardeningByRef(rawRecords) {
+  const map = new Map();
+  for (const r of rawRecords) {
+    if (r && r.type === TYPE_HARDENING && typeof r.ref === 'string') {
+      const prev = map.get(r.ref);
+      if (!prev || String(r.timestamp || '') >= String(prev.timestamp || '')) map.set(r.ref, r);
+    }
+  }
+  return map;
+}
+
+/**
+ * Separa registros de hardening E entradas ok_pattern das heurísticas (uso interno).
+ * SF8.3: ok_pattern sai do pool ANTES de merge/conflito/ranking — mesmo padrão dos
+ * hardenings; ambos permanecem no log cru (append-only, auditoria intacta).
+ */
+function splitRaw(rawRecords) {
+  const hardenings = [];
+  const okPatterns = [];
+  const entries = [];
+  for (const r of rawRecords) {
+    if (r && r.type === TYPE_HARDENING) hardenings.push(r);
+    else if (isOkPattern(r)) okPatterns.push(r);
+    else entries.push(r);
+  }
+  return { hardenings, okPatterns, entries };
+}
+
+// ── Leitura do log cru (uso interno — nunca exposto ao agente) ────────────────
+function readRawEntries(rawPath) {
+  if (!fs.existsSync(rawPath)) return [];
+  return fs.readFileSync(rawPath, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+// ── merge idempotente de um .jsonl de auditoria (conflitos, arquivados) ────────
+// Funde os registros já em disco com os novos, dedup por `keyFn`, ordena pela chave
+// (determinístico) e reescreve. Novos sobrescrevem homônimos; antigos ausentes dos
+// novos (ex.: fonte já rotacionada) são PRESERVADOS. Bytes idênticos em reexecução.
+function mergeJsonlByKey(filePath, newRecords, keyFn) {
+  const existing = fs.existsSync(filePath)
+    ? fs.readFileSync(filePath, 'utf8').split('\n').map((l) => l.trim()).filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean)
+    : [];
+  const byKey = new Map();
+  for (const r of existing) byKey.set(keyFn(r), r);
+  for (const r of newRecords) byKey.set(keyFn(r), r); // novos vencem
+  const sorted = [...byKey.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map(([, r]) => r);
+  fs.writeFileSync(filePath, sorted.map((r) => `${JSON.stringify(r)}\n`).join(''));
+}
+
+// ── dedup/merge — agrupa por dedupKey, soma ocorrências/evidência ─────────────
+function mergeEntries(entries) {
+  const byKey = new Map();
+  for (const e of entries) {
+    const key = dedupKey(e);
+    const prev = byKey.get(key);
+    if (!prev) {
+      byKey.set(key, {
+        ...e,
+        occurrences: 1,
+        _evidence: evidenceCount(e),
+        _obsolete: e.obsolete === true,
+        _ids: [e.id],
+      });
+    } else {
+      prev.occurrences += 1;
+      prev._evidence += evidenceCount(e);
+      prev._ids.push(e.id);
+      // mantém a mais recente como representante (recência + estado obsolete atual)
+      if ((e.ts || 0) >= (prev.ts || 0)) {
+        prev.ts = e.ts;
+        prev.recommendation = e.recommendation;
+        prev.tier = e.tier || prev.tier;
+        prev.attributed_by = e.attributed_by || prev.attributed_by;
+        prev._obsolete = e.obsolete === true;
+        if (e.impact != null) prev.impact = e.impact;
+        if (e.contradicts != null) prev.contradicts = e.contradicts;
+      }
+    }
+  }
+  return [...byKey.values()];
+}
+
+// ── (c) detecção/resolução de conflito ────────────────────────────────────────
+// Heurística determinística documentada (NÃO NLP): duas heurísticas conflitam se
+//   (1) campo estruturado explícito `contradicts: <id>` casa, OU
+//   (2) mesmo trigger normalizado + mesmo núcleo de recomendação (sem tokens de
+//       negação) + POLARIDADE oposta (uma afirma, a outra nega a mesma ação).
+// Desempate ORDENADO (SPEC §G1): 1º `evidence.count` maior; 2º `ts` mais recente.
+function detectConflicts(merged) {
+  const conflicts = [];
+  const loserKeys = new Set();
+  if (merged.length === 0) return { conflicts, loserKeys };
+
+  // índice de qualquer id (inclui os fundidos em _ids) → entrada representante
+  const idIndex = new Map();
+  for (const m of merged) {
+    for (const id of (m._ids || [m.id])) idIndex.set(id, m);
+  }
+
+  // grafo de conflito por índice em `merged`; arestas ligam pares em conflito
+  const idxOf = new Map(merged.map((m, i) => [m, i]));
+  const adj = merged.map(() => new Set());
+  const link = (a, b) => {
+    const i = idxOf.get(a);
+    const j = idxOf.get(b);
+    if (i !== undefined && j !== undefined && i !== j) {
+      adj[i].add(j);
+      adj[j].add(i);
+    }
+  };
+
+  // (1) contradição EXPLÍCITA via campo estruturado `contradicts: <id>` (cruza
+  //     cores/triggers diferentes — não depende da heurística de negação).
+  for (const m of merged) {
+    if (m.contradicts != null && idIndex.has(m.contradicts)) {
+      link(m, idIndex.get(m.contradicts));
+    }
+  }
+
+  // (2) POLARIDADE oposta dentro do mesmo conflictKey (mesmo trigger + mesmo
+  //     núcleo de recomendação, uma afirma e a outra nega).
+  const groups = new Map();
+  for (const m of merged) {
+    const k = conflictKey(m);
+    if (!groups.has(k)) groups.set(k, []);
+    groups.get(k).push(m);
+  }
+  for (const key of [...groups.keys()].sort()) {
+    const group = groups.get(key);
+    if (group.length < 2) continue;
+    const positives = group.filter((g) => !polarity(g.recommendation));
+    const negatives = group.filter((g) => polarity(g.recommendation));
+    for (const p of positives) for (const n of negatives) link(p, n);
+  }
+
+  const lastId = (m) => (m._ids ? m._ids[m._ids.length - 1] : m.id);
+  const record = (winner, loser, bothCritical, resolution) => {
+    conflicts.push({
+      // ts DETERMINÍSTICO derivado do vencedor (M1) — não do relógio; garante
+      // byte-idempotência de conflicts.jsonl (não Date.now()).
+      ts: winner.ts || 0,
+      trigger: winner.trigger,
+      winner_id: lastId(winner),
+      winner_recommendation: winner.recommendation,
+      loser_id: lastId(loser),
+      loser_recommendation: loser.recommendation,
+      criterion: bothCritical ? 'evidence.count desc, ts desc' : 'critical-protected (piso categórico)',
+      both_critical: bothCritical,
+      resolution,
+    });
+  };
+
+  // componentes conexos. Iteração em ordem de índice = reprodutível.
+  const seen = new Array(merged.length).fill(false);
+  let criticalConflictNeedsCuration = false;
+  for (let i = 0; i < merged.length; i++) {
+    if (seen[i] || adj[i].size === 0) continue;
+    const comp = [];
+    const stack = [i];
+    while (stack.length) {
+      const x = stack.pop();
+      if (seen[x]) continue;
+      seen[x] = true;
+      comp.push(merged[x]);
+      for (const y of adj[x]) if (!seen[y]) stack.push(y);
+    }
+
+    // ── H1 fix: CRITICAL é PISO CATEGÓRICO (SPEC §G1 item e) ──────────────────
+    // Um CRITICAL ativo SÓ pode perder conflito para OUTRO CRITICAL. Conflito
+    // CRITICAL×NORMAL NUNCA despeja o pin: o lado normal é rebaixado, o pin
+    // permanece, o conflito é registrado e sinaliza needsCuration (a resolução é
+    // curadoria humana, jamais automática).
+    const activeCriticals = comp.filter(isActiveCritical);
+    const nonCriticals = comp.filter((m) => !isActiveCritical(m));
+
+    if (activeCriticals.length === 0) {
+      // conflito puramente NORMAL — resolução por evidência (comportamento original)
+      const ranked = [...comp].sort(compareConflict);
+      const winner = ranked[0];
+      for (let k = 1; k < ranked.length; k++) {
+        loserKeys.add(dedupKey(ranked[k]));
+        record(winner, ranked[k], false, 'evidence');
+      }
+      continue;
+    }
+
+    // Há ≥1 CRITICAL ativo no componente.
+    // (a) crit-vs-crit: entre os CRITICAIS, resolução por evidência é PERMITIDA
+    //     (SPEC: "resolução de conflito entre DOIS CRITICALs"). Top critical vence;
+    //     os demais criticais perdem — mas só entre eles, nunca para um normal.
+    const rankedCriticals = [...activeCriticals].sort(compareConflict);
+    const survivingCritical = rankedCriticals[0];
+    for (let k = 1; k < rankedCriticals.length; k++) {
+      loserKeys.add(dedupKey(rankedCriticals[k]));
+      record(survivingCritical, rankedCriticals[k], true, 'evidence');
+    }
+    // (b) todo NORMAL em conflito com um pin perde; o pin PERMANECE. Sinaliza
+    //     curadoria humana (needsCuration), nunca resolvido automaticamente.
+    for (const nc of nonCriticals) {
+      loserKeys.add(dedupKey(nc));
+      record(survivingCritical, nc, false, 'critical-protected');
+      criticalConflictNeedsCuration = true;
+    }
+  }
+  return { conflicts, loserKeys, needsCuration: criticalConflictNeedsCuration };
+}
+
+// CRITICAL ATIVO = tier critical + atribuição válida + não obsoleto (piso do pin)
+function isActiveCritical(m) {
+  return m.tier === TIER_CRITICAL && VALID_ATTRIBUTION.has(m.attributed_by) && !m._obsolete;
+}
+
+// vencedor primeiro: maior evidência; empate → mais recente; empate → id estável
+function compareConflict(a, b) {
+  if (b._evidence !== a._evidence) return b._evidence - a._evidence;
+  if ((b.ts || 0) !== (a.ts || 0)) return (b.ts || 0) - (a.ts || 0);
+  return String(a.id).localeCompare(String(b.id));
+}
+
+// ── rerank determinístico: frequência × recência × impacto ────────────────────
+function scoreEntries(entries) {
+  const tsList = entries.map((e) => e.ts || 0);
+  const minTs = Math.min(...tsList, 0);
+  const maxTs = Math.max(...tsList, 1);
+  const span = maxTs - minTs || 1;
+  for (const e of entries) {
+    const freq = Math.max(1, e.occurrences || 1);
+    const recency = 1 + (((e.ts || 0) - minTs) / span); // [1,2], newer = maior
+    const impact = impactOf(e);
+    e._score = freq * recency * impact;
+  }
+  // ordena por score desc; desempate reprodutível: ts desc, depois id asc
+  entries.sort((a, b) => {
+    if (b._score !== a._score) return b._score - a._score;
+    if ((b.ts || 0) !== (a.ts || 0)) return (b.ts || 0) - (a.ts || 0);
+    return String(a.id).localeCompare(String(b.id));
+  });
+  return entries;
+}
+
+// ── render do consolidado (.md) ───────────────────────────────────────────────
+function renderConsolidated(pod, pins, ranked, hardened = []) {
+  const lines = [];
+  lines.push(`# Memória consolidada — ${pod}`);
+  lines.push('');
+  lines.push('> Curado por pod-memory.cjs (SF2.1). Único artefato de memória lido pelo agente.');
+  lines.push('> Log cru (learnings.jsonl) NÃO é lido pelo agente — auditoria apenas.');
+  lines.push('');
+  if (pins.length > 0) {
+    lines.push('## CRITICAL (pinado)');
+    lines.push('');
+    lines.push('_Piso categórico — nunca despejado por poda/rotação. Sai só por curadoria._');
+    lines.push('');
+    for (const p of pins) {
+      lines.push(`- **[${p.trigger}]** ${p.recommendation} _(fonte: ${p.attributed_by})_`);
+    }
+    lines.push('');
+  }
+  lines.push('## Heurísticas (top-N)');
+  lines.push('');
+  if (ranked.length === 0) {
+    lines.push('_Nenhuma heurística consolidada ainda._');
+  } else {
+    for (const r of ranked) {
+      lines.push(`- **[${r.trigger}]** ${r.recommendation} _(x${r.occurrences})_`);
+    }
+  }
+  lines.push('');
+  // SF7.6/ADR-012 — endurecidas: FORA do top-N ativo (não competem por injeção),
+  // NUNCA removidas. SF11.4/ADR-022 (DF-SF11.4-1) — e agora também fora do INLINE:
+  // o detalhe (asserção, aprovador, momento) migrou para `memory/learnings.hardened.md`
+  // e aqui fica uma REFERÊNCIA AGREGADA. Motivo medido: a linha inline de cada
+  // endurecida é um PONTEIRO para um arquivo de knowledge que já é leitura obrigatória
+  // da etapa (ADR-021) — era 53,5% do artefato orçado e 40,3% do brief da run, gastos
+  // repetindo o que o agente já é obrigado a ler. ADR-021/DF-SF11.2-3 rege o caminho:
+  // rebaixar a REFERÊNCIA nomeada e visível, nunca DESCARTAR em silêncio.
+  if (hardened.length > 0) {
+    const counts = new Map();
+    for (const h of hardened) {
+      // hardeningTargetLabel valida a FORMA do registro (fail-loud, DF-SF10.10-1):
+      // um `knowledge/undefined` somado num agregado seria pior que inline (some no total).
+      const label = hardeningTargetLabel(h);
+      counts.set(label, (counts.get(label) || 0) + 1);
+    }
+    const summary = [...counts.entries()]
+      .sort((a, b) => String(a[0]).localeCompare(String(b[0])))
+      .map(([label, n]) => `${label} (${n})`)
+      .join(', ');
+    lines.push('## Endurecidas (🔒 → enforcement)');
+    lines.push('');
+    lines.push(
+      `_${hardened.length} heurística(s) já viraram forma canônica do pod — enforcement substitui injeção: ${summary}. ` +
+      'O knowledge citado é LEITURA OBRIGATÓRIA da etapa e o veto citado bloqueia em disco; por isso o texto delas não é reinjetado aqui._',
+    );
+    lines.push(`_Detalhe auditável (asserção, aprovador, momento): ${HARDENED_DETAIL_REL} — append-only, nunca podado._`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Rótulo do ALVO de um registro de hardening — `knowledge/<file>` ou `veto <tipo> em
+ * <etapa>`. Fonte ÚNICA do rótulo para os dois consumidores (a referência agregada do
+ * consolidado e a trilha auditável), e ponto ÚNICO do fail-loud de forma: registro
+ * malformado LANÇA com mensagem acionável em vez de renderizar calado
+ * "knowledge/undefined" (SF10.10/DF-SF10.10-1; `appendHardening` já rejeita na origem —
+ * aqui é a simetria para log editado à mão).
+ */
+function hardeningTargetLabel(h) {
+  const t = (h.mark && h.mark.target) || {};
+  const kind = hardeningKind(t); // ausente ⇒ 'veto'; desconhecido ⇒ throw
+  if (kind === HARDEN_KIND_KNOWLEDGE) {
+    if (typeof t.file !== 'string' || t.file.trim() === '' ||
+        /[\\/]/.test(t.file) || t.file.includes('..')) {
+      throw new Error(
+        `pod-memory: registro de hardening kind "knowledge" malformado (ref: ${h.mark.ref}) — ` +
+          `target.file deve ser nome simples sob knowledge/ (recebido: ${JSON.stringify(t.file)}). ` +
+          'Registro corrompido no log cru; corrija a origem (appendHardening valida).',
+      );
+    }
+    return `knowledge/${t.file}`;
+  }
+  if (!t.assertion || typeof t.assertion.type !== 'string' || !t.step) {
+    throw new Error(
+      `pod-memory: registro de hardening kind "veto" malformado (ref: ${h.mark.ref}) — ` +
+        'exige target.step e target.assertion.type. Registro corrompido no log cru; corrija a origem (appendHardening valida).',
+    );
+  }
+  return `veto ${t.assertion.type} em ${t.step}`;
+}
+
+/**
+ * (SF11.4/ADR-022 DF-SF11.4-1) Trilha auditável das endurecidas — o DETALHE que saiu do
+ * artefato injetado. Linha por endurecida, no MESMO formato que o consolidado emitia
+ * inline (nada de formato novo de dado — ADR-012:80: o que é de tamanho não-limitado
+ * pertence ao git, não ao artefato orçado).
+ */
+function renderHardenedDetail(pod, hardened) {
+  const lines = [];
+  lines.push(`# Endurecidas (🔒) — trilha auditável — ${pod}`);
+  lines.push('');
+  lines.push('> Escrita por pod-memory.cjs (SF11.4/ADR-022). APPEND-ONLY: sem poda, sem teto.');
+  lines.push('> ARTEFATO DE AUDITORIA — fora do caminho de injeção: o agente NÃO lê este arquivo');
+  lines.push('> (lê só learnings.consolidated.md, que cita a referência agregada). Não viaja no bundle do export.');
+  lines.push('');
+  for (const h of hardened) {
+    lines.push(
+      `${HARDENED_DETAIL_BULLET}**[${h.entry.trigger}]** ${h.entry.recommendation} — endurecida → ${hardeningTargetLabel(h)} _(por ${h.mark.approved_by}, ${h.mark.timestamp})_`,
+    );
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function estTokens(str) {
+  return Math.ceil(Buffer.byteLength(str, 'utf8') / 4);
+}
+
+// ── computeConsolidation — o CÁLCULO da consolidação, SEM ESCRITA ─────────────
+/**
+ * (SF10.10) Extraído de `consolidate` para que a listagem de candidatos (DF-SF10.10-3)
+ * use EXATAMENTE o mesmo conjunto curado, sem duplicar regra e sem escrever nada.
+ * READ-ONLY: lê o log cru e devolve o estado curado + o .md renderizado; quem escreve
+ * é `consolidate`. Determinística: mesmo log ⇒ mesmo resultado.
+ */
+function computeConsolidation(pod, opts = {}) {
+  const paths = memoryPaths(pod, opts);
+  // SF7.6: registros de hardening são MARCA, não heurística — separados antes do
+  // merge (não entram em dedup/conflito/ranking). SF8.3: ok_pattern idem — trilha
+  // de auditoria de estabilidade no log cru, nunca compete por slot do top-N.
+  const { hardenings, okPatterns, entries: rawHeuristics } = splitRaw(readRawEntries(paths.raw));
+  const raw = rawHeuristics;
+  const hardenedRefs = hardeningByRef(hardenings);
+  const merged = mergeEntries(raw);
+
+  // conflito primeiro — perdedores são removidos do pool e arquivados. Um
+  // CRITICAL ativo NUNCA é perdedor de conflito com NORMAL (H1 fix): detectConflicts
+  // protege o pin e sinaliza needsCuration quando isso ocorre.
+  const { conflicts, loserKeys, needsCuration: conflictNeedsCuration } = detectConflicts(merged);
+  const survivors = merged.filter((m) => !loserKeys.has(dedupKey(m)));
+
+  // separa pinados (critical, atribuição válida, não obsoleto) do pool normal
+  const activeCritical = survivors.filter(isActiveCritical);
+  const normalPool = survivors.filter((m) => !isActiveCritical(m) && !m._obsolete);
+
+  // ── SF7.6/ADR-012: DEMOÇÃO das endurecidas do top-N ativo ──────────────────
+  // Heurística com registro de hardening sai do conjunto que compete por injeção
+  // (orçamento finito; enforcement substitui injeção) e vira anotação 🔒 —
+  // permanece no consolidado e no log cru (nunca removida).
+  const hardened = [];
+  const normals = [];
+  for (const m of normalPool) {
+    const mark = hardenedRefs.get(dedupKey(m));
+    if (mark) hardened.push({ entry: m, mark });
+    else normals.push(m);
+  }
+  // ordem determinística da seção 🔒: timestamp da promoção asc, depois ref asc
+  hardened.sort((a, b) =>
+    String(a.mark.timestamp).localeCompare(String(b.mark.timestamp)) ||
+    String(a.mark.ref).localeCompare(String(b.mark.ref)));
+
+  // ── trava (iii): teto ≤10 do conjunto pinado ──────────────────────────────
+  // ordem determinística dos pins: ts asc (lições mais antigas são fundacionais),
+  // depois id asc. Excedente vai p/ overflow (retido, sinalizado, NUNCA escrito
+  // como pin permanente nem descartado do log cru).
+  const pinsSorted = [...activeCritical].sort((a, b) =>
+    ((a.ts || 0) - (b.ts || 0)) || String(a.id).localeCompare(String(b.id)));
+  const pins = pinsSorted.slice(0, PIN_CAP);
+  const overflow = pinsSorted.slice(PIN_CAP).map((p) => ({
+    id: p._ids ? p._ids[p._ids.length - 1] : p.id,
+    trigger: p.trigger,
+    recommendation: p.recommendation,
+  }));
+  // needsCuration dispara por TRÊS vias: teto de pins estourado (trava iii), conflito
+  // CRITICAL×NORMAL (H1 — resolução é curadoria humana, não automática) OU heurística
+  // ativa NÃO ADMITIDA no consolidado (SF11.4b/DF-SF11.4b-1 — pelas DUAS vias de corte,
+  // calculadas abaixo em `admit`).
+
+  // ── ADMISSÃO ÚNICA: ranking + os DOIS cortes num só ponto ──────────────────
+  const scored = scoreEntries(normals);
+  const budget = effectiveTokenBudget(pod, opts);
+  const { ranked, evicted, md } = admit(scored, {
+    budgetTokens: budget.tokens,
+    render: (list) => renderConsolidated(pod, pins, list, hardened),
+  });
+
+  const needsCuration = pinsSorted.length > PIN_CAP || conflictNeedsCuration || evicted.length > 0;
+
+  return {
+    paths, merged, loserKeys, conflicts, pins, ranked, hardened, hardenedRefs,
+    md, needsCuration, overflow, evicted, okPatterns,
+    // SF11.4b/DF-SF11.4b-2 — orçamento EFETIVO desta consolidação e o alvo declarado
+    // (ou `null`). Campos ADITIVOS: o ledger precisa deles para nomear a causa do corte
+    // por custo sem que cada emissor releia o manifesto por conta própria.
+    tokenBudget: budget.tokens, memoryCost: budget.target,
+  };
+}
+
+/**
+ * (SF11.4b/ADR-023 DF-SF11.4b-1) **Admissão única** — um ponto de corte, um campo, um
+ * canal. Tudo que fica FORA de `ranked` entra em `evicted` com `reason`, seja qual for
+ * a via: `'top_n'` (teto de ATENÇÃO) ou `'budget'` (alvo/teto de CUSTO em bytes).
+ *
+ * POR QUE UM SÓ CAMPO, E NÃO UM `truncated` SEPARADO (Alternativa 1 do ADR-023,
+ * RECUSADA): a semântica dos dois eventos é IDÊNTICA — heurística ativa, que não existe
+ * em outro lugar do brief, que não foi injetada. Dois campos para um evento
+ * reproduziriam o sub-relato num terceiro lugar: quem lê `evicted.length` continuaria
+ * vendo "1" com 13 fora. `reason` é fato observável sobre QUAL caminho removeu a
+ * entrada — sem limiar, sem julgamento (DF4-5 satisfeito).
+ *
+ * O DEFEITO QUE ISTO FECHA (medido, ADR-023 §C1-C2): `scored.slice(0, TOP_N)` cortava
+ * ANTES de qualquer checagem de orçamento e não escrevia em `evicted`, não ligava
+ * `needsCuration`, não emitia linha nenhuma. Em pool 42 do `hn-carousel`, 13 heurísticas
+ * ficavam fora do brief e o runner anunciava **1** — sub-relato de 13×, classe PIOR que
+ * o silêncio (dá conforto e não sustenta a linha).
+ *
+ * ORDEM: `evicted` traz primeiro os cortes por atenção (score DESC — os que ficaram
+ * logo abaixo do teto vêm na frente) e depois os por custo (a cauda sai por último).
+ * Determinístico: mesmo pool ⇒ mesmo `evicted`, item a item.
+ *
+ * @param {Array} scored pool ativo já ranqueado (score DESC); pinados e 🔒 fora
+ * @param {{budgetTokens:number, render:(list:Array)=>string}} o
+ * @returns {{ranked:Array, evicted:Array, md:string}}
+ */
+function admit(scored, { budgetTokens, render }) {
+  const evicted = [];
+  // ponto ÚNICO de registro de não-admissão: as duas vias passam por aqui, então
+  // nenhuma pode ficar muda sozinha. O corte por TOP_N ficou mudo por três ADRs
+  // justamente por ter um caminho próprio, sem passar por registro nenhum.
+  const drop = (entry, reason) => {
+    evicted.push({
+      trigger: entry.trigger,
+      recommendation: entry.recommendation,
+      score: entry._score,
+      reason,
+    });
+  };
+
+  // (1) teto de ATENÇÃO — TOP_N. Corta o excedente do pool ranqueado, COM VOZ.
+  let ranked = scored.slice(0, TOP_N);
+  for (const out of scored.slice(TOP_N)) drop(out, 'top_n');
+
+  // (2) alvo/teto de CUSTO — remove os de MENOR score (cauda) até o .md caber no
+  // orçamento efetivo. Pinados são piso categórico e nunca entram nesta poda;
+  // endurecidas (🔒) são referência agregada (nunca removidas — ADR-012), tampouco
+  // podadas. `evicted` é campo próprio, não sobrecarga de `overflow` (que tem semântica
+  // definida: excedente do teto de pins CRITICAL, RETIDO).
+  let md = render(ranked);
+  while (ranked.length > 0 && estTokens(md) > budgetTokens) {
+    drop(ranked[ranked.length - 1], 'budget');
+    ranked = ranked.slice(0, ranked.length - 1);
+    md = render(ranked);
+  }
+  return { ranked, evicted, md };
+}
+
+/**
+ * (SF11.4b/ADR-023 DF-SF11.4b-1) **Ledger de curadoria** — fonte ÚNICA da mensagem que
+ * os emissores imprimem. Existe como função, e não como string em cada emissor, por uma
+ * exigência do desenho: **nenhum emissor pode imprimir um número que não seja
+ * `evicted.length` total**. O total vem primeiro; a quebra por `reason` depois; o custo
+ * por último. Um emissor que conhecesse só uma das vias voltaria a dizer "1" com 13 fora.
+ *
+ * Unidade declarada DENTRO da mensagem: tokens = `Math.ceil(bytes UTF-8 / 4)` — o mesmo
+ * `estTokens` do mecanismo (a divergência UTF-16×UTF-8 já custou uma medição na SF11.2).
+ *
+ * @param {string} pod
+ * @param {object} result retorno de `consolidate()` (ou de `computeConsolidation`)
+ * @returns {string|null} `null` quando nada ficou de fora — nada a reportar
+ */
+function formatEvictionLedger(pod, result) {
+  const evicted = Array.isArray(result && result.evicted) ? result.evicted : [];
+  if (evicted.length === 0) return null;
+  const byTopN = evicted.filter((e) => e.reason === 'top_n').length;
+  const byBudget = evicted.filter((e) => e.reason === 'budget').length;
+  const unclassified = evicted.length - byTopN - byBudget;
+  const budget = (result && result.tokenBudget) || TOKEN_BUDGET;
+  const parts = [];
+  if (byTopN > 0) parts.push(`${byTopN} por teto de atenção TOP_N=${TOP_N}`);
+  if (byBudget > 0) parts.push(`${byBudget} por ${result && result.memoryCost ? 'alvo' : 'teto'} de custo ${budget} tok`);
+  if (unclassified > 0) parts.push(`${unclassified} sem causa registrada`);
+  const names = evicted.map((e) => `"${e.trigger}"`).join(', ');
+  const tokens = result && typeof result.tokens === 'number' ? result.tokens : null;
+  const steps = result && result.memoryCost ? result.memoryCost.steps : null;
+  const lines = [
+    `[memory] AVISO: ${evicted.length} heurística(s) NÃO entraram no consolidado do pod "${pod}"` +
+      ` (${parts.join(' · ')}): ${names}`,
+  ];
+  if (tokens != null) {
+    lines.push(steps
+      ? `  Custo do consolidado: ${tokens} tok/etapa × ${steps} etapa(s) = ${tokens * steps} tok/rodada` +
+        ' (tokens = ceil(bytes UTF-8 / 4); o consolidado entra INTEGRAL no brief de cada etapa).'
+      : `  Custo do consolidado: ${tokens} tok/etapa (tokens = ceil(bytes UTF-8 / 4); o consolidado entra` +
+        ' INTEGRAL no brief de cada etapa — declare "memoryCost.steps" no pod-spec.json para ver o custo/rodada).');
+  }
+  lines.push('  A substância continua no log cru — nada foi apagado. Para abrir espaço: cure o consolidado' +
+    ' (marque redundância como obsolete) ou endureça (*harden-learning — promover LIBERA orçamento, ADR-022 DF-SF11.4-1).');
+  return lines.join('\n');
+}
+
+// ── (b)/(e)/(f) consolidate ───────────────────────────────────────────────────
+/**
+ * Lê o log cru, deduz/mescla, resolve conflito, aplica ranking, poda ao top-N e ao
+ * budget de tokens, pina os CRITICAL (fora do ranking, com teto ≤10), e escreve o
+ * learnings.consolidated.md. Idempotente. Função PURA/chamável (o disparo por
+ * cadência K é do CALLER/SF2.2).
+ * @returns {{ pinnedCount, topNCount, tokens, needsCuration, overflow, evicted, conflicts }}
+ */
+function consolidate(pod, opts = {}) {
+  const c = computeConsolidation(pod, opts);
+  const { paths, pins, ranked, hardened, md, merged, loserKeys, conflicts } = c;
+  ensureDir(paths.dir);
+  fs.writeFileSync(paths.consolidated, md);
+  writeHardenedDetail(paths, pod, hardened);
+
+  // registra conflitos + arquiva as perdedoras (nunca deletadas do log cru) de
+  // forma AUDITÁVEL, IDEMPOTENTE e com HISTÓRICO PRESERVADO (L3): funde os registros
+  // existentes com os recomputados, dedup por chave estável, ordena determinístico.
+  // - M1: cada registro carrega ts derivado do vencedor (não Date.now) ⇒ rodar 2x
+  //   produz bytes idênticos.
+  // - L3: registros antigos cujas fontes já rotacionaram para archive/ NÃO são
+  //   perdidos — a fusão preserva-os (§G1 "conflito registrado").
+  if (conflicts.length > 0) {
+    ensureDir(paths.archiveDir);
+    mergeJsonlByKey(paths.conflicts, conflicts, (x) => `${x.winner_id}||${x.loser_id}`);
+    const losers = merged.filter((m) => loserKeys.has(dedupKey(m)))
+      .map((m) => ({ id: m.id, trigger: m.trigger, recommendation: m.recommendation, reason: 'conflict-loser' }));
+    mergeJsonlByKey(paths.archivedEntries, losers, (m) => String(m.id));
+  }
+
+  return {
+    pinnedCount: pins.length,
+    topNCount: ranked.length,
+    tokens: estTokens(md),
+    needsCuration: c.needsCuration,
+    overflow: c.overflow,
+    // SF11.4/DF-SF11.4-2 — o que ficou FORA de `ranked` nesta consolidação. Campo
+    // ADITIVO: nenhum caller quebra por não conhecê-lo; quem conhece (pc-run-pod,
+    // forge-harden-learning, forge-ingest-memory) para de deixar a poda passar calada.
+    // SF11.4b/DF-SF11.4b-1 — cada item agora traz `reason: 'top_n' | 'budget'` e a lista
+    // é COMPLETA: as duas vias de não-injeção passam pelo mesmo campo (antes, o corte
+    // por TOP_N não aparecia aqui e o total ficava sub-relatado — ADR-023 §C2).
+    evicted: c.evicted,
+    // SF11.4b/DF-SF11.4b-2 — orçamento efetivo aplicado e o alvo declarado (ou null).
+    tokenBudget: c.tokenBudget,
+    memoryCost: c.memoryCost,
+    conflicts,
+    hardenedCount: hardened.length,
+    okPatternCount: c.okPatterns.length, // SF8.3 — fora do ranking, vivos no log cru
+  };
+}
+
+/**
+ * (SF11.4/ADR-022 DF-SF11.4-1) Escreve a trilha auditável das endurecidas.
+ *
+ * APPEND-ONLY POR CONSTRUÇÃO, não por promessa: as linhas derivadas do log cru são
+ * reescritas (determinístico ⇒ idempotente), e QUALQUER linha 🔒 já presente no arquivo
+ * que não seja derivável do log atual é PRESERVADA numa seção própria. Assim uma linha
+ * escrita aqui nunca some — nem se o registro-fonte for arquivado/perdido no log cru.
+ * Não cria o arquivo quando não há endurecida nenhuma (pod sem promoção não ganha
+ * artefato vazio).
+ */
+function writeHardenedDetail(paths, pod, hardened) {
+  const exists = fs.existsSync(paths.hardenedDetail);
+  if (hardened.length === 0 && !exists) return;
+  const derived = renderHardenedDetail(pod, hardened);
+  const derivedBullets = new Set(
+    derived.split('\n').filter((l) => l.startsWith(HARDENED_DETAIL_BULLET)),
+  );
+  let preserved = [];
+  if (exists) {
+    preserved = fs.readFileSync(paths.hardenedDetail, 'utf8')
+      .split(/\r?\n/)
+      .filter((l) => l.startsWith(HARDENED_DETAIL_BULLET) && !derivedBullets.has(l))
+      .sort(); // ordem determinística: rodar 2x produz bytes idênticos
+  }
+  let out = derived;
+  if (preserved.length > 0) {
+    out += [
+      '## Preservadas (registro-fonte não mais derivável do log cru)',
+      '',
+      '_Append-only: linha já escrita nesta trilha NUNCA é removida, mesmo que o registro que a originou saia do log cru (rotação/edição). Ver ADR-012 (endurecida nunca é removida)._',
+      '',
+      ...preserved,
+      '',
+    ].join('\n');
+  }
+  fs.writeFileSync(paths.hardenedDetail, out);
+}
+
+// ── (SF10.10/DF-SF10.10-3) listCandidates — DIFERENÇA DE CONJUNTOS, read-only ──
+/**
+ * Heurísticas que estão no CONSOLIDADO CURADO (pins + top-N já podado) e ainda NÃO
+ * têm registro de hardening — nem `veto`, nem `knowledge`. É uma diferença de
+ * conjuntos verificável, na MESMA ordem determinística em que aparecem no
+ * consolidado (pins por ts asc; ranqueadas por score desc).
+ *
+ * FRONTEIRA (vinculante, DF-SF10.10-3): esta função NÃO classifica heurística como
+ * "de conteúdo" vs "mecanizável por command_check" — não há oráculo para essa
+ * distinção, e ADR-012 §Escopo OUT reserva a tradução heurística→forma ao humano.
+ * Não escreve nada, não promove nada, não ordena por "importância" inventada.
+ * @returns {Array<{ref, trigger, recommendation, occurrences, last_id, section}>}
+ */
+function listCandidates(pod, opts = {}) {
+  const { pins, ranked, hardenedRefs } = computeConsolidation(pod, opts);
+  const pinSet = new Set(pins);
+  const out = [];
+  for (const m of [...pins, ...ranked]) {
+    const ref = dedupKey(m);
+    if (hardenedRefs.has(ref)) continue; // já endurecida (qualquer kind) ⇒ não é candidata
+    out.push({
+      ref,
+      trigger: m.trigger,
+      recommendation: m.recommendation,
+      occurrences: m.occurrences || 1,
+      last_id: m._ids && m._ids.length ? m._ids[m._ids.length - 1] : m.id,
+      section: pinSet.has(m) ? 'critical' : 'top-n',
+    });
+  }
+  return out;
+}
+
+// ── (g) rotação do log cru ────────────────────────────────────────────────────
+/**
+ * Operação SEPARADA e explícita (append permanece puramente append-only). Move as
+ * entradas mais antigas (por ts) para archive/learnings-{ts}.jsonl quando o log cru
+ * excede M=500, mantendo as M mais novas. NUNCA remove uma entrada-fonte de um
+ * CRITICAL pinado ainda ATIVO (trava (e) — "nunca despejado por rotação"): tais
+ * entradas são preservadas no log cru mesmo se antigas.
+ * @returns {{ rotated: number, kept: number, archiveFile: string|null }}
+ */
+function rotate(pod, opts = {}) {
+  const paths = memoryPaths(pod, opts);
+  const all = readRawEntries(paths.raw);
+  if (all.length <= ROTATE_M) return { rotated: 0, kept: all.length, archiveFile: null };
+
+  // registros de hardening são MARCA de auditoria (ADR-012: nunca removida) — não
+  // entram no merge e NUNCA rotacionam; suas heurísticas-fonte também ficam (a
+  // anotação 🔒 do consolidado depende delas permanecerem no log cru).
+  const { hardenings, entries: heuristicEntries } = splitRaw(all); // okPatterns rotacionam normalmente (SF8.3 — auditoria arquivável, nunca deletada)
+  const hardenedRefKeys = new Set(hardeningByRef(hardenings).keys());
+
+  // chaves dedup dos CRITICAL ativos → suas entradas-fonte nunca rotacionam
+  const activeCriticalKeys = new Set(
+    mergeEntries(heuristicEntries)
+      .filter((m) => m.tier === TIER_CRITICAL && VALID_ATTRIBUTION.has(m.attributed_by) && !m._obsolete)
+      .map((m) => dedupKey(m)),
+  );
+  const isProtected = (e) =>
+    e.type === TYPE_HARDENING ||
+    (e.tier === TIER_CRITICAL && VALID_ATTRIBUTION.has(e.attributed_by)) ||
+    activeCriticalKeys.has(dedupKey(e)) ||
+    hardenedRefKeys.has(dedupKey(e));
+
+  // ordena por ts asc; candidatas a rotação são as mais antigas NÃO protegidas
+  const indexed = all.map((e, i) => ({ e, i }));
+  indexed.sort((a, b) => ((a.e.ts || 0) - (b.e.ts || 0)) || (a.i - b.i));
+
+  const toArchive = [];
+  const keepKeys = new Set();
+  let removable = all.length - ROTATE_M;
+  for (const { e } of indexed) {
+    if (removable > 0 && !isProtected(e)) {
+      toArchive.push(e);
+      removable -= 1;
+    }
+  }
+  const archiveSet = new Set(toArchive);
+  const kept = all.filter((e) => !archiveSet.has(e));
+
+  if (toArchive.length === 0) {
+    return { rotated: 0, kept: all.length, archiveFile: null };
+  }
+
+  ensureDir(paths.archiveDir);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const archiveFile = path.join(paths.archiveDir, `learnings-${stamp}.jsonl`);
+  fs.writeFileSync(archiveFile, toArchive.map((e) => `${JSON.stringify(e)}\n`).join(''));
+  // reescreve o log cru só com as retidas (rotação NÃO deleta — arquiva)
+  fs.writeFileSync(paths.raw, kept.map((e) => `${JSON.stringify(e)}\n`).join(''));
+  void keepKeys;
+  return { rotated: toArchive.length, kept: kept.length, archiveFile };
+}
+
+// ── (h.6 / AC10) contrato "agente nunca lê cru" ──────────────────────────────
+/**
+ * ÚNICA fonte de conteúdo-para-brief que um consumidor (SF2.2) usa. Retorna
+ * EXCLUSIVAMENTE o conteúdo do consolidado curado. NÃO abre, referencia nem recebe
+ * o path do log cru — verificável por inspeção do corpo desta função na suíte.
+ * @returns {string} conteúdo do learnings.consolidated.md (ou '' se ausente).
+ */
+function getConsolidatedForBrief(pod, opts = {}) {
+  const consolidatedPath = memoryPaths(pod, opts).consolidated;
+  if (!fs.existsSync(consolidatedPath)) return '';
+  return fs.readFileSync(consolidatedPath, 'utf8');
+}
+
+module.exports = {
+  append,
+  appendHardening,
+  consolidate,
+  rotate,
+  getConsolidatedForBrief,
+  // SF10.10 — 2º alvo de promoção (knowledge) + detecção de candidatos
+  listCandidates,
+  computeConsolidation,
+  hardeningKind,
+  HARDEN_KIND_VETO,
+  HARDEN_KIND_KNOWLEDGE,
+  // SF11.4/ADR-022 — trilha auditável das endurecidas (fora do caminho de injeção)
+  HARDENED_DETAIL_FILE,
+  HARDENED_DETAIL_REL,
+  renderHardenedDetail,
+  // SF11.4b/ADR-023 — admissão única: ledger (fonte ÚNICA da mensagem dos emissores),
+  // alvo de custo declarado pelo dono e orçamento efetivo.
+  formatEvictionLedger,
+  readMemoryCost,
+  effectiveTokenBudget,
+  POD_SPEC_FILE,
+  MEMORY_COST_FIELD,
+  // helpers exportados p/ a suíte (não fazem parte do contrato de consumo)
+  memoryPaths,
+  detectConflicts,
+  mergeEntries,
+  normalizeText,
+  dedupKey,
+  TYPE_HARDENING,
+  TYPE_OK_PATTERN,
+  isOkPattern,
+  // constantes do ADR-003
+  TOP_N,
+  ROTATE_M,
+  CONSOLIDATE_K,
+  TOKEN_BUDGET,
+  PIN_CAP,
+};