stealthos-cli 0.1.0-alpha.2 → 0.1.0-alpha.4

package/ai/specs/BRD/_TEMPLATE.md

@@ -0,0 +1,50 @@
+---
+id: BRD-NNNN
+slug: <slug-kebab>
+status: draft  # draft | review | approved | deprecated
+owner: product-manager
+created: AAAA-MM-DD
+stakeholders: [...]
+related:
+  - PRD-NNNN
+---
+
+# BRD-NNNN — <Iniciativa de negócio>
+
+> BRD é o **porquê de negócio** atrás do PRD. Use quando há stakeholders externos, ROI a justificar, ou decisão estratégica.
+
+## 1. Objetivo de negócio
+1 parágrafo: qual o resultado de negócio desejado?
+
+## 2. Contexto
+Por que isso é importante AGORA? (oportunidade de mercado, pressão regulatória, retenção, competição)
+
+## 3. Stakeholders
+| Papel | Nome | Interesse |
+|---|---|---|
+| Patrocinador | ... | ROI |
+| Usuário-chave | ... | Eficiência |
+| Operação | ... | Custo |
+
+## 4. Métricas de negócio
+- **Receita / custo evitado esperado**: $X em Y meses
+- **Adoção esperada**: N usuários, % conversão
+- **Indicadores qualitativos**: NPS, CSAT
+
+## 5. Investimento estimado
+- Engenharia: <semanas-pessoa>
+- Infra: <$/mês>
+- Outros: <$>
+
+## 6. ROI / Payback
+- Payback estimado: <meses>
+- Cenários: pessimista / realista / otimista
+
+## 7. Restrições de negócio
+- Prazo: <data> (motivo: <evento>)
+- Compliance: LGPD / GDPR / PCI / HIPAA / outro
+- Orçamento: <teto>
+
+## 8. Aprovação
+- [ ] Patrocinador aprovou
+- [ ] Pronto para gerar PRD (`product-manager` continua)

package/ai/specs/PRD/_TEMPLATE.md

@@ -0,0 +1,72 @@
+---
+id: PRD-NNNN
+slug: <slug-kebab>
+status: draft  # draft | review | approved | deprecated | superseded-by-NNNN
+owner: product-manager
+created: AAAA-MM-DD
+updated: AAAA-MM-DD
+supersedes: null
+related:
+  - BRD-NNNN
+  - SDD-NNNN (a ser criado por architect)
+---
+
+# PRD-NNNN — <Título conciso da feature>
+
+## 1. Problema
+O que NÃO funciona hoje? Quem sofre? Qual o tamanho do problema (qualitativo + quantitativo se possível)?
+
+## 2. Objetivo
+1 frase: "Permitir que <persona> faça <ação> para alcançar <benefício>."
+
+## 3. KPIs / Métricas de sucesso
+- **North-star**: <métrica principal — ex.: "% de uploads que disparam alerta em <60s">
+- **Leading indicators**: <métricas que prevêem o north-star>
+- **Guard-rails**: <métricas que NÃO podem piorar — performance, custo, satisfação>
+
+## 4. Usuários / Personas
+Referência a `product/personas.md`. Quais personas usam essa feature? Em qual jornada (`product/user-journeys.md`)?
+
+## 5. Casos de uso
+1. **<Caso primário>** — Como <persona>, quero <ação> para <objetivo>.
+2. **<Caso secundário>** — ...
+3. **<Caso de exceção>** — ...
+
+## 6. Requisitos funcionais
+- RF-01: O sistema DEVE <comportamento>.
+- RF-02: O sistema DEVE <comportamento>.
+- RF-03: ...
+
+## 7. Requisitos não-funcionais
+- RNF-01: **Performance** — p95 < 200ms para <operação>.
+- RNF-02: **Disponibilidade** — 99.5% uptime.
+- RNF-03: **Segurança** — autenticação obrigatória, dados sensíveis criptografados.
+- RNF-04: **Acessibilidade** — WCAG 2.1 AA mínimo.
+- RNF-05: **Custo** — ≤ $X/mês adicionais em infra.
+
+## 8. Critérios de aceitação
+Testáveis. Cada RF tem 1+ critério.
+- **AC-01**: Dado <contexto>, quando <ação>, então <resultado verificável>.
+- **AC-02**: ...
+
+## 9. Fora de escopo
+O que **explicitamente** NÃO está nesta entrega? Evita scope-creep.
+
+## 10. Dependências / Riscos
+- Dep: <feature/sistema X precisa estar pronto>
+- Risco: <O que pode dar errado> — Mitigação: <ação>
+
+## 11. Rollout
+- **Estratégia**: feature flag | canário | gradual | big-bang
+- **Métricas de rollout**: <quais sinais indicam "ok prosseguir" vs "rollback">
+
+## 12. Aprovação
+- [ ] Founder aprovou (G2)
+- [ ] Pronto para entregar ao `architect` (G3)
+
+---
+
+## Histórico de mudanças
+| Versão | Data | Autor | Mudança |
+|---|---|---|---|
+| 0.1 | AAAA-MM-DD | product-manager | Draft inicial |

package/ai/specs/README.md

@@ -0,0 +1,43 @@
+---
+version: 1.0.0
+updated: 2026-05-15
+tier: on_demand
+audience: humano + agente
+---
+
+# Specs — Documentos canônicos
+
+> Templates padronizados que materializam o pipeline IDEIA → DEPLOY. Cada doc tem **owner** (agente responsável) e **gate** que produz.
+
+| Pasta | Doc | Owner | Gate |
+|---|---|---|---|
+| `PRD/` | Product Requirements Document | `product-manager` | G2 |
+| `BRD/` | Business Requirements Document | `product-manager` | G1 (auxiliar) |
+| `SDD/` | Software Design Document | `architect` | G3 |
+| `ADR/` | Architecture Decision Record | `architect` | G3 (parte do SDD) |
+| `RFC/` | Request for Comments | `tech-lead` | G4 (mudança em decisão) |
+| `RUNBOOKS/` | Operational runbooks | `sre-engineer` | G9 |
+| `TASKS/` | Decomposição de tasks | `tech-lead` | G4 |
+
+## Nomenclatura
+
+- `PRD-NNNN-<slug-kebab>.md` (PRD-0001-events-heatmap)
+- `SDD-NNNN-<slug>.md`
+- `ADR-NNNN-<slug>.md` (espelha em `memory/decisions.md`)
+- `RFC-NNNN-<slug>.md`
+- `RUNBOOK-NNNN-<slug>.md`
+- `TASK-NNNN-<slug>.md` (ou consolida em `execution/backlog.md`)
+
+Numeração contínua (não reusar). Status no front-matter (`draft | review | approved | deprecated | superseded-by-NNNN`).
+
+## Templates
+
+Cada pasta contém `_TEMPLATE.md` (prefixo `_` para ordem alfabética + indicar uso). Copiar e renomear.
+
+## Ciclo de vida
+
+```
+draft → review (gate aplicável) → approved → (deprecated | superseded-by)
+```
+
+Doc aprovado é **imutável** exceto correção tipográfica. Mudança real = novo doc com `supersedes: <antigo>`.

package/ai/specs/RFC/RFC-0001-runtime-orchestrator.md

@@ -0,0 +1,149 @@
+---
+id: RFC-0001
+slug: runtime-orchestrator
+status: accepted
+opened: 2026-05-16
+author: tech-lead
+related:
+  - ADR-0002 (typescript-runtime — base sobre a qual orquestramos)
+  - ADR-0004 (a ser criado — decisão consolidada)
+---
+
+# RFC-0001 — Runtime Orchestrator: workflows determinísticos sobre as 17 tools MCP
+
+## Mudança proposta
+
+Substituir o modelo atual de **"17 tools MCP soltas + 8 slash commands granulares"** por um **Runtime Orchestrator** com 3 camadas:
+
+1. **Commands consolidados** — apenas `/init`, `/sync`, `/work`. Os 8 antigos são aposentados.
+2. **Workflow Engine** — workflows declarativos em JSON (`.ai/workflows/<name>.json`) que orquestram chamadas determinísticas às 17 tools primitivas existentes.
+3. **Runtime State** — `.ai/runtime/state.json` persistindo `project_phase`, `last_sync`, `current_focus`, `active_artifacts`.
+
+A LLM continua escolhendo *quando* invocar `/init`/`/sync`/`/work`, mas a *sequência interna* de tools é determinística (definida pelo workflow JSON, não improvisada pela LLM).
+
+## Motivação
+
+Sinal observado em sessão 2026-05-16 (Antigravity Workbench):
+- 17 tools `aios_*` aparecem como flat list, sem indicação de sequência ou dependência.
+- LLM sem orquestração tende a: (a) usar tools fora de ordem, (b) esquecer steps obrigatórios (snapshot após mudança de estado, memory update após decisão), (c) repetir chamadas, (d) escolher tool errada.
+- 8 slash commands granulares (`/analyze`, `/context`, `/snapshot`, `/audit`, `/load-os`, `/os-status`, `/compact-memory`, `/promote-learning`) sobrecarregam superfície de uso e ainda não compõem fluxos.
+
+Sintoma esperado se não mudar:
+- Cada nova capacidade adicionada vira nova tool → superfície cresce linearmente, complexidade cognitiva cresce mais que linear.
+- Workflows críticos (init de projeto, sync após desenvolvimento, execução de tarefa) viram conhecimento implícito da LLM → não auditável, não rastreável, não testável.
+
+## Estado atual
+
+Sob ADR-0002 (Runtime v0.1):
+- 17 tools MCP expostas via `.ai/server/aios-server.mjs` (12 base + 5 Runtime v0.1).
+- 8 slash commands em `.claude/commands/*.md` (Claude Code only).
+- Comandos chamam tools individuais; sem composição automática.
+- Sem state persistente entre sessões além de `.ai/memory/*` (que é narrativa, não estado operacional).
+- Tier system existe (core/conditional/on-demand) mas não há tool que devolva tier sob demanda — LLM precisa ler manualmente.
+- Artefatos vivem espalhados (`.ai/specs/*`, `.ai/snapshots/*`, `.ai/context/packages/*`) sem índice unificado.
+
+## Alternativas
+
+### Alt 1 — Status quo (não mudar)
+- Custo: 0
+- Resultado: dívida arquitetural cresce; LLM cada vez mais erra ordem operacional; difícil onboardar nova IDE/CLI sem replicar 8 commands.
+- **Descartada**: sinal claro de degradação.
+
+### Alt 2 — Runtime Orchestrator (esta proposta)
+- Custo: 4 fases incrementais, ~40-50 arquivos tocados, 4 ADRs novos.
+- Resultado: 3 commands, workflows determinísticos, state persistente, context layers explícitas, artifact index.
+- **Escolhida**.
+
+### Alt 3 — Manter 8 commands + adicionar 3 novos como "orchestrators"
+- Custo: menor (sem deletar).
+- Resultado: superfície cresce de 8 para 11; ambiguidade sobre quando usar granular vs composto.
+- **Descartada pelo usuário**: opção explícita por "substituir tudo pelos 3 novos" (sessão 2026-05-16).
+
+## Plano de migração (4 fases)
+
+### Fase 1 — Workflow Engine MVP
+**Entrega**: `aios_run_workflow(name, input)` + 3 workflows JSON + 3 slash commands consolidados + remoção dos 8 antigos.
+
+**Arquivos novos**:
+- `.ai/workflows/init.json` — projeto novo / primeira sessão
+- `.ai/workflows/sync.json` — sincronização periódica de estado
+- `.ai/workflows/work.json` — execução de tarefa (MVP, expandido na Fase 4)
+- `.claude/commands/{init,sync,work}.md`
+
+**Arquivos modificados**:
+- `.ai/server/aios-server.mjs` — nova tool `aios_run_workflow` + handler + helper `resolveArgs`
+- `AGENTS.md`, `.ai/clients/{README,antigravity,claude-code}.md`, `.ai/runtime.md`, `.ai/README.md`, `.cursor/rules/ai-os.mdc` — atualizar tabelas: 3 comandos novos substituem 8 antigos
+- `.claude/settings.local.json` — permitir nova tool
+
+**Arquivos deletados**:
+- `.claude/commands/{analyze,audit,compact-memory,context,load-os,os-status,promote-learning,snapshot}.md` (8 arquivos)
+
+**ADR**: ADR-0005 (workflow-engine).
+
+### Fase 2 — Runtime State
+**Entrega**: `.ai/runtime/state.json` + tools `aios_state_get`, `aios_state_set`, `aios_state_advance` + workflows da Fase 1 passam a atualizar state.
+
+**Schema state.json**:
+```json
+{
+  "project_phase": "discovery|planning|development|maintenance",
+  "last_sync_at": "ISO-8601",
+  "last_snapshot_id": "string|null",
+  "current_focus": "string|null",
+  "active_artifacts": { "specs": [], "packages": [], "snapshots": [] },
+  "open_decisions": [],
+  "open_tasks": []
+}
+```
+
+**ADR**: ADR-0006 (runtime-state).
+
+### Fase 3 — Context Layers explícitas + Artifact Index
+**Entrega**:
+- Tool `aios_get_context(layer: "core"|"working"|"deep", focus?: string)` que devolve apenas o tier pedido.
+- `.ai/artifacts/index.json` consolidando metadata de specs/snapshots/packages/ADRs.
+- Tool `aios_artifact_list(type, status)` para consultar o índice.
+
+**ADR**: ADR-0007 (context-layers-and-artifact-index).
+
+### Fase 4 — Intent Runtime para `/work`
+**Entrega**: expandir `work.json` para implementar fluxo: Intent Classification → Gap Analysis → Clarification → Plan → Approval → Execution → Validation → Memory → Snapshot.
+
+Requer:
+- Workflow conditional branches (if/else por classification).
+- Step de "pause for user input" (interrupção controlada).
+- Tool `aios_intent_classify(query)` (heurística + opcional LLM-call no servidor — provavelmente sem LLM no MVP).
+
+**ADR**: ADR-0008 (intent-runtime).
+
+### Rollback
+- Cada fase isolada em commit/ADR próprio.
+- Para reverter Fase 1: restaurar 8 commands antigos do git history; remover `aios_run_workflow` e workflows JSON.
+- Cuidado: docs cross-IDE referenciam novos commands — rollback exige atualizar docs também.
+
+## Riscos
+
+| Risco | Mitigação |
+|---|---|
+| Workflow JSON vira config-language proprietária e implícita | Mantê-lo simples: só `steps[]` com `tool/args/on_error`. Não criar DSL. |
+| LLM ignora workflows e chama tools primitivas direto | Tools primitivas continuam expostas (não remover); docs orientam preferência por workflows |
+| YAML vs JSON debate | JSON: zero-deps no Node; pode ler/escrever com `JSON.parse/stringify`. YAML exigiria nova dep. |
+| Aposentar 8 commands quebra muscle memory | Documentar mapeamento "antigo → novo" em `.ai/clients/README.md`; deixar nota em commit |
+| Substituição de variável `${...}` vira mini-template engine | Manter restrito a `${input.X}`, `${timestamp}`, `${state.X}` (Fase 2+). Sem condicionais nem loops. |
+| Pause-for-input na Fase 4 exige MCP protocol extension | Fase 4 desenhada para usar AskUserQuestion (Claude) / Function Calling pause (Gemini) externamente, workflow apenas declara pontos de pausa |
+
+## Métricas de sucesso
+
+- Métrica 1: **Superfície de slash commands** — 8 → 3 (-62%)
+- Métrica 2: **Reprodutibilidade de fluxo `sync`** — execuções independentes geram mesmo conjunto de artefatos (verificar via `aios_snapshot_diff` entre snapshots de syncs consecutivos)
+- Métrica 3: **Token economy** — workflows devolvem relatório resumido em vez de dumps individuais (target: -40% tokens por sync típico)
+- Métrica 4: **Onboardabilidade** — novo cliente IDE precisa documentar 3 commands em vez de 8
+
+## Decisão
+
+- [x] **Aceito** → criar ADR-0004 (decisão consolidada) + ADRs por fase (0005, 0006, 0007, 0008).
+- Aprovado por: usuário (sessão 2026-05-16, AskUserQuestion "escopo: 4 fases" + "ação com commands antigos: substituir tudo pelos 3 novos").
+
+## Comentários
+
+- [2026-05-16] tech-lead: Inspiração de análise externa apresentada pelo usuário (aprofundamento sobre AI Engineering Runtime vs MCP puro). Filtrada para alinhar com estado real do projeto (Project Graph, Decision Engine, Context Layers já existem parcialmente sob outros nomes).

package/ai/specs/RFC/RFC-0002-runtime-orchestrator-extended.md

@@ -0,0 +1,134 @@
+---
+id: RFC-0002
+slug: runtime-orchestrator-extended
+status: accepted
+opened: 2026-05-16
+author: tech-lead
+related:
+  - RFC-0001 (proposta original — esta RFC ESTENDE, não substitui)
+  - ADR-0004 (decisão consolidada)
+  - ADR-0005 (Fase 1 — Workflow Engine MVP)
+---
+
+# RFC-0002 — Runtime Orchestrator Extended: State Compiler, Lifecycle, Drift Detection, Contracts, Confidence
+
+## Mudança proposta
+
+Estender o Runtime Orchestrator definido em RFC-0001 com **5 conceitos operacionais** que transformam o sistema de "orquestrador de tools" em **runtime operacional persistente com ciclo contínuo de engenharia**:
+
+1. **Project State Compiler** — `/sync` produz `.ai/runtime/runtime-context.json` único, compilado semanticamente. `/work` consome esse artefato em vez de relê tudo.
+2. **Runtime Lifecycle** — campo `phase` no state.json (`discovery|planning|implementation|stabilization|production`) + `mode` (`readonly|analysis|execution|validation`). Comportamento do `/work` adapta-se à fase.
+3. **Documentation Drift Detection** — tool `aios_detect_drift` compara código atual vs specs/snapshots; reporta divergências; `/sync` mostra como warning.
+4. **Execution Contracts** — workflows declaram `guarantees: []` (snapshot_created, memory_updated, ...); engine valida cumprimento ao final.
+5. **Context TTL + Confidence System** — separar memory em `persistent` (architecture, decisions) vs `rotating` (recent_errors, active_focus) com TTL; cada categoria registra `confidence: low|medium|high` para guiar perguntas/assumptions da LLM.
+
+## Motivação
+
+Sessão 2026-05-16 (após Fase 1 entregue): análise externa apresentada pelo usuário aponta que o sistema agora tem **continuidade operacional** (o ciclo /init → /sync → /work → /sync → /work), mas ainda carece de:
+
+- **Single compiled state** que `/work` consuma → hoje cada `/work` precisa reler CORE + memory + context. Custo de tokens cresce linearmente com sessão.
+- **Drift awareness** → código pode mudar sem que specs/decisions reflitam; LLM acaba citando documentação obsoleta.
+- **Lifecycle awareness** → `/work` em fase "discovery" deveria fazer mais perguntas; em "stabilization" deveria priorizar testes/validação. Hoje é homogêneo.
+- **Auditabilidade de contratos** → workflow declara o que faz nos `steps[]`, mas não declara o que **garante** ao chamador. Difícil verificar pós-execução.
+- **Confidence registration** → LLM assume com mesma confiança fatos sólidos (architecture) e inferências fracas (telemetry_rules). Custo: erros de "alta convicção".
+
+## Estado atual (após Fase 1)
+
+- **Entregue** (ADR-0005): Workflow Engine MVP + 3 workflows + 3 commands consolidados; 19 tools MCP (17 primitivas + 2 do orchestrator).
+- **Pendente do RFC-0001**: Fases 2 (Runtime State), 3 (Context Layers + Artifact Index), 4 (Intent Runtime para `/work`).
+
+Esta RFC **redistribui e expande** Fases 2-4 e adiciona Fase 5.
+
+## Alternativas
+
+### Alt 1 — Não estender; entregar Fases 2-4 originais minimalistas
+- Custo: 0 (plano original).
+- Resultado: sistema funcional mas perde os 5 conceitos novos que mitigam problemas reais identificados pela análise externa.
+- **Descartada**: usuário aprovou adoção completa.
+
+### Alt 2 — Esta proposta (estender + Fase 5 nova)
+- Custo: 4 fases (2-5), ~30 arquivos novos/modificados, 4 ADRs (0006-0009).
+- Resultado: runtime operacional completo com state compilado, lifecycle awareness, drift detection, execution contracts, confidence system.
+- **Escolhida**.
+
+### Alt 3 — Substituir RFC-0001 inline
+- Pros: 1 RFC vivo.
+- Cons: perde rastreabilidade da evolução.
+- **Descartada**: usuário preferiu manter RFC-0001 + criar RFC-0002.
+
+## Plano de migração (Fases 2-5 redistribuídas)
+
+### Fase 2 — Runtime State + Lifecycle + Context TTL + Execution Contracts + Safety Rule
+**ADR-0006**.
+
+Entregáveis:
+- `.ai/runtime/state.schema.json` + `.ai/runtime/state.json` (inicializado vazio).
+- Schema: `{ identity, lifecycle: { phase, mode }, persistent: {...}, rotating: { ttl_days, entries: [...] }, active_workflow_history: [...] }`.
+- Tools: `aios_state_get(path?)`, `aios_state_set(path, value)`, `aios_state_advance(phase|mode)`, `aios_state_reset()`.
+- Workflow schema estendido: campos opcionais `guarantees: [...]` (lista de strings auditáveis: "snapshot_created", "memory_updated", "context_recompiled", "lint_clean") + `safety: { project_files_readonly: boolean }`.
+- `runWorkflow` valida guarantees após execução; reporta `unmet_guarantees: [...]` no relatório.
+- Workflows `init`/`sync`/`work` atualizados para escrever no `state.json` (último step) e declarar guarantees.
+- Token namespace expandido: `${state.X}` agora resolve.
+
+### Fase 3 — Project State Compiler + Drift Detection + Context Layers + Artifact Index
+**ADR-0007**.
+
+Entregáveis:
+- Tool `aios_compile_runtime_context()` — produz `.ai/runtime/runtime-context.json` consolidando: identity (do state) + active_modules (do project-state) + engineering_memory (decisions + errors-and-solutions, comprimidos) + active_work_state (do state.rotating) + runtime_rules (de rules/* e governance/*, índice apenas) + context_prioritization (top-N módulos por relevância).
+- **Tamanho-alvo**: ≤ 4000 tokens (compressão semântica, não dump).
+- Tool `aios_detect_drift({ since_snapshot? })` — compara AST atual (`project-state.json`) vs último snapshot e specs (`PRD/SDD/ADR/_TEMPLATE.md`); retorna `{ code_changes_without_spec_update: [...], specs_updated_no_code: [...], orphan_modules: [...] }`.
+- Tool `aios_get_context(layer: "core"|"working"|"deep", focus?)` — atalho para devolver só o tier pedido.
+- `.ai/artifacts/index.json` — índice consolidado de specs/snapshots/packages/ADRs com metadata (id, type, status, created_at, refs).
+- Tool `aios_artifact_list(type?, status?)`.
+- Workflow `sync` ganha steps `compile_runtime_context` + `detect_drift` no final.
+- Workflow `work` consome `runtime-context.json` no primeiro step (substitui `load_core` + parte de `route_query`).
+
+### Fase 4 — Intent Runtime para `/work` + Discovery Runtime ramificado em `/init`
+**ADR-0008**.
+
+Entregáveis:
+- Workflow `work` v2: pipeline completo Intent → Gap Analysis → Clarification (pause) → Plan → Approval (pause) → Execute → Validate → Memory Update → Snapshot. Pause-for-input declarado em campo `pause_for: { reason, prompt }`; engine retorna relatório com `status: "paused"` e cliente externo (AskUserQuestion/Function Calling) resolve.
+- Workflow `init` v2: ramificação automática `if state.identity.maturity == "empty" → discovery_branch; else → reverse_engineering_branch`.
+- Schema de workflow ganha `branches: { condition, steps: [...] }`.
+- Tool `aios_resume_workflow(execution_id, user_input)` para retomar workflow pausado.
+
+### Fase 5 — Confidence System + Maturity Tracking
+**ADR-0009**.
+
+Entregáveis:
+- Schema `state.confidence`: `{ architecture, modules, telemetry, decisions, ... }` com valores `low|medium|high`.
+- Tool `aios_confidence_get(category?)`, `aios_confidence_set(category, value, reason)`.
+- Workflows registram updates de confidence em pontos chave (`work` aumenta confiança em módulo após validação bem-sucedida; `sync` reduz se detectou drift).
+- `runtime-context.json` inclui top-3 categorias de baixa confiança como **flags** para LLM perguntar.
+
+### Rollback
+- Cada fase tem ADR próprio. Reverter Fase N implica remover tools, schema fields e workflow steps; outras fases permanecem.
+- Fase 5 é independente — pode ser desligada sem afetar 1-4.
+
+## Riscos
+
+| Risco | Mitigação |
+|---|---|
+| `runtime-context.json` vira dump (quebra o ponto do compiler) | Auditoria de tamanho: tool valida ≤ 4000 tokens; rejeita se exceder. Compressão prioriza decisions + critical modules. |
+| Drift Detection gera falsos positivos | Severity tiers (warning, no-op, info); só `info` por default; usuário pode subir |
+| Workflow pause-for-input vira deadlock | Timeout opcional (default 30 min); engine marca `execution_id` como expirado |
+| Confidence System vira micromanage | Adoção opt-in; `work` só consulta se categoria estiver `low` |
+| Schema do state.json vira "god object" | Validação strict via JSON Schema; mudanças exigem ADR |
+| Performance: `compile_runtime_context` em projetos grandes | Cache invalidado por hash do project-state.json; recomputa só se mudou |
+
+## Métricas de sucesso
+
+- Métrica 1: **Tokens lidos por `/work`** — baseline atual ~5k (CORE + memory grep + context package). Target pós-Fase 3: **≤ 2k** (só `runtime-context.json`).
+- Métrica 2: **Drift detectado vs corrigido** — `/sync` reporta drift; queremos ≥ 80% corrigido na próxima sessão.
+- Métrica 3: **Lifecycle adoption** — `state.lifecycle.phase` muda ao longo do projeto; mensurar diversidade de phases usadas em 1 mês.
+- Métrica 4: **Confidence atomicity** — # categorias com `low` confidence reduzido ao longo de sprints.
+- Métrica 5: **Guarantees fulfillment** — % de execuções com `unmet_guarantees: []`.
+
+## Decisão
+
+- [x] **Aceito** — usuário aprovou "Adotar TUDO incluindo Confidence System (Fase 5)" e "Tudo em sequência (2 → 3 → 4) até acabar" (sessão 2026-05-16).
+- Cada fase exige ADR próprio antes de execução (ADR-0006 a 0009).
+
+## Comentários
+
+- [2026-05-16] tech-lead: Conceitos vieram de análise externa apresentada pelo usuário. Filtrei: aceitei State Compiler/Drift/Lifecycle/Contracts/TTL/Confidence; descartei "criar pastas duplicadas" (`domain/`, `validations/`, etc. — conceitos já existem em outros nomes); mantive JSON em vez de YAML (zero-deps).

package/ai/specs/RFC/_TEMPLATE.md

@@ -0,0 +1,61 @@
+---
+id: RFC-NNNN
+slug: <slug-kebab>
+status: open  # open | accepted | rejected | withdrawn | superseded-by-NNNN
+opened: AAAA-MM-DD
+author: tech-lead
+related:
+  - ADR-NNNN (decisão que está sendo questionada/refinada)
+  - SDD-NNNN
+---
+
+# RFC-NNNN — <Mudança proposta em frase curta>
+
+> RFC é para **proposta de mudança em decisão prévia** ou **escolha técnica controversa**. Diferente do ADR (decisão tomada), o RFC é discussão aberta.
+
+## Mudança proposta
+1-2 parágrafos: o que muda, em relação ao estado atual.
+
+## Motivação
+Por quê agora? Que dado/sinal motivou essa proposta? (perf medida, custo, complexidade, bug recorrente)
+
+## Estado atual
+Como funciona hoje (cite ADR-NNNN se aplicável). Limitações observadas.
+
+## Alternativas
+
+### Alt 1 — Status quo (não mudar)
+- Custo: 0
+- Resultado: problema persiste
+
+### Alt 2 — <proposta principal>
+- Custo: <esforço/risco>
+- Resultado esperado: <medido como>
+
+### Alt 3 — <alternativa>
+- ...
+
+## Plano de migração (se Alt 2 aceita)
+1. Fase 1: ...
+2. Fase 2: ...
+3. Rollback: ...
+
+## Riscos
+| Risco | Mitigação |
+|---|---|
+| ... | ... |
+
+## Métricas de sucesso
+Como saberemos que a mudança foi positiva?
+- Métrica 1: <antes> → <depois esperado>
+- Métrica 2: ...
+
+## Comentários
+> Discussão aberta. Stakeholders comentam aqui antes de aceitar/rejeitar.
+
+- [date] [author]: ...
+
+## Decisão
+- [ ] Aceito → criar ADR-NNNN substituindo o anterior, marcar este RFC como `accepted`.
+- [ ] Rejeitado → marcar `rejected`, justificar.
+- [ ] Withdrawn → autor retirou.

package/ai/specs/RUNBOOKS/_TEMPLATE.md

@@ -0,0 +1,68 @@
+---
+id: RUNBOOK-NNNN
+slug: <slug-kebab>
+status: active  # active | deprecated | superseded-by-NNNN
+owner: sre-engineer
+created: AAAA-MM-DD
+updated: AAAA-MM-DD
+severity: P0 | P1 | P2 | P3
+related:
+  - SDD-NNNN
+  - alert: <nome do alerta no Grafana/Datadog>
+---
+
+# RUNBOOK-NNNN — <Cenário operacional>
+
+## Quando este runbook se aplica
+Quando o alerta `<nome>` dispara OU quando observar o sintoma <X>.
+
+## Severidade
+**P<N>** — impacto: <descrição>. SLA de resposta: <tempo>.
+
+## Diagnóstico (em ordem)
+
+### 1. Verificar health endpoints
+```bash
+curl -fsS https://<host>/health
+curl -fsS https://<host>/health/db
+```
+Esperado: 200 + JSON com `status: ok`. Se 5xx → siga §2. Se timeout → siga §3.
+
+### 2. Verificar logs recentes
+```bash
+# Loki / Sentry / equivalente
+kubectl logs -n <ns> -l app=<app> --tail=200
+```
+Procurar por: `[ERROR]`, `ECONNREFUSED`, `Timeout`, `OOM`.
+
+### 3. Verificar métricas
+- Dashboard: <link>
+- Métricas chave: error_rate, p99_latency, queue_depth, db_connections
+
+### 4. Verificar dependências
+| Dep | Comando |
+|---|---|
+| Postgres | `psql -h $DB_HOST -c "SELECT 1"` |
+| Redis | `redis-cli -h $REDIS_HOST ping` |
+| Getrak API | `curl -fsS https://api.getrak.com/status` |
+
+## Mitigação
+
+### Cenário A: <causa provável A>
+```bash
+# Comando exato de mitigação
+```
+Tempo estimado: <X min>. Reversível: sim/não.
+
+### Cenário B: <causa provável B>
+...
+
+## Escalação
+- Após <tempo> sem resolução → notificar <canal/pessoa>.
+- Se afetar >X usuários → status page + comunicação.
+
+## Pós-incidente
+- [ ] Postmortem aberto em `memory/errors-and-solutions.md`
+- [ ] Causa-raiz identificada
+- [ ] Ação preventiva listada (vira task em `pending-tasks.md`)
+- [ ] Runbook atualizado se faltou algo