@jaimevalasek/aioson 1.6.0 → 1.7.0

package/docs/pt/monitor-de-contexto.md

@@ -1,14 +1,16 @@
 # Monitor de Contexto
 
-> Visualiza em tempo real o uso de janela de contexto por agente, com alertas automáticos de warning e critical.
+> Visualiza em tempo real o uso de janela de contexto por agente, com alertas automáticos de warning e critical. Também funciona no modo de budget de projeto para sessões diretas.
 
-O `context:monitor` lê o arquivo `context-monitor.json` de uma squad e exibe barras de progresso ASCII com o percentual de contexto utilizado por cada agente. Útil para acompanhar sessões longas e antecipar quando um agente está próximo de compactar.
+O `context:monitor` tem dois modos de operação:
+- **Modo squad** — lê `context-monitor.json` da squad e exibe barras de progresso por agente
+- **Modo budget** — recebe `--budget` + `--tokens` e calcula a zona de alerta da sessão atual
 
 ---
 
-## Comando
+## Modo squad
 
-### `context:monitor`
+### `context:monitor --squad`
 
 ```bash
 aioson context:monitor [path] [opções]
@@ -18,7 +20,7 @@ aioson context:monitor [path] [opções]
 
 | Opção | Descrição |
 |---|---|
-| `--squad=<slug>` | Squad a monitorar (obrigatório) |
+| `--squad=<slug>` | Squad a monitorar (obrigatório neste modo) |
 | `--agent=<id>` | Filtrar por agente específico (opcional) |
 | `--json` | Retorna dados estruturados em JSON |
 
@@ -37,6 +39,58 @@ aioson context:monitor . --squad=meu-squad --json
 
 ---
 
+## Modo budget de projeto
+
+Útil em sessões diretas (sem squad) para checar se você está próximo do limite da janela de contexto.
+
+### `context:monitor --budget`
+
+```bash
+aioson context:monitor [path] --budget=<tokens-totais> --tokens=<tokens-atuais>
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--budget=<n>` | Limite total em tokens (ex: `80000` para Claude Sonnet) |
+| `--tokens=<n>` | Tokens consumidos atualmente na sessão |
+| `--json` | Retorna JSON com zona, percentual e budget |
+
+**Zonas:**
+
+| Zona | Faixa | Ícone | Ação sugerida |
+|---|---|---|---|
+| safe | < 60% | ✓ | Continuar normalmente |
+| warning | 60–80% | ⚠ | Planejar `/clear` antes do próximo agente |
+| critical | ≥ 80% | ! | Rodar `context:health` e reduzir carga |
+
+**Exemplos:**
+
+```bash
+# Sessão em safe zone
+aioson context:monitor . --budget=80000 --tokens=28000
+#   ✓ Context: 28,000 tokens (35%) — SAFE
+
+# Sessão em warning zone
+aioson context:monitor . --budget=80000 --tokens=52000
+#   ⚠ Context: 52,000 tokens (65%) — WARNING
+#   Suggestion: /clear before next agent activation
+
+# Sessão em critical zone
+aioson context:monitor . --budget=80000 --tokens=67000
+#   ! Context: 67,000 tokens (84%) — CRITICAL
+#   Run: aioson context:health . for reduction options
+
+# JSON para automação
+aioson context:monitor . --budget=80000 --tokens=52000 --json
+# { "ok": true, "tokens": 52000, "budget": 80000, "pct": 65, "zone": "warning" }
+```
+
+Quando a zona é `warning` ou `critical`, um evento `context_budget_warning` ou `context_budget_critical` é automaticamente registrado no SQLite (na run ativa mais recente), ficando visível no dashboard.
+
+---
+
 ## Saída
 
 ```

package/docs/pt/sdd-automation-scripts.md

@@ -0,0 +1,557 @@
+# SDD Automation Scripts — Regra dos 80%
+
+> Referência completa dos 12 comandos determinísticos do AIOSON que movem trabalho de arquivo/estado/validação para fora do contexto LLM.
+
+## Por que esses scripts existem
+
+Antes desses scripts, verificações como "o gate A está aprovado?" ou "qual o classificação desse projeto?" eram resolvidas dentro da janela de contexto do agente — custando entre 7.200 e 18.500 tokens por feature. Os scripts SDD cobrem exatamente esses 80% de trabalho determinístico, deixando o agente focar nos 20% que exigem raciocínio.
+
+---
+
+## preflight
+
+```
+aioson preflight [path] [--agent=<agent>] [--feature=<slug>] [--json]
+```
+
+Coleta todos os dados de pré-voo em uma chamada só: modo do projeto, classificação, framework detectado, test runner, artefatos disponíveis, estado dos phase gates, dev-state, contexto compacto e prontidão para o agente pedido.
+
+**Flags:**
+
+| Flag | Descrição |
+|---|---|
+| `--agent=<name>` | Filtra prontidão para o agente específico (dev, qa, analyst…) |
+| `--feature=<slug>` | Slug da feature para procurar artefatos e gates |
+| `--json` | Saída estruturada JSON |
+
+**Saída JSON (campos principais):**
+
+```json
+{
+  "ok": true,
+  "mode": "feature",
+  "classification": "SMALL",
+  "framework": "Laravel",
+  "test_runner": "phpunit",
+  "artifacts": { "prd": true, "spec": true, "implementation_plan": false },
+  "phase_gates": { "A": "approved", "B": "approved", "C": null, "D": null },
+  "readiness": { "status": "READY", "blockers": [] },
+  "rules": ["process-atomic-commits.md"]
+}
+```
+
+**Quando usar:** no início de qualquer sessão de agente para eliminar a necessidade de ler vários arquivos manualmente.
+
+---
+
+## classify
+
+```
+aioson classify [path] [--feature=<slug>] [--interactive] [--json]
+```
+
+Detecta a classificação da feature (MICRO / SMALL / MEDIUM) automaticamente a partir do PRD e dos requirements, ou interativamente via prompts.
+
+**Algoritmo de pontuação:**
+
+| Dimensão | 0 pts | 1 pt | 2 pts |
+|---|---|---|---|
+| Tipos de usuário | 1 | 2 | 3+ |
+| Integrações externas | nenhuma | 1 | 2+ |
+| Regras de negócio | simples | moderadas | complexas |
+
+- **0–1:** MICRO — só `@dev`, sem fases
+- **2–3:** SMALL — `@product → @analyst → @dev → @qa`
+- **4–6:** MEDIUM — adiciona `@architect`, paralelismo, conformance
+
+**Flags:**
+
+| Flag | Descrição |
+|---|---|
+| `--feature=<slug>` | Lê `prd-<slug>.md` e `requirements-<slug>.md` automaticamente |
+| `--interactive` | Prompts no terminal para entrada manual |
+| `--json` | Saída estruturada |
+
+---
+
+## sizing
+
+```
+aioson sizing [path] [--feature=<slug>] [--prd=<path>] [--json]
+```
+
+Lê o PRD e determina o modelo de sizing: `inplace`, `phased_inplace` ou `phased_external`.
+
+**Critérios:**
+
+| Decisão | Quando |
+|---|---|
+| `inplace` | ≤ 3 entidades, ≤ 2 fases, sem integração externa |
+| `phased_inplace` | 4–7 entidades, 3–5 fases, 1 integração |
+| `phased_external` | 8+ entidades ou 6+ fases ou 2+ integrações |
+
+**Saída:**
+
+```json
+{
+  "ok": true,
+  "sizing": "phased_inplace",
+  "entities": 5,
+  "phases": 4,
+  "integrations": 1,
+  "score": 10
+}
+```
+
+---
+
+## detect:test-runner
+
+```
+aioson detect:test-runner [path] [--json]
+```
+
+Detecta o test runner do projeto verificando arquivos de configuração e `package.json`.
+
+**Frameworks detectados:**
+
+| Framework | Arquivo de configuração |
+|---|---|
+| PHPUnit | `phpunit.xml`, `phpunit.xml.dist` |
+| Pest | `phpunit.xml` com `pestphp` |
+| Jest | `jest.config.js`, `jest.config.ts`, `jest.config.mjs` |
+| Vitest | `vitest.config.js`, `vitest.config.ts` |
+| Pytest | `pytest.ini`, `pyproject.toml`, `setup.cfg` |
+| RSpec | `.rspec`, `spec/spec_helper.rb` |
+| Forge | `phpunit.xml` com `orchestra/testbench` |
+| node:test | `package.json` com script `test` usando `node --test` |
+
+**Saída:**
+
+```json
+{
+  "ok": true,
+  "name": "jest",
+  "command": "npx jest",
+  "configFile": "jest.config.ts"
+}
+```
+
+---
+
+## pulse:update
+
+```
+aioson pulse:update [path] --agent=<agent> [--feature=<slug>] [--gate=<text>] [--action=<text>] [--next=<text>] [--json]
+```
+
+Cria ou atualiza `.aioson/context/project-pulse.md` com o estado atual da sessão.
+
+**O que atualiza:**
+- `active_agent`, `active_feature`, `active_work`
+- `last_gate` e `last_agent`
+- Seção `## Recent Activity` (mantém as últimas 3 entradas)
+
+**Flags:**
+
+| Flag | Descrição |
+|---|---|
+| `--agent=<name>` | Agente ativo (obrigatório) |
+| `--feature=<slug>` | Feature em andamento |
+| `--gate=<text>` | Último gate avançado |
+| `--action=<text>` | O que está sendo feito agora |
+| `--next=<text>` | Próximo passo previsto |
+
+**Exemplo:**
+
+```bash
+aioson pulse:update . \
+  --agent=dev \
+  --feature=checkout \
+  --gate="Gate C: approved" \
+  --action="Implementing Phase 2: AddToCart" \
+  --next="Phase 3: Payment webhook"
+```
+
+---
+
+## state:save
+
+```
+aioson state:save [path] --feature=<slug> [--phase=<n>] [--next=<text>] [--spec-version=<n>] [--status=<status>] [--json]
+```
+
+Cria ou atualiza `.aioson/context/dev-state.md` com o ponto de continuação atual.
+
+**Status válidos:** `in_progress`, `blocked`, `complete`, `paused`
+
+**O que grava:**
+- Frontmatter: `feature`, `phase`, `status`, `spec_version`, `updated_at`
+- Seção `## History` com entrada timestampada para auditoria
+
+**Exemplo:**
+
+```bash
+aioson state:save . \
+  --feature=checkout \
+  --phase=3 \
+  --next="Implement webhook idempotency" \
+  --spec-version=4 \
+  --status=in_progress
+```
+
+---
+
+## feature:close
+
+```
+aioson feature:close [path] --feature=<slug> --verdict=<PASS|FAIL> [--residual=<text>] [--notes=<text>] [--json]
+```
+
+Fecha uma feature após QA sign-off. Atualiza três arquivos:
+
+1. **`spec-<slug>.md`** — adiciona bloco `## QA Sign-off` e atualiza `gate_execution` no frontmatter
+2. **`features.md`** — muda status para `done` ou `qa_failed`
+3. **`project-pulse.md`** — zera `active_feature`, atualiza `last_gate`
+
+**Exemplo (PASS):**
+
+```bash
+aioson feature:close . --feature=checkout --verdict=PASS
+# Com residual (item não testado mas aceito):
+aioson feature:close . \
+  --feature=checkout \
+  --verdict=PASS \
+  --residual="Email delivery not tested E2E"
+```
+
+**Exemplo (FAIL):**
+
+```bash
+aioson feature:close . \
+  --feature=checkout \
+  --verdict=FAIL \
+  --notes="Auth edge case missing — re-open after fix"
+```
+
+**Saída JSON:**
+
+```json
+{
+  "ok": true,
+  "feature": "checkout",
+  "verdict": "PASS",
+  "date": "2026-04-04",
+  "residual": null,
+  "updates": [
+    "spec-checkout.md: added QA sign-off (2026-04-04, PASS)",
+    "features.md: checkout → done (2026-04-04)",
+    "project-pulse.md: updated active work"
+  ]
+}
+```
+
+---
+
+## gate:check
+
+```
+aioson gate:check [path] --feature=<slug> --gate=<gate> [--json]
+```
+
+Verifica se um phase gate pode ser aprovado. Retorna `PASS` ou `BLOCKED` com lista de evidências.
+
+**Gates aceitos:** `A` / `requirements`, `B` / `design`, `C` / `plan`, `D` / `execution`
+
+**Pré-requisitos por gate:**
+
+| Gate | Requer | Artefato obrigatório |
+|---|---|---|
+| A | — | `requirements-<slug>.md` ou `prd-<slug>.md` |
+| B | Gate A | `spec-<slug>.md` |
+| C | Gates A + B | `implementation-plan-<slug>.md` |
+| D | Gates A + B + C | QA sign-off em `spec-<slug>.md` |
+
+**Exemplo:**
+
+```bash
+aioson gate:check . --feature=checkout --gate=C --json
+```
+
+```json
+{
+  "ok": true,
+  "gate": "C",
+  "gate_name": "plan",
+  "verdict": "PASS",
+  "evidence": [
+    "Gate A: approved",
+    "Gate B: approved",
+    "implementation-plan-checkout.md: found"
+  ]
+}
+```
+
+**Quando BLOCKED:**
+
+```json
+{
+  "ok": false,
+  "gate": "C",
+  "verdict": "BLOCKED",
+  "blockers": ["Gate B not approved — spec-checkout.md missing or gate_design not set"],
+  "evidence": ["Gate A: approved"]
+}
+```
+
+---
+
+## artifact:validate
+
+```
+aioson artifact:validate [path] --feature=<slug> [--json]
+```
+
+Valida a cadeia completa de artefatos de uma feature. Verifica a existência de cada arquivo esperado e reporta o que está presente, ausente ou opcional.
+
+**Cadeia verificada:**
+
+```
+project.context.md
+  → prd-<slug>.md
+    → sheldon-<slug>.md (opcional para MICRO)
+      → requirements-<slug>.md
+        → spec-<slug>.md
+          → architecture.md
+            → implementation-plan-<slug>.md
+              → conformance-<slug>.yaml (somente MEDIUM)
+```
+
+**Saída:**
+
+```json
+{
+  "ok": true,
+  "feature": "checkout",
+  "classification": "SMALL",
+  "present": ["project.context.md", "prd-checkout.md", "spec-checkout.md"],
+  "missing": ["implementation-plan-checkout.md"],
+  "optional_missing": ["sheldon-checkout.md"],
+  "chain_complete": false,
+  "next_missing": "implementation-plan-checkout.md"
+}
+```
+
+---
+
+## workflow:execute
+
+```
+aioson workflow:execute [path] --feature=<slug> [--tool=<tool>] [--classification=<tier>] [--dry-run] [--start-from=<agent>] [--json]
+```
+
+Monta e executa o plano de agentes para uma feature com base na classificação.
+
+**Planos por tier:**
+
+| Tier | Passos |
+|---|---|
+| MICRO | `@dev` |
+| SMALL | `@product → @analyst → @dev → @qa` |
+| MEDIUM | `@product → @analyst → @architect → gate:check C → @dev (por fase) → @qa` |
+
+**Flags:**
+
+| Flag | Descrição |
+|---|---|
+| `--tool=<tool>` | Ferramenta a usar (`claude`, `codex`, `gemini`) |
+| `--classification=<tier>` | Override manual da classificação |
+| `--dry-run` | Mostra o plano sem executar |
+| `--start-from=<agent>` | Pula agentes anteriores ao agente dado |
+
+**Exemplo dry-run:**
+
+```bash
+aioson workflow:execute . \
+  --feature=checkout \
+  --classification=SMALL \
+  --dry-run \
+  --json
+```
+
+```json
+{
+  "ok": true,
+  "dry_run": true,
+  "feature": "checkout",
+  "classification": "SMALL",
+  "steps": [
+    { "agent": "product", "skip": false, "reason": "prd not found" },
+    { "agent": "analyst", "skip": false },
+    { "agent": "dev", "skip": false },
+    { "agent": "qa", "skip": false }
+  ]
+}
+```
+
+**Exemplo com retomada:**
+
+```bash
+# Feature travada em dev — pular product e analyst
+aioson workflow:execute . \
+  --feature=checkout \
+  --tool=claude \
+  --start-from=dev
+```
+
+---
+
+## runner:queue:from-plan
+
+```
+aioson runner:queue:from-plan [path] --feature=<slug> [--plan=<path>] [--agent=<agent>] [--dry-run] [--json]
+```
+
+Extrai as fases de um plano de implementação e as enfileira no runner do AIOSON com prioridades correspondentes ao número da fase.
+
+**Formato reconhecido:**
+
+O arquivo deve conter headers `## Phase N: Título da fase` (onde N é um inteiro). Qualquer nível de heading funciona.
+
+**Requer:** banco de runtime inicializado (`aioson runtime:init .` ou uso prévio do runner).
+
+**Flags:**
+
+| Flag | Descrição |
+|---|---|
+| `--feature=<slug>` | Lê `.aioson/context/implementation-plan-<slug>.md` |
+| `--plan=<path>` | Caminho arbitrário para o arquivo de plano |
+| `--agent=<name>` | Agente padrão para as tarefas enfileiradas |
+| `--dry-run` | Lista as fases sem enfileirar |
+
+**Exemplo:**
+
+```bash
+# Dry-run para ver as fases antes de enfileirar
+aioson runner:queue:from-plan . --feature=checkout --dry-run
+
+# Enfileirar todas as fases para o agente dev
+aioson runner:queue:from-plan . --feature=checkout --agent=dev
+```
+
+**Saída (modo enfileirado):**
+
+```json
+{
+  "ok": true,
+  "feature": "checkout",
+  "queued": [
+    { "phase": 1, "title": "Create database migrations", "priority": 1 },
+    { "phase": 2, "title": "Implement AddToCart action", "priority": 2 },
+    { "phase": 3, "title": "Payment webhook handler", "priority": 3 }
+  ]
+}
+```
+
+---
+
+## learning:auto-promote
+
+```
+aioson learning:auto-promote [path] [--threshold=<n>] [--dry-run] [--json]
+```
+
+Lê `project_learnings` do SQLite de runtime e promove automaticamente aprendizados de processo e qualidade de alta frequência para arquivos de regra em `.aioson/rules/`.
+
+**Tipos promovidos:** `process`, `quality`
+**Tipos não promovidos:** `domain` (anotados em `noted_items`, não viram regras)
+
+**Threshold padrão:** 3 ocorrências
+
+**Arquivo gerado:** `.aioson/rules/<type>-<slug>.md`
+
+**Exemplo:**
+
+```bash
+# Ver o que seria promovido sem escrever nada
+aioson learning:auto-promote . --threshold=3 --dry-run
+
+# Promover com threshold mais alto
+aioson learning:auto-promote . --threshold=5
+```
+
+**Saída:**
+
+```json
+{
+  "ok": true,
+  "dry_run": false,
+  "threshold": 3,
+  "eligible": 2,
+  "promoted": 2,
+  "skipped": 0,
+  "noted": 1,
+  "promoted_items": [
+    { "title": "Commit after each atomic step", "type": "process", "file": ".aioson/rules/process-commit-after-each-atomic-step.md" },
+    { "title": "Run tests before commit", "type": "process", "file": ".aioson/rules/process-run-tests-before-commit.md" }
+  ],
+  "noted_items": [
+    { "title": "Cart uniqueness constraint", "type": "domain" }
+  ]
+}
+```
+
+---
+
+## Fluxo completo de uma feature SMALL
+
+```bash
+# 1. Pré-voo: ver o estado antes de começar
+aioson preflight . --agent=dev --feature=checkout
+
+# 2. Classificar automaticamente
+aioson classify . --feature=checkout
+
+# 3. Verificar cadeia de artefatos
+aioson artifact:validate . --feature=checkout
+
+# 4. Checar gate C antes de começar dev
+aioson gate:check . --feature=checkout --gate=C
+
+# 5. Executar workflow (ou dry-run primeiro)
+aioson workflow:execute . --feature=checkout --tool=claude --dry-run
+aioson workflow:execute . --feature=checkout --tool=claude
+
+# 6. Durante dev: salvar estado ao final de cada fase
+aioson state:save . --feature=checkout --phase=2 --status=in_progress \
+  --next="Phase 3: webhook" --spec-version=3
+aioson pulse:update . --agent=dev --feature=checkout \
+  --action="Phase 2 done" --next="Phase 3"
+
+# 7. QA sign-off
+aioson feature:close . --feature=checkout --verdict=PASS
+
+# 8. Promover aprendizados para regras
+aioson learning:auto-promote . --threshold=3
+```
+
+---
+
+## Integração com a Regra dos 80%
+
+Esses scripts foram criados conforme o **Plan 79 — SDD Automation Scripts**. A ideia central é:
+
+- **80% do trabalho** de verificação, estado e validação é determinístico — scripts fazem melhor que LLMs
+- **20% restantes** exigem raciocínio — reserve o contexto do agente para isso
+
+**Economia estimada por feature:**
+
+| Comando | Tokens economizados |
+|---|---|
+| `preflight` | 1.800–3.200 tokens (leitura de vários arquivos) |
+| `classify` | 800–1.500 tokens (análise de scoring) |
+| `gate:check` | 600–1.200 tokens (verificação de pré-requisitos) |
+| `artifact:validate` | 500–900 tokens (varredura de cadeia) |
+| `state:save` + `pulse:update` | 300–600 tokens (escrita de estado) |
+| `feature:close` | 800–1.400 tokens (atualização de três arquivos) |
+| **Total** | **4.800–8.800 por feature** |