@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/5-referencia/sdd-framework.md

@@ -0,0 +1,115 @@
+# Spec-Driven Development (SDD)
+
+> **Para quem é:** quem quer entender por que o AIOSON funciona do jeito que funciona — ou quer customizar o processo.
+> **Tempo de leitura:** 8 min
+> **O que você vai sair sabendo:**
+> - Os 3 artefatos que governam o SDD
+> - Como a profundidade de processo muda por classificação
+> - O que é "The 80% Rule" e por que ela existe
+
+## Para que serve
+
+Sem processo explícito, cada sessão de IA inventa o seu próprio fluxo. O `@dev` começa a implementar antes de ter spec. O `@qa` testa antes de entender os ACs. O `@architect` decide stack sem ter visto os requisitos. O resultado é código que responde à pergunta errada, ou responde certo mas de um jeito que ninguém mais vai conseguir manter.
+
+O SDD (Spec-Driven Development) é a metodologia que o AIOSON adota para garantir que cada agente trabalha na ordem certa, com o artefato certo, antes de prosseguir. Não é burocracia — é a estrutura mínima que evita retrabalho.
+
+Assim como a classificação MICRO/SMALL/MEDIUM (ver [Decisões iniciais](../2-comecar/decisoes-iniciais.md)), o SDD escala: projetos menores recebem menos cerimônia.
+
+## Os 3 artefatos que governam o SDD
+
+### 1. Constitution (`constitution.md`)
+
+Localização: `.aioson/constitution.md`
+
+Os 7 artigos que nenhum agente pode quebrar. São princípios imutáveis — qualquer agente pode citar um artigo para justificar uma recusa ou uma decisão.
+
+| Artigo | Princípio |
+|---|---|
+| I | Spec First — features começam como especificação |
+| II | Right-Sized Process — MICRO ≠ MEDIUM |
+| III | Observable Work — decisões viram artefatos |
+| IV | Testable Behavior — ACs verificáveis independentemente |
+| V | Clean Handoffs — artefatos auto-suficientes |
+| VI | Simplicity Over Ceremony — sem camadas desnecessárias |
+| VII | Zero Trust by Default — segurança é baseline, não feature |
+
+Ver detalhes em [Por que ele existe](../1-entender/por-que-existe.md#os-6-princípios-da-constitution).
+
+### 2. Project Pulse (`project-pulse.md`)
+
+Localização: `.aioson/context/project-pulse.md`
+
+Estado vivo do projeto. Lido no início de cada sessão, atualizado ao fim. Responde: "o que está acontecendo neste projeto agora?" — sem precisar reler histórico.
+
+Contém: feature em andamento, agente atual, último checkpoint, bloqueios conhecidos, próxima ação.
+
+### 3. Skill `aioson-spec-driven`
+
+Localização: `.aioson/skills/process/aioson-spec-driven/SKILL.md`
+
+O playbook do processo. Define exatamente quais fases existem, quais artefatos cada fase produz, e quais gates precisam ser aprovados antes do handoff. Agentes carregam partes dele sob demanda (não o arquivo inteiro — apenas a referência relevante à fase atual).
+
+```
+Fases do SDD:
+Specify → Research → Requirements → Design → Tasks → Execute → State
+```
+
+## Profundidade por classificação
+
+A beleza do SDD é que ele se contrai para projetos pequenos:
+
+| Fase | MICRO | SMALL | MEDIUM |
+|---|---|---|---|
+| Specify (PRD lite) | obrigatória | obrigatória | obrigatória |
+| Research (@sheldon) | opcional | recomendada | obrigatória |
+| Requirements (@analyst) | pulada | obrigatória | obrigatória |
+| Design (@architect, @ux-ui) | pulada | seletiva | obrigatória |
+| Tasks/Plan | opcional | recomendada | obrigatória |
+| Execute (@dev) | direto | após gates | após gates |
+| QA/Validation | opcional | obrigatória | audit-blocking |
+
+Para MICRO: você vai de spec lite direto ao @dev. Nenhuma cerimônia.
+Para MEDIUM: cada fase tem gate de aprovação antes do próximo agente.
+
+## Gates de aprovação
+
+Em SMALL e MEDIUM, antes do handoff entre fases, um gate é verificado. Exemplo: antes do `@dev` começar, deve existir:
+- `spec-<slug>.md` com ACs verificáveis
+- `architecture.md` com decisões técnicas documentadas
+- (MEDIUM) `implementation-plan-<slug>.md` com fases de execução
+
+O gate não bloqueia automaticamente em projetos SMALL — é consultivo. Em MEDIUM, Gate D (pré-ship) bloqueia em findings High/Critical de segurança.
+
+## The 80% Rule e SDD Automation Scripts
+
+"The 80% Rule" é o princípio de que 80% do processo SDD pode ser automatizado — preflight checks, classificação, detecção de test runner, aprovação de gates — deixando os 20% críticos (decisões de produto, revisão humana) para você.
+
+Scripts implementados (commit `e0722ef`, `1cdfa6a`):
+- `sdd-preflight` — verifica se o projeto está pronto para iniciar uma fase
+- `sdd-classify` — detecta classificação com base nos critérios do `config.md`
+- `sdd-gate-check` — verifica se os artefatos necessários para o gate estão presentes
+- `detect-test-runner` — detecta o runner de testes automaticamente
+
+```bash
+# Verificar se o projeto está pronto para @dev
+aioson gate:check . --gate=C
+
+# Aprovar um gate manualmente
+aioson gate:approve . --gate=C --reason="spec revisada e validada"
+
+# Detectar test runner do projeto
+aioson detect:test-runner .
+```
+
+## Quando o SDD não se aplica
+
+- Exploração rápida sem intenção de manter. Use prompt direto.
+- Scripts de automação MICRO sem usuário externo. O `@dev` pode receber a spec no chat.
+- Quando você não vai usar o projeto de novo. Sem continuidade, sem artefatos — não tem perda.
+
+## Próximo passo
+
+- [Constitution completa](../1-entender/por-que-existe.md)
+- [Classificação MICRO/SMALL/MEDIUM](../2-comecar/decisoes-iniciais.md)
+- [SDD Automation Scripts](./sdd-automation-scripts.md)
+- [Feature Dossier](./feature-dossier.md) — onde os artefatos de cada feature vivem

package/docs/pt/5-referencia/sdd-planos-e-estrutura.md

@@ -0,0 +1,321 @@
+# SDD: Planos e estrutura de artefatos
+
+> Referência técnica da nomenclatura, hierarquia de artefatos e estrutura de planos do SDD (Spec-Driven Development).
+>
+> **Veja também:** [SDD Framework](./sdd-framework.md) — princípios e metodologia.
+
+---
+
+## O problema que este doc resolve
+
+O AIOSON tem múltiplas pastas que contêm algo chamado "plano":
+
+- `plans/` na raiz
+- `.aioson/plans/`
+- `.aioson/context/`
+- `.aioson/context/parallel/`
+
+Cada uma tem um propósito diferente. Confundi-las quebra o fluxo de agentes.
+
+---
+
+## Mapa geral de artefatos
+
+```
+projeto/
+│
+├── plans/                          ← SUAS pesquisas (pré-produção, gitignored)
+│   ├── pesquisa-stripe.md
+│   ├── analise-concorrentes.md
+│   └── source-manifest.md          ← registro de consumo
+│
+└── .aioson/
+    ├── context/                    ← ARTEFATOS do ciclo de agentes
+    │   ├── project.context.md      ← @setup
+    │   ├── project-pulse.md        ← estado global (atualizado a cada sessão)
+    │   ├── prd.md                  ← @product (projeto novo)
+    │   ├── prd-{slug}.md           ← @product (feature específica)
+    │   ├── sheldon-enrichment.md   ← @sheldon (histórico de enriquecimento)
+    │   ├── architecture.md         ← @analyst + @architect
+    │   ├── design-doc.md           ← @ux-ui
+    │   ├── tasks.md                ← @pm
+    │   ├── dev-state.md            ← @dev (continuidade de sessão)
+    │   ├── test-plan.md            ← @qa
+    │   ├── features.md             ← registro de features (status por slug)
+    │   └── parallel/               ← @orchestrator (lanes paralelas)
+    │       ├── lane-backend.md
+    │       ├── lane-ui.md
+    │       └── harness-contract.json
+    │
+    └── plans/                      ← PLANOS FASEADOS gerados por @sheldon
+        └── {slug}/
+            ├── phase-1.md
+            ├── phase-2.md
+            ├── harness-contract.json
+            └── progress.json
+```
+
+---
+
+## `plans/` (raiz) — pesquisas pré-produção
+
+| Característica | Detalhe |
+|---|---|
+| **Quem escreve** | Você — antes do ciclo de agentes |
+| **Conteúdo** | Rascunhos, exportações de chat, benchmarks, análises |
+| **Gitignored?** | Sim (padrão) |
+| **Lido por** | `@briefing`, `@product`, `@sheldon` |
+| **Modificado por agentes?** | Nunca — read-only |
+| **Quando remover** | Você decide; tipicamente após entrega completa |
+
+O arquivo especial `plans/source-manifest.md` é criado automaticamente e registra qual agente consumiu qual arquivo e que artefato foi produzido. Serve para auditoria: "o que foi gerado a partir do quê?".
+
+Veja [Plans externos para @product](../3-receitas/plans-externos-para-product.md) para o fluxo de uso.
+
+---
+
+## `.aioson/context/` — artefatos do ciclo
+
+É a pasta central do AIOSON. Cada agente lê e escreve aqui dentro de sua responsabilidade.
+
+### Artefatos de produto e planejamento
+
+| Arquivo | Criado por | Consumido por |
+|---|---|---|
+| `project.context.md` | `@setup` | todos os agentes (sempre) |
+| `project-pulse.md` | qualquer agente (ao fechar sessão) | todos os agentes (ao iniciar sessão) |
+| `prd.md` | `@product` (projeto novo) | `@sheldon`, `@analyst`, `@ux-ui`, `@pm`, `@dev` |
+| `prd-{slug}.md` | `@product` (feature) | idem |
+| `sheldon-enrichment.md` | `@sheldon` | `@sheldon` (re-entrada), `@analyst` |
+| `architecture.md` | `@analyst` + `@architect` | `@ux-ui`, `@pm`, `@dev`, `@qa` |
+| `design-doc.md` | `@ux-ui` | `@pm`, `@dev` |
+| `tasks.md` | `@pm` | `@orchestrator`, `@dev` |
+| `features.md` | qualquer agente | todos (status por slug) |
+
+### Artefatos de execução
+
+| Arquivo | Criado por | Consumido por |
+|---|---|---|
+| `dev-state.md` | `@dev` (ao pausar/fechar) | `@deyvin` (retomada), `@dev` |
+| `test-plan.md` | `@qa` | `@qa` (iterações), `@validator` |
+| `qa-report-{slug}.md` | `@qa` | `@validator`, `@tester` |
+| `test-inventory.md` | `@tester` | `@qa` (rodada seguinte) |
+| `security-findings-{slug}.json` | `@pentester` | `@dev` (correção), `@qa` (regressão) |
+| `last-handoff.json` | `@validator` | fechamento da feature |
+
+### `parallel/` — lanes do `@orchestrator`
+
+O `@orchestrator` cria esta subpasta quando detecta trabalho paralelizável:
+
+```
+.aioson/context/parallel/
+├── lane-backend.md         ← tarefas sem dependência de UI
+├── lane-ui.md              ← componentes front-end
+├── lane-migration.md       ← schema de banco
+└── harness-contract.json   ← contrato de sucesso (lido por @validator)
+```
+
+Cada `lane-*.md` tem:
+- Lista de tarefas com ordem de execução
+- Dependências entre lanes (ex: "lane-ui depende da API definida em lane-backend")
+- Critérios de aceite por lane
+
+O `@dev` pode trabalhar uma lane por sessão. O `@deyvin` retoma a lane que ficou incompleta.
+
+---
+
+## `.aioson/plans/` — planos faseados do `@sheldon`
+
+Criado quando o `@sheldon` detecta que a feature é grande demais para implementação única. Contém o plano de execução faseada.
+
+```
+.aioson/plans/{slug}/
+├── phase-1.md              ← escopo, entidades, ACs da fase 1
+├── phase-2.md              ← escopo da fase 2
+├── harness-contract.json   ← critérios de sucesso de cada fase
+└── progress.json           ← status corrente (lido por @dev, @qa)
+```
+
+### Estrutura de um `phase-N.md`
+
+```markdown
+---
+phase: 1
+title: "Core subscription model"
+status: in_progress
+depends_on: []
+---
+
+## Escopo
+O que está incluso nesta fase e o que fica para depois.
+
+## Entidades
+Quais entidades de domínio são introduzidas ou modificadas.
+
+## ACs desta fase
+- AC-01: ...
+- AC-02: ...
+
+## Fora do escopo desta fase
+...
+```
+
+### `harness-contract.json`
+
+Contrato binário lido pelo `@validator` no gate D:
+
+```json
+{
+  "feature": "billing-assinatura",
+  "phases": [
+    {
+      "phase": 1,
+      "required": ["AC-01", "AC-02", "AC-03"],
+      "optional": ["AC-09"]
+    }
+  ],
+  "global_required": ["nenhum HIGH em security-findings"]
+}
+```
+
+### `progress.json`
+
+Estado corrente atualizado pelo `@dev`:
+
+```json
+{
+  "feature": "billing-assinatura",
+  "current_phase": 2,
+  "phases": {
+    "1": "complete",
+    "2": "in_progress",
+    "3": "pending"
+  },
+  "updated_at": "2026-05-07T14:30:00Z"
+}
+```
+
+---
+
+## `tasks.md` — o backlog do `@pm`
+
+Criado pelo `@pm` (somente em MEDIUM). Formato:
+
+```markdown
+# Tasks — {feature-slug}
+
+## Epic 1: Subscription Model
+
+### US-01: Criar plano de assinatura
+**Como** admin, **quero** criar planos (mensal/anual), **para** oferecer opções ao cliente.
+
+**ACs:**
+- [ ] POST /plans retorna 201 com id, name, price, interval
+- [ ] Validação: price > 0, interval in ["monthly", "annual"]
+- [ ] Duplicate name retorna 422
+
+**Story points:** 3
+**Dependências:** nenhuma
+
+---
+
+### US-02: Assinar plano
+**Como** cliente...
+```
+
+O `@orchestrator` lê `tasks.md` para identificar dependências e criar lanes paralelas.
+
+---
+
+## `features.md` — registro de features
+
+Mantido por múltiplos agentes. Rastreia o status de cada feature por slug:
+
+```markdown
+# Features Registry
+
+| slug | status | started | closed | verdict |
+|------|--------|---------|--------|---------|
+| billing-assinatura | in_progress | 2026-05-01 | — | — |
+| push-notifications | done | 2026-04-15 | 2026-04-22 | PASS |
+| checkout-v2 | qa_failed | 2026-04-28 | 2026-04-30 | FAIL |
+```
+
+**Status possíveis:**
+
+| Status | Significado |
+|---|---|
+| `planned` | PRD existe, implementação não iniciou |
+| `in_progress` | `@dev` ativo |
+| `qa_review` | Aguardando `@qa` |
+| `done` | Fechada com PASS via `feature:close` |
+| `qa_failed` | Fechada com FAIL — requer re-abertura |
+
+---
+
+## `project-pulse.md` — estado global da sessão
+
+Atualizado por todos os agentes ao fechar cada sessão. Serve como "onde estávamos?" para a próxima sessão.
+
+```markdown
+---
+active_agent: dev
+active_feature: billing-assinatura
+last_agent: sheldon
+last_gate: "Gate B: approved"
+updated_at: 2026-05-07T15:00:00Z
+---
+
+# Project Pulse
+
+## Active work
+Implementando Phase 2 de billing-assinatura: webhook handler com idempotency.
+
+## Next step
+Phase 3: Dunning cron job (3 tentativas, intervalos 1d/3d/7d).
+
+## Recent Activity
+- 2026-05-07 15:00 · @dev · Phase 2 iniciada
+- 2026-05-07 10:00 · @sheldon · PRD enriquecido, phased plan criado
+- 2026-05-06 18:00 · @product · PRD criado
+```
+
+O `aioson pulse:update` atualiza este arquivo via script (sem precisar de LLM). Ver [SDD Automation Scripts](./sdd-automation-scripts.md).
+
+---
+
+## Fluxo de artefatos por classificação
+
+### MICRO
+
+```
+plans/ → prd.md → [dev implementa] → qa-report.md
+```
+
+### SMALL
+
+```
+plans/ → prd.md → sheldon-enrichment.md → architecture.md
+       → dev-state.md → test-plan.md → qa-report.md
+```
+
+### MEDIUM (completo)
+
+```
+plans/ → prd.md → sheldon-enrichment.md → .aioson/plans/{slug}/
+       → architecture.md → design-doc.md → tasks.md
+       → parallel/ → dev-state.md (por lane)
+       → test-plan.md → qa-report.md → test-inventory.md
+       → security-findings.json → last-handoff.json
+```
+
+---
+
+## Referências cruzadas
+
+- [SDD Framework](./sdd-framework.md) — princípios, Constitution, MICRO/SMALL/MEDIUM
+- [SDD Automation Scripts](./sdd-automation-scripts.md) — comandos para mover estado sem LLM
+- [Feature Dossier](./feature-dossier.md) — ponto único de verdade por feature
+- [Agent-chain continuity](./agent-chain-continuity.md) — como `dev-state.md` é usado para retomada
+- [Plans externos para @product](../3-receitas/plans-externos-para-product.md) — usar `plans/` como entrada
+- [Feature completa com @sheldon](../3-receitas/feature-completa-com-sheldon.md) — fluxo prático com todos os artefatos

package/docs/pt/5-referencia/secure-by-default.md

@@ -0,0 +1,117 @@
+# Secure by Default
+
+> **Para quem é:** desenvolvedores que querem entender como o AIOSON trata segurança — e como configurar o baseline.
+> **Tempo de leitura:** 7 min
+> **O que você vai sair sabendo:**
+> - Os 8 controles do baseline e como cada um funciona
+> - O que muda por classificação (MICRO/SMALL/MEDIUM)
+> - Como o git:guard protege seus commits
+
+## Para que serve
+
+Segurança costuma ser tratada como etapa opcional — "a gente adiciona autenticação depois". O AIOSON inverte isso: o baseline de segurança é o estado padrão. Cada agente técnico (`@analyst`, `@architect`, `@dev`, `@qa`) carrega as regras automaticamente. Você não precisa pedir.
+
+Isso é o **Artigo VII da Constitution: Zero Trust by Default**. Controles de segurança têm IDs estáveis (`SEC-SBD-01..08`) para que specs, QA reports e security-findings possam referenciá-los sem ambiguidade.
+
+## Os 8 controles
+
+O baseline vive em `.aioson/rules/security-baseline.md` (carregado automaticamente por agentes técnicos).
+
+| Controle | O que protege | Mapeamento OWASP |
+|---|---|---|
+| **SEC-SBD-01** | Limites de input server-side (campo, tipo, range) | A03 / A04 |
+| **SEC-SBD-02** | Autenticação e autorização (toda rota protegida explicitamente) | A01 / A07 |
+| **SEC-SBD-03** | Tratamento seguro de uploads (validação de tipo, tamanho, armazenamento) | A04 / A05 |
+| **SEC-SBD-04** | Redação de secrets em logs (nunca logar tokens, senhas, chaves) | A09 |
+| **SEC-SBD-05** | Rate limiting em endpoints sensíveis (auth, pagamento, busca pública) | A04 |
+| **SEC-SBD-06** | Validação de URLs externas (SSRF — não seguir redirects de forma cega) | A10 |
+| **SEC-SBD-07** | Política de dependências (sem deps com CVEs conhecidos no publish path) | A06 |
+| **SEC-SBD-08** | Headers de segurança (CORS, CSP, HSTS, X-Frame conforme contexto) | A05 |
+
+Cada controle define: owner agent, evidence obrigatória, e se pode ser marcado N/A (com rationale na spec).
+
+## O que muda por classificação
+
+| Classificação | Comportamento |
+|---|---|
+| **MICRO** | Advisory. Os controles são surfaçados como recomendações. Nenhum bloqueio automático. |
+| **SMALL** | Scan-oriented. Checks estáticos rodam automaticamente. Findings Medium+ são reportados mas não bloqueiam. |
+| **MEDIUM** | Audit-blocking. **Gate D bloqueia o ship** se houver findings High ou Critical abertos. Precisam ser resolvidos ou waived com rationale na `spec-<slug>.md`. |
+
+Em qualquer classificação, `@pentester` pode ser invocado manualmente quando a feature envolve auth, dinheiro, upload, URLs externas ou ownership.
+
+## git:guard — proteção no commit
+
+O `git:guard` inspeciona os arquivos em staging antes do commit. Detecta:
+
+- Secrets em texto plano (tokens, senhas, chaves API em assignments)
+- Arquivos que não deveriam ir para o repositório (node_modules, logs, etc.)
+- Extensões ou paths bloqueados pela política do projeto
+
+```bash
+# Inspeção manual
+aioson git:guard .
+
+# Com saída JSON (para scripts)
+aioson git:guard . --json
+
+# Instalar como pre-commit hook (bloqueia automático antes de todo commit)
+aioson git:guard . --install-hook
+
+# Remover o hook
+aioson git:guard . --uninstall-hook
+
+# Inspecionar mas não bloquear em warnings
+aioson git:guard . --allow-warnings
+```
+
+A política do projeto fica em `.aioson/git-guard.json`:
+
+```json
+{
+  "version": 1,
+  "allowPaths": [],
+  "contentAllowPaths": [],
+  "blockPaths": ["node_modules/**", "aioson-logs/**"],
+  "allowExtensions": [],
+  "blockExtensions": []
+}
+```
+
+## Como os agentes consomem o baseline
+
+Quando `@dev` vai implementar uma rota de pagamento:
+
+```
+@dev > Carregando security-baseline.md...
+       SEC-SBD-01: input limits — adicionando validação de amount > 0 e <= 999999.
+       SEC-SBD-02: auth — rota protegida com middleware verifyJWT.
+       SEC-SBD-05: rate limit — 10 req/min em POST /checkout.
+       SEC-SBD-04: logs — payment ID logado, mas não o número do cartão.
+```
+
+O agente não precisa de instrução sua. Ele lê as regras e aplica. Se um controle não se aplica à feature, ele registra `N/A` com rationale na spec.
+
+## Saídas em disco
+
+```
+.aioson/
+├── rules/
+│   └── security-baseline.md          ← baseline (carregado por agentes técnicos)
+└── git-guard.json (na raiz do template) ← política de commit
+
+.aioson/context/
+└── security-findings-<slug>.json     ← findings gerados por @pentester ou @qa
+```
+
+## Quando NÃO usar
+
+- `git:guard --install-hook` em projetos com pipeline CI que já faz análise similar. Pode gerar conflito de gatekeeping.
+- Marcar controles como N/A sem rationale. A spec deve registrar explicitamente por que um controle não se aplica.
+- Invocar `@pentester` em todo commit de MICRO. Ele é para features com superfície de ataque real.
+
+## Próximo passo
+
+- [Ficha do @pentester](../4-agentes/pentester.md) — revisão adversarial completa
+- [SDD Framework](./sdd-framework.md) — como os gates bloqueiam em findings de segurança
+- [Por que ele existe](../1-entender/por-que-existe.md) — Artigo VII da Constitution