@daniellins/power-claude 0.16.3

package/template/.claude/hooks/enforce-ready-oracles.cjs

@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * POWER CLAUDE — PreToolUse hook: a trava de `Ready` (story SF13.2, `ADR-032`).
+ *
+ * O que ele faz: interrompe a transição `Draft`→`Ready` de uma story sempre
+ * que o conteúdo resultante da escrita contiver um dos 5 defeitos de forma
+ * DECIDÍVEIS SEM EXECUTAR NADA — e fica em silêncio absoluto em qualquer
+ * outro caso.
+ *
+ * A propriedade central (`ADR-032`, `DF-SF13.2-1`): **este hook é PURO**.
+ * Zero subprocesso, zero execução de oráculo — ele só consulta as funções
+ * puras já expostas por `scripts/validate-story-acs.cjs`. Executar os 47
+ * oráculos de uma story custa 1,23 s no caminho quente de TODA escrita de
+ * arquivo e herdaria a superfície de execução de texto de terceiro (a ameaça
+ * T2 do `ADR-011`); o passe puro custa 49 ms para as 85 stories do repo.
+ * Por isso nenhuma linha aqui spawna processo: a pureza não é performance,
+ * é fronteira de segurança.
+ *
+ * Limiar (`DF-SF13.2-3`, `D-Dono-1`): a única decisão que este hook emite é
+ * `ask`. Ele NUNCA nega — nenhuma classe hoje é "positivamente conhecida e
+ * positivamente errada" (medido: 7 falsos positivos em 7 da família
+ * `[Guarda]` contra a própria `sf13.1.story.md`). A negativa é estrutural,
+ * não disciplinar: o literal da decisão negativa não existe neste arquivo.
+ *
+ * Os 8 predicados (zero falso positivo medido sobre as stories reais):
+ *   P1 — fence órfã: nº de blocos `oraculo` na seção `## Acceptance Criteria`
+ *        MAIOR que o nº de ACs a que o parser os atribuiu (o parser está cego).
+ *   P2 — `[Guarda] (...)` que não casa nenhuma das 3 formas reconhecidas.
+ *   P3 — `[Guarda] (prova: AC-N)` apontando para um AC que não existe.
+ *   P4 — `# espera:` presente e não reconhecido.
+ *   P5 — fence `oraculo` declarada e vazia.
+ *   P6 — oráculo que o validador recusaria (cabeçalho fora da allow-list,
+ *        metacaractere de shell, subcomando `git` fora da sub-allow-list).
+ *   P7 — `[Guarda] (sem irmão)` sem asserção de AUSÊNCIA no oráculo.
+ *   P8 — contagem ingênua (`grep -c` sem `-w`/`-x`/âncora) sob `exit0`.
+ *
+ * A leitura *"a família `[Guarda]` (P2/P3/P7) fica FORA por falso positivo
+ * medido (7 em 7 contra `sf13.1.story.md`)"* está SUPERADA — não repetir. A
+ * causa-raiz daqueles 7 era `parseGuarda` não distinguir CITAÇÃO de USO, e foi
+ * consertada na SF13.7; a SF13.9 remediu o corpus real ANTES de ligar os 3
+ * (zero disparo), com controle positivo de alcançabilidade. O que NÃO mudou:
+ * os 3 entram na mesma escada de 2 degraus, `ask`-only — promover qualquer um
+ * a `deny` continua exigindo `D-Dono-2` completo, que não está pago.
+ *
+ * Fonte única, sem cópia (`ADR-031` Emenda 10 através de uma fronteira de
+ * arquivo): NENHUM predicado é reimplementado aqui. A simulação da edição
+ * vem do hook irmão `enforce-cycle-authority.cjs`; a análise dos ACs vem de
+ * `scripts/validate-story-acs.cjs`. Duas implementações paralelas divergem.
+ *
+ * Raiz do repositório: ancorada em `path.resolve(__dirname, '..', '..')`
+ * (Emenda 1 do `ADR-032`). NUNCA `input.cwd`/`process.cwd()` — `resolveGitDir`
+ * do hook irmão NÃO sobe diretórios (ele testa só `<cwd>/.git`), e derivar o
+ * path de um `require` de dado de ENTRADA abriria exatamente a superfície que
+ * este desenho fecha por não abrir.
+ *
+ * Loaders PREGUIÇOSOS e GUARDADOS (Emenda 2 do `ADR-032`, item 4): nenhum
+ * `require` de irmão/validador no topo do módulo. Um `require` top-level de
+ * arquivo ausente lançaria ANTES de `runWithFailSafe` existir — o processo
+ * morreria mudo e a ferramenta passaria. Zero decisão emitida é o pior
+ * desfecho possível deste desenho (fail-open silencioso).
+ *
+ * Ordem normativa em `main()`/`runMain()` (Emenda 2, item 3):
+ *   silêncio cedo (`tool_name`, `file_path`) → `loadCycleAuthority()` →
+ *   transição `Draft`→`Ready` → `loadValidator()` → predicados → orçamento →
+ *   emissão. O loader do irmão vem ANTES do detector de transição: se a
+ *   falha do loader virasse `false` dentro do detector, o resultado seria
+ *   silêncio — indistinguível de "não é a transição". O caminho de
+ *   degradação não pode se parecer com o caminho feliz.
+ *
+ * As 5 rotas de degradação (`DF-SF13.2-4` + Emenda 2, item 1) — todas FALAM,
+ * nenhuma lança, nenhuma nega: exceção em qualquer ponto; irmão ausente;
+ * validador ausente; orçamento interno (2000 ms) estourado; JSON de entrada
+ * ilegível (fail-closed proporcional: `ask` só se o texto bruto aparentar
+ * `Status`/`Ready`, senão silêncio).
+ *
+ * Alcance declarado: `Edit`/`Write` sobre `*.story.md`. A cobertura real é
+ * função da adoção da convenção ` ```oraculo ` pelo PRODUTOR de stories —
+ * hoje ~2,4% (2 de 85). Quem quiser cobertura maior mexe no produtor, não
+ * aqui (`DF-SF13.2-6`).
+ *
+ * Circuito de destravamento: docs/mecanismos/hooks-de-autoridade-do-ciclo.md
+ * §Destravamento.
+ *
+ * Sem dependências externas (roda em qualquer instalação limpa).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BUDGET_MS = 2000;
+const MECANISMO_DOC = 'docs/mecanismos/hooks-de-autoridade-do-ciclo.md';
+const DESTRAVAMENTO = `Se isto é um falso positivo, veja ${MECANISMO_DOC} §Destravamento.`;
+
+// ---------------------------------------------------------------------------
+// I/O do protocolo de hook.
+//
+// `readStdin`/`parseHookInput` são locais de propósito, e isso NÃO contradiz
+// a regra de fonte única: a leitura do payload acontece ANTES de qualquer
+// loader (é o que decide se há sequer um `input` para trabalhar), então não
+// pode depender do hook irmão — que pode estar ausente (5ª rota).
+// ---------------------------------------------------------------------------
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function parseHookInput(rawInput) {
+  try {
+    const parsed = JSON.parse(rawInput || '{}');
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function emitDecision(permissionDecision, permissionDecisionReason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision,
+      permissionDecisionReason,
+    },
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Raiz e loaders guardados.
+// ---------------------------------------------------------------------------
+
+// O hook vive sempre em `<raiz>/.claude/hooks/` numa instalação. Aritmética
+// de path pura: não consulta disco, não consulta `input` — logo não tem modo
+// de falha (Emenda 2, item 2: a rota "raiz não resolvível" é INALCANÇÁVEL).
+function resolveRepoRoot() {
+  return path.resolve(__dirname, '..', '..');
+}
+
+// Superfície de export do irmão de que ESTE hook depende. Checada na carga,
+// não presumida: uma instalação em SKEW (`ADR-019` — template atualizado num
+// lado só) carrega o módulo sem erro e devolve `undefined` no ponto de uso,
+// e um `undefined(...)` no meio do detector viraria exceção genérica ou, pior,
+// `false` — indistinguível de "não é a transição". O caminho de degradação não
+// pode se parecer com o caminho feliz (`ADR-032` Emenda 2, item 3).
+const REQUIRED_SIBLING_EXPORTS = ['simulateResult', 'extractStatusSection', 'statusToken'];
+
+function loadCycleAuthority() {
+  const p = path.join(__dirname, 'enforce-cycle-authority.cjs');
+  let mod;
+  try {
+    mod = require(p);
+  } catch (err) {
+    return { ok: false, error: err, path: p };
+  }
+  const faltando = REQUIRED_SIBLING_EXPORTS.filter((nome) => !mod || typeof mod[nome] !== 'function');
+  if (faltando.length > 0) {
+    return {
+      ok: false,
+      skew: true,
+      faltando,
+      error: new Error(`superfície de export incompleta — faltam: ${faltando.join(', ')}`),
+      path: p,
+    };
+  }
+  return { ok: true, mod, path: p };
+}
+
+function loadValidator(repoRoot) {
+  const p = path.join(repoRoot, 'scripts', 'validate-story-acs.cjs');
+  try {
+    return { ok: true, mod: require(p), path: p };
+  } catch (err) {
+    return { ok: false, error: err, path: p };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detecção da transição, por SIMULAÇÃO (nunca por leitura do texto do diff).
+//
+// `cycleAuthorityMod` é o módulo JÁ carregado por `runMain()` e passado como
+// argumento — a função é pura em relação ao loader e testável sem ele.
+//
+// Comparação por TOKEN nos DOIS lados (`ADR-032` Emenda 3, `FINDING-8` do gate
+// da SF13.7). A IGUALDADE ESTRITA pós-normalização que estava aqui está
+// SUPERADA — não repetir: ela deixava a trava MUDA sempre que um papel
+// anotava o status (`Ready (validado pelo PO, 10/10)`, `Ready — aguardando
+// dev`), coisa que já aconteceu 4× em `docs/stories/`, por 2 papéis
+// diferentes, no mesmo dia em que a trava nasceu. O silêncio era total: nem
+// `ask`, nem log.
+//
+// Exigir os dois lados continua sendo o que impede a interrupção a cada
+// escrita: `depois === 'ready'` sozinho daria verdadeiro para qualquer edição
+// numa story já `Ready` que nem toca o `## Status`.
+//
+// Escada de 2 DEGRAUS (token ⇒ `ask`; resto ⇒ silêncio), deliberadamente
+// diferente da escada de 3 do P1 do irmão (`ADR-032` E3.10): este sítio só
+// emite `ask`, e com uma severidade só não há para onde descer — um degrau de
+// "menção" faria interromper toda NEGAÇÃO (`Not Ready`, `ainda não está
+// Ready`). Quem "uniformizar" as duas escadas está revertendo essa decisão.
+// ---------------------------------------------------------------------------
+
+function detectDraftToReady(input, cycleAuthorityMod) {
+  if (!cycleAuthorityMod || !cycleAuthorityMod.simulateResult || !cycleAuthorityMod.statusToken) return false;
+  const sim = cycleAuthorityMod.simulateResult(input);
+  if (!sim) return false;
+  const antes = cycleAuthorityMod.statusToken(cycleAuthorityMod.extractStatusSection(sim.before));
+  const depois = cycleAuthorityMod.statusToken(cycleAuthorityMod.extractStatusSection(sim.after));
+  return antes === 'draft' && depois === 'ready';
+}
+
+// ---------------------------------------------------------------------------
+// Os 5 predicados puros. Toda a análise é delegada ao validador
+// (`extractAcSection`, `parseAcs`, `parseEspera` — via `parseAcs` —,
+// `wouldBeRefused`, `looksLikeNaiveCounting`).
+// ---------------------------------------------------------------------------
+
+// Abertura de fence `oraculo` REAL (CommonMark): início de linha, nada além
+// de espaço/tab até o fim da linha. Distingue de menção inline em prosa.
+const ORACLE_FENCE_OPEN_RE = /^```oraculo[ \t]*\r?$/gm;
+
+function countOracleFences(section) {
+  const re = new RegExp(ORACLE_FENCE_OPEN_RE.source, ORACLE_FENCE_OPEN_RE.flags);
+  let n = 0;
+  while (re.exec(section)) n += 1;
+  return n;
+}
+
+// P1 — fence órfã. Comparação de contagem ESTRUTURAL, não heurística de
+// texto: se a seção declara N blocos e o parser atribuiu M < N a ACs, o
+// parser está cego. `fences === 0` é silêncio declarado, fora do alcance
+// (83 de 85 stories, `DF-SF13.2-6`) — não é aprovação, é ausência de matéria.
+function evaluateFenceOrfa(content, validatorMod) {
+  const section = validatorMod.extractAcSection(content);
+  if (!section) return null;
+  const fences = countOracleFences(section);
+  if (fences === 0) return null;
+  const atribuidas = validatorMod.parseAcs(content).filter((ac) => ac.hasOraculo).length;
+  if (fences <= atribuidas) return null;
+  return {
+    predicate: 'P1',
+    id: null,
+    detail: `a seção "## Acceptance Criteria" declara ${fences} bloco(s) \`oraculo\` e o parser atribuiu apenas ${atribuidas} a um AC — o parser está cego para ao menos um. Causas conhecidas: cabeçalho fora da convenção \`**AC-N.**\`, heading de seção divergente, ou AC dentro de lista numerada.`,
+  };
+}
+
+// P2/P3/P7 (família `[Guarda]`) + P4/P5/P6/P8 — por AC.
+//
+// A família `[Guarda]` ficou FORA da v1 por falso positivo MEDIDO (7 em 7
+// contra `sf13.1.story.md`), cuja causa-raiz era `parseGuarda` não distinguir
+// CITAÇÃO de USO. A causa foi consertada na SF13.7, e o pré-requisito para
+// ligar os 3 aqui foi medido ANTES do wiring (SF13.9, AC-15): zero disparo de
+// P2/P3/P7 sobre as stories reais de `docs/stories/`, com controle positivo de
+// que as 3 formas de fato disparam quando aplicadas de verdade.
+//
+// Nenhuma lógica de `parseGuarda` é reimplementada aqui — só a LEITURA de
+// `ac.guarda.forma`/`ac.guarda.provaId`, já produzidos por `parseAcs`, no
+// mesmo padrão em que P4/P5/P6/P8 leem `ac.espera`/`ac.oracleCmd`.
+//
+// Os 3 entram na MESMA escada de 2 degraus dos outros 5 — sempre `ask`, nunca
+// `deny` (`DF-SF13.2-3`). Promover qualquer um exige `D-Dono-2` COMPLETO (10
+// transições reais registradas E o conserto de `parseGuarda`); só a segunda
+// condição foi paga.
+function evaluatePerAcPredicates(content, validatorMod) {
+  const acs = validatorMod.parseAcs(content);
+  const acIds = new Set(acs.map((ac) => ac.id));
+  const hits = [];
+  for (const ac of acs) {
+    // ANTES do `continue` de `!hasOraculo`, de propósito: um AC pode ter
+    // `[Guarda]` malformado E não ter oráculo nenhum, e é justamente esse o
+    // caso mais grave (nada prova nada). Se este bloco viesse depois do
+    // `continue`, P2/P3 ficariam cegos para ele em silêncio.
+    if (ac.guarda) {
+      if (ac.guarda.forma === 'desconhecida') {
+        hits.push({
+          predicate: 'P2',
+          id: ac.id,
+          detail: `a etiqueta \`[Guarda] (${ac.guarda.raw})\` não casa nenhuma das 3 formas reconhecidas — o guarda não classifica, logo não vale como declaração. Formas válidas: \`(prova: AC-N)\`, \`(sem irmão — ...)\`, \`(citação de fato pré-existente, ...)\`.`,
+        });
+      }
+      if (ac.guarda.forma === 'prova' && !acIds.has(ac.guarda.provaId)) {
+        hits.push({
+          predicate: 'P3',
+          id: ac.id,
+          detail: `o guarda aponta para \`${ac.guarda.provaId}\` como o AC que prova a mudança, e esse AC NÃO existe nesta story — o par declarado não fecha, e o controle fica sem prova pareada.`,
+        });
+      }
+      if (ac.guarda.forma === 'sem-irmao') {
+        const tipo = ac.espera && ac.espera.type;
+        const isAusencia = tipo === 'stdout-vazio' || (tipo === 'stdout==' && String(ac.espera.value).trim() === '0');
+        if (!isAusencia) {
+          hits.push({
+            predicate: 'P7',
+            id: ac.id,
+            detail: `o guarda declara "sem irmão" (ausência), mas a asserção do oráculo (\`${tipo || 'exit0'}\`) não é de AUSÊNCIA — só \`stdout-vazio\` ou \`stdout == 0\` sustentam "não existe"; um \`exit0\` qualquer passa sem provar a ausência que o guarda promete.`,
+          });
+        }
+      }
+    }
+
+    if (!ac.hasOraculo) continue;
+
+    if (ac.oracleEmpty) {
+      hits.push({
+        predicate: 'P5',
+        id: ac.id,
+        detail: 'fence `oraculo` declarada e VAZIA — nenhum comando dentro do bloco, logo o AC não tem oráculo nenhum apesar de aparentar ter.',
+      });
+      continue;
+    }
+
+    if (ac.espera && ac.espera.type === 'desconhecida') {
+      hits.push({
+        predicate: 'P4',
+        id: ac.id,
+        detail: `"# espera: ${ac.espera.raw}" não é uma forma reconhecida — o validador cairia no default \`exit0\` e o AC não provaria o que o texto promete. Formas válidas: exit0, exit!=0, stdout-vazio, stdout-nao-vazio, stdout== <valor>.`,
+      });
+    }
+
+    const recusa = validatorMod.wouldBeRefused(ac.oracleCmd);
+    if (recusa && recusa.refused) {
+      hits.push({
+        predicate: 'P6',
+        id: ac.id,
+        detail: `o oráculo seria RECUSADO pelo validador (${recusa.reason}) — um AC recusado nunca vira prova.`,
+      });
+    }
+
+    const sobExit0 = !ac.espera || ac.espera.type === 'exit0';
+    if (sobExit0 && validatorMod.looksLikeNaiveCounting(ac.oracleCmd)) {
+      hits.push({
+        predicate: 'P8',
+        id: ac.id,
+        detail: '`grep -c` sem `-w`/`-x`/âncora sob `# espera: exit0` imprime `0` e sai com código 0 mesmo quando não acha nada — pode ser no-op. (Hedge do instrumento reproduzido literalmente: ele diz "pode ser", e este hook não afirma mais que ele.)',
+      });
+    }
+  }
+  return hits;
+}
+
+function evaluateReadyOracles(content, validatorMod) {
+  const hits = [];
+  const orfa = evaluateFenceOrfa(content, validatorMod);
+  if (orfa) hits.push(orfa);
+  for (const hit of evaluatePerAcPredicates(content, validatorMod)) hits.push(hit);
+  return hits;
+}
+
+// ---------------------------------------------------------------------------
+// Orçamento e fail-safe.
+// ---------------------------------------------------------------------------
+
+// Pura: recebe os dois instantes, nunca espera nem consulta relógio.
+function budgetExceeded(startedAtMs, nowMs) {
+  return Number(nowMs) - Number(startedAtMs) > BUDGET_MS;
+}
+
+function runWithFailSafe(fn) {
+  try {
+    return fn();
+  } catch (err) {
+    emitDecision('ask', `O hook lançou uma exceção (${err && err.message}) — aprovação humana necessária, nunca falha silenciosa. ${DESTRAVAMENTO}`);
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Mensagem de interrupção.
+// ---------------------------------------------------------------------------
+
+function buildHitsMessage(filePath, hits) {
+  const linhas = hits.map((h) => `  - ${h.predicate}${h.id ? ` (${h.id})` : ''}: ${h.detail}`).join('\n');
+  return [
+    `A trava de Ready encontrou ${hits.length} defeito(s) de forma nos oráculos de "${filePath}", decidíveis sem executar nada:`,
+    linhas,
+    'A transição Draft→Ready foi INTERROMPIDA para você responder — nada foi bloqueado: aprove se o achado for falso positivo, ou corrija a story antes.',
+    `Detalhe completo: node scripts/validate-story-acs.cjs "${filePath}". ${DESTRAVAMENTO}`,
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Núcleo testável. `opts.now` e `opts.evaluateReadyOracles` são injeção de
+// dependência com default REAL (`Date.now`, `evaluateReadyOracles`) — existem
+// para permitir teste determinístico sem espera real, não são backdoor: em
+// produção `main()` chama `runMain(input)` sem `opts`.
+//
+// `runMain` NÃO tem try/catch próprio, de propósito: quem protege é o
+// `runWithFailSafe` de `main()`. Se ele tivesse a sua própria rede, a rede
+// externa nunca seria exercitada e a rota de exceção viraria letra morta.
+// ---------------------------------------------------------------------------
+
+function runMain(input, opts) {
+  const options = opts || {};
+  const now = options.now || Date.now;
+  const startedAtMs = now();
+
+  // 1. Silêncio o mais cedo possível — o caminho quente é TODA escrita.
+  if (!input || (input.tool_name !== 'Edit' && input.tool_name !== 'Write')) return;
+  const filePath = input.tool_input && input.tool_input.file_path;
+  if (typeof filePath !== 'string' || !/\.story\.md$/i.test(filePath)) return;
+
+  // 2. Irmão ANTES da transição (Emenda 2, item 3): ignorância sobre a
+  //    própria dependência é ignorância sobre a story — fala, nunca cala.
+  const cycleAuthority = loadCycleAuthority();
+  if (!cycleAuthority.ok) {
+    const motivo = cycleAuthority.skew
+      ? `carregou o hook irmão "${cycleAuthority.path}", mas a superfície de export dele está em SKEW — faltam as funções: ${cycleAuthority.faltando.join(', ')} (instalação com os dois hooks em versões diferentes; rode a atualização do motor a partir do framework)`
+      : `não conseguiu carregar o hook irmão "${cycleAuthority.path}" (${cycleAuthority.error && cycleAuthority.error.message})`;
+    emitDecision(
+      'ask',
+      `A trava de Ready ${motivo} — sem ele nem dá para decidir se esta escrita é a transição Draft→Ready. Aprovação humana necessária: silêncio aqui seria indistinguível de "não é a transição". ${DESTRAVAMENTO}`,
+    );
+    return;
+  }
+
+  // 3. Gate por TRANSIÇÃO antes do gate por CONTEÚDO: fora de Draft→Ready o
+  //    hook não avalia predicado nenhum, nem que a story tenha defeito.
+  if (!detectDraftToReady(input, cycleAuthority.mod)) return;
+
+  // 4. Validador — resolvido a partir do `__dirname` do próprio hook.
+  const validator = loadValidator(resolveRepoRoot());
+  if (!validator.ok) {
+    emitDecision(
+      'ask',
+      `Transição Draft→Ready detectada em "${filePath}", mas scripts/validate-story-acs.cjs ausente ou não carregável em "${validator.path}" (${validator.error && validator.error.message}) — nada se sabe sobre os oráculos desta story. Conserto: rode a atualização do motor ("adopt" + "update --scope motor") a partir do framework. Aprovação humana necessária. ${DESTRAVAMENTO}`,
+    );
+    return;
+  }
+
+  // 5. Predicados sobre o conteúdo RESULTANTE da escrita (simulado, sem tocar
+  //    o disco) — nunca sobre o conteúdo atual do arquivo.
+  const simulado = cycleAuthority.mod.simulateResult(input);
+  const conteudo = simulado ? simulado.after : '';
+  const avaliar = options.evaluateReadyOracles || evaluateReadyOracles;
+  const hits = avaliar(conteudo, validator.mod);
+
+  // 6. Orçamento — checado SEMPRE, mesmo com zero achado, e vence a decisão
+  //    de silêncio: nunca travar para sempre, nunca liberar em silêncio.
+  if (budgetExceeded(startedAtMs, now())) {
+    emitDecision(
+      'ask',
+      `A trava de Ready estourou o orçamento interno de 2000 ms avaliando "${filePath}" — o passe pode ter ficado incompleto, então o veredito de silêncio não é confiável. Aprovação humana necessária. ${DESTRAVAMENTO}`,
+    );
+    return;
+  }
+
+  // 7. Emissão. Sem achado: silêncio absoluto.
+  if (!hits || hits.length === 0) return;
+  emitDecision('ask', buildHitsMessage(filePath, hits));
+}
+
+function main() {
+  runWithFailSafe(() => {
+    const rawInput = readStdin();
+    const input = parseHookInput(rawInput);
+
+    if (!input) {
+      // Fail-closed proporcional, precedente literal de
+      // `enforce-cycle-authority.cjs:261-274`: sem JSON não há story
+      // resolvível, mas se o texto bruto aparenta a transição que esta trava
+      // guarda, perguntar custa uma tecla e calar custa a garantia.
+      const aparentaTransicao = /status/i.test(rawInput) && /ready/i.test(rawInput);
+      if (aparentaTransicao) {
+        emitDecision(
+          'ask',
+          `O hook não conseguiu interpretar o input do PreToolUse e o texto bruto aparenta tocar Status/Ready. Aprovação humana necessária. ${DESTRAVAMENTO}`,
+        );
+      }
+      return;
+    }
+
+    runMain(input);
+  });
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  BUDGET_MS,
+  REQUIRED_SIBLING_EXPORTS,
+  readStdin,
+  parseHookInput,
+  emitDecision,
+  resolveRepoRoot,
+  loadCycleAuthority,
+  loadValidator,
+  detectDraftToReady,
+  countOracleFences,
+  evaluateFenceOrfa,
+  evaluatePerAcPredicates,
+  evaluateReadyOracles,
+  budgetExceeded,
+  runWithFailSafe,
+  buildHitsMessage,
+  runMain,
+  main,
+};

package/template/.claude/rules/authority.md

@@ -0,0 +1,76 @@
+# Matriz de Autoridade — Ciclo de Desenvolvimento
+
+Regra global do ambiente POWER CLAUDE. Separação de papéis é o mecanismo central de qualidade: cada transição de estado de uma story tem um dono exclusivo, e ninguém revisa o próprio trabalho.
+
+## Matriz de papéis
+
+| Papel | Autoridade exclusiva | Proibido |
+|---|---|---|
+| **PO** (valida) | Veredito GO/NO-GO da story (Draft → Ready); correções mecânicas do draft | Implementar; mudar escopo/ACs materialmente; aprovar implementação |
+| **Dev** (implementa) | Código, testes, commits locais; Status Ready → InProgress → InReview | `git push`; setar Done; validar a própria story; editar QA Results |
+| **QA** (aprova) | Veredito do gate (PASS/CONCERNS/FAIL/WAIVED); **único que seta Done**; seção QA Results | Implementar correções; revisar código que ele mesmo escreveu |
+| **DevOps** (publica) | **Único que faz `git push` / `gh pr create` / `gh pr merge`** | Force-push (proibido para TODOS, inclusive devops — bloqueado por hook) |
+| **Planner** (planeja) | SPEC, epics e drafts de story (fase Plan) | Validar o próprio draft (→ PO); implementar; mudar story Done |
+| **Analyst** (explora) | Brief, research, benchmark, brainstorming (fase Explore) | Escrever SPEC/PRD (→ Planner); decidir arquitetura (→ Architect) |
+| **Architect** (decide) | Classificação de complexidade; decisões de stack/arquitetura com ADR; revisão de arquitetura pré-dev | Implementar; aprovar a própria arquitetura no QA gate |
+
+Enforcement determinístico: `.claude/hooks/enforce-git-push-authority.cjs` nega force-push para qualquer agente e exige aprovação humana para push/PR de quem não é devops; `.claude/hooks/enforce-cycle-authority.cjs` mecaniza as 2 garantias de autoridade do ciclo que não podem depender só de disciplina — **só QA marca `Status: Done`** e **só QA escreve `docs/qa/gates/*.yaml`** (predicados 1/2), e **Dev não edita código enquanto a story associada está `Draft`** (predicado 3). Ver `docs/mecanismos/hooks-de-autoridade-do-ciclo.md`.
+
+**Fronteira real de `enforce-git-push-authority.cjs` (D6/D7, story SF12.3, fix rounds F3/F5):** este hook é **guard-rail contra erro, não barreira contra evasão deliberada**. Ele pega a forma direta de `git`/`gh` em qualquer sintaxe (flags combinadas, opções globais, comandos encadeados) e **alias em AMBOS os branches** — alias de `git` (`git config alias.<nome>`, inclusive já configurado no repositório, resolvido por consulta a `git config`) e alias NATIVO de `gh` (`gh alias set`, inclusive já configurado, resolvido por consulta a `gh alias list`) — os 2 mecanismos foram simetrizados no fix round F5, depois de o F3 ter coberto só o `git`. Ele **não pega** indireção por `sh -c`/`bash -c`/`eval`/`npm run`/`node -e`/scripts externos (ex.: `./deploy.sh`) que por sua vez rodem git/gh — qualquer uma dessas contorna o hook por desenho, decisão do dono: perseguir essas variantes não converge e não é o problema que este guard-rail resolve.
+
+## Roster de status da story — este arquivo é a FONTE DA VERDADE
+
+O conjunto de status do ciclo é **fechado** e mora aqui. Quem muda o processo edita **este arquivo primeiro**; toda outra ocorrência (comentário de código, AC de story, asserção de teste) é **cópia** e deve derivar daqui, nunca ser a autoridade.
+
+<!-- roster:status -->
+`Draft` · `Ready` · `InProgress` · `InReview` · `Done`
+
+| Status | Quem transiciona para ele | Quando |
+|---|---|---|
+| `Draft` | Planner | Story recém-escrita, ainda não validada |
+| `Ready` | **PO** (exclusivo) | Veredito GO da validação do draft |
+| `InProgress` | Dev | Dev começa a implementar — **e a cada `FAIL` do gate**, quando a story volta para o loop de fix (duas rotas de entrada) |
+| `InReview` | Dev | Implementação concluída, entregue ao gate |
+| `Done` | **QA** (exclusivo) | Veredito do gate não-FAIL, com gate file em `docs/qa/gates/` |
+
+**Negação explícita — leitura SUPERADA, não repetir:** a enumeração `{draft, ready, inreview, done, blocked}`, publicada em `ADR-032` (`E3.2`/`E3.12`) e copiada daí para o comentário do hook e para um AC de story, está **errada nos dois sentidos**: omite `InProgress`, que é **mandatório** no ciclo, e inclui `Blocked`, que nenhum documento do framework define como status de story (`ADR-032` Emenda 5, `E5.1`/`E5.3`). O `blocked` do motor de pod/pipeline e o `blocked` do `state.json` de `pc-wave` são **outro namespace** — fase de execução, não lifecycle de story; nunca unificar por semelhança de nome.
+
+**Como incluir um status novo:** ele entra **primeiro** nesta seção, com dono de transição definido na tabela acima, e só então as cópias o seguem. Um status que existe só no roster de um teste ou de um ADR é um status sem dono — e um controle que aceita valor que ninguém definiu deixa de detectar o evento que existe para detectar (um status entrar no ciclo sem ninguém decidir).
+
+**Mecanismo, não disciplina:** `scripts/__tests__/enforce-cycle-authority.test.cjs` **deriva** o roster da âncora `<!-- roster:status -->` acima e o compara com um literal escrito à mão no próprio teste. Divergência **nos dois sentidos** fica vermelha — inclusive a remoção da âncora. Derivar sem comparar contra literal independente ficaria verde para qualquer documento, inclusive um errado: **derivar sozinho não é tripwire** (`ADR-032` Emenda 5, `E5.5`).
+
+**Este teste não viaja para a instalação — qualificação que faltava (`F-3`, gate `SF13.10`, fechada por `SF13.11`).** `scripts/__tests__/` está na lista de exclusão de `installer/motor-scripts.json` (`exclude`), por desenho: o tripwire protege quem EDITA este arquivo (autor do template, dentro deste repositório, via `npm test`), não quem o RECEBE — nada numa instalação altera o roster deste arquivo depois de instalado. **Negação explícita, não repetir:** a leitura anterior ("mecanismo, não disciplina", sem qualificação) deixava a impressão de que a instalação também é guardada; não é — numa instalação de terceiro, este parágrafo descreve um mecanismo que só existe no repositório do framework. **Por que não fazer o teste viajar:** fazê-lo seria recriar uma NOVA cópia hardcoded do roster dentro de `installer/doctor.js` (comparando contra um literal ali) para o `doctor` poder checá-lo — o mesmo anti-padrão (roster copiado 3×, uma errada) que originou a `SF13.9`/`SF13.10`; a correção certa não recria o defeito que veio corrigir. Se uma instalação real precisar desta garantia, a resposta é outra: nada no ciclo de uma instalação edita o roster deste arquivo depois de copiado — só quem publica uma versão nova do framework o faz, e é lá, no repositório do framework, que o tripwire já roda.
+
+## Regra anti-self-review
+
+1. Quem implementou uma story **não pode** executar o QA gate dela na mesma sessão/contexto.
+2. O revisor **re-executa** os gates (lint, typecheck, test) — nunca aceita o relato do implementador como evidência.
+3. Quem aplica fixes de QA devolve para **re-review**; nunca fecha o próprio fix.
+4. Se só existe um operador humano, a separação vale entre agentes: subagente Dev implementa, subagente QA revisa com contexto limpo.
+
+## Fluxo canônico
+
+```
+PO valida (GO) → Dev implementa → QA gate → [FAIL? Dev corrige → re-review] → QA seta Done → DevOps publica
+```
+
+## Escalação
+
+| Situação | Ação |
+|---|---|
+| Gate FAIL | Dev entra no loop de fix (`pc-apply-qa-fixes`) e devolve para re-review |
+| 3 iterações de fix sem PASS | **PARA. Escala ao humano** com o histórico dos vereditos — nunca afrouxar o gate para fechar |
+| Veredito WAIVED | Só com justificativa registrada no gate file e ciência humana |
+| Conflito de autoridade entre papéis | Escala ao humano; nenhum agente arbitra o próprio limite |
+
+## Aplicação a subagentes
+
+- Os papéis são encarnados pelos subagentes `pc-analyst`, `pc-planner`, `pc-architect`, `pc-po`, `pc-dev`, `pc-qa` e `pc-devops` (`.claude/agents/`); especialistas de pod (`db-architect`, `ux-architect`) entram por gatilho registrado na story. Spawnar o subagente correto é a forma prática de garantir contexto limpo entre implementação e revisão.
+- A identidade devops é lida pelo hook exclusivamente de `input.agent_type` (payload do `PreToolUse`, o `subagent_type` literal do despacho) — SEM fallback a variáveis de ambiente (`PC_ACTIVE_AGENT`/`CLAUDE_AGENT_NAME`/`CLAUDE_CODE_AGENT` não existem no produto, medido; mantê-las como fonte reabriria a autoproclamação via `.claude/settings.json`). Prefixo inline no comando e env var no processo não conferem autoridade (Bloco M da SF12.3, D1/M-1). Calibração de 3 níveis (D4): `git push`/`gh pr create` liberados para `pc-devops`, sem `ask`; `gh pr merge` continua `ask` para TODO agente, sem exceção; force-push continua `deny` para TODO agente.
+- Sessão principal sem papel declarado opera como generalista: pode orquestrar, mas herda as proibições de todos os papéis (sem Done, sem push, sem self-review).
+
+## Invariantes
+
+- Nenhuma story chega a Done sem gate file em `docs/qa/gates/{story}.yaml` com veredito não-FAIL.
+- Push é sempre fast-forward, sempre com aprovação humana ou papel devops ativo.
+- Toda decisão autônoma de um papel fica registrada no artefato da story como `[AUTO-DECISION]`.

package/template/.claude/rules/curadoria-de-conhecimento.md

@@ -0,0 +1,30 @@
+# Curadoria de Conhecimento — Destino de Artefatos ao Fechar Trabalho
+
+Regra global do ambiente POWER CLAUDE. Aplica-se sempre que o fechamento de um ciclo, story, épico ou sessão deixa para trás um artefato cujo destino precisa ser decidido — doc de mecanismo, ADR, nota de backlog, fixture, run de evidência, arquivo de scratch. **Palavras do dono, formuladas ao fechar o backlog parqueado do épico `pod-export`:** *"Conhecimento importante deve ser organizado e eternizado, ou mantido no backlog para uso e depois descarte (pós-mecanismo pronto). Conhecimento temporário já utilizado pode virar documentação se for regra ou comportamento importante. Se for apenas lembrete do processo de desenvolvimento, pode ser excluído se já foi resolvido. Lixo deve ser descartado, conhecimento válido deve ser documentado."*
+
+## Os 4 destinos
+
+| Classe do artefato | Destino | Gatilho de saída do destino |
+|---|---|---|
+| Conhecimento importante e duradouro | **Documentar/eternizar** (doc de mecanismo, ADR, story) | Nenhum — é permanente por natureza |
+| Conhecimento importante mas transitório (ainda serve de insumo a um mecanismo em construção) | **Backlog**, mantido para uso | O mecanismo fica pronto **e** a regra/comportamento vira documentação — só então o artefato bruto vira descartável |
+| Conhecimento temporário já utilizado, que registra regra ou comportamento importante | **Vira documentação** (o comportamento sobrevive; o rastro bruto não precisa) | — |
+| Conhecimento temporário já utilizado, que é só lembrete de processo já resolvido | **Excluído** | Já disparou — o processo foi resolvido |
+| Lixo (não é nenhuma das classes acima) | **Descartado** | Já disparou |
+
+## Regra central
+
+Ao decidir o que fazer com um artefato ao fechar trabalho, pergunte nesta ordem:
+
+1. **É regra ou comportamento que vai continuar valendo?** → documente/eternize (destino 1). Não fica pendurado em backlog nem em disco solto — vira página de mecanismo, ADR ou seção de story.
+2. **É válido mas só serve de insumo enquanto um mecanismo específico ainda está em construção?** → backlog (destino 2), com o gatilho de saída **nomeado e datável** (não "algum dia"): o mecanismo ficar pronto E as regras que ele revela virarem documentação. O descarte é **consequência de a documentação existir**, não do tempo passar.
+3. **Já foi consumido e a única coisa que resta é rastro de processo** (uma prova que já foi transcrita para onde interessa, um comentário de sessão, um arquivo de trabalho intermediário)? → se o processo que ele documentava já foi resolvido, **exclua** (destino 3b). Se o rastro em si é a regra/comportamento (não só a prova de que algo aconteceu), documente primeiro (destino 3a), então exclua o bruto.
+4. **Nenhuma das anteriores?** → é lixo. Descarte (destino 4).
+
+**Quem decide:** o papel `pc-planner`, ao curar backlog/SPEC/epic, e a sessão coordenadora, ao fechar o trabalho de um subagente — nunca por omissão silenciosa. Um artefato sem destino decidido não é "resolvido depois", é órfão.
+
+## Não confundir com a triagem de ITEM
+
+Esta regra decide o destino do **artefato** (o que fica gravado em disco/documentação sobre um achado). É complementar, não sobreposta, à disciplina de **decidir imediatamente o destino de um item de trabalho** (entra no ciclo agora / fica parqueado com gatilho concreto de retorno / nunca) que já existe na prática deste framework — um item entra, é parqueado ou nunca acontece; **isto aqui** responde, para o conhecimento que qualquer um dos três desfechos produziu, se ele é digno de virar documentação permanente, backlog transitório, ou lixo. As duas disciplinas juntas fecham o ciclo completo: nada fica pendurado por esquecimento, nem no nível do item, nem no nível do que ele deixou para trás.
+
+Um backlog de itens parqueados com gatilho de retorno nomeado — cada item registrando o quê, a evidência, por que ficou fora e o gatilho que o traz de volta — é a materialização em disco do **destino 2** desta régua: conhecimento importante mas transitório, mantido para uso até o mecanismo que o resolve estar pronto.

package/template/.claude/rules/model-matrix.md

@@ -0,0 +1,34 @@
+# Matriz de Modelos por Papel — Modo Desempenho (padrão)
+
+Régua de decisão: **profundidade de julgamento por chamada × custo do erro × frequência**. A coordenadora aplica a matriz via override `model:` (e `effort`) nas chamadas do Agent tool.
+
+## Matriz padrão
+
+| Papel | Modelo |
+|---|---|
+| Coordenadora (sessão principal) | Modelo de topo disponível |
+| architect | Modelo de topo disponível (chamadas raras, alavancagem máxima) |
+| qa (gate adversarial) | opus |
+| dev | opus |
+| devops / planner / analyst / po | sonnet |
+| Etapas mecânicas (transições de status, commits de docs) | haiku + `effort: low` |
+
+## Gatilhos de escalada (um degrau acima)
+
+A coordenadora escala o papel envolvido **um degrau** (sonnet → opus; opus → modelo de topo), sem pedir, quando a story toca:
+
+- Segurança / autenticação / autorização
+- Migration de dados
+- Dinheiro / cobrança / preço
+- Compliance / dados pessoais
+- Desempate fundamentado entre especialistas divergentes
+
+Nunca escalar por padrão — escalada é por gatilho, não por hábito.
+
+## Âncora inviolável
+
+**O gate adversarial do QA nunca desce de opus** — em nenhum modo, sob nenhuma economia. O funil de detecção permanece na potência integral.
+
+## Modo econômico
+
+`/power:modo economico` escreve `.claude/rules/economy-mode.md`, que suspende parcialmente esta matriz enquanto existir (`/power:modo desempenho` remove). Esta matriz padrão nunca é editada pelo toggle.