@daniellins/power-claude 0.16.3

package/scripts/pod-memory-note.cjs

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * pod-memory-note.cjs — Story SF11.5 / ADR-020 §Revisão 3 (`DF-SF10.21-15` a `-19`).
+ *
+ * O comentário que o DONO digita no checkpoint bloqueante (ao `approve` ou ao `revise`)
+ * vira uma entrada de aprendizado do pod. Invocador FINO sobre `podMemory.append` — a
+ * captura vive na CAMADA DO COMANDO, nunca no motor:
+ *
+ *   - `pc-run-pod.cjs` fica INTOCADO (`DF-SF10.21-15`). `approve`/`revise` continuam
+ *     decidindo transição e só isso; o que o humano PENSOU do artefato não é insumo de
+ *     transição de máquina de estados.
+ *   - Este script NÃO importa `pc-run-pod.cjs`. O único acoplamento ao motor é a LEITURA
+ *     do `state.json` que ele já escreve (`pod`, `run_id`, `steps`) — verificável por grep.
+ *
+ * VÃO QUE ISTO FECHA (medido em código, não hipótese): `revise()` não appenda NADA. Um
+ * artefato que passou em todos os vetos e ainda assim foi reprovado pelo dono desaparecia
+ * sem deixar o porquê — a informação mais valiosa do pod (`DF-SF10.21-17`).
+ *
+ * A MENSAGEM NUNCA VIAJA POR ARGV (`DF-SF10.21-15`, razão explícita de recusa da opção
+ * `node -e` inline): o texto do dono tem aspas, acentos e quebras de linha, e argv é
+ * visível em `ps` e no histórico do shell. Só `--file <arquivo>` ou stdin. Qualquer flag
+ * de texto livre (`--message`, `--comment`, ...) é ERRO DE USO explícito, não silêncio.
+ *
+ * SILÊNCIO NÃO VIRA LEARNING (`DF-SF10.21-17`): o comentário é OPCIONAL — a opcionalidade
+ * vive no COMANDO, que simplesmente não invoca este script quando o dono não comenta.
+ * Este script invocado com mensagem vazia é CHAMADA ERRADA: exit 2, zero append, nunca
+ * uma entrada fabricada.
+ *
+ * `attributed_by` é o ENUM FECHADO de `pod-memory.cjs` (`VALID_ATTRIBUTION = {human,
+ * deterministic_rule}`) — NÃO é nome de pessoa. Aqui é sempre a string literal "human"
+ * (`DF-SF10.21-16`): a proveniência humana é preservada também em `tier: normal`, sem
+ * gastar slot de pin. NÃO CONFUNDIR com `pod-spec.json → memoryCost.acceptedBy`
+ * ("Alexa Exemplo"), que é atribuição NOMINAL de outro campo, com outro propósito.
+ * Omitir `attributed_by` cairia em `null` em silêncio (`pod-memory.cjs:351`, o default só
+ * é cobrado em `critical`) — por isso o literal é fixado aqui e testado por igualdade.
+ *
+ * Uso:
+ *   node scripts/pod-memory-note.cjs --state <state.json> \
+ *        --workflow-file <pods/<pod>/workflows/wf-*.yaml> \
+ *        --step <id> --verdict approve|revise \
+ *        [--file <arquivo com o comentário>]   (omitido ⇒ lê stdin) \
+ *        [--tier critical] [--pod-root <dir>]
+ *
+ * Exit: 0 gravado · 2 erro de uso (inclui mensagem vazia) · 1 falha de execução.
+ * Node >= 18, sem dependências externas.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const podMemory = require('./pod-memory.cjs');
+const { podRootFor } = require('./validate-pod-workflow.cjs');
+
+const VERDICTS = new Set(['approve', 'revise']);
+// Espelham `pod-memory.cjs:80-81` (TIER_NORMAL/TIER_CRITICAL não estão no module.exports
+// da biblioteca — copiar o literal é o único caminho sem editar o contrato dela).
+const TIER_NORMAL = 'normal';
+const TIER_CRITICAL = 'critical';
+// Rótulo determinístico por veredito — o `trigger` NUNCA é fabricado a partir do conteúdo
+// do comentário (texto livre do dono viraria chave de dedup imprevisível). A "história" do
+// julgamento vive em `recommendation` (verbatim) e em `evidence`/`source_run_id`.
+const VERDICT_LABEL = { approve: 'aprovado', revise: 'revisado' };
+// ENUM de pod-memory.cjs — NUNCA um nome próprio (ver cabeçalho).
+const ATTRIBUTED_BY_HUMAN = 'human';
+// Classe do registro, preservada por `append` (SF8.3). Marca de auditoria: distingue o
+// julgamento humano do checkpoint dos registros que o runner monta sozinho
+// (`verification_failed`, `ok_pattern`). Não altera dedup/ranking/poda.
+const TYPE_CHECKPOINT_COMMENT = 'checkpoint_comment';
+
+/** Erro de USO (o chamador errou): a CLI traduz para exit 2. */
+class UsageError extends Error {}
+
+// ---------------------------------------------------------------------------
+// Núcleo puro (testável sem CLI)
+// ---------------------------------------------------------------------------
+
+/**
+ * Apara SOMENTE as bordas em branco (artefato de arquivo/stdin: o editor acrescenta `\n`
+ * final). O conteúdo INTERNO é preservado byte a byte — aspas, acentos e quebras de linha
+ * do dono chegam íntegros ao log cru.
+ */
+function normalizeMessage(raw) {
+  return String(raw == null ? '' : raw).replace(/^\uFEFF/, '').trim();
+}
+
+/** True quando o dono não disse nada (silêncio não vira learning). */
+function isSilence(raw) {
+  return normalizeMessage(raw) === '';
+}
+
+/**
+ * Monta a entrada de memória a partir do julgamento humano. Determinística: mesmo
+ * (step, verdict, message, runId) ⇒ mesma entrada, exceto `id`/`ts` (do motor).
+ * @returns {object} entry no contrato público de `podMemory.append`
+ */
+function buildNoteEntry({ step, verdict, message, runId, tier }) {
+  if (!step || typeof step !== 'string' || step.trim() === '') {
+    throw new UsageError('pod-memory-note: --step é obrigatório (id da etapa do checkpoint)');
+  }
+  if (!VERDICTS.has(verdict)) {
+    throw new UsageError(
+      `pod-memory-note: --verdict inválido ${JSON.stringify(verdict)} (use "approve" ou "revise")`,
+    );
+  }
+  const t = tier || TIER_NORMAL;
+  if (t !== TIER_NORMAL && t !== TIER_CRITICAL) {
+    throw new UsageError(`pod-memory-note: --tier inválido "${t}" (use "normal" ou "critical")`);
+  }
+  const text = normalizeMessage(message);
+  if (text === '') {
+    throw new UsageError(
+      'pod-memory-note: mensagem VAZIA — silêncio não vira learning (DF-SF10.21-17). ' +
+        'Nada foi gravado. O comentário é opcional: quando o dono não comenta, o comando ' +
+        'simplesmente NÃO invoca este script.',
+    );
+  }
+  return {
+    trigger: `checkpoint "${step.trim()}" ${VERDICT_LABEL[verdict]} pelo dono`,
+    recommendation: text,
+    evidence: { step: step.trim(), verdict, run_id: runId || null },
+    tier: t,
+    // Fixado, nunca omitido: omissão cai em null silencioso para tier normal.
+    attributed_by: ATTRIBUTED_BY_HUMAN,
+    source_run_id: runId || null,
+    type: TYPE_CHECKPOINT_COMMENT,
+  };
+}
+
+/**
+ * Grava o comentário do checkpoint na memória do pod e CONSOLIDA na sequência, devolvendo
+ * o ledger de eviction do motor (mesmo padrão de `forge-ingest-memory.cjs:120-131` — quem
+ * consolida trata `evicted`; nenhum emissor monta contador próprio, ADR-023 §C2).
+ *
+ * @param {{pod:string, podDir:string, step:string, verdict:'approve'|'revise',
+ *          message:string, runId?:string, tier?:string}} args
+ * @returns {{appended:boolean, reason?:string, entry?:object, ledger:?string,
+ *            consolidateError:?Error}}
+ */
+function noteCheckpointComment(args) {
+  const { pod, podDir, message } = args;
+  if (!pod) throw new UsageError('pod-memory-note: `pod` é obrigatório');
+  if (!podDir) throw new UsageError('pod-memory-note: `podDir` é obrigatório');
+  // Silêncio é resposta legítima da BIBLIOTECA (nenhum append, sem exceção); a CLI é que
+  // trata a chamada com mensagem vazia como uso errado (o comando não deveria chamá-la).
+  if (isSilence(message)) return { appended: false, reason: 'empty', ledger: null, consolidateError: null };
+
+  const entry = buildNoteEntry(args);
+  const opts = { podDir };
+  const { entry: record } = podMemory.append(pod, entry, opts);
+
+  // Consolida SEMPRE (não a cada K): a captura é rara — uma por decisão de checkpoint — e
+  // é justamente o ato que empurra a cauda para fora do artefato orçado. Appendar e não
+  // ver o que saiu é o sub-relato que ADR-022/ADR-023 fecharam.
+  let ledger = null;
+  let consolidateError = null;
+  try {
+    const res = podMemory.consolidate(pod, opts);
+    ledger = podMemory.formatEvictionLedger(pod, res);
+  } catch (e) {
+    consolidateError = e; // surface, não suprime — a CLI reporta; o append já está em disco.
+  }
+  return { appended: true, entry: record, ledger, consolidateError };
+}
+
+// ---------------------------------------------------------------------------
+// Leitura de contexto (state.json do motor — LEITURA apenas, zero import do runner)
+// ---------------------------------------------------------------------------
+
+/** Lê o `state.json` do run e valida os campos que esta captura consome. */
+function readRunContext(statePath) {
+  const p = path.resolve(statePath);
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw new UsageError(`pod-memory-note: state.json ilegível em ${p}: ${e.message}`);
+  }
+  for (const k of ['pod', 'run_id', 'steps']) {
+    if (!(k in state)) throw new UsageError(`pod-memory-note: state.json inválido (campo "${k}" ausente) em ${p}`);
+  }
+  return state;
+}
+
+/**
+ * Diretório do pod onde a memória vive. Precedência idêntica à do runner (SF9.2
+ * CONCERNS-1): (1) override explícito; (2) roteamento GRAVADO no state (`memory_pod_dir`,
+ * honrado sem re-derivar — é o que impede a captura de um run isolado contaminar o pod
+ * real); (3) raiz do pod derivada do `--workflow-file`.
+ */
+function resolveMemoryPodDir({ state, workflowFile, podRootOverride, memoryPodDirOverride }) {
+  if (memoryPodDirOverride) return path.resolve(memoryPodDirOverride);
+  if (state && state.memory_pod_dir) return path.resolve(state.memory_pod_dir);
+  if (!workflowFile) {
+    throw new UsageError('pod-memory-note: --workflow-file é obrigatório (deriva a raiz do pod)');
+  }
+  return podRootFor(path.resolve(workflowFile), podRootOverride);
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+// Flags de TEXTO LIVRE recusadas por desenho — a mensagem nunca entra por argv. Recusar
+// NOMEANDO é o ponto: aceitar-e-ignorar traria de volta, em silêncio, o defeito que
+// `DF-SF10.21-15` fechou.
+const FORBIDDEN_TEXT_FLAGS = new Set([
+  '--message', '--comment', '--recommendation', '--note', '--text', '--msg', '-m',
+]);
+
+const USAGE = [
+  'Uso: node scripts/pod-memory-note.cjs --state <state.json> --workflow-file <wf.yaml> \\',
+  '       --step <id> --verdict approve|revise [--file <arquivo>] [--tier critical] [--pod-root <dir>]',
+  '',
+  'A mensagem do dono NUNCA entra por argv: use --file <arquivo> ou stdin.',
+].join('\n');
+
+function parseArgs(args) {
+  const o = { tier: TIER_NORMAL };
+  const need = (i, flag) => {
+    if (i >= args.length) throw new UsageError(`pod-memory-note: ${flag} exige um valor`);
+    return args[i];
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (FORBIDDEN_TEXT_FLAGS.has(a)) {
+      throw new UsageError(
+        `pod-memory-note: "${a}" NÃO existe por desenho — o comentário do dono nunca viaja ` +
+          'por argv (aspas/acentos/quebras de linha quebram no shell, e argv é visível em ' +
+          '`ps` e no histórico). Escreva o texto num arquivo e use --file <arquivo>, ou envie ' +
+          'por stdin. (ADR-020 DF-SF10.21-15)',
+      );
+    }
+    switch (a) {
+      case '--state': o.state = need(++i, '--state'); break;
+      case '--workflow-file': o.workflowFile = need(++i, '--workflow-file'); break;
+      case '--pod-root': o.podRoot = need(++i, '--pod-root'); break;
+      case '--memory-pod-dir': o.memoryPodDir = need(++i, '--memory-pod-dir'); break;
+      case '--step': o.step = need(++i, '--step'); break;
+      case '--verdict': o.verdict = need(++i, '--verdict'); break;
+      case '--file': o.file = need(++i, '--file'); break;
+      case '--tier': o.tier = need(++i, '--tier'); break;
+      case '--help': case '-h': o.help = true; break;
+      default:
+        throw new UsageError(
+          `pod-memory-note: argumento não reconhecido ${JSON.stringify(a)}.\n${USAGE}`,
+        );
+    }
+  }
+  return o;
+}
+
+/** Lê a mensagem: `--file` OU stdin. Nunca argv. */
+function readMessage(o) {
+  if (o.file) {
+    const p = path.resolve(o.file);
+    try {
+      return fs.readFileSync(p, 'utf8');
+    } catch (e) {
+      throw new UsageError(`pod-memory-note: --file ilegível (${p}): ${e.message}`);
+    }
+  }
+  if (process.stdin.isTTY) {
+    throw new UsageError(
+      'pod-memory-note: sem --file e sem stdin — nada a gravar.\n' +
+        'Escreva o comentário do dono num arquivo (ferramenta de escrita, nunca heredoc/echo) ' +
+        `e passe --file <arquivo>.\n${USAGE}`,
+    );
+  }
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch (e) {
+    throw new UsageError(`pod-memory-note: falha ao ler stdin: ${e.message}`);
+  }
+}
+
+function main() {
+  let o;
+  try {
+    o = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+  }
+  if (o.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  try {
+    if (!o.state) throw new UsageError(`pod-memory-note: --state é obrigatório.\n${USAGE}`);
+    const state = readRunContext(o.state);
+    if (o.step && !Object.prototype.hasOwnProperty.call(state.steps, o.step)) {
+      throw new UsageError(
+        `pod-memory-note: etapa "${o.step}" não existe no run ${state.run_id} ` +
+          `(etapas: ${Object.keys(state.steps).join(', ')}). Comentário NÃO gravado.`,
+      );
+    }
+    const podDir = resolveMemoryPodDir({
+      state,
+      workflowFile: o.workflowFile,
+      podRootOverride: o.podRoot,
+      memoryPodDirOverride: o.memoryPodDir,
+    });
+    const message = readMessage(o);
+    if (isSilence(message)) {
+      // Exit 2 com zero append: o comando não deveria ter chamado. Fail-loud > entrada vazia.
+      throw new UsageError(
+        'pod-memory-note: mensagem VAZIA (--file/stdin sem conteúdo) — silêncio não vira ' +
+          'learning (DF-SF10.21-17). NADA foi gravado. O comentário é opcional: quando o dono ' +
+          'não comenta, o comando simplesmente NÃO invoca este script. Se ele comentou, ' +
+          `escreva o texto num arquivo e passe --file <arquivo>.\n${USAGE}`,
+      );
+    }
+    const r = noteCheckpointComment({
+      pod: state.pod,
+      podDir,
+      step: o.step,
+      verdict: o.verdict,
+      message,
+      runId: state.run_id,
+      tier: o.tier,
+    });
+    console.log(
+      `[memory] comentário do dono gravado: pod "${state.pod}" · etapa "${o.step}" · ` +
+        `veredito "${o.verdict}" · tier ${r.entry.tier} · run ${state.run_id}`,
+    );
+    if (r.ledger) console.error(r.ledger);
+    if (r.consolidateError) {
+      console.error(
+        `[memory] AVISO: a entrada JÁ FOI GRAVADA no log cru, mas a consolidação falhou: ` +
+          `${r.consolidateError.message}\n  NÃO reexecute este comando (duplicaria a entrada): ` +
+          'corrija a causa e reconsolide.',
+      );
+      process.exit(1);
+    }
+    process.exit(0);
+  } catch (e) {
+    console.error(e instanceof UsageError ? e.message : `pod-memory-note: ${e.message}`);
+    process.exit(e instanceof UsageError ? 2 : 1);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  buildNoteEntry,
+  noteCheckpointComment,
+  normalizeMessage,
+  isSilence,
+  readRunContext,
+  resolveMemoryPodDir,
+  parseArgs,
+  UsageError,
+  ATTRIBUTED_BY_HUMAN,
+  TYPE_CHECKPOINT_COMMENT,
+  VERDICT_LABEL,
+  FORBIDDEN_TEXT_FLAGS,
+};