@daniellins/power-claude 0.16.3

package/scripts/arena.cjs

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * arena.cjs — MOTOR determinístico da skill `pc-arena` (harness de comparação cega
+ * reutilizável). ADR-009 Decisão 1/2. Generaliza o protocolo do benchmark 4-braços
+ * (second-brain docs/benchmark/PROTOCOLO-4-bracos.md; RELATORIO-FINAL.md) para N≥2
+ * braços quaisquer.
+ *
+ * FRONTEIRA (ADR-002 reaplicada à AVALIAÇÃO): este motor faz o DETERMINÍSTICO e
+ * propenso-a-bug — permutação de rótulos com uniquidade validada (bijeção braço↔rótulo),
+ * mapa selado com permissão restrita (chmod 600), REVEAL-GATE (recusa revelar até todas
+ * as rodadas pontuadas), hash de congelamento de insumos, soma de tokens, e o veredito
+ * (diferença ≥ limiar sustentada em K de N; empate é resultado válido). A SKILL faz o
+ * JULGAMENTO/orquestração — brief verbatim, dispatch do operador fresco, notas 0-5 cegas.
+ * O motor NUNCA julga conteúdo, só recomputa e valida forma.
+ *
+ * Os 2 bugs reais da operação MANUAL em zsh viram fixture de regressão (arena.test.cjs):
+ *   (bug 1) indexação 1-based portada p/ linguagem 0-based → braço perdido / rótulo
+ *           undefined. Guarda: validatePermutation exige bijeção total (0-indexed).
+ *   (bug 2) estado/contador perdido entre iterações → reveal-gate nunca destrava (ou
+ *           destrava cedo). Guarda: fonte única em disco, escrita atômica, recarga fresca;
+ *           o gate lê a CONTAGEM PERSISTIDA, não um contador em memória.
+ *   NOTA de causa-raiz (Task 2/AC4): a mecânica zsh relatada (pipe|while perdendo contador)
+ *   NÃO reproduz no zsh moderno (última etapa do pipe roda no shell atual); a CLASSE real e
+ *   portável — "estado não persistido entre iterações/invocações" — reproduz no Node (alvo
+ *   deste motor) e é o que a fixture trava. Divergência registrada no Dev Record da SF7.4.
+ *
+ * Uso (CLI): node scripts/arena.cjs <cmd> <expDir> [flags]   — ver help() para os cmds.
+ * 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 REPO_ROOT = path.resolve(__dirname, '..');
+
+class ArenaError extends Error {}
+function fail(msg) { throw new ArenaError(msg); }
+
+// Rótulos cegos neutros (não ordenados como os braços A1..An).
+const DEFAULT_LABELS = ['W', 'X', 'Y', 'Z', 'V', 'U', 'T', 'S', 'R', 'Q', 'P', 'N'];
+
+// ---------------------------------------------------------------------------
+// PRNG determinístico (mulberry32) — permutação reprodutível por seed (testável).
+// ---------------------------------------------------------------------------
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function () {
+    a |= 0; a = (a + 0x6D2B79F5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+function seedFor(baseSeed, round) {
+  // Seed distinta e determinística por rodada (evita permutação idêntica acidental).
+  return (crypto.createHash('sha256').update(`${baseSeed}:${round}`).digest().readUInt32BE(0)) >>> 0;
+}
+
+// ---------------------------------------------------------------------------
+// Permutação e sua VALIDAÇÃO (guarda do bug-class 1: bijeção total, 0-indexed).
+// ---------------------------------------------------------------------------
+/** Fisher-Yates 0-indexed (guarda estrutural contra a indexação 1-based). */
+function shuffle(arr, rnd) {
+  const a = arr.slice();
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(rnd() * (i + 1)); // 0..i inclusive — nunca acessa a[len]
+    [a[i], a[j]] = [a[j], a[i]];
+  }
+  return a;
+}
+
+/** Gera o mapa rótulo→braço para uma rodada. N≥3 rejeita a permutação identidade (tell óbvio). */
+function permute(arms, labels, seed) {
+  if (arms.length !== labels.length) {
+    fail(`permute: #braços (${arms.length}) != #rótulos (${labels.length})`);
+  }
+  const rnd = mulberry32(seed);
+  let shuffled = shuffle(arms, rnd);
+  // N≥3: se saiu a identidade (rótulo i → braço i na ordem de declaração), re-embaralha.
+  if (arms.length >= 3) {
+    let guard = 0;
+    while (shuffled.every((arm, i) => arm === arms[i]) && guard++ < 16) {
+      shuffled = shuffle(shuffled, rnd);
+    }
+  }
+  const map = {};
+  labels.forEach((label, i) => { map[label] = shuffled[i]; });
+  validatePermutation(map, arms, labels);
+  return map;
+}
+
+/** Bijeção total: cada braço exatamente uma vez, cada rótulo usado, sem undefined/duplicata. */
+function validatePermutation(map, arms, labels) {
+  const mappedLabels = Object.keys(map);
+  if (mappedLabels.length !== labels.length) {
+    fail(`permutação inválida: ${mappedLabels.length} rótulos mapeados, esperado ${labels.length}`);
+  }
+  for (const label of labels) {
+    if (!(label in map)) fail(`permutação inválida: rótulo "${label}" sem braço (bug de indexação?)`);
+    const arm = map[label];
+    if (arm === undefined || arm === null) {
+      fail(`permutação inválida: rótulo "${label}" → braço undefined (indexação 1-based portada p/ 0-based?)`);
+    }
+    if (!arms.includes(arm)) fail(`permutação inválida: rótulo "${label}" → braço desconhecido "${arm}"`);
+  }
+  const armsCovered = new Set(Object.values(map));
+  if (armsCovered.size !== arms.length) {
+    fail(`permutação inválida: bijeção quebrada — ${armsCovered.size} braços distintos cobertos de ${arms.length} (braço duplicado ou perdido)`);
+  }
+  for (const arm of arms) {
+    if (!armsCovered.has(arm)) fail(`permutação inválida: braço "${arm}" não recebeu rótulo (perdido)`);
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Estado durável em disco (guarda do bug-class 2: fonte única, escrita atômica).
+// ---------------------------------------------------------------------------
+function statePath(expDir) { return path.join(expDir, 'state.json'); }
+function sealedPath(expDir) { return path.join(expDir, 'sealed-map.json'); }
+
+function loadState(expDir) {
+  const p = statePath(expDir);
+  if (!fs.existsSync(p)) fail(`experimento não inicializado: ${p} não existe (rode 'init')`);
+  let raw;
+  try { raw = fs.readFileSync(p, 'utf8'); } catch (e) { fail(`falha ao ler state.json: ${e.message}`); }
+  let s;
+  try { s = JSON.parse(raw); } catch (e) { fail(`state.json corrompido (JSON inválido): ${e.message}`); }
+  for (const k of ['arms', 'labels', 'rounds', 'rubric', 'scores']) {
+    if (!(k in s)) fail(`state.json inválido: campo "${k}" ausente`);
+  }
+  return s;
+}
+
+/** Escrita ATÔMICA (tmp + rename): nunca deixa um state.json parcial entre iterações. */
+function saveState(expDir, state) {
+  state.updated_at = new Date().toISOString();
+  const p = statePath(expDir);
+  const tmp = `${p}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, p);
+}
+
+// ---------------------------------------------------------------------------
+// Rubrica — fronteira máquina (PASS/FAIL) vs julgamento humano (0-5), configurável.
+// ---------------------------------------------------------------------------
+function validateRubric(rubric) {
+  if (!rubric || typeof rubric !== 'object') fail('rubrica ausente ou inválida');
+  if (!Array.isArray(rubric.dimensions) || rubric.dimensions.length === 0) {
+    fail('rubrica.dimensions ausente ou vazio');
+  }
+  const scale = rubric.scale || 5;
+  let sumW = 0;
+  for (const d of rubric.dimensions) {
+    if (!d.name) fail('dimensão sem name');
+    if (typeof d.weight !== 'number' || d.weight <= 0) fail(`dimensão "${d.name}": weight deve ser número > 0`);
+    if (d.type !== 'machine' && d.type !== 'human') fail(`dimensão "${d.name}": type deve ser machine|human`);
+    if (d.type === 'machine' && (!Number.isInteger(d.checks) || d.checks < 1)) {
+      fail(`dimensão "${d.name}" (machine): checks deve ser inteiro >= 1`);
+    }
+    sumW += d.weight;
+  }
+  if (Math.abs(sumW - 1) > 1e-6) fail(`soma dos pesos = ${sumW.toFixed(4)}, esperado 1.0`);
+  const v = rubric.verdict || {};
+  if (typeof v.minDiff !== 'number' || v.minDiff < 0) fail('rubrica.verdict.minDiff deve ser número >= 0');
+  if (!Number.isInteger(v.kOfN) || v.kOfN < 1) fail('rubrica.verdict.kOfN deve ser inteiro >= 1');
+  return { scale };
+}
+
+/** Score ponderado de UMA rodada de UM rótulo, RECOMPUTADO da rubrica (nunca confia no reportado). */
+function weightedRoundScore(dimScores, rubric) {
+  const scale = rubric.scale || 5;
+  let acc = 0;
+  for (const d of rubric.dimensions) {
+    const raw = dimScores[d.name];
+    let s;
+    if (d.type === 'machine') {
+      // PASS/FAIL: espera { passed: <int> } → proporção × escala.
+      if (!raw || typeof raw.passed !== 'number') fail(`dimensão máquina "${d.name}": esperado { passed: int }`);
+      if (raw.passed < 0 || raw.passed > d.checks) fail(`dimensão "${d.name}": passed ${raw.passed} fora de 0..${d.checks}`);
+      s = (raw.passed / d.checks) * scale;
+    } else {
+      if (typeof raw !== 'number') fail(`dimensão humana "${d.name}": esperado nota numérica 0-${scale}`);
+      if (raw < 0 || raw > scale) fail(`dimensão "${d.name}": nota ${raw} fora de 0..${scale}`);
+      s = raw;
+    }
+    acc += s * d.weight;
+  }
+  return acc; // pesos somam 1 → já é a média ponderada
+}
+
+// ---------------------------------------------------------------------------
+// Veredito por eixo — diferença ≥ minDiff sustentada em K de N; empate é válido.
+// ---------------------------------------------------------------------------
+function verdictForAxis(perRoundA, perRoundB, minDiff, kOfN) {
+  if (perRoundA.length !== perRoundB.length) fail('veredito: #rodadas divergente entre os dois braços');
+  const n = perRoundA.length;
+  const diffs = perRoundA.map((a, i) => a - perRoundB[i]);
+  const meanA = perRoundA.reduce((x, y) => x + y, 0) / n;
+  const meanB = perRoundB.reduce((x, y) => x + y, 0) / n;
+  const aWins = diffs.filter((d) => d >= minDiff).length;   // A vence a rodada por ≥ limiar
+  const bWins = diffs.filter((d) => -d >= minDiff).length;  // B vence a rodada por ≥ limiar
+  let winner = 'tie';
+  if (aWins >= kOfN && aWins > bWins) winner = 'A';
+  else if (bWins >= kOfN && bWins > aWins) winner = 'B';
+  return {
+    winner, meanA: round2(meanA), meanB: round2(meanB), meanDiff: round2(meanA - meanB),
+    perRoundDiff: diffs.map(round2), aRoundsOverThreshold: aWins, bRoundsOverThreshold: bWins,
+    minDiff, kOfN, tie: winner === 'tie',
+  };
+}
+function round2(x) { return Math.round(x * 100) / 100; }
+
+// ---------------------------------------------------------------------------
+// Reveal-gate — só destrava com TODAS as rodadas pontuadas (contagem PERSISTIDA).
+// ---------------------------------------------------------------------------
+function scoredRoundsCount(state) {
+  let done = 0;
+  for (let r = 1; r <= state.rounds; r++) {
+    const byLabel = state.scores[String(r)];
+    if (byLabel && state.labels.every((l) => l in byLabel)) done++;
+  }
+  return done;
+}
+function canReveal(state) { return scoredRoundsCount(state) === state.rounds; }
+
+// ---------------------------------------------------------------------------
+// Comandos (mutam o estado em disco; salvam após cada mutação).
+// ---------------------------------------------------------------------------
+function init(expDir, { arms, rounds, rubric, labels, seed }) {
+  if (!Array.isArray(arms) || arms.length < 2) fail('init: --arms exige N >= 2 braços');
+  if (new Set(arms).size !== arms.length) fail('init: rótulos de braço duplicados');
+  if (!Number.isInteger(rounds) || rounds < 1) fail('init: --rounds deve ser inteiro >= 1');
+  validateRubric(rubric);
+  const lbls = labels || DEFAULT_LABELS.slice(0, arms.length);
+  if (lbls.length !== arms.length) fail(`init: #rótulos (${lbls.length}) != #braços (${arms.length})`);
+  if (new Set(lbls).size !== lbls.length) fail('init: rótulos cegos duplicados');
+  fs.mkdirSync(expDir, { recursive: true });
+  const state = {
+    version: 1,
+    arms, labels: lbls, rounds, rubric,
+    seed: seed == null ? (crypto.randomBytes(4).readUInt32BE(0) >>> 0) : (seed >>> 0),
+    created_at: new Date().toISOString(),
+    pinned: {}, scores: {}, tokens: { creation: {}, rounds: {} },
+    revealed: false,
+  };
+  // Sela TODAS as permutações na inicialização (uma por rodada), arquivo com chmod 600.
+  const sealed = {};
+  for (let r = 1; r <= rounds; r++) {
+    sealed[String(r)] = permute(arms, lbls, seedFor(state.seed, r));
+  }
+  writeSealed(expDir, sealed);
+  saveState(expDir, state);
+  return state;
+}
+
+function writeSealed(expDir, sealed) {
+  const p = sealedPath(expDir);
+  const tmp = `${p}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(sealed, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, p);
+  try { fs.chmodSync(p, 0o600); } catch { /* FS sem permissões POSIX — best-effort */ }
+}
+function readSealed(expDir) {
+  const p = sealedPath(expDir);
+  if (!fs.existsSync(p)) fail(`mapa selado ausente: ${p}`);
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function pin(expDir, round, inputs) {
+  const state = loadState(expDir);
+  assertRound(state, round);
+  const hash = crypto.createHash('sha256').update(JSON.stringify(inputs)).digest('hex');
+  state.pinned[String(round)] = { hash, inputs, frozen_at: new Date().toISOString() };
+  saveState(expDir, state);
+  return hash;
+}
+
+function recordScore(expDir, round, label, dimScores) {
+  const state = loadState(expDir);
+  assertRound(state, round);
+  if (!state.labels.includes(label)) fail(`rótulo "${label}" não pertence ao experimento`);
+  weightedRoundScore(dimScores, state.rubric); // valida a forma antes de gravar
+  state.scores[String(round)] = state.scores[String(round)] || {};
+  state.scores[String(round)][label] = dimScores;
+  saveState(expDir, state);
+}
+
+function recordTokens(expDir, { arm, round, tokens }) {
+  const state = loadState(expDir);
+  if (!state.arms.includes(arm)) fail(`braço "${arm}" não pertence ao experimento`);
+  if (typeof tokens !== 'number' || tokens < 0) fail('tokens deve ser número >= 0');
+  if (round == null) state.tokens.creation[arm] = tokens;
+  else {
+    assertRound(state, round);
+    state.tokens.rounds[String(round)] = state.tokens.rounds[String(round)] || {};
+    state.tokens.rounds[String(round)][arm] = tokens;
+  }
+  saveState(expDir, state);
+}
+
+function assertRound(state, round) {
+  if (!Number.isInteger(round) || round < 1 || round > state.rounds) {
+    fail(`rodada ${round} fora de 1..${state.rounds}`);
+  }
+}
+
+/** REVEAL-GATE: recusa (fail-loud) até todas as rodadas pontuadas; só então lê o mapa selado. */
+function reveal(expDir) {
+  const state = loadState(expDir);
+  const done = scoredRoundsCount(state);
+  if (done !== state.rounds) {
+    fail(`REVEAL-GATE bloqueado: ${done}/${state.rounds} rodadas pontuadas — revelação proibida até todas ` +
+      `estarem completas (evita calibrar o julgamento sabendo quem está ganhando). Nenhum mapa lido.`);
+  }
+  const sealed = readSealed(expDir);
+  state.revealed = true;
+  saveState(expDir, state);
+  return sealed;
+}
+
+/** Agregação: só após reveal. Junta scores(por rótulo) aos braços e recomputa tudo. */
+function tally(expDir) {
+  const state = loadState(expDir);
+  if (!canReveal(state)) fail(`tally: experimento incompleto (${scoredRoundsCount(state)}/${state.rounds} rodadas)`);
+  const sealed = readSealed(expDir);
+  const rubric = state.rubric;
+  const machineDims = rubric.dimensions.filter((d) => d.type === 'machine');
+  // perRoundByArm[arm] = [score_r1, ..., score_rN]
+  const perRoundByArm = {};
+  // machineAggregate[arm] = { passed, total, pass, byDim } — checks de MÁQUINA somados por
+  // braço sobre todas as rodadas, PASS/FAIL SEPARADO da média ponderada (§7.1 do protocolo:
+  // uma falha estrutural desqualificante fica VISÍVEL, não escondida na média).
+  const machineAggregate = {};
+  for (const arm of state.arms) {
+    perRoundByArm[arm] = [];
+    machineAggregate[arm] = { passed: 0, total: 0, byDim: {} };
+    for (const md of machineDims) machineAggregate[arm].byDim[md.name] = { passed: 0, total: 0 };
+  }
+  for (let r = 1; r <= state.rounds; r++) {
+    const map = sealed[String(r)];                 // rótulo → braço
+    const byLabel = state.scores[String(r)];
+    for (const label of state.labels) {
+      const arm = map[label];
+      const dimScores = byLabel[label];
+      perRoundByArm[arm].push(round2(weightedRoundScore(dimScores, rubric)));
+      for (const md of machineDims) {
+        const passed = dimScores[md.name].passed;
+        machineAggregate[arm].passed += passed;
+        machineAggregate[arm].total += md.checks;
+        machineAggregate[arm].byDim[md.name].passed += passed;
+        machineAggregate[arm].byDim[md.name].total += md.checks;
+      }
+    }
+  }
+  for (const arm of state.arms) {
+    machineAggregate[arm].pass = machineAggregate[arm].total > 0
+      && machineAggregate[arm].passed === machineAggregate[arm].total;
+  }
+  const means = {};
+  for (const arm of state.arms) {
+    const xs = perRoundByArm[arm];
+    means[arm] = { mean: round2(xs.reduce((a, b) => a + b, 0) / xs.length), median: round2(median(xs)) };
+  }
+  const axes = [];
+  for (const ax of (rubric.axes || [])) {
+    const v = verdictForAxis(perRoundByArm[ax.a], perRoundByArm[ax.b], rubric.verdict.minDiff, rubric.verdict.kOfN);
+    axes.push({ name: ax.name, a: ax.a, b: ax.b, ...v });
+  }
+  return { perRoundByArm, means, machineAggregate, axes, tokens: state.tokens };
+}
+function median(xs) {
+  const s = xs.slice().sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+}
+
+/** Relatório final com revelação (texto markdown + objeto). */
+function report(expDir) {
+  const state = loadState(expDir);
+  const sealed = reveal(expDir); // aplica o gate; falha se incompleto
+  const t = tally(expDir);
+  const lines = [];
+  lines.push(`# Arena — relatório final (revelação ${new Date().toISOString().slice(0, 10)})`);
+  lines.push('');
+  lines.push('## 1. Revelação dos mapas (rótulo → braço)');
+  lines.push(`| Rodada | ${state.labels.join(' | ')} |`);
+  lines.push(`|${'---|'.repeat(state.labels.length + 1)}`);
+  for (let r = 1; r <= state.rounds; r++) {
+    lines.push(`| R${r} | ${state.labels.map((l) => sealed[String(r)][l]).join(' | ')} |`);
+  }
+  lines.push('');
+  lines.push('## 2. Scores ponderados por rodada');
+  lines.push(`| Braço | ${Array.from({ length: state.rounds }, (_, i) => `R${i + 1}`).join(' | ')} | Média | Mediana |`);
+  lines.push(`|${'---|'.repeat(state.rounds + 3)}`);
+  for (const arm of state.arms) {
+    lines.push(`| ${arm} | ${t.perRoundByArm[arm].join(' | ')} | **${t.means[arm].mean}** | ${t.means[arm].median} |`);
+  }
+  lines.push('');
+  const machineDims = state.rubric.dimensions.filter((d) => d.type === 'machine');
+  if (machineDims.length > 0) {
+    lines.push('## 3. Estrutura verificável por máquina — PASS/FAIL agregado (SEPARADO da média ponderada)');
+    lines.push('_Uma falha estrutural desqualificante fica visível aqui, não escondida na média — um braço pode vencer no score e ainda reprovar aqui._');
+    lines.push(`| Braço | ${machineDims.map((d) => d.name).join(' | ')} | Agregado | PASS? |`);
+    lines.push(`|${'---|'.repeat(machineDims.length + 3)}`);
+    for (const arm of state.arms) {
+      const agg = t.machineAggregate[arm];
+      const cols = machineDims.map((d) => `${agg.byDim[d.name].passed}/${agg.byDim[d.name].total}`);
+      lines.push(`| ${arm} | ${cols.join(' | ')} | ${agg.passed}/${agg.total} | ${agg.pass ? 'SIM' : '**NÃO**'} |`);
+    }
+    lines.push('');
+  }
+  lines.push(`## 4. Veredito por eixo (critério: diferença ≥ ${state.rubric.verdict.minDiff} em ≥ ${state.rubric.verdict.kOfN}/${state.rounds} rodadas; empate é válido)`);
+  for (const ax of t.axes) {
+    const verd = ax.tie ? 'EMPATE (resultado válido, não forçado)'
+      : `VITÓRIA DE ${ax.winner === 'A' ? ax.a : ax.b}`;
+    lines.push(`- **${ax.name}** (${ax.a} vs ${ax.b}): ${verd} — diferença média ${ax.meanDiff}; por rodada [${ax.perRoundDiff.join(', ')}]; ≥limiar ${ax.aRoundsOverThreshold}(${ax.a})/${ax.bRoundsOverThreshold}(${ax.b}).`);
+  }
+  lines.push('');
+  lines.push('## 5. Tokens por braço/rodada');
+  lines.push(`| Braço | Criação | ${Array.from({ length: state.rounds }, (_, i) => `R${i + 1}`).join(' | ')} |`);
+  lines.push(`|${'---|'.repeat(state.rounds + 2)}`);
+  for (const arm of state.arms) {
+    const rr = Array.from({ length: state.rounds }, (_, i) => (state.tokens.rounds[String(i + 1)] || {})[arm] ?? '—');
+    lines.push(`| ${arm} | ${state.tokens.creation[arm] ?? '—'} | ${rr.join(' | ')} |`);
+  }
+  lines.push('');
+  if (state.rubric.prediction) {
+    lines.push('## 6. Conferência da previsão (registrada ANTES do experimento — viés de confirmação declarado)');
+    lines.push(`> ${state.rubric.prediction}`);
+    lines.push('');
+    lines.push('_Limitação honesta: uma previsão vista antes do julgamento é viés conhecido; a conferência é autoavaliação declarada, não validação cega de terceiro._');
+  }
+  return { text: lines.join('\n'), tally: t, sealed };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+function parseFlags(argv) {
+  const f = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) { const k = a.slice(2); const v = argv[i + 1]; if (v && !v.startsWith('--')) { f[k] = v; i++; } else f[k] = true; }
+  }
+  return f;
+}
+function readJson(spec) {
+  if (spec === '-' ) return JSON.parse(fs.readFileSync(0, 'utf8'));
+  if (spec && (spec.startsWith('{') || spec.startsWith('['))) return JSON.parse(spec);
+  return JSON.parse(fs.readFileSync(spec, 'utf8'));
+}
+function help() {
+  return [
+    'arena.cjs — motor determinístico da skill pc-arena. Comandos:',
+    '  init    <expDir> --arms A1,A2,.. --rounds N --rubric <f.json> [--labels W,X,..] [--seed S]',
+    '  pin     <expDir> --round R --inputs <f.json|->     (congela insumos c/ hash)',
+    '  score   <expDir> --round R --label W --scores <f.json|->',
+    '  tokens  <expDir> --arm A1 [--round R] --tokens N',
+    '  status  <expDir>                                    (rodadas pontuadas / reveal liberado?)',
+    '  reveal  <expDir>                                    (REVEAL-GATE: só com todas as rodadas pontuadas)',
+    '  report  <expDir>                                    (relatório final com revelação)',
+  ].join('\n');
+}
+
+function main() {
+  const [cmd, expDir, ...rest] = process.argv.slice(2);
+  if (!cmd || cmd === 'help' || cmd === '--help') { console.log(help()); process.exit(0); }
+  if (!expDir) { console.error('erro: <expDir> obrigatório\n' + help()); process.exit(2); }
+  const f = parseFlags(rest);
+  try {
+    if (cmd === 'init') {
+      const arms = String(f.arms || '').split(',').map((s) => s.trim()).filter(Boolean);
+      const labels = f.labels ? String(f.labels).split(',').map((s) => s.trim()) : null;
+      init(expDir, { arms, rounds: parseInt(f.rounds, 10), rubric: readJson(f.rubric), labels, seed: f.seed != null ? parseInt(f.seed, 10) : null });
+      console.log(`[OK] experimento iniciado em ${expDir} — ${arms.length} braços × ${f.rounds} rodadas; mapa selado (chmod 600).`);
+    } else if (cmd === 'pin') {
+      const h = pin(expDir, parseInt(f.round, 10), readJson(f.inputs));
+      console.log(`[OK] insumos da rodada ${f.round} congelados — hash ${h}`);
+    } else if (cmd === 'score') {
+      recordScore(expDir, parseInt(f.round, 10), f.label, readJson(f.scores));
+      console.log(`[OK] notas cegas registradas — rodada ${f.round}, rótulo ${f.label}`);
+    } else if (cmd === 'tokens') {
+      recordTokens(expDir, { arm: f.arm, round: f.round != null ? parseInt(f.round, 10) : null, tokens: parseInt(f.tokens, 10) });
+      console.log(`[OK] tokens registrados — braço ${f.arm}${f.round != null ? `, rodada ${f.round}` : ' (criação)'}`);
+    } else if (cmd === 'status') {
+      const s = loadState(expDir);
+      console.log(`rodadas pontuadas: ${scoredRoundsCount(s)}/${s.rounds} · reveal ${canReveal(s) ? 'LIBERADO' : 'BLOQUEADO'}`);
+    } else if (cmd === 'reveal') {
+      console.log(JSON.stringify(reveal(expDir), null, 2));
+    } else if (cmd === 'report') {
+      console.log(report(expDir).text);
+    } else {
+      console.error(`comando desconhecido: ${cmd}\n` + help()); process.exit(2);
+    }
+    process.exit(0);
+  } catch (e) {
+    if (e instanceof ArenaError) { console.error(`[FALHA] ${e.message}`); process.exit(1); }
+    throw e;
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  init, pin, recordScore, recordTokens, reveal, tally, report,
+  permute, validatePermutation, shuffle, mulberry32, seedFor,
+  weightedRoundScore, verdictForAxis, validateRubric,
+  canReveal, scoredRoundsCount, loadState, saveState, sealedPath, statePath,
+  DEFAULT_LABELS, ArenaError,
+};