stealthos-cli 0.1.0-alpha.3 → 0.1.0-alpha.5

package/ai/skills/security.md

@@ -0,0 +1,71 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~700
+load: security
+triggers: segurança, security, auth, senha, token, xss, csrf, sql injection, vulnerab, lgpd, gdpr
+---
+
+# Skill: Security
+
+## Princípios
+
+- **Defense in depth.** Múltiplas camadas; nunca confiar em uma só.
+- **Least privilege.** Token/role mínimo necessário, expirando o mais cedo possível.
+- **Validate at boundaries.** Input do usuário, retorno de APIs externas, leituras de DB.
+- **Secrets never in code.** Sempre via cofre (Vault, KMS, env injection em runtime).
+
+## OWASP Top 10 — Checklist
+
+- [ ] **Injection** (SQL, NoSQL, command, LDAP): parametrize sempre.
+- [ ] **Broken auth**: hashes fortes (argon2/bcrypt), MFA, rate limit em login.
+- [ ] **Sensitive data exposure**: HTTPS, criptografia em repouso, mascaramento em logs.
+- [ ] **XXE**: desabilitar entidades externas em parsers XML.
+- [ ] **Broken access control**: checagem por recurso, não só por role.
+- [ ] **Security misconfig**: defaults seguros, headers (CSP, HSTS, X-Frame-Options).
+- [ ] **XSS**: escape por contexto (HTML, JS, attr, URL).
+- [ ] **Deserialization**: nunca desserializar input não confiável sem validação.
+- [ ] **Vulnerable deps**: auditoria contínua (`npm audit`, Dependabot, Snyk).
+- [ ] **Logging & monitoring**: log de eventos de segurança, alerta em anomalias.
+
+## Autenticação
+
+- Senhas: argon2id ou bcrypt (cost >= 12).
+- Tokens: JWT só com expiração curta + refresh; ou session opaca server-side.
+- MFA via TOTP > SMS.
+- Reset de senha: token de uso único, expiração < 1h.
+
+## Autorização
+
+- RBAC > ACL ad-hoc.
+- Verificar permissão em CADA endpoint, não confiar em UI esconder botão.
+- Avoid IDOR: verificar ownership do recurso, não só ID.
+
+## Segredos
+
+- Nunca em código, nunca em commit, nunca em log.
+- Rotação automática quando possível.
+- Diferentes por ambiente (dev/staging/prod).
+- `.env` no `.gitignore`; `.env.example` versionado sem valores.
+
+## Headers HTTP
+
+```
+Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
+Content-Security-Policy: default-src 'self'; ...
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Referrer-Policy: strict-origin-when-cross-origin
+```
+
+## Logs e PII
+
+- Não logar: senhas, tokens, PII completa, cartões.
+- Mascarar ao logar (`user_***@domain`).
+- LGPD/GDPR: minimização, propósito, prazo, direito ao apagamento.
+
+## Registro
+
+Vulnerabilidade encontrada → `memory/decisions.md` com severidade + correção + data.
+Se virou padrão → `evolution/patterns-discovered.md`.

package/ai/skills/testing.md

@@ -0,0 +1,77 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~550
+load: testing
+triggers: teste, test, tdd, unit, e2e, integration, mock, cobertura
+---
+
+# Skill: Testing
+
+## Princípios
+
+- **Teste comportamento, não implementação.** Refatorar não deve quebrar testes.
+- **Pirâmide.** Muito unit, médio integração, pouco E2E.
+- **Determinístico.** Sem flaky. Se flaky, corrigir ou remover — nunca retry cego.
+- **Rápido.** Suite unit < 30s. Se demorar, isolar lentos.
+
+## Tipos
+
+| Tipo | Cobre | Custo | Velocidade |
+|---|---|---|---|
+| Unit | função/módulo puro | baixo | ms |
+| Integration | múltiplos módulos + I/O real | médio | s |
+| E2E | usuário → sistema completo | alto | s a min |
+| Contract | borda entre serviços | médio | ms |
+| Property-based | invariantes em N inputs aleatórios | médio | s |
+
+## O que testar
+
+- **Sempre**: regra de negócio, transformação de dados, branching condicional.
+- **Frequentemente**: integração com DB/API externa (com mock controlado).
+- **Estrategicamente**: fluxo crítico ponta-a-ponta (login, checkout, etc.).
+- **Não obsessivamente**: getters/setters triviais, código de framework.
+
+## AAA / Given-When-Then
+
+```
+// Arrange / Given
+const order = buildOrder({ items: 3, discount: 0.1 });
+
+// Act / When
+const total = calculateTotal(order);
+
+// Assert / Then
+expect(total).toBe(270);
+```
+
+## Mocks — quando usar
+
+- I/O externo lento ou caro (rede, disco, API paga).
+- Tempo (`Date.now`, timers).
+- Aleatoriedade.
+
+## Mocks — quando NÃO usar
+
+- Banco em testes de integração (use container real ou in-memory equivalente).
+- Lógica que você está testando — se está mockando o sujeito do teste, está testando o mock.
+
+## Test data
+
+- Builders / factories > literais espalhados.
+- Fixtures versionadas para dados complexos.
+- Limpar estado entre testes (transação rollback em DB, reset em memória).
+
+## CI
+
+- Toda PR roda lint + type + unit + integration.
+- E2E em pipeline separado, possivelmente em scheduled (não em todo push).
+- Flaky test detectado → quarentena + issue, nunca silenciar com retry.
+
+## Anti-padrões
+
+- Teste que só passa em ordem específica.
+- Teste com `sleep(N)` arbitrário em vez de espera explícita por condição.
+- Teste que duplica a implementação ("assert que a função foi chamada com X").
+- Cobertura como métrica final (90% de cobertura testando nada útil é pior que 50% testando o crítico).

package/ai/specs/ADR/ADR-0002-typescript-runtime.md

@@ -0,0 +1,103 @@
+---
+id: ADR-0002
+title: Adoção de TypeScript + dependências controladas para Runtime v0.1
+status: accepted
+date: 2026-05-15
+deciders: igor.araujoedv@gmail.com (Founder)
+supersedes: null
+superseded_by: null
+related: [`.ai/server/package.json`, `.ai/server/tsconfig.json`, `.ai/server/aios-server.mjs`]
+tags: [runtime, build, dependencies, breaking-policy]
+note_on_numbering: "ADR-0001 foi reservado em IMP-001 (guard-edit hook) sem arquivo real escrito. Este é o primeiro ADR formalmente registrado."
+---
+
+# ADR-0002 — TypeScript + ts-morph + commander para Runtime v0.1
+
+## Contexto
+
+O AI Operating System (v4.0.0) entregou estrutura passiva sólida: 91+ arquivos markdown + MCP daemon Node.js (`aios-server.mjs`) com 12 tools de lookup/leitura. Toda a "inteligência" estava em **documentos**, não em **código executável**.
+
+Pesquisa do Founder identificou três componentes de alto ROI ausentes (referenciados como "AI-DOS v0.1 — Núcleo"):
+
+1. **Context Packager** — comprime o projeto em representação semântica (YAML-blocks) em vez de servir arquivos brutos ao LLM. Reduz drasticamente custo de tokens e alucinação.
+2. **Project State Engine** — mapa factual e queryable: módulos, imports/exports, grafo de dependências, code smells.
+3. **Snapshot System** — captura estado (state.json + hashes + memória relevante) pré/pós mudança.
+
+Implementar esses três motores sem AST parsing decente é inviável: regex-based module discovery em TS/JS produz alucinação inaceitável (imports dinâmicos, re-exports, barrel files, type-only imports são todos casos onde regex falha). Análise estrutural confiável exige parser real.
+
+## Decisão
+
+Adotar **TypeScript** + um conjunto pequeno e auditado de dependências para o Runtime v0.1:
+
+| Dependência | Categoria | Justificativa |
+|---|---|---|
+| `ts-morph` ^22.0.0 | runtime | API tipada sobre o compilador TypeScript. Trata corretamente imports, re-exports, decorators, generics. Mantido pelo autor do tsmorph (David Sherret). |
+| `commander` ^12.1.0 | runtime | CLI tipada para futuros entrypoints. Substitui `process.argv.slice(2)` manual no `aios-server.mjs`. |
+| `typescript` ^5.4.0 | dev | Compilador. |
+| `esbuild` ^0.21.0 | dev | Bundler que produz **um único `.mjs`** em `dist/index.mjs`, sem `node_modules` em runtime. |
+| `@types/node` ^20.12.0 | dev | Tipos do Node. |
+
+O runtime compilado (`dist/index.mjs`) é importado pelo `aios-server.mjs` (que **continua sendo um `.mjs` puro**, sem build próprio). Isso mantém o entrypoint MCP simples enquanto permite que a lógica complexa seja escrita em TypeScript tipado.
+
+## Alternativas consideradas
+
+### A. Manter zero-deps (`.mjs` puro)
+- **Prós**: zero supply-chain surface, sem build, sem `npm install`, alinhado ao princípio "memória reduz alucinação, regras reduzem deriva".
+- **Contras**: AST parsing decente é praticamente impossível em Node nativo. Implementar nosso próprio parser TS seria reinventar 10 anos de tsc. Resultado seria *menos confiável*, contrariando o motivo de adotar AST em primeiro lugar.
+- **Rejeitada** porque o custo de não ter AST decente é maior que o custo das deps.
+
+### B. TypeScript + ts-morph SEM bundler
+- **Prós**: setup mais simples.
+- **Contras**: `node_modules/` em produção (>500 arquivos). Risco de divergência entre dev e prod. Mais difícil de auditar.
+- **Rejeitada** em favor do bundle `dist/index.mjs` único.
+
+### C. SQLite (better-sqlite3) para storage
+- Considerada mas **rejeitada para v0.1**. JSON sidecar + Markdown atende. SQLite só se justifica quando queries complexas (ranking, joins, full-text) ficarem necessárias.
+
+## Consequências
+
+### Positivas
+- AST parsing confiável (ts-morph faz o que o tsc faz).
+- TypeScript em desenvolvimento → menos bugs por type-error.
+- CLI tipada → entrypoints futuros (`/spec`, `/task`, `/dialog`) ficam baratos.
+- Bundle único `dist/index.mjs` mantém runtime simples (zero `node_modules` em produção quando build é feito).
+- `aios-server.mjs` **continua zero-deps no runtime** (importa `dist/index.mjs` que é self-contained).
+
+### Negativas
+- Quebra a regra **"NUNCA instalar dependência nova sem justificar e pedir confirmação"** do CLAUDE.md global. Mitigado por:
+  - Esta ADR é o registro formal.
+  - User aprovou explicitamente via AskUserQuestion (2026-05-15).
+  - Deps são pequenas, populares, mantidas. Auditáveis em <30min cada.
+- Requer `npm install` + `npm run build` antes do primeiro uso do runtime v0.1.
+- `start-os.{ps1,sh}` precisa detectar ausência de Node/npm e dar mensagem clara.
+
+### Neutras
+- Versionamento: `dist/` é gerado (gitignored). `package-lock.json` versionado para reprodutibilidade.
+
+## Mitigações
+
+| Risco | Mitigação |
+|---|---|
+| Supply chain attack em deps | Lockfile versionado; `npm audit` no CI futuro; pinning de versões major. |
+| Build quebrado em dev novo | `start-os` detecta ausência de `dist/` e executa `npm install && npm run build` automaticamente; mensagem clara se Node não está instalado. |
+| TypeScript version drift | Versão pinada em `^5.4.0`; bumps requerem nova ADR ou minor (não major). |
+| `aios-server.mjs` virar dependent | Mantido `.mjs` puro com `import` opcional de `dist/index.mjs`. Se import falhar, daemon continua funcionando com as 12 tools antigas (graceful degradation). |
+
+## Status
+
+**Aceito em 2026-05-15.** Implementação na branch atual.
+
+## Validação
+
+- [x] User aprovou stack via AskUserQuestion
+- [ ] `npm install && npm run build` produz `dist/index.mjs` válido
+- [ ] `aios-server.mjs` carrega `dist/index.mjs` sem erro
+- [ ] As 12 tools antigas continuam funcionando após a integração
+- [ ] As 5 tools novas (`aios_analyze_project`, `aios_build_context_package`, `aios_snapshot`, `aios_snapshot_list`, `aios_snapshot_diff`) estão expostas
+
+(checkmarks restantes serão preenchidos ao concluir a Verification end-to-end do plano)
+
+## Notas
+
+- Próxima ADR esperada: **ADR-0003** quando v0.2 introduzir embeddings/SQLite (se necessário).
+- Esta decisão NÃO autoriza adicionar deps fora desta lista sem nova ADR.

package/ai/specs/ADR/ADR-0004-runtime-orchestrator.md

@@ -0,0 +1,94 @@
+---
+id: ADR-0004
+slug: runtime-orchestrator
+status: accepted
+date: 2026-05-16
+deciders: [user, tech-lead]
+related:
+  - RFC-0001 (proposta consolidada)
+  - ADR-0002 (typescript-runtime — base)
+---
+
+# ADR-0004 — Runtime Orchestrator com 3 commands consolidados
+
+## Contexto
+
+Sob ADR-0002, o `.ai/server/` expõe 17 tools MCP primitivas; sob a estrutura atual, `.claude/commands/` tem 8 slash commands granulares (`/analyze`, `/audit`, `/compact-memory`, `/context`, `/load-os`, `/os-status`, `/promote-learning`, `/snapshot`).
+
+Em sessão 2026-05-16, ao habilitar o servidor MCP no Antigravity (Gemini), constatou-se que a LLM recebe **lista plana de 17 tools sem indicação de sequência ou dependência**. Risco: LLM erra ordem, esquece steps obrigatórios, repete chamadas, escolhe tool errada. Sintoma esperado: degradação cumulativa com cada nova capacidade.
+
+Análise externa apresentada pelo usuário e refinada em RFC-0001 propõe substituir a superfície granular por **3 commands consolidados** que executam **workflows determinísticos** sobre as 17 primitivas.
+
+## Decisão
+
+**Decidimos adotar o Runtime Orchestrator descrito em RFC-0001**, em 4 fases incrementais, cada uma com seu próprio ADR de execução:
+
+1. **Fase 1** (ADR-0005): Workflow Engine MVP. Aposentar os 8 commands antigos. Criar `/init`, `/sync`, `/work`.
+2. **Fase 2** (ADR-0006): Runtime State em `.ai/runtime/state.json`.
+3. **Fase 3** (ADR-0007): Context Layers explícitas + Artifact Index.
+4. **Fase 4** (ADR-0008): Intent Runtime para `/work` (gap analysis, clarification, plan/approve).
+
+Cada fase é entregável independente e pode ser validada antes da próxima.
+
+## Consequências
+
+### Positivas
+- LLM recebe **3 entrypoints semânticos** em vez de 17 primitivas planas → menor risco de ordem errada / step esquecido.
+- Workflows são **declarativos e auditáveis** (JSON em `.ai/workflows/`). Pode-se rastrear cada execução.
+- Composição passa a ser **first-class**: nova capacidade complexa vira novo workflow, não nova tool.
+- Onboarding de IDEs cross-platform fica mais simples (documentar 3 commands).
+
+### Negativas / Trade-offs aceitos
+- **Muscle memory**: quem usa `/analyze`, `/context`, etc. precisa migrar para `/sync` ou `/work`. Documentação faz mapeamento.
+- **Indireção adicional**: chamar `/sync` em vez de `aios_snapshot` direto adiciona um hop de leitura+parse de JSON. Aceitável dado que rodamos local.
+- **JSON em vez de YAML**: workflows ficam mais verbosos, mas zero-deps no Node (sem adicionar parser).
+- **Substituição de variáveis** `${input.X}` introduz mini-template engine; mantido propositalmente trivial (sem condicionais/loops) para não virar DSL.
+
+### Neutras
+- 17 tools primitivas continuam expostas — workflow é uma camada acima, não substitui.
+- ADR-0002 (Runtime v0.1) permanece base válida.
+
+## Alternativas consideradas
+
+### Alternativa A — Status quo
+- Pros: zero custo agora.
+- Cons: dívida cresce; LLM cada vez mais erra ordem; difícil portar para mais IDEs.
+- **Descartada**: sinal claro de degradação.
+
+### Alternativa B — Adicionar 3 commands consolidados E manter os 8 antigos
+- Pros: zero quebra de muscle memory.
+- Cons: superfície vai de 8 para 11; ambiguidade sobre quando usar granular vs composto.
+- **Descartada pelo usuário** (sessão 2026-05-16): preferiu superfície limpa, aceitou custo de migração.
+
+### Alternativa C — Workflow Engine em outra linguagem (Python, Rust)
+- Pros: ecossistema de ferramentas mais maduro.
+- Cons: violaria zero-deps de ADR-0002 (Node puro); exige novo runtime.
+- **Descartada**: incompatível com decisão prévia.
+
+## Critérios de decisão
+
+| Critério | Peso | Status Quo | Alt B (10 cmds) | **Esta decisão (3 cmds)** |
+|---|---|---|---|---|
+| Superfície semântica simples | Alto | Baixo (8) | Médio (11) | **Alto (3)** |
+| Determinismo de sequência | Alto | Baixo | Médio | **Alto** |
+| Zero-deps preservado | Alto | Alto | Alto | **Alto** |
+| Custo de migração | Médio | Zero | Baixo | **Médio (~40 arquivos)** |
+| Auditabilidade | Alto | Baixo | Médio | **Alto** |
+
+## Impacto futuro
+
+Se essa decisão se mostrar errada (sinais: workflows ficam muito rígidos, LLMs modernos preferem chamar primitivas direto, comunidade adota outra convenção):
+- **Reverter Fase 1** é caro (8 commands precisam ser recriados; docs cross-IDE atualizadas).
+- **Reverter Fases 2-4** é mais barato (são adições; podem ser desligadas sem quebrar Fase 1).
+- Mitigação: cada fase tem ADR próprio, então podemos parar entre fases se sinal negativo aparecer.
+
+## Referências
+
+- RFC-0001 (proposta detalhada, plano de migração, riscos)
+- ADR-0002 (TypeScript Runtime — base sobre a qual o orquestrador opera)
+- Sessão 2026-05-16: AskUserQuestion confirmou "Fases 1+2+3+4" e "substituir tudo pelos 3 novos"
+- Análise externa apresentada pelo usuário (síntese sobre AI Engineering Runtime vs MCP puro)
+
+---
+
+> **Lembrete**: este ADR cobre a decisão consolidada. Cada fase tem ADR próprio (0005, 0006, 0007, 0008) com detalhes técnicos da implementação. Espelho em `.ai/memory/decisions.md`.

package/ai/specs/ADR/ADR-0005-workflow-engine.md

@@ -0,0 +1,105 @@
+---
+id: ADR-0005
+slug: workflow-engine
+status: accepted
+date: 2026-05-16
+deciders: [user, tech-lead]
+related:
+  - ADR-0004 (decisão consolidada Runtime Orchestrator)
+  - RFC-0001 (proposta detalhada)
+---
+
+# ADR-0005 — Workflow Engine MVP (Fase 1)
+
+## Contexto
+
+Sob ADR-0004, decidimos implementar o Runtime Orchestrator em 4 fases. Este ADR cobre **Fase 1**: substituir os 8 slash commands granulares por 3 commands consolidados que executam workflows determinísticos sobre as 17 tools primitivas existentes.
+
+## Decisão
+
+**Implementamos um Workflow Engine MVP** com 5 componentes:
+
+1. **Workflow descriptors** em `.ai/workflows/<id>.json`:
+   - Schema declarado em `.ai/workflows/_schema.json` (JSON Schema draft-07).
+   - Campos obrigatórios: `id`, `version`, `description`, `steps[]`.
+   - Cada step: `id`, `tool` (uma das 17 primitivas `aios_*`), `args` (opcional), `on_error` (`abort` | `continue`, default `abort`).
+   - Args suportam substituição de variáveis `${input.X}`, `${timestamp}`, com fallback literal `'string'`.
+
+2. **Tool MCP `aios_run_workflow(name, input)`** no `.ai/server/aios-server.mjs`:
+   - Carrega `.ai/workflows/<name>.json` (validando regex `^[a-z][a-z0-9_-]{0,32}$` para evitar path traversal).
+   - Executa steps em sequência, capturando duração e preview do resultado (truncado em 400 chars).
+   - Retorna relatório JSON: `{ workflow, version, started_at, finished_at, status, steps: [...] }`.
+   - `on_error: continue` permite step falhar sem abortar o workflow.
+
+3. **Tool MCP `aios_list_workflows()`** para listar workflows disponíveis.
+
+4. **3 workflows iniciais**:
+   - `.ai/workflows/init.json` — detect_stack → analyze_project → build_context_package → snapshot baseline → load CORE
+   - `.ai/workflows/sync.json` — detect_stack → analyze_project → rebuild context → lint → snapshot incremental
+   - `.ai/workflows/work.json` (MVP) — classify_task → route_query → load CORE → search_memory → focused context
+
+5. **3 slash commands** em `.claude/commands/`:
+   - `/init`, `/sync`, `/work` — cada um chama `aios_run_workflow` com o nome respectivo.
+   - **Os 8 commands antigos foram deletados** (`/analyze`, `/audit`, `/compact-memory`, `/context`, `/load-os`, `/os-status`, `/promote-learning`, `/snapshot`).
+
+## Consequências
+
+### Positivas
+- Superfície de slash commands: 8 → 3 (redução de 62%).
+- Sequência de tools deixa de ser improvisada pela LLM — workflows são determinísticos.
+- Workflows são **declarativos** (JSON) e auditáveis — facil debugar qual step falhou.
+- Composição vira first-class: nova capacidade complexa é novo workflow JSON, não nova tool.
+- Zero novas dependências (JSON parser é built-in no Node).
+
+### Negativas / Trade-offs aceitos
+- Muscle memory: quem usa `/analyze`, `/context`, etc. precisa migrar para `/sync` ou `/work`.
+- `aios_run_workflow` adiciona um hop de indireção (parse JSON + iterate steps). Aceitável em uso local.
+- Substituição de variável `${...}` introduz mini-template engine; mantido propositalmente trivial (sem condicionais/loops) para não virar DSL.
+- JSON é mais verboso que YAML, mas evita nova dep.
+
+### Neutras
+- 17 tools primitivas continuam expostas — workflows são uma camada acima.
+- Slash command `/init` colide nominalmente com built-in `init` (Initialize CLAUDE.md) do Claude Code. Custom commands em `.claude/commands/` têm precedência para slash commands; para Skill tool a desambiguação é manual. Documentado em `.claude/commands/init.md`.
+
+## Alternativas consideradas
+
+### Alternativa A — YAML em vez de JSON
+- Pros: mais legível para humanos.
+- Cons: exige dep (js-yaml ou similar), violando zero-deps de ADR-0002.
+- **Descartada**.
+
+### Alternativa B — Workflow engine externo (Temporal, n8n)
+- Pros: feature-rich, durável, observable.
+- Cons: dep externa pesada, overkill para uso local single-user.
+- **Descartada**.
+
+### Alternativa C — DSL própria (com condicionais, loops)
+- Pros: mais expressivo.
+- Cons: vira projeto paralelo de manter; risco de "in-house programming language".
+- **Descartada**: manter steps lineares; condicionais ficam para Fase 4 (Intent Runtime).
+
+## Critérios de decisão
+
+| Critério | Peso | Alt A (YAML) | Alt B (Temporal) | **Esta (JSON nativo)** |
+|---|---|---|---|---|
+| Zero-deps | Alto | Baixo | Baixo | **Alto** |
+| Simplicidade implementação | Alto | Médio | Baixo | **Alto** |
+| Expressividade | Médio | Médio | Alto | **Médio** |
+| Tempo até MVP | Alto | Médio | Baixo | **Alto** |
+
+## Impacto futuro
+
+- Fase 2 (Runtime State) vai adicionar `${state.X}` à substituição de variáveis.
+- Fase 4 (Intent Runtime) vai estender com pause-for-input e conditional branches — exige cuidado para não virar DSL completo.
+- Se workflow JSON ficar muito grande, considerar split por arquivo (`init/steps.json` + `init/meta.json`).
+
+## Referências
+
+- ADR-0004 (decisão consolidada)
+- RFC-0001 (proposta detalhada)
+- `.ai/workflows/_schema.json` (validação)
+- `.ai/server/aios-server.mjs` (implementação)
+
+---
+
+> Espelho em `.ai/memory/decisions.md`. Próxima fase: ADR-0006 (Runtime State).

package/ai/specs/ADR/ADR-0006-runtime-state.md

@@ -0,0 +1,104 @@
+---
+id: ADR-0006
+slug: runtime-state
+status: accepted
+date: 2026-05-16
+deciders: [user, tech-lead]
+related:
+  - RFC-0002 (extensão consolidada)
+  - ADR-0005 (Fase 1 — Workflow Engine MVP)
+---
+
+# ADR-0006 — Runtime State + Lifecycle + Context TTL + Execution Contracts + Safety Rule (Fase 2)
+
+## Contexto
+
+Sob ADR-0005 (Fase 1), o Workflow Engine executa workflows sem persistir estado entre sessões: cada `/sync` ou `/work` começa "do zero". A análise externa de 2026-05-16 destacou que isso impede **continuidade operacional** — LLM não sabe em que fase do projeto está, qual o foco atual, quais decisões foram tomadas recentemente.
+
+Esta ADR cobre **Fase 2** do RFC-0002.
+
+## Decisão
+
+**Decidimos persistir o estado operacional em `.ai/runtime/state.json`** com 5 componentes:
+
+1. **Identity** — nome do projeto, maturity (empty/minimal/partial/mature), stack.
+2. **Lifecycle** — `phase` (discovery/planning/implementation/stabilization/production) + `mode` (readonly/analysis/execution/validation).
+3. **Persistent context** — refs a decisões arquiteturais + rules (não rotaciona).
+4. **Rotating context** — TTL configurável (default 30 dias): active_focus, recent_errors, open_questions. Entries com `expires_at`; tools podem prunar.
+5. **Workflow history** — últimas N execuções de workflows com timestamp, status, guarantees met/unmet.
+
+**4 tools MCP novas**: `aios_state_get`, `aios_state_set`, `aios_state_advance`, `aios_state_reset`.
+
+**Workflow schema estendido** com 2 campos opcionais:
+- `guarantees: [string]` — lista de invariantes auditáveis. Engine valida cumprimento após execução; relatório inclui `unmet_guarantees: []`.
+- `safety: { project_files_readonly: boolean }` — declarativo; futuro: engine pode bloquear steps que tentem editar fora de `.ai/` quando flag ativa.
+
+**Substituição de variáveis em workflows** ganha `${state.X}` (ex: `${state.lifecycle.phase}`).
+
+Mapeamento `guarantee → tools provedoras` é fixo no servidor:
+```
+snapshot_created     → aios_snapshot
+state_updated        → aios_state_set, aios_state_advance, aios_state_reset
+context_compiled     → aios_build_context_package
+lint_clean           → aios_lint
+stack_detected       → aios_detect_stack
+project_analyzed     → aios_analyze_project
+core_loaded          → aios_get_core_bundle
+```
+
+Workflows `init`/`sync`/`work` atualizados:
+- `init`: guarantees todas + state advance para `discovery`.
+- `sync`: guarantees stack+analyzed+context+lint+snapshot+state_updated.
+- `work`: guarantees core_loaded+context_compiled (sem state advance — work é repetível).
+
+## Consequências
+
+### Positivas
+- LLM tem fonte única de verdade sobre estado operacional (`/work` pode consultar `aios_state_get({path: "lifecycle.phase"})` em vez de inferir).
+- Workflow guarantees criam contrato auditável (relatório mostra se algum invariante falhou).
+- Context TTL evita acúmulo infinito de `recent_errors`/`open_questions`.
+- Base preparada para Fase 3 (State Compiler vai ler do state.json) e Fase 5 (Confidence vive sob state).
+
+### Negativas / Trade-offs aceitos
+- `.ai/runtime/state.json` é mais um arquivo a manter sincronizado. Mitigação: workflows escrevem nele automaticamente.
+- Guarantees mapeamento hardcoded no servidor; nova guarantee exige edit de código (não declarável só no workflow JSON). Aceitável: lista pequena, estável.
+- `${state.X}` introduz acoplamento workflows ↔ state schema. Schema versionado.
+
+### Neutras
+- Manifest atualizado para incluir `.ai/runtime/state.schema.json` e `.ai/runtime/state.json` como required.
+- Diretório `.ai/runtime/` já existia (PID file); agora ganha state.
+
+## Alternativas consideradas
+
+### Alternativa A — Estado em memory/_summary.md (markdown narrativo)
+- Pros: humanamente legível.
+- Cons: não-estruturado; LLM precisa parsear; falsos negativos em busca.
+- **Descartada**: precisamos de schema validável.
+
+### Alternativa B — SQLite em `.ai/runtime/state.db`
+- Pros: queries ricas, transações.
+- Cons: viola zero-deps (better-sqlite3 ou similar); overkill para single-writer.
+- **Descartada**.
+
+### Alternativa C — Guarantees como JSON Schema validação do output
+- Pros: declarativo total.
+- Cons: cada tool teria que produzir output conformante; refactor grande.
+- **Descartada**: mapeamento tool→guarantee é simples e suficiente.
+
+## Impacto futuro
+
+- Fase 3 (State Compiler) vai produzir `runtime-context.json` consolidando `state.json` + outras fontes.
+- Fase 4 (Intent Runtime) vai usar `state.lifecycle.phase` para adaptar comportamento do `/work`.
+- Fase 5 (Confidence) vai estender schema do state com bloco `confidence: {}`.
+- Se schema do state.json se mostrar limitante: nova versão major + migration ADR.
+
+## Referências
+
+- RFC-0002 (proposta consolidada Fases 2-5)
+- ADR-0005 (Fase 1 — base sobre a qual estendemos)
+- `.ai/runtime/state.schema.json` (validação)
+- `.ai/server/aios-server.mjs` (implementação)
+
+---
+
+> Espelho em `.ai/memory/decisions.md`. Próxima fase: ADR-0007 (State Compiler + Drift + Context Layers + Artifact Index).

package/ai/specs/ADR/ADR-0007-state-compiler-drift-context-layers-artifact-index.md

@@ -0,0 +1,82 @@
+---
+id: ADR-0007
+slug: state-compiler-drift-context-layers-artifact-index
+status: accepted
+date: 2026-05-16
+deciders: [user, tech-lead]
+related:
+  - RFC-0002 (extensão consolidada)
+  - ADR-0006 (Fase 2 — Runtime State)
+---
+
+# ADR-0007 — State Compiler + Drift Detection + Context Layers + Artifact Index (Fase 3)
+
+## Contexto
+
+Sob ADR-0006 (Fase 2), o sistema persiste estado operacional. Mas o `/work` ainda relê CORE + memory + context a cada execução (~5k tokens). A análise externa propõe um **Project State Compiler** que produz um pacote operacional único e otimizado, consumido por `/work`.
+
+Esta ADR cobre **Fase 3** do RFC-0002.
+
+## Decisão
+
+**Decidimos implementar 4 capacidades novas**:
+
+1. **State Compiler** — tool `aios_compile_runtime_context()` produz `.ai/runtime/runtime-context.json` consolidando state.json + project-state.json + últimas N decisions + top-M módulos por relevância + memory rotating. **Target: ≤ 4000 tokens** (compressão semântica, não dump). Cache invalidado por hash do project-state.
+
+2. **Drift Detection** — tool `aios_detect_drift({ since_snapshot? })` compara arquivos atuais vs último snapshot (ou snapshot informado): retorna `{ code_changes_without_spec_update, specs_updated_no_code_change, orphan_modules }`. Sem AST profundo (Fase 4 pode aprofundar) — usa hash + mtime + presença de SDD/ADR referenciando o módulo.
+
+3. **Context Layers explícitas** — tool `aios_get_context(layer, focus?)` atalho para devolver:
+   - `core` → `aios_get_core_bundle()`
+   - `working` → state + project-state resumido + memory rotating + últimas 3 decisions
+   - `deep` → working + full project-state + memory full + all decisions
+
+4. **Artifact Index** — tool `aios_artifact_list({ type?, status? })` retorna catálogo de specs/snapshots/packages/ADRs. Mantém `.ai/artifacts/index.json` opcionalmente (auto-gerado por `aios_compile_runtime_context`).
+
+Workflow `sync` ganha 2 steps finais: `compile_runtime_context` + `detect_drift` (drift como info, não bloqueante).
+Workflow `work` v2.1 ganha step inicial `load_runtime_context` opcional (preferido a `load_core` quando context recente existe).
+
+## Consequências
+
+### Positivas
+- `/work` pode carregar **um único arquivo** (`runtime-context.json` ~4k tokens) em vez de CORE + memory + context separados (~5k).
+- Drift detection alerta divergências antes que virem inconsistência crônica.
+- `aios_get_context(layer)` simplifica chamada — LLM não precisa saber quais tools compor.
+- Artifact index torna inventário consultável (útil para `/work` decidir se precisa de spec específico).
+
+### Negativas / Trade-offs aceitos
+- Cache do runtime-context invalida facilmente (qualquer change em project-state). Aceitável: recompilar é barato (~1s para projetos médios).
+- Drift detection sem AST profundo pode gerar falsos positivos (arquivo mudou mas spec atualizada não detectada). Mitigação: severity tier `info` por default.
+- Runtime context é JSON estruturado, não markdown narrativo — menos legível para humano. Mitigação: opcional `aios_compile_runtime_context({ format: "markdown" })` futuro.
+
+### Neutras
+- `.ai/runtime/runtime-context.json` é arquivo gerado; gitignore opcional.
+- `.ai/artifacts/index.json` é arquivo gerado; gitignore opcional.
+
+## Alternativas consideradas
+
+### A — Sempre recompilar sob demanda (sem cache em disco)
+- Pros: nunca stale.
+- Cons: latência por chamada; perde benefício de "single file leitor".
+- **Descartada**: cache em disco é mais eficiente; invalidação é rápida.
+
+### B — Drift detection via AST diff completo
+- Pros: precisão alta.
+- Cons: lento; reusaria ts-morph; complexidade grande.
+- **Descartada na Fase 3**: hash+mtime+ref-check é suficiente como MVP; Fase 4+ pode aprofundar.
+
+### C — Artifact Index gerado por crawler separado
+- Pros: roda em background.
+- Cons: mais um processo a coordenar.
+- **Descartada**: index gerado in-process pelo compile_runtime_context.
+
+## Impacto futuro
+
+- Fase 4 (Intent Runtime) vai consumir `runtime-context.json` no início do `/work`.
+- Fase 5 (Confidence) vai adicionar bloco `confidence` ao compiled context.
+- Se runtime-context exceder 4000 tokens repetidamente: revisar algoritmo de compressão; pode precisar de tiered context (core/working/deep no próprio arquivo).
+
+## Referências
+
+- RFC-0002 (Fase 3 detalhada)
+- ADR-0006 (state.json — fonte de identity/lifecycle/rotating)
+- `.ai/server/aios-server.mjs` (implementação)