feat(kernel): v0.5.2 — hooks, self-test no CI, plugin manifest, regras reequilibradas e testes

.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "ai-dev-operating-system",
+  "version": "0.5.2",
+  "description": "Day-zero operating system for AI-assisted SaaS development. A 5-phase Project Genesis Wizard that prototypes before it specifies, 27 skills, 12 agents, 11 commands, a curated registry of 72 external packs, a 1.346-project self-hosted catalogue, and PreToolUse hooks that block secret commits mechanically rather than by asking nicely.",
+  "author": {
+    "name": "Lucas Galvão",
+    "url": "https://github.com/lglucas"
+  },
+  "homepage": "https://github.com/lglucas/ai-dev-operating-system",
+  "repository": "https://github.com/lglucas/ai-dev-operating-system",
+  "license": "MIT",
+  "keywords": [
+    "saas",
+    "wizard",
+    "vibe-coding",
+    "product-discovery",
+    "business-plan",
+    "prototyping",
+    "sprint-planning",
+    "secrets",
+    "self-hosted",
+    "portuguese"
+  ]
+}

.claude/agents/business-red-team-agent.md

@@ -1,6 +1,6 @@
 ---
 name: business-red-team-agent
-description: Reviews business model, pricing, CAC, LTV, GTM, margins, operations, and financial realism.
+description: Attacks the business model — pricing, CAC, LTV, margins, GTM, retention and financial realism — proposing a fix for each hole. Runs in Wave 2 of WIZARD stage 2.5, and as a reviewer role in multi-ai-review. Use when the user says "quanto devo cobrar?", "isso fecha a conta?", "esse preço faz sentido?", "dá pra viver disso?", or before any pricing or packaging change.
 tools: Read, Write, Edit, Grep, Glob
 model: opus
 ---

.claude/agents/competitor-research-agent.md

@@ -1,6 +1,6 @@
 ---
 name: competitor-research-agent
-description: Finds, filters, and analyzes competitors for a new project.
+description: Finds up to 20 competitors, narrows to the top 5, and analyzes positioning, pricing, onboarding, integrations and public complaints into knowledge-base/competitors/. Runs in Wave 1 of WIZARD stage 2.4. Use when the user asks "quem são meus concorrentes?", "alguém já faz isso?", "por que alguém escolheria eu e não eles?". Never invents a competitor or a price.
 tools: Read, Write, Edit, WebSearch, WebFetch
 model: sonnet
 ---

.claude/agents/coordinator-agent.md

@@ -1,6 +1,6 @@
 ---
 name: coordinator-agent
-description: Consolidates multi-agent work, resolves conflicts, checks completeness, and approves deliverables.
+description: Consolidates the output of several agents, resolves their contradictions, checks completeness and approves the deliverable. Runs in Wave 3 of WIZARD stage 2.6 and as the final gate in release-check. Use when two agents disagree, or when the user asks "e agora, quem tá certo?", "dá pra fechar isso?", "tá completo?", "posso considerar pronto?".
 tools: Read, Write, Edit, Grep, Glob
 model: opus
 ---

.claude/agents/copywriter-agent.md

@@ -1,6 +1,6 @@
 ---
 name: copywriter-agent
-description: Turns structured research and decisions into persuasive, clear business and product documents.
+description: Turns validated research and decisions into readable, persuasive text — the Business Plan v0.0.1 in Wave 3 of WIZARD stage 2.6, plus landing copy, product messaging and emails later. Use when the user says "escreve isso bonito", "como eu explico isso pro investidor?", "faz o texto da landing", "isso tá confuso demais". Never adds a claim the research does not support.
 tools: Read, Write, Edit, Grep, Glob
 model: sonnet
 ---

.claude/agents/dev-product-agent.md

@@ -1,6 +1,6 @@
 ---
 name: dev-product-agent
-description: Reviews product scope, architecture, implementation plans, and technical feasibility.
+description: Reviews product scope, architecture and implementation plans for feasibility — whether what is described can actually be built at this size, in this order, by this team. Reads PRODUCT-BRIEF.md and TECHNICAL-PLAN.md. Use when the user asks "dá pra fazer isso no MVP?", "isso é muita coisa?", "por onde eu começo a construir?", "esse escopo cabe na sprint?".
 tools: Read, Write, Edit, Grep, Glob, Bash
 model: sonnet
 ---

.claude/agents/devils-advocate-agent.md

@@ -1,6 +1,6 @@
 ---
 name: devils-advocate-agent
-description: Stress-tests ideas, business plans, assumptions, and sprint plans while proposing concrete fixes.
+description: Attacks weak assumptions, contradictions and fragile claims in an idea, BP or sprint plan — and proposes a concrete fix for every objection. Runs in Wave 2 of WIZARD stage 2.5, and as a reviewer role in multi-ai-review. Use when the user says "acha que isso funciona?", "onde isso pode dar errado?", "me critica isso", "tá bom demais pra ser verdade?".
 tools: Read, Write, Edit, Grep, Glob
 model: opus
 ---

.claude/agents/legal-compliance-agent.md

@@ -1,6 +1,6 @@
 ---
 name: legal-compliance-agent
-description: Vibe-coder-friendly legal baseline — Privacy Policy, Terms of Service, LGPD/GDPR data flows, age gates, refund policy, cookie disclosure. Generates plain-Portuguese first drafts that a real lawyer can later review. Activated before public launch, before collecting user data, or when payments are wired.
+description: Vibe-coder-friendly legal baseline — Privacy Policy, Terms of Service, LGPD/GDPR data flows, age gates, refund policy, cookie disclosure. Generates plain-Portuguese first drafts a real lawyer can later review; never a legal opinion. Activated before public launch, before collecting user data, before charging, and when the user says "preciso de política de privacidade?", "e a LGPD?", "posso usar essa licença no meu SaaS?", "isso me processa?". Activated before public launch, before collecting user data, or when payments are wired.
 ---
 
 # Legal Compliance Agent

.claude/agents/market-research-agent.md

@@ -1,6 +1,6 @@
 ---
 name: market-research-agent
-description: Researches market context, trends, customer behavior, and validation sources.
+description: Researches market size, customer behaviour, regulatory constraints and credible benchmarks into knowledge-base/market/, always with a source index. Runs in Wave 1 of WIZARD stage 2.4. Use when the user asks "esse mercado existe?", "quantas pessoas têm esse problema?", "tem regulação nisso?", "quanto o pessoal cobra por isso?". Never fabricates a market number — asks for links when it cannot verify.
 tools: Read, Write, Edit, WebSearch, WebFetch
 model: sonnet
 ---

.claude/agents/research-agent.md

@@ -1,6 +1,6 @@
 ---
 name: research-agent
-description: Performs source-backed research and separates facts from assumptions.
+description: Does general source-backed research into knowledge-base/, always separating fact-with-source from inference, assumption and open question per .claude/rules/research-discipline.md. Broader than the market and competitor agents — use it for anything else the project needs verified. Triggers on "pesquisa isso pra mim", "isso é verdade?", "tem dado sobre isso?", "de onde veio esse número?". Says "não encontrei" instead of inventing.
 tools: Read, Write, Edit, WebSearch, WebFetch
 model: sonnet
 ---

.claude/agents/technical-security-red-team-agent.md

@@ -1,6 +1,6 @@
 ---
 name: technical-security-red-team-agent
-description: Reviews technical feasibility, architecture, security, privacy, compliance, scalability, and MVP complexity.
+description: Attacks technical feasibility, architecture, security, privacy, compliance, scalability and MVP complexity — proposing a fix for each risk. Runs in Wave 2 of WIZARD stage 2.5, and as a reviewer role in multi-ai-review. Use when the user says "isso é seguro?", "aguenta quanta gente?", "dá pra construir isso mesmo?", "e se alguém tentar invadir?", or before wiring auth, payments or personal data.
 tools: Read, Write, Edit, Grep, Glob, Bash
 model: opus
 ---

.claude/commands/bp-review.md

@@ -1,3 +1,7 @@
+---
+description: Aplica suas correções ao Business Plan e roda o impact review — preço mexe em projeção e LTV, persona mexe em GTM e escopo. Produz o BP v0.0.2.
+---
+
 # /bp-review
 
 Run BP revision after user feedback: apply corrections, run impact review, produce BP v0.0.2, update changelog and session log.

.claude/commands/grow-sustainably.md

@@ -1,3 +1,7 @@
+---
+description: Planeja o crescimento de 100 para ~1000 usuários sem queimar fundador, caixa nem base. Sucessor do first-100-users. Use ao dizer "já tenho 100 usuários, e agora?" ou "o WhatsApp 1-a-1 não escala mais".
+---
+
 # /grow-sustainably
 
 Plan post-first-100-users growth without burning out the founder, the budget, or the user base.

.claude/commands/multi-ai-review.md

@@ -1,3 +1,7 @@
+---
+description: Passa uma decisão difícil de reverter por 2–4 revisores independentes e reconcilia as divergências antes de você agir. Use ao dizer "não dá pra desfazer fácil" — arquitetura, segurança, preço, deploy, texto jurídico.
+---
+
 # /multi-ai-review
 
 Cross-review a hard-to-reverse decision through 2–4 independent reviewer roles, reconcile disagreements, and decide proceed / modify / block before committing.

.claude/commands/processize.md

@@ -1,3 +1,7 @@
+---
+description: Transforma um fluxo que você já validou na mão em processo documentado e parcialmente automatizável. Use ao dizer "tô fazendo isso toda semana" ou "vamos automatizar?". Nunca automatiza o que ainda não funcionou manualmente.
+---
+
 # /processize
 
 Codify a manually-validated workflow into a documented, partially-automatable process. Validate-then-automate, never the reverse.

.claude/commands/project-start.md

@@ -1,3 +1,7 @@
+---
+description: Inicia o Project Genesis Wizard — do "me fale sobre teu projeto" até o primeiro sprint de código, em 5 fases. Não escreve código.
+---
+
 # /project-start
 
 Start the Project Genesis Wizard.

.claude/commands/prototype-lab.md

@@ -1,3 +1,7 @@
+---
+description: Cria o Prototype Lab da Fase 3 — três direções visuais distintas em HTML/CSS/JS com o mesmo mock data. Roda ANTES do Product Brief, não depois.
+---
+
 # /prototype-lab
 
 Create the isolated HTML Prototype Lab with three distinct UI/UX directions using the same mock data.

.claude/commands/registry-pick.md

@@ -1,3 +1,7 @@
+---
+description: Recomenda packs externos do registry que servem pro projeto atual. Roda duas vezes no wizard — packs de design no 3.1, stack completa no 4.3. Nunca instala nada.
+---
+
 # /registry-pick
 
 Recommend external repository packs from the registry that fit the current project.
@@ -14,7 +18,14 @@ Optional arguments:
 /registry-pick stack="<stack>" domain="<domain>" compliance="<compliance>"
 ```
 
-If arguments are omitted, the skill will read project signals from `docs/business/BUSINESS-PLAN.md`, `docs/product/PRODUCT-BRIEF.md`, `docs/technical/TECHNICAL-PLAN.md`, and the repo manifest files (`package.json`, `Anchor.toml`, etc.).
+If arguments are omitted, the skill reads project signals from whatever exists at that point in the wizard — the input contract differs per pass:
+
+| Pass | Lê | NÃO lê |
+|---|---|---|
+| **3.1** design | `docs/business/BUSINESS-PLAN.md` v0.0.2, `knowledge-base/` | Product Brief e Technical Plan — ainda não existem |
+| **4.3** stack | tudo acima + `docs/product/PRODUCT-BRIEF.md`, `docs/technical/TECHNICAL-PLAN.md`, `prototype-lab/`, manifestos (`package.json`, `Anchor.toml`…) | — |
+
+Pedir na passada de design um arquivo que a Fase 3 ainda não produziu trava o wizard sem motivo.
 
 ## Actions
 

.claude/commands/research-waves.md

@@ -1,3 +1,7 @@
+---
+description: Executa as 3 ondas de pesquisa da Fase 2 — mercado e concorrentes, red team, consolidação e BP v0.0.1. Nunca inventa dado de mercado.
+---
+
 # /research-waves
 
 Prepare or execute the 3-wave research plan from `WIZARD.md`.

.claude/commands/sprint-close.md

@@ -1,3 +1,7 @@
+---
+description: Fecha a sprint ativa — atualiza changelog e session log, checa a DoD e prepara a tag. Use ao dizer "fecha a sprint" ou "terminei essa etapa".
+---
+
 # /sprint-close
 
 Close the active sprint.

.claude/commands/sprint-plan.md

@@ -1,3 +1,7 @@
+---
+description: Monta o roadmap de 14–20 sprints com DoD, entregáveis, gates de segurança e riscos. Roda no estágio 4.4, depois do Product Brief e do Technical Plan.
+---
+
 # /sprint-plan
 
 Create or update the 14–20 sprint roadmap with DoD, deliverables, agents, skills, tests, security gates, risks, and artifacts.

.claude/commands/sprint-start.md

@@ -1,3 +1,8 @@
+---
+description: Abre uma sprint — cria a branch, o doc da sprint e o objetivo com DoD. Use quando disser "vamos começar a sprint" ou ao terminar a anterior.
+argument-hint: sprint=NN theme="Foundation" dates="YYYY-MM-DD to YYYY-MM-DD"
+---
+
 # /sprint-start
 
 Start a new sprint.

.claude/hooks/README.md

@@ -0,0 +1,91 @@
+# Hooks — o kernel do OS
+
+Todo o resto deste operating system é **instrução**: regras que o agente lê, skills que ele invoca, um wizard que ele segue. Funciona porque o modelo colabora.
+
+Hooks são a única camada que **não depende de colaboração.** São processos que o Claude Code executa antes da ferramenta rodar, e cujo código de saída ele não pode ignorar.
+
+Por isso existe pouco aqui, e por isso o que existe é só sobre segredo — a única classe de erro cujo custo não dá para desfazer pedindo desculpa.
+
+---
+
+## O que está ativo
+
+| Hook | Dispara em | Bloqueia |
+|---|---|---|
+| [`block-secret-commit.js`](block-secret-commit.js) | `Bash` → qualquer `git commit` | commit cujo diff adiciona algo com formato de credencial, ou que staged um `.env`/`.pem`/`.key` |
+| [`protect-env-files.js`](protect-env-files.js) | `Write`, `Edit`, `MultiEdit`, `NotebookEdit` | escrita em `.env` real (libera `.env.example`) |
+
+Configurados em [`../settings.json`](../settings.json). Contrato: **exit 0 permite, exit 2 bloqueia** e mostra o stderr ao Claude.
+
+---
+
+## Por que os padrões exigem formato completo
+
+A regra [`../rules/secrets.md`](../rules/secrets.md) lista `sk-`, `ghp_`, `AKIA` como padrões a detectar. Se o hook casasse por prefixo, **bloquearia commitar a própria regra que define os padrões** — o arquivo contém aquele texto literalmente.
+
+Então os padrões exigem o formato inteiro:
+
+| Padrão | Exige |
+|---|---|
+| OpenAI | `sk-` + 20 caracteres ou mais |
+| GitHub PAT | `ghp_` + exatamente 36 |
+| GitHub fine-grained | `github_pat_` + 50 ou mais |
+| AWS | `AKIA` + exatamente 16 maiúsculas/dígitos |
+| Google | `AIza` + exatamente 35 |
+| Slack | `xox[baprs]-` + 10 ou mais |
+| Stripe | `sk_live_` / `rk_live_` + 20 ou mais |
+| Chave privada | bloco `-----BEGIN ... PRIVATE KEY-----` |
+
+Documentação que menciona o prefixo passa. Uma chave real, não.
+
+**O hook nunca imprime o valor encontrado** — só o arquivo e o nome do padrão. Um alerta que ecoa a credencial no terminal a espalha em vez de contê-la.
+
+Só linhas **adicionadas** são inspecionadas. Remover uma chave vazada precisa continuar possível.
+
+---
+
+## Escape hatch
+
+Falso positivo acontece. Cada hook tem uma variável de ambiente que o desliga por uma execução:
+
+```bash
+AIOS_ALLOW_SECRET_COMMIT=1 git commit -m "fixture de teste com token falso"
+AIOS_ALLOW_ENV_WRITE=1
+```
+
+**Se usar, registre o porquê no `session-log/`.** Um escape sem justificativa vira hábito, e o hook para de servir para alguma coisa.
+
+---
+
+## Requisito
+
+**Node.js.** Os hooks são `.js` sem nenhuma dependência — rodam com o Node que já está na máquina.
+
+A escolha foi por portabilidade: shell script quebra no Windows sem git-bash, e Python não é garantido. Node é o denominador comum de quem constrói SaaS, que é o público deste OS.
+
+Sem Node instalado, os hooks falham ao iniciar e o Claude Code segue sem eles. **O OS continua funcionando, só perde o kernel** — volta a depender de o modelo colaborar.
+
+---
+
+## Adicionar um hook novo
+
+1. Escreva o `.js` em `.claude/hooks/`, lendo o payload JSON do stdin.
+2. Saia com 0 para permitir, 2 para bloquear com mensagem no stderr.
+3. **Falhe aberto** em payload malformado — um hook quebrado não pode travar a sessão inteira.
+4. Registre em `settings.json` e `settings.example.json`.
+5. Escreva o teste em `scripts/test/` e rode com `node --test scripts/test/*.test.js` — **sem aspas**. Passar o diretório faz o Node resolvê-lo como módulo; aspas só funcionam no Node 21+, que adicionou glob ao `--test`. Sem aspas, quem expande é o shell, e funciona em qualquer versão.
+6. Documente aqui, com o escape hatch.
+
+O ponto 3 é o mais importante. Um hook que bloqueia por engano é pior que hook nenhum: o usuário desliga tudo e perde junto o que funcionava.
+
+---
+
+## O que deliberadamente NÃO virou hook
+
+Foi tentador, e seria errado:
+
+- **Forçar o wizard.** Bloquear escrita em `src/` antes da Fase 5 pune quem legitimamente quer só um protótipo rápido. O wizard convence; não prende.
+- **Exigir changelog em todo commit.** Vira ruído em commit de typo.
+- **Bloquear push para `main`.** Isso é branch protection do GitHub, e já existe. Hook local seria redundante e contornável.
+
+Regra de bolso: **hook para o que é irreversível.** Segredo vazado é irreversível. Ordem de estágio do wizard, não.