@daniellins/power-claude 0.16.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Lins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# POWER CLAUDE
+
+Framework enxuto de agentes para Claude Code — **pods por job-to-be-done**, com budget de tokens como gate de qualidade.
+
+## Princípios
+
+1. **Pods por job-to-be-done** — em vez de dezenas de agentes genéricos, cada pod resolve um trabalho concreto (criar conteúdo com autoridade, montar aulas, automatizar processos, desenvolver com IA, forjar novos pods). Você instala só o que usa.
+2. **Budget de tokens como gate** — todo agente declara `budget_tokens` no frontmatter e um validador determinístico (`scripts/validate-budgets.js`) bloqueia qualquer agente que estoure o próprio budget, o teto global (1.500 tokens) ou 150 linhas. Contexto enxuto não é convenção: é gate.
+3. **Enforcement determinístico** — regras críticas viram hooks e scripts, não pedidos educados no prompt. Exemplo: o hook `enforce-git-push-authority.cjs` bloqueia `git push` fora do fluxo autorizado, direto no `PreToolUse`.
+4. **Verificação adversarial embutida** — os pods incluem agentes críticos (red-team) que revisam o próprio output antes de você confiar nele.
+5. **Garantia por código, não por prosa** — um pod é dado declarativo (`workflows/wf-*.yaml` + templates de etapa + `squad-io.yaml`), executado por um runner determinístico (`scripts/pc-run-pod.cjs`, skill `pc-run-pod`) que verifica o artefato EM DISCO — existe, casa com o template, todas as `veto.assertions` passam — antes de liberar a etapa seguinte. A garantia de processo é código, não prosa no prompt do agente.
+
+Documentação operacional de cada mecanismo (uso, não só decisão): `docs/mecanismos/`.
+
+## O que mudou na v0.3 (runner, memória evolutiva, migração)
+
+**Runner determinístico.** Todo workflow de pod roda por um contrato `wf-*.yaml` validado estaticamente (`scripts/validate-pod-workflow.cjs` — ciclos, handoffs abertos, vetos malformados, templates ausentes) e provado em runtime pelo smoke dinâmico (`scripts/smoke-pod-workflow.cjs`). O runner (`scripts/pc-run-pod.cjs`, skill `pc-run-pod`) despacha um subagente fresco por etapa, aplica checkpoints bloqueantes e retoma por run-id.
+
+**Memória evolutiva dos pods.** Um pod aprende do próprio uso, sem virar ruído: log cru append-only + consolidado podado por budget de tokens (`scripts/pod-memory.cjs`), watcher heurístico que audita aderência ao consolidado (`scripts/watcher-audit.cjs`) e ingest inicial de memória com dedupe (`scripts/forge-ingest-memory.cjs`). O runner injeta só o consolidado no brief do agente — nunca o log cru.
+
+**`*migrate-squad` — migração squad legado → pod com gates completos.** Comando do `forge-chief` que leva um squad inteiro pelas fases F0 (inventário) → F1 (triagem, para no humano) → F2 (geração + gates por workflow) → F3 (fechamento), com raiz de confiança em código no manifest de migração (`scripts/migration-manifest.cjs`) e paridade decidida pela máquina entre G5-LITE (2 runs) e G5-FULL (5 runs) via `scripts/harness-g5-lite.cjs`.
+
+## Instalação
+
+Enquanto o pacote não está publicado no npm, instale direto do GitHub:
+
+```bash
+cd seu-projeto
+npx github:daniellins/power-claude install
+```
+
+Quando publicado no npm:
+
+```bash
+npx @daniellins/power-claude install
+```
+
+O instalador pergunta quais pods instalar, se deve inicializar git e registra tudo em `.power-claude/manifest.json`. Em modo não-interativo:
+
+```bash
+npx @daniellins/power-claude install --yes
+```
+
+O instalador **nunca sobrescreve** arquivos seus: conflitos são perguntados (interativo) ou preservados (`--yes`). O `.claude/settings.json` recebe merge aditivo em `hooks`/`permissions` (a entrada nova do template é acrescentada sem remover nem alterar o que você já tem); nas demais chaves, suas chaves vencem, as do template entram só onde faltam.
+
+## Comandos do CLI
+
+| Comando | O que faz |
+|---|---|
+| `power-claude install` | Instala o framework no diretório atual (default) |
+| `power-claude adopt` | Adota uma instalação montada à mão (sem manifest): classifica o disco contra o template (idêntico / modificado / ausente), gera o `.power-claude/manifest.json` sem sobrescrever nada e coloca a instalação ao alcance do `update` |
+| `power-claude update` | Atualiza; arquivos que você modificou são preservados (com diff resumido no modo interativo) |
+| `power-claude doctor` | Diagnóstico: integridade do manifest, hooks, `.gitignore`, gate de budgets, tamanho do CLAUDE.md |
+| `power-claude uninstall` | Remove apenas o que o instalador colocou e continua intacto; o que você modificou fica |
+| `power-claude --help` / `--version` | Ajuda / versão |
+
+Flag global: `--yes` (`-y`) para modo não-interativo.
+
+## Estrutura instalada
+
+```text
+seu-projeto/
+├── .claude/
+│   ├── CLAUDE.md                  # instruções enxutas (budget ~2.000 tokens)
+│   ├── settings.json              # hooks + permissions (merge com o seu)
+│   └── hooks/
+│       └── enforce-git-push-authority.cjs
+├── pods/
+│   ├── academy/                   # aulas, palestras, treinamentos
+│   ├── authority-content/         # conteúdo com voz própria e fact-check
+│   ├── automation/                # N8N + Langgraph
+│   ├── dev-ia/                    # ciclo de desenvolvimento com IA
+│   └── squad-forge/               # cria novos agentes e pods
+├── knowledge/
+│   └── voice-dna/                 # DNA de voz para conteúdo autoral
+├── scripts/
+│   └── validate-budgets.js        # gate de budget dos agentes
+└── .power-claude/
+    └── manifest.json              # estado da instalação (base do update/uninstall)
+```
+
+**Nota honesta sobre o runner/memória/migração:** `power-claude install` copia `template/` inteiro (inclui a skill `pc-run-pod` em `.claude/skills/`) mais `scripts/validate-budgets.js` avulso — **só isso é distribuído automaticamente** (`installer/install.js`/`copy.js`). Os scripts que o runner, a memória e o `*migrate-squad` invocam (`pc-run-pod.cjs`, `pod-memory.cjs`, `migration-manifest.cjs`, `validate-pod-workflow.cjs`, `smoke-pod-workflow.cjs`, `harness-g5-lite.cjs`, `watcher-audit.cjs`, `forge-*.cjs`, `validate-no-clone.cjs`) vivem só em `scripts/` na raiz deste repositório e **não são copiados para o projeto instalado**. Hoje essas capacidades operam via o próprio repositório do framework (dogfooding) ou por sync manual dos scripts para o projeto consumidor — gap registrado em `BACKLOG.md`.
+
+## Personalização — opcional, em três degraus
+
+**Nenhum pod exige que você construa um DNA de voz.** Os pods que assinam peças **em seu nome**
+perguntam quem é você — **uma vez, três campos** (nome, handle, uma linha de autoridade). Tudo o
+mais — voz, tom, léxico, objetivos — é opcional, tem default funcional, e vai se ajustando com o
+seu feedback durante o uso.
+
+| Degrau | O que você fornece | Onde mora | O que muda |
+|---|---|---|---|
+| **1 — sem voz** | nada | — | Roda. Saída correta, tom neutro. |
+| **2 — guia de estilo** | pessoa gramatical, léxico proibido, uma linha de tom | `pods/<pod>/knowledge/dono.yaml` (cópia de `dono.example.yaml`) | O texto para de soar como assistente. Melhor custo-benefício. |
+| **3 — DNA de voz** | um corpus do que você já escreveu | `knowledge/voice-dna/voice-dna.yaml`, extraído por `/power:forge` → `mind-extractor` → `*extract {corpus}` | O texto passa a soar como você, com evidência citada por campo. |
+
+**Uma ressalva honesta, porque os pods não são iguais.** Os pods de **método** (`dev-ia`,
+`automation`, `hormozi-method`) não dependem de quem você é: sem personalizar nenhum campo, a
+saída deles é a mesma. Já os pods de **identidade** (`content-carousel`, `authority-content`,
+`academy`, `squad-forge`) produzem peças assinadas — sem o trio de atribuição, a saída não é
+neutra, é **genérica**, que é exatamente o defeito que esses pods existem para evitar. Por isso o
+trio é a única coisa que um pod pode pedir antes de prosseguir; voz e estilo, nunca.
+
+**Nada disso vai para o pacote.** O DNA de voz e a configuração de dono são dado pessoal: o
+template distribui só os `*.example.*`, e um oráculo (`scripts/owner-layer.cjs` +
+`scripts/owner-layer.test.cjs`) reprova o empacotamento se qualquer arquivo dessa camada sair sem
+ser um placeholder marcado. Passo a passo de instanciação: `knowledge/voice-dna/README.md` na sua
+instalação.
+
+## Validação no repositório do framework
+
+```bash
+npm test           # suíte completa: instalador, adopt, runner, memória, migração, smoke/sweep
+npm run validate   # budgets + branding + validate-no-clone
+```
+
+## Licença
+
+[MIT](./LICENSE) — Copyright (c) 2026 **Daniel Lins**.
+
+Use, copie e adapte à vontade, mantendo a atribuição a Daniel Lins conforme a licença.

package/bin/cli.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * power-claude — CLI do framework POWER CLAUDE.
+ *
+ * Uso:
+ *   npx @daniellins/power-claude [install] [--yes]   instala no diretório atual (default)
+ *   npx @daniellins/power-claude adopt [--yes]       adota instalação sem manifest
+ *   npx @daniellins/power-claude update [--yes] [--scope motor]
+ *                                        atualiza uma instalação existente
+ *   npx @daniellins/power-claude doctor              diagnóstico da instalação
+ *   npx @daniellins/power-claude uninstall [--yes]   remove a instalação
+ *   npx @daniellins/power-claude --help | --version
+ *
+ * Node >= 18, sem dependências externas.
+ */
+
+const path = require('node:path');
+const pkg = require(path.join(__dirname, '..', 'package.json'));
+
+const COMMANDS = new Set(['install', 'adopt', 'update', 'doctor', 'uninstall']);
+
+const HELP = `power-claude ${pkg.version} — ${pkg.description}
+
+Uso:
+  npx @daniellins/power-claude [comando] [flags]
+
+Comandos:
+  install     Instala o framework no diretório atual (default)
+  adopt       Adota uma instalação sem manifest (gera o manifest a partir do
+              disco para que o update passe a alcançá-la)
+  update      Atualiza uma instalação existente (preserva suas modificações)
+  doctor      Diagnóstico: manifest, hooks, .gitignore, budgets, CLAUDE.md
+  uninstall   Remove apenas o que o instalador colocou (manifest-driven)
+
+Flags:
+  -y, --yes       Modo não-interativo (assume padrões; nunca sobrescreve nem
+                  remove arquivos modificados por você)
+      --scope motor
+                  Só em "update": restringe a atualização aos scripts do motor
+                  (installer/motor-scripts.json) com owner instalado, e trata
+                  divergência como DEFASAGEM — sobrescreve, como o install
+                  sempre fez. Imprime a tabela sha256 antes→depois e pede UMA
+                  confirmação para o conjunto. Não toca o template.
+  -h, --help      Mostra esta ajuda
+  -v, --version   Mostra a versão
+`;
+
+function parseArgs(argv) {
+  const args = { command: 'install', yes: false, help: false, version: false, scope: null };
+  for (let i = 0; i < argv.length; i++) {
+    const raw = argv[i];
+    if (raw === '--yes' || raw === '-y') args.yes = true;
+    else if (raw === '--help' || raw === '-h') args.help = true;
+    else if (raw === '--version' || raw === '-v') args.version = true;
+    else if (raw === '--scope') {
+      args.scope = argv[++i];
+      if (!args.scope) {
+        console.error('--scope exige um valor (ex.: --scope motor)\n');
+        console.error(HELP);
+        process.exit(2);
+      }
+    } else if (raw.startsWith('--scope=')) args.scope = raw.slice('--scope='.length);
+    else if (COMMANDS.has(raw)) args.command = raw;
+    else {
+      console.error(`Argumento desconhecido: ${raw}\n`);
+      console.error(HELP);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    console.log(HELP);
+    return 0;
+  }
+  if (args.version) {
+    console.log(pkg.version);
+    return 0;
+  }
+
+  if (args.scope !== null && args.command !== 'update') {
+    console.error(`--scope só se aplica ao comando "update" (recebido em "${args.command}").\n`);
+    console.error(HELP);
+    return 2;
+  }
+
+  switch (args.command) {
+    case 'install': {
+      const { install } = require('../installer/install');
+      return install({ yes: args.yes });
+    }
+    case 'adopt': {
+      const { adopt } = require('../installer/adopt');
+      return adopt({ yes: args.yes });
+    }
+    case 'update': {
+      const { update } = require('../installer/update');
+      return update({ yes: args.yes, scope: args.scope });
+    }
+    case 'doctor': {
+      const { doctor } = require('../installer/doctor');
+      return doctor();
+    }
+    case 'uninstall': {
+      const { uninstall } = require('../installer/uninstall');
+      return uninstall({ yes: args.yes });
+    }
+    default:
+      console.error(HELP);
+      return 2;
+  }
+}
+
+main()
+  .then((code) => process.exit(code || 0))
+  .catch((error) => {
+    console.error(`Erro: ${error.message}`);
+    process.exit(1);
+  });

package/installer/__tests__/doctor-ready-oracles.test.cjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * doctor-ready-oracles.test.cjs — a checagem de distribuição da trava de
+ * `Ready` no `installer/doctor.js` (story SF13.2, `ADR-032` `DF-SF13.2-4`).
+ *
+ * ESCOPO DELIBERADAMENTE ESTREITO. Este é o 1º teste de `doctor.js` no repo,
+ * e cobre SÓ a checagem desta story — não é mandato para cobrir as outras
+ * checagens já existentes no arquivo. Cobri-las por arrasto seria emendar
+ * escopo numa story já STANDARD.
+ *
+ * O que a checagem existe para impedir: o hook e o validador viajam por
+ * canais DIFERENTES. Numa instalação em skew (`ADR-019`) o hook chega e
+ * `scripts/validate-story-acs.cjs` não — e a trava degrada para `ask` em toda
+ * transição `Draft`→`Ready`, para sempre. Guard que sempre pergunta é guard
+ * desligado com uma tecla a mais.
+ *
+ * Os 3 sub-casos são o remédio para o não-bloqueante 4 do `*review`: o
+ * controle positivo precisa DISCRIMINAR (linha `[OK   ]` explícita), não
+ * apenas "não ter FALHA" — que seria vacuamente verdadeiro sem uma linha de
+ * código nova.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { doctor } = require(path.resolve(__dirname, '..', 'doctor.js'));
+
+const LABEL = 'Validador de ACs presente (exigido pela trava de Ready)';
+
+let failures = 0;
+const tmpDirs = [];
+
+function assert(ok, msg) {
+  if (ok) {
+    console.log(`[OK   ] ${msg}`);
+  } else {
+    console.error(`[FALHA] ${msg}`);
+    failures++;
+  }
+}
+
+/** Instalação mínima: `.claude/settings.json` (com ou sem o hook) e `scripts/`. */
+function mkFixture({ withValidator, withHook }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-ero-'));
+  tmpDirs.push(dir);
+  fs.mkdirSync(path.join(dir, '.claude'), { recursive: true });
+  const hooks = withHook
+    ? {
+      PreToolUse: [{
+        matcher: 'Edit|Write',
+        hooks: [{ type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-ready-oracles.cjs"' }],
+      }],
+    }
+    : {};
+  fs.writeFileSync(path.join(dir, '.claude', 'settings.json'), JSON.stringify({ hooks }));
+  if (withValidator) {
+    fs.mkdirSync(path.join(dir, 'scripts'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'scripts', 'validate-story-acs.cjs'), 'module.exports = {};\n');
+  }
+  return dir;
+}
+
+/**
+ * Roda o `doctor` sobre a fixture capturando `console.log`. A fixture não é
+ * uma instalação completa (sem manifest, sem .gitignore), então outras
+ * checagens falham — irrelevante: este teste olha SÓ a linha desta story.
+ */
+async function runDoctor(dir) {
+  const lines = [];
+  const origLog = console.log;
+  const cwd0 = process.cwd();
+  console.log = (...args) => lines.push(args.join(' '));
+  process.chdir(dir);
+  try {
+    await doctor();
+  } catch (err) {
+    lines.push(`[EXCECAO] ${err && err.message}`);
+  } finally {
+    process.chdir(cwd0);
+    console.log = origLog;
+  }
+  return lines;
+}
+
+function linhaDaChecagem(lines) {
+  return lines.filter((l) => l.includes(LABEL));
+}
+
+async function main() {
+  console.log('POWER CLAUDE — checagem de distribuição da trava de Ready no doctor (SF13.2)');
+
+  const okLines = await runDoctor(mkFixture({ withValidator: true, withHook: true }));
+  const failLines = await runDoctor(mkFixture({ withValidator: false, withHook: true }));
+  const skipLines = await runDoctor(mkFixture({ withValidator: false, withHook: false }));
+
+  const okLine = linhaDaChecagem(okLines);
+  const failLine = linhaDaChecagem(failLines);
+  const skipLine = linhaDaChecagem(skipLines);
+
+  assert(okLine.length === 1, 'a checagem emite exatamente 1 linha quando o hook está registrado (positivo)');
+  assert(
+    okLine.some((l) => /\[OK\s*\]/.test(l)),
+    'hook registrado + validador presente ⇒ [OK   ] EXPLÍCITO (a checagem rodou e passou, não foi pulada)',
+  );
+
+  assert(
+    failLine.some((l) => /\[FALHA\]/.test(l)),
+    'hook registrado + validador ausente ⇒ [FALHA]',
+  );
+  assert(
+    failLine.some((l) => /adopt/.test(l) && /update/.test(l)),
+    'a FALHA nomeia o comando de conserto (fixCmd: adopt + update --scope motor)',
+  );
+  assert(
+    failLine.some((l) => /Draft.*Ready/.test(l)),
+    'a FALHA explica a CONSEQUÊNCIA — toda transição Draft→Ready passa a pedir aprovação',
+  );
+
+  assert(
+    skipLine.some((l) => /\[AVISO\]/.test(l) && /checagem pulada/.test(l)),
+    'hook NÃO registrado ⇒ [AVISO] "checagem pulada" (a checagem é condicional, não incondicional)',
+  );
+  assert(
+    !skipLine.some((l) => /\[FALHA\]/.test(l)),
+    'controle negativo: numa instalação sem a trava, exigir o validador seria FALHA inventada',
+  );
+
+  for (const d of tmpDirs) fs.rmSync(d, { recursive: true, force: true });
+
+  if (failures > 0) {
+    console.error(`\nSuíte FALHOU: ${failures} violação(ões).`);
+    process.exit(1);
+  }
+  console.log('\nSuíte verde.');
+  process.exit(0);
+}
+
+main();