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

package/ai/specs/ADR/ADR-0008-intent-runtime-discovery-branching.md

@@ -0,0 +1,93 @@
+---
+id: ADR-0008
+slug: intent-runtime-discovery-branching
+status: accepted
+date: 2026-05-16
+deciders: [user, tech-lead]
+related:
+  - RFC-0002 (extensão consolidada)
+  - ADR-0007 (Fase 3 — State Compiler)
+---
+
+# ADR-0008 — Intent Runtime para /work + Discovery Runtime ramificado em /init (Fase 4)
+
+## Contexto
+
+Sob ADR-0005 (Fase 1), `/work` é pipeline linear de tools. Sob ADR-0007 (Fase 3), consome `runtime-context.json`. Mas ainda falta o **pipeline operacional completo** descrito na análise externa: Intent → Gap Analysis → Clarification (pause) → Plan → Approval (pause) → Execute → Validate → Memory Update → Snapshot. E `/init` precisa **ramificar** entre projeto novo (Discovery Runtime) vs existente (Reverse Engineering Runtime).
+
+Esta ADR cobre **Fase 4** do RFC-0002.
+
+## Decisão
+
+**Decidimos estender o Workflow Engine com 2 capacidades:**
+
+1. **Pause-for-input** — step pode declarar `pause_for: { reason, prompt, expected_input? }`. Quando alcançado:
+   - Engine salva snapshot da execução em `.ai/runtime/paused-executions/<execution_id>.json`.
+   - Retorna `{ status: "paused", execution_id, pause_info, steps_completed }`.
+   - Cliente externo (Claude AskUserQuestion, Gemini Function Calling pause, etc.) mostra `prompt` ao usuário e chama `aios_resume_workflow({execution_id, user_input})`.
+   - Engine recarrega state, deserializa, continua do step seguinte com `ctx.resumed_input` populado.
+
+2. **Branches condicionais** — step pode ter `branches: [{ when: "<expr>", steps: [...] }, { default: true, steps: [...] }]`. Avaliação simples: `when` é dotted-path com operador (`==`, `!=`, `in`) comparado a literal. Ex.: `state.identity.maturity == "empty"`.
+
+**Workflow `work` v3.0.0 (Intent Runtime completo)**:
+1. `load_runtime_context` — base operacional consolidada.
+2. `classify_intent` — refina classify_task.
+3. `gap_analysis` — heurística: arquivos/specs ausentes para o intent.
+4. `clarification` (pause_for, opcional se complex) — questiona ambiguidades.
+5. `generate_plan` — pseudo-step que retorna template; LLM externa preenche.
+6. `approval` (pause_for) — pede OK do usuário.
+7. `execute` — placeholder; execução real é da LLM externa via tool calls subsequentes.
+8. `validate` — `aios_lint` + `aios_validate_audit` no resultado.
+9. `memory_update` — state.rotating.active_focus + sugestão append em completed-tasks.
+10. `post_snapshot` — snapshot final.
+
+**Workflow `init` v3.0.0 (ramificado)** — usa `branches`:
+- Branch A `when: state.identity.maturity == "empty"` → Discovery Runtime (perguntas extensas).
+- Branch default → Reverse Engineering Runtime (steps atuais do init v2).
+
+**3 tools novas**: `aios_resume_workflow`, `aios_list_paused_executions`, `aios_cancel_paused_execution`.
+
+## Consequências
+
+### Positivas
+- `/work` vira **runtime operacional completo** (não pipeline linear).
+- Discovery em projeto novo deixa de exigir intervenção manual.
+- Pausa-resume permite workflows multi-turno preservando estado.
+- Cliente externo decide UI da pausa (AskUserQuestion, prompt customizado, etc.) — engine só declara intenção.
+
+### Negativas / Trade-offs aceitos
+- Estado de execução pausada vive em disco; precisa expiração (TTL 30 min default). Tool `aios_list_paused_executions` ajuda gestão.
+- `branches` é mini-expression language; risco de virar DSL. Limito a `==`, `!=`, `in` e literal vs dotted-path.
+- Workflow `work` v3 tem steps que são "placeholders" (`generate_plan`, `execute`) — LLM externa precisa entender que esses são marcadores. Documentado no workflow JSON.
+
+### Neutras
+- Workflows v2 (init/sync/work atuais) continuam válidos; v3 é opt-in via nome `work-v3` se preferir parallel. Decisão: substituir direto (mantém UX dos 3 commands).
+
+## Alternativas consideradas
+
+### A — Pause-for-input via MCP notifications nativas
+- Pros: idiomático MCP.
+- Cons: nem todo cliente MCP suporta server-initiated notifications interativas.
+- **Descartada**: status:paused + execution_id é portável.
+
+### B — Branches via expressões JavaScript completas
+- Pros: máxima expressividade.
+- Cons: eval security; vira motor de scripts.
+- **Descartada**: 3 operadores são suficientes.
+
+### C — Pular Fase 4 / manter work como pipeline linear
+- Pros: zero custo.
+- Cons: usuário aprovou expansão; análise externa pediu explicitamente.
+- **Descartada**.
+
+## Impacto futuro
+
+- Fase 5 (Confidence) pode usar `pause_for` para perguntar sobre low-confidence categories.
+- Se branches virarem onerosos, podemos converter para "sub-workflows" (workflow chama outro workflow).
+- `paused-executions/` precisa cleanup periódico → adicionar step `prune_expired` em `sync` futuro.
+
+## Referências
+
+- RFC-0002 (Fase 4)
+- ADR-0005 (engine base)
+- ADR-0007 (runtime-context consumido por work v3)

package/ai/specs/ADR/ADR-0009-confidence-system-maturity-tracking.md

@@ -0,0 +1,113 @@
+---
+id: ADR-0009
+slug: confidence-system-maturity-tracking
+status: accepted
+date: 2026-05-16
+deciders: [user, tech-lead]
+related:
+  - RFC-0002 (extensão consolidada)
+  - ADR-0006 (state.json — onde confidence vive)
+  - ADR-0007 (runtime-context — onde flags aparecem)
+---
+
+# ADR-0009 — Confidence System + Maturity Tracking (Fase 5)
+
+## Contexto
+
+Sob ADR-0008, o runtime tem ciclo operacional completo. Mas a LLM ainda **assume com mesma confiança** fatos sólidos (architecture, decisions registradas) e inferências fracas (telemetria de módulos novos, padrões emergentes). Custo: erros de "alta convicção" em áreas mal compreendidas.
+
+Análise externa propõe **Confidence System** registrando confiança por categoria. LLM consulta → faz mais perguntas onde confidence é baixa.
+
+Esta ADR cobre **Fase 5** do RFC-0002 (última).
+
+## Decisão
+
+**Estendemos `state.json` com bloco `confidence`** e adicionamos **3 tools MCP**:
+
+### Schema extension
+```json
+{
+  "confidence": {
+    "categories": {
+      "architecture": { "level": "high", "reason": "...", "updated_at": "..." },
+      "modules": { "level": "medium", "reason": "...", "updated_at": "..." },
+      "telemetry": { "level": "low", "reason": "...", "updated_at": "..." },
+      "decisions": { "level": "high", "reason": "...", "updated_at": "..." },
+      "domain": { "level": "medium", "reason": "...", "updated_at": "..." }
+    },
+    "default_level": "medium"
+  }
+}
+```
+
+Levels: `low | medium | high`. Nova categoria pode ser criada por `aios_confidence_set`.
+
+### Tools
+- `aios_confidence_get({ category? })` — retorna toda confidence ou uma categoria.
+- `aios_confidence_set({ category, level, reason })` — registra/atualiza.
+- `aios_confidence_assess()` — heurística que olha state + project-state + drift e propõe níveis. Retorna sugestões; usuário/LLM aplica via set.
+
+### Integração com runtime-context (ADR-0007)
+`aios_compile_runtime_context` ganha bloco `low_confidence_flags`: top-3 categorias com `level=low`, expostas para LLM ler sem precisar puxar state. Ex.:
+```json
+{
+  "low_confidence_flags": [
+    { "category": "telemetry", "reason": "módulo telemetry-injector adicionado mas sem SDD" },
+    { "category": "modules", "reason": "16 orphan modules detectados em drift" }
+  ]
+}
+```
+
+LLM externa orientada a **perguntar antes de assumir** quando categoria do escopo está com low confidence.
+
+### Maturity Tracking (lightweight)
+`identity.maturity` (já existe sob ADR-0006: empty|minimal|partial|mature) ganha regra heurística em `aios_confidence_assess`:
+- `empty`: sem state.identity.project_name + sem ADRs.
+- `minimal`: project_name preenchido + ≤2 ADRs.
+- `partial`: 3-9 ADRs + project-state.json existe.
+- `mature`: ≥10 ADRs + project-state com >10 módulos + ≥3 syncs em workflow_history.
+
+Tool sugere upgrade; não força.
+
+## Consequências
+
+### Positivas
+- LLM tem sinal explícito para fazer mais perguntas em zonas frágeis.
+- Drift detection (ADR-0007) agora pode rebaixar confidence automaticamente (ex.: detectar orphan modules → confidence.modules ← medium).
+- Maturity tracking permite UX adaptativa (init em projeto `empty` é mais didático que `mature`).
+
+### Negativas / Trade-offs aceitos
+- Mais um bloco no state.json para manter. Aceitável: tools fazem set automático.
+- Heurística de `assess` é opinion: pode discordar do usuário. Mitigação: `assess` apenas sugere, não escreve.
+- `low_confidence_flags` adiciona ~200 tokens ao runtime-context. Ainda muito abaixo do budget 4000.
+
+### Neutras
+- Categorias são strings livres — extensível sem mudança de schema.
+
+## Alternativas consideradas
+
+### A — Confidence numérico (0-1)
+- Pros: granularidade.
+- Cons: usuário precisa traduzir 0.6 → "low? medium?"; mais ruído.
+- **Descartada**: 3 níveis bastam.
+
+### B — Confidence por arquivo individual
+- Pros: precisão.
+- Cons: explode em projetos grandes.
+- **Descartada**: agregação por categoria é suficiente.
+
+### C — Esperar caso de uso para implementar
+- Pros: evita over-engineering.
+- Cons: usuário aprovou explicitamente "Adotar TUDO incluindo Confidence System (Fase 5)".
+- **Descartada por aprovação**.
+
+## Impacto futuro
+
+- Workflows futuros podem ter `pause_for` condicional baseado em confidence (ex.: pausa se categoria envolvida está low).
+- Confidence pode ser exportado como métrica de qualidade do conhecimento do projeto.
+
+## Referências
+
+- RFC-0002 (Fase 5)
+- ADR-0006 (state.json — host do bloco confidence)
+- ADR-0007 (runtime-context — local dos flags)

package/ai/specs/ADR/ADR-0010-structural-architecture-standards.md

@@ -0,0 +1,121 @@
+---
+id: ADR-0010
+slug: structural-architecture-standards
+status: accepted
+date: 2026-05-16
+deciders: [user, tech-lead]
+related:
+  - ADR-0004 (Runtime Orchestrator base)
+  - ADR-0006 (state.json — identity ganha campo structural_profile)
+  - ADR-0007 (artifact_list — blueprints aparecem como artifacts)
+---
+
+# ADR-0010 — Structural Architecture Standards: Canon, Constraints, Blueprints, Composition Engine
+
+## Contexto
+
+Sob ADR-0004..0009 entregamos o Runtime Operacional. A próxima carência identificada é estrutural: projetos modernos são **híbridos** (saas + telemetry + crm + mobile + …) e estruturas tradicionais (`controllers/services/models`) viram caos rápido. A análise externa de 2026-05-16 propõe **AI-Native Project Architecture Standards** com 3 camadas:
+
+1. **Structural Canon** — regras universais (domain-first, vertical slice, isolated runtime contexts, contracts required, etc.).
+2. **Structural Blueprints** — fragmentos por tipo de projeto (web, saas, crm, mobile, game, ai-platform, telemetry, realtime).
+3. **Composition Engine** — compõe blueprints híbridos via union semântica.
+
+Convergência com pesquisa (2026): Modular Monolith + Vertical Slice Architecture é state-of-the-art; AI-native monorepos exigem instruções por-path e boundaries explícitos.
+
+## Decisão
+
+**Adotamos uma camada de Standards estruturais** com 3 artefatos + 3 tools MCP:
+
+### Artefatos
+- `.ai/rules/structure-canon.md` — princípios universais (domain-first, modular by responsibility, vertical slice, isolated boundaries, contracts required, AI-navigable).
+- `.ai/rules/structural-constraints.md` — limites operacionais (max module deps, max file lines, depth, naming).
+- `.ai/blueprints/_schema.json` — schema dos blueprints (JSON).
+- `.ai/blueprints/README.md` — guia de composição.
+- `.ai/blueprints/{web,saas,crm,mobile,game,ai-platform,telemetry,realtime}.json` — 8 blueprints declarativos.
+
+### Schema blueprint
+```json
+{
+  "id": "saas",
+  "description": "...",
+  "extends": ["web"],
+  "folders": ["billing/", "tenancy/", "subscriptions/", "permissions/", "audit/"],
+  "modules": ["billing", "tenancy", "permissions", "audit"],
+  "packages_recommended": ["auth-sdk", "stripe-adapter"],
+  "integrations_recommended": ["stripe", "sendgrid"],
+  "notes": "..."
+}
+```
+
+### Tools MCP (3)
+- `aios_list_blueprints()` — lista os 8 blueprints disponíveis.
+- `aios_get_blueprint({name})` — devolve o blueprint completo.
+- `aios_compose_structure({types: ["saas","telemetry","realtime"]})` — faz union semântica (dedup, resolve `extends` transitivo) e retorna estrutura final consolidada: folders, modules, packages, integrations, applicable_constraints.
+
+### Princípios do Canon (resumo)
+1. **Domain-first**: organizar por bounded context (telemetry/, tracking/, billing/), não por tipo de arquivo.
+2. **Modular Monolith + Vertical Slice**: cada módulo é self-contained (application/domain/infrastructure/contracts/events/tests/docs).
+3. **Boundaries explícitos**: módulo só conversa com outro via API pública (contracts).
+4. **No global utils**: utils ficam em packages tipados (`packages/utils/`) ou no próprio módulo.
+5. **AI-navigable**: cada módulo tem `index.ts` + `README.md` curto descrevendo responsabilidade.
+6. **Contracts required**: APIs entre módulos têm tipos compartilhados em `packages/contracts/`.
+7. **Evolutionary**: estrutura cresce com o projeto; não força tudo no início.
+
+### Constraints (defaults razoáveis)
+- `max_module_dependencies`: 5
+- `max_file_lines`: 500
+- `max_folder_depth`: 4
+- `require_module_readme`: true
+- `require_module_index`: true
+- `forbid_global_singletons`: true
+- `forbid_circular_module_deps`: true
+
+`state.identity.structural_profile` (novo campo, opcional) registra os tipos compostos (`["saas", "telemetry"]`).
+
+## Consequências
+
+### Positivas
+- Projeto novo recebe estrutura inicial **composta** (não copy-paste de template gigante).
+- IA tem **vocabulário comum** para navegar projetos (módulos por domínio, não por camada).
+- Hibridização: SaaS + Telemetry + Realtime pode ser composto sem inventar pasta nova.
+- Constraints auditáveis (drift detection futura pode reportar violação).
+- Pesquisa 2026 confirma: AI agents performam melhor com path-aware boundaries.
+
+### Negativas / Trade-offs aceitos
+- Adicionar `.ai/blueprints/` e `.ai/rules/structure-canon.md` aumenta superfície de leitura. Mitigação: tier `on-demand` no manifest.
+- Blueprints são templates; podem virar dogma. Mitigação: composition engine encoraja mistura, não substituição.
+- Constraints como números (5 deps, 500 linhas) são heurísticas. Aceitável: customizáveis por projeto.
+
+### Neutras
+- Blueprints em JSON (zero-deps); README.md em markdown.
+- `structural_profile` em state.json é optional — projetos legados não quebram.
+
+## Alternativas consideradas
+
+### A — Templates fixos (1 estrutura por tipo)
+- Pros: simples.
+- Cons: não escala para híbridos (saas+telemetry+crm).
+- **Descartada**: análise externa explicitamente rejeita.
+
+### B — Schema OpenAPI-like para estrutura
+- Pros: muito formal.
+- Cons: over-engineering; nossa necessidade é declaração simples.
+- **Descartada**.
+
+### C — Não criar (deixar projeto definir)
+- Pros: zero overhead.
+- Cons: cada projeto reinventa; IA não tem vocabulário comum.
+- **Descartada**: usuário aprovou implementação explícita.
+
+## Impacto futuro
+
+- Workflow `init` v4 (futuro) pode chamar `aios_compose_structure` se usuário declarar tipos.
+- Drift detection (ADR-0007) pode ser estendida com **structural drift**: módulo cresceu além do `max_file_lines`, viola circular_dep, etc.
+- Blueprints novos podem ser adicionados sem mudança de código (engine lê `.ai/blueprints/*.json`).
+
+## Referências
+
+- RFC-0001/0002 (Runtime Orchestrator — base)
+- Pesquisa 2026: Milan Jovanović "Vertical Slices Inside Modular Monolith", Spectro Cloud "AI Turning 2026 into Year of Monorepo", d4b "AI agents in monorepos"
+- ADR-0006 (state.identity ganha structural_profile)
+- ADR-0007 (artifact_list inclui blueprints)

package/ai/specs/ADR/ADR-0011-mcp-prompts.md

@@ -0,0 +1,86 @@
+---
+id: ADR-0011
+slug: mcp-prompts
+status: accepted
+date: 2026-05-16
+deciders: [user, tech-lead]
+related:
+  - ADR-0004 (Runtime Orchestrator)
+  - ADR-0005 (Workflow Engine)
+  - ADR-0008 (Intent Runtime + Discovery Branching)
+---
+
+# ADR-0011 — MCP Prompts como discovery mechanism cross-IDE
+
+## Contexto
+
+Os 3 comandos canônicos (`/init`, `/sync`, `/work`) eram expostos apenas via `.claude/commands/*.md` — um mecanismo **proprietário do Claude Code CLI**. Em qualquer outra IDE (Antigravity, Cursor, Windsurf, Cline, Continue, Copilot, TRAE, Gemini CLI) digitar `/init` no chat era tratado como texto literal, e o usuário precisava recorrer a linguagem natural ("inicialize o conhecimento do projeto") para que a LLM acertasse a tool MCP. Isso quebra a promessa "conecte o MCP e use" — o produto parecia incompleto fora do Claude Code.
+
+O servidor MCP `ai-os` (`.ai/server/aios-server.mjs`) já expunha 36 tools via `tools/list` + `tools/call`, mas declarava capabilities apenas `{ tools: {} }`. O protocolo MCP (spec 2024-11-05) define um segundo primitivo, **Prompts**, que IDEs MCP-compatíveis renderizam **nativamente** no autocomplete de `/` (no Claude Code aparecem como `/mcp__<server>__<prompt>`; outras IDEs adotaram convenções similares).
+
+## Decisão
+
+**Expor os 3 workflows canônicos também como MCP Prompts**, mantendo as tools intactas. Adotamos o modelo **híbrido** (decidido com o usuário em 2026-05-16):
+
+1. `capabilities` do servidor passa a declarar `{ tools: {}, prompts: {} }`.
+2. Novos métodos JSON-RPC:
+   - `prompts/list` → enumera prompts derivados de `.ai/workflows/*.json` (whitelist: `init`, `sync`, `work`).
+   - `prompts/get` → retorna `{ description, messages: [{ role: "user", content: { type, text } }] }`.
+3. **Conteúdo híbrido** do prompt retornado:
+   - Cabeçalho com nome + versão + descrição do workflow.
+   - **Ação**: bloco JSON com a chamada exata a `aios_run_workflow` (a LLM cliente executa).
+   - **Garantias**: lista dos `guarantees` do workflow.
+   - **Contexto enriquecido**: snapshot compacto de `state.identity` / `state.lifecycle` / `maturity`.
+   - **ROUTER hint** (quando `intent` for fornecido): rotas casadas + arquivos condicionais.
+   - **Lembrete de protocolo**: `OS:loaded(...)` + classificação + `[OS Audit]`.
+4. **Argumentos** dos prompts:
+   - `init`, `sync`: `intent` (opcional).
+   - `work`: `intent` (required = true na descriptor; tool aceita ausente como fallback).
+
+## Por que híbrido (vs. inline-execute)
+
+Considerados:
+- **Apenas instrução** (LLM faz tool call) — simples, mas perde a chance de injetar contexto que economiza reads.
+- **Inline-execute no servidor** — 1 round-trip, mas perde os pause/resume interativos do `work` v3 (clarification + approval) e quebra o contrato do Workflow Engine de ADR-0005.
+- **Híbrido (escolhido)** — instrução pra LLM chamar a tool + estado/ROUTER pré-carregados como contexto. Robusto, preserva pause/resume, e dá ao prompt valor além de "atalho pra digitar a tool call".
+
+## Consequências
+
+**Positivas:**
+- IDEs MCP-aware (Claude Code, Cursor recente, e quem implementar o primitivo Prompts no futuro) expõem `/init`, `/sync`, `/work` **só conectando o MCP** — sem stub específico.
+- Contexto enriquecido reduz round-trips: a LLM já recebe `state.identity` + ROUTER hint no `prompts/get`, evita ler 3 arquivos manualmente.
+- `tools/list` permanece com 36 tools — zero regressão para clientes existentes.
+- Versão do server bumps `1.0.0` → `1.1.0` (minor: feature add).
+
+**Negativas / limitações:**
+- IDEs sem suporte a MCP Prompts (Windsurf, Cline, Continue, Copilot, TRAE em versões antigas) continuam dependentes de linguagem natural ou snippet de instrução nos stubs (resolvido por Fase 2 — fora do escopo desta ADR).
+- A whitelist `PROMPT_WORKFLOWS` é estática; adicionar um 4º prompt requer editar o servidor (intencional: prompts são produto, tools são API).
+- O conteúdo do prompt é gerado em runtime — depende de `state.json` legível. Falhas são tratadas como `null` (graceful).
+
+## Implementação
+
+- `.ai/server/aios-server.mjs`:
+  - Bloco `MCP Prompts (ADR-0011)` adicionado antes de `handleRpc`.
+  - Helpers: `listMcpPrompts()`, `buildRouterHint(intent)`, `getMcpPrompt(name, args)`.
+  - Constante `PROMPT_WORKFLOWS = ["init", "sync", "work"]`.
+  - `initialize` declara `capabilities.prompts = {}`.
+  - `handleRpc` aceita `prompts/list` e `prompts/get`.
+
+## Validação
+
+Testado via HTTP em port 47791 (2026-05-16):
+
+| Chamada | Resultado |
+|---|---|
+| `initialize` | `capabilities.prompts: {}`, `serverInfo.version: 1.1.0` ✅ |
+| `prompts/list` | retorna 3 prompts (init, sync, work) com `arguments` ✅ |
+| `prompts/get init` | retorna messages com instrução + state.identity ✅ |
+| `prompts/get work {intent}` | retorna messages com ROUTER hint matched ✅ |
+| `prompts/get unknown` | erro `-32000: Unknown prompt` ✅ |
+| `tools/list` (retrocompat) | 36 tools, sem alteração ✅ |
+
+## Próximas fases (fora desta ADR)
+
+- **Fase 2** — snippet de instrução universal para stubs (`CLAUDE.md`, `GEMINI.md`, `GPT.md`, `AGENTS.md`, `.cursorrules`, `.clinerules`, `.windsurfrules`, `.continue/rules/ai-os.md`, `.trae/rules/project_rules.md`, `.github/copilot-instructions.md`) — cópia controlada via script.
+- **Fase 3** — padronizar nome MCP `ai-os` em todos os 8 configs.
+- **Fase 4** — reescrever `.ai/clients/README.md` linhas 54-85 (tabela "slash não porta" → "slash porta via MCP Prompts onde suportado").

package/ai/specs/ADR/ADR-0012-stealthos-hybrid-architecture.md

@@ -0,0 +1,174 @@
+---
+id: ADR-0012
+slug: stealthos-hybrid-architecture
+status: accepted
+date: 2026-05-16
+deciders: [user, tech-lead]
+related:
+  - ADR-0011 (MCP Prompts cross-IDE)
+  - ADR-0008 (Intent Runtime)
+  - ADR-0010 (Structural Architecture Standards)
+---
+
+# ADR-0012 — StealthOS Hybrid Architecture (daemon global + projeto leve)
+
+## Contexto
+
+O harness hoje despeja **toda a árvore `.ai/`** (~50 arquivos: server, manual, workflows, memory, snapshots, context) dentro do projeto do usuário. Isso polui o repo-alvo, viaja no git, conflita com convenções alheias e dificulta atualização do OS (cada projeto carrega sua própria cópia, divergindo do canônico).
+
+O usuário definiu a visão do produto **StealthOS**: "assistente de desenvolvimento que **não interfere no projeto**". A descrição literal: *"fora dele será o ambiente onde o usuário vai construir os projetos, e o StealthOS não pode interferir no funcionamento do projeto"*.
+
+Considerados 3 modelos:
+- **A — In-project** (estado atual): tudo dentro do projeto. Auto-contido mas invasivo.
+- **B — Daemon global puro**: nada no projeto exceto 1 arquivo. Refator gigante; IDEs perdem capacidade de auto-detectar stubs.
+- **C — Híbrido** (escolhido): daemon global + state fora do projeto + stubs IDE leves dentro (necessários porque IDEs como Claude Code, Cursor, Antigravity só auto-detectam configs na raiz do projeto).
+
+## Decisão
+
+**Adotar o Modelo C — StealthOS Hybrid Architecture**:
+
+### Layout `~/.stealthos/` (instalado uma vez por máquina)
+
+```
+~/.stealthos/
+├── server/                    # aios-server.mjs + dist + node_modules
+├── manual/                    # hub master (capítulos do .manual\ atual)
+├── templates/                 # stubs por IDE (claude-code/, cursor/, ...)
+├── workflows/                 # init.json, sync.json, work.json (canônicos)
+├── projects/
+│   └── <project_hash>/        # state por projeto, fora do dir do projeto
+│       ├── state.json
+│       ├── runtime/
+│       ├── snapshots/
+│       ├── memory/
+│       └── context/
+└── VERSION
+```
+
+### Layout do projeto do usuário (mínimo necessário)
+
+```
+meu-projeto/
+├── .stealthos.yml             # registro do projeto (hash, IDEs ativas, modo)
+├── CLAUDE.md                  # stub IDE (só se Claude Code marcado)
+├── .claude/                   # idem
+├── GEMINI.md                  # só se Antigravity marcado
+├── .gemini/                   # idem
+└── src/                       # código do usuário, intocado
+```
+
+Quem marcou só Claude Code: **3 itens** (`.stealthos.yml`, `CLAUDE.md`, `.claude/`). Quem marcou Cursor: **3 itens**. Quem marcou 5 IDEs: **~9 itens**. Versus os **14 atuais**.
+
+### Project hash
+
+```
+project_hash = sha256(normalize(absolute_project_path)).slice(0, 12)
+```
+
+Determinístico, estável entre sessões, único por path absoluto. Mover o projeto = novo hash (intencional — força revalidação).
+
+### Server resolution
+
+Servidor passa a aceitar 2 modos via `STEALTHOS_MODE` env var ou `.stealthos.yml`:
+
+- **`embedded`** (retrocompat, padrão até v2.0): state em `<project>/.ai/runtime/` — modo atual.
+- **`hybrid`** (novo, padrão a partir de v2.0): state em `${STEALTHOS_HOME}/projects/<hash>/`, onde `STEALTHOS_HOME` default = `~/.stealthos`.
+
+O servidor lê `cwd` no startup, calcula `project_hash`, resolve `STATE_PATH` dinamicamente.
+
+## Mecanismo `.stealthos.yml`
+
+```yaml
+# StealthOS project registry — leve, versionável, ~15 linhas
+version: 1
+project_hash: a3f7c9e2d1b8
+project_name: TripPlanner
+mode: hybrid                 # ou 'embedded'
+ides:
+  - claude-code
+  - antigravity
+stack: node
+created_at: 2026-05-16T18:00:00Z
+stealthos_version: ">=2.0.0"
+```
+
+## Migration path (versões do servidor)
+
+| Versão | Capabilities | State |
+|---|---|---|
+| v1.0 | tools/* | embedded |
+| v1.1 | tools/* + prompts/* (ADR-0011) | embedded |
+| **v1.2 (atual)** | tools/* + prompts/* + `STEALTHOS_MODE` | embedded OU hybrid |
+| **v2.0** (futura) | idem | hybrid default; embedded como flag |
+
+## Consequências
+
+**Positivas:**
+- Projeto-alvo limpo (~3-9 itens vs 14). Alinhado com visão "não interfere".
+- Update do StealthOS = atualizar `~/.stealthos/server/` — atinge todos os projetos.
+- State pesado (snapshots, memory) **não viaja no git** do projeto-alvo.
+- Múltiplos projetos isolados por hash sem cross-contamination.
+- Caminho natural pra modo SaaS futuro: `~/.stealthos/` vira API hospedada.
+
+**Negativas / mitigadas:**
+- **cwd-dependent**: IDE em monorepo pode confundir cwd → hash errado. **Mitigação**: `.stealthos.yml` no projeto serve como ground-truth do hash (server lê primeiro).
+- **Migration**: projetos existentes em modo embedded continuam funcionando (retrocompat). `stealthos migrate <project>` (futuro) move state pra hybrid.
+- **Discoverability do server**: stubs IDE precisam apontar pro `~/.stealthos/server/aios-server.mjs` (path absoluto resolvido por scaffolder).
+
+## Implementação por fases
+
+1. **Esta ADR** — decisão registrada.
+2. **Etapa 2 (scaffolder)** — `packages/create-stealthos/` que:
+   - Pergunta IDEs + stack + novo/existente.
+   - Escreve `.stealthos.yml` (modo `embedded` enquanto v1.2 não saiu).
+   - Copia stubs IDE selecionados (placeholders substituídos por cwd).
+   - Configura MCP em cada IDE (usa caminho do `~/.stealthos/server/` se já instalado, senão usa `.ai/server/` do projeto fallback).
+3. **Etapa 3 (server v1.2)** — sessão separada. Refator:
+   - Introduzir `STEALTHOS_HOME` (default `~/.stealthos`).
+   - `STEALTHOS_MODE=hybrid` resolve state path por hash.
+   - `STATE_PATH`, `WORKFLOWS_DIR`, `RUNTIME_DIR` viram funções resolvidas em runtime.
+4. **Etapa 4 (validação cross-OS)** — Windows + Linux VM + projeto novo + projeto existente.
+5. **Etapa 5 (publish npm)** — `create-stealthos@1.0.0` no npm.
+
+## Validação desta ADR
+
+### Etapa 3 — server v1.2 (concluída 2026-05-16)
+
+Refator do `.ai/server/aios-server.mjs` para multi-tenant. Mudanças:
+
+- Novos imports: `createHash` (crypto), `homedir` (os).
+- Novos constants:
+  - `STEALTHOS_MODE = process.env.STEALTHOS_MODE || "embedded"`
+  - `STEALTHOS_HOME = process.env.STEALTHOS_HOME || ~/.stealthos`
+  - `PROJECT_ROOT` resolve por modo (embedded: `__dirname/../..`; hybrid: `STEALTHOS_PROJECT_DIR || process.cwd()`)
+  - `PROJECT_HASH = sha256(absolute(PROJECT_ROOT)).slice(0, 12)`
+  - `KB_DIR` (knowledge base canônico): `STEALTHOS_HOME` em hybrid, `<project>/.ai` em embedded
+  - `PROJECT_STATE_DIR` (state por projeto): `${STEALTHOS_HOME}/projects/${PROJECT_HASH}` em hybrid, `<project>/.ai` em embedded
+  - `AI_DIR` mantido como alias para `KB_DIR` (retrocompat).
+- Refatorados: `WORKFLOWS_DIR` → KB, `RUNTIME_DIR/STATE_PATH/PAUSED_DIR/ARTIFACTS_INDEX_PATH/RUNTIME_CONTEXT_PATH` → PROJECT_STATE, `BLUEPRINTS_DIR` → KB.
+- Refatoradas referências inline a `AI_DIR`: `memory/`, `snapshots/`, `context/`, `specs/`, `architecture/`, `product/`, `artifacts/`, `.runtime/` → todas para `PROJECT_STATE_DIR`.
+- `safeResolve` refatorado com lista de prefixos `PROJECT_STATE_PREFIXES` (`memory|runtime|snapshots|context|artifacts|specs|architecture|product`) — paths com esses prefixos resolvem em PROJECT_STATE; o resto em KB.
+- `aios_health` agora reporta `mode`, `stealthos_home`, `project_hash`, `kb_dir`, `kb_exists`, `project_state_dir`, `project_state_exists`.
+- Startup banner indica modo.
+- `serverInfo.version: "1.1.0" → "1.2.0"`.
+
+### Testes realizados (HTTP em portas isoladas)
+
+| Cenário | Comando | Resultado |
+|---|---|---|
+| **Embedded** (regressão zero) | `node aios-server.mjs --http --port 47792` no Harness | health.mode=embedded, KB+state ambos em `<Harness>/.ai`, 36 tools, 3 prompts ✓ |
+| Embedded — `aios_read CONTRACT.md` | read KB path | retornado, conteúdo OK ✓ |
+| Embedded — `aios_read memory/project-context.md` | read PROJECT_STATE path | retornado, conteúdo OK ✓ |
+| Embedded — `aios_state_get identity` | leu state.json local | retornou identity real do projeto ✓ |
+| **Hybrid** (projeto fake 1) | `STEALTHOS_MODE=hybrid STEALTHOS_HOME=sthome STEALTHOS_PROJECT_DIR=fake-project` | hash `55442f48c00f`, projects/<hash>/ auto-criado ✓ |
+| Hybrid — `aios_list_workflows` | leu de sthome/workflows/ | retornou `init.json` (versão "hybrid-test") ✓ |
+| Hybrid — `aios_state_set identity.project_name="hybrid-test"` | grava em projects/55442f48c00f/runtime/state.json | gravado ✓ |
+| **Isolamento entre projetos** | Subir 2º server com `STEALTHOS_PROJECT_DIR=fake-project-2` | hash distinto `2b73b6fa31c1`, state.identity.project_name=null (não vê state do 1º projeto) ✓ |
+| Coabitação em sthome | `ls sthome/projects/` | lista `55442f48c00f` e `2b73b6fa31c1` lado a lado ✓ |
+
+Conclusão: refator multi-tenant funcional. Modo embedded sem regressão (Harness continua operando normalmente). Modo hybrid isola state por hash de cwd. Workflows + manifest + ROUTER lidos de KB. State + memory + snapshots + context gravam em PROJECT_STATE.
+
+## Notas
+
+- Nome do produto: **StealthOS** (com L). Confirmado pelo usuário em 2026-05-16.
+- Nome do pacote npm: `create-stealthos` (convenção `create-*` para scaffolders, alinhado com `create-react-app`, `create-vite`).

package/ai/specs/ADR/_TEMPLATE.md

@@ -0,0 +1,60 @@
+---
+id: ADR-NNNN
+slug: <slug-kebab>
+status: proposed  # proposed | accepted | superseded-by-NNNN | deprecated
+date: AAAA-MM-DD
+deciders: [founder, architect, ...]
+related:
+  - PRD-NNNN
+  - SDD-NNNN
+---
+
+# ADR-NNNN — <Decisão em frase curta>
+
+## Contexto
+O que motivou a decisão? Restrições, requisitos, problema. Cite dados, não opinião.
+
+## Decisão
+**Decidimos X.**
+Frase clara, acionável.
+
+## Consequências
+
+### Positivas
+- ...
+
+### Negativas / Trade-offs aceitos
+- ...
+
+### Neutras
+- ...
+
+## Alternativas consideradas
+
+### Alternativa A — <nome>
+- Pros: ...
+- Cons: ...
+- **Descartada** porque: ...
+
+### Alternativa B — <nome>
+- Pros: ...
+- Cons: ...
+- **Descartada** porque: ...
+
+## Critérios de decisão
+| Critério | Peso | Alt-A | Alt-B | Escolhida |
+|---|---|---|---|---|
+| Performance | Alto | Médio | Alto | Alta |
+| Custo | Médio | Baixo | Médio | Baixo |
+| Manutenibilidade | Alto | Médio | Alto | Alto |
+
+## Impacto futuro
+O que precisaríamos mudar se essa decisão se mostrar errada? Quão caro reverter?
+
+## Referências
+- Links, PRs, issues, papers, benchmarks externos.
+
+---
+
+> **Lembrete**: ADR aceito não se edita. Mudança = novo ADR com `supersedes: ADR-NNNN`.
+> Espelho histórico desta decisão também aparece em `.ai/memory/decisions.md` (append-only).