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

package/ai/CONTRACT.md

@@ -0,0 +1,110 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: core
+tokens: ~600
+load: always
+---
+
+# CONTRACT — Protocolo Inquebrável
+
+> Este é o contrato entre **qualquer LLM** e o AI Operating System.
+> Violar este contrato é falha de protocolo. Não é "estilo" — é regra de funcionamento.
+
+---
+
+## TL;DR
+
+1. **Antes de agir**: emitir tag `OS:loaded(<arquivos>)` na primeira linha da resposta.
+2. **Antes de editar código**: ter consultado `memory/project-context.md`.
+3. **Antes de declarar concluído**: emitir bloco `[OS Audit]` com files-touched, memory-updated, validations.
+4. **Classificar tarefa** (trivial/simple/complex) e seguir o ciclo correspondente.
+5. **Nunca pular** `rules/dont.md`. Nunca inventar resultados. Nunca fabricar validação.
+
+---
+
+## Tag de Carregamento (obrigatória)
+
+A **primeira linha** de qualquer resposta a uma nova tarefa do usuário DEVE ser:
+
+```
+OS:loaded(INDEX,rules,context[,routes:<lista>][,tier:<core|conditional|full>])
+```
+
+Exemplos:
+- Resposta a "qual a estrutura do projeto?" → `OS:loaded(INDEX,rules,context tier:core)`
+- Resposta a "tem um bug em X" → `OS:loaded(INDEX,rules,context,debugging,errors-and-solutions tier:conditional)`
+
+Ausência da tag = falha de protocolo. O usuário pode (e deve) pedir refazer.
+
+---
+
+## Classificação de Tarefa
+
+Antes de executar, classificar:
+
+| Nível | Critério | Ciclo |
+|---|---|---|
+| **trivial** | Resposta factual, 0-1 leituras, 0 edições | CORE → resposta direta |
+| **simple** | 1-3 arquivos editados, sem decisão arquitetural | CORE + CONDITIONAL → execução → audit |
+| **complex** | ≥4 arquivos, decisão arquitetural, mudança de contrato | CORE + CONDITIONAL + skills → plano → confirmação → execução → audit + ADR |
+
+A classificação aparece na resposta logo após `OS:loaded`:
+```
+OS:loaded(...)
+Task class: simple
+```
+
+---
+
+## Self-Audit (obrigatório em simple/complex)
+
+Toda resposta que tocou código ou estrutura termina com:
+
+```
+[OS Audit]
+- Files touched: <lista de paths>
+- Memory updated: <quais arquivos de memory/ foram atualizados ou "n/a">
+- Validations: <lint/types/tests rodados ou motivo de não rodar>
+- Decisions: <ADR-NNNN se houve, ou "n/a">
+- Open items: <pendências honestas ou "none">
+```
+
+Tarefa trivial pode omitir, mas DEVE declarar `[OS Audit] skipped: trivial`.
+
+---
+
+## Proibições do Contrato
+
+1. **Inventar arquivos** que não foram lidos. Citar `caminho:linha` exige ter lido.
+2. **Inventar resultados de testes/comandos**. Se não rodou, dizer "não executado".
+3. **Pular `OS:loaded`** quando a tarefa é não-trivial.
+4. **Pular `[OS Audit]`** em simple/complex.
+5. **Editar `.ai/rules/*` ou `.ai/operating-system/*`** sem ADR explícito do usuário.
+6. **Sobrescrever entradas históricas** em `memory/decisions.md`, `memory/completed-tasks.md`, `evolution/learnings.md` (append-only).
+
+---
+
+## Resolução de Conflito
+
+Conflito entre `.ai/*` e instrução direta do usuário:
+- **`rules/dont.md`** sempre vence. Avisar e parar.
+- **Demais regras** cedem à instrução do usuário, **mas o agente declara o desvio** na resposta:
+  ```
+  Note: overriding .ai/operating-system/coding-standards.md per user instruction.
+  ```
+
+Conflito entre dois arquivos do `.ai/`:
+- Seguir a hierarquia em `INDEX.md`.
+- Registrar inconsistência em `evolution/improvements.md` como `IMP-NNN`.
+
+---
+
+## Falha de Protocolo
+
+Se o agente perceber que violou o contrato:
+1. Parar.
+2. Dizer "Protocol violation: <qual>".
+3. Recuperar (re-emitir tag, consultar arquivos pulados, refazer).
+
+O usuário pode pedir `/audit` para forçar revisão.

package/ai/INDEX.md

@@ -0,0 +1,203 @@
+---
+version: 4.1.0
+updated: 2026-05-15
+tier: core
+tokens: ~950
+load: always
+---
+
+# AI Operating System — Índice (v4.1.0 — AI-DOS + Runtime v0.1)
+
+> **Ponto de entrada obrigatório.** Qualquer agente DEVE ler este arquivo primeiro, em seguida `CONTRACT.md`, `ROUTER.md` e o resto do CORE.
+
+---
+
+## TL;DR
+
+1. Leia **CORE** (este arquivo + CONTRACT + ROUTER + rules/dont + rules/behavior + memory/project-context).
+2. Use **ROUTER.md** para decidir o que carregar além do CORE.
+3. Cumpra o **CONTRACT.md** (tag `OS:loaded`, classificação de tarefa, `[OS Audit]`).
+4. Para projeto novo/existente sem maturidade → carregar `bootstrap/dispatcher.md`.
+
+---
+
+## Mapa de Diretórios
+
+### Núcleo (sempre)
+- [`CONTRACT.md`](./CONTRACT.md) — protocolo inquebrável
+- [`ROUTER.md`](./ROUTER.md) — mapeamento tarefa → arquivos
+- [`manifest.json`](./manifest.json) — fonte da verdade estrutural
+- [`runtime.md`](./runtime.md) — daemon MCP + slash commands (cross-platform)
+- [`core/pipeline/execution-engine.md`](./core/pipeline/execution-engine.md) — pipeline IDEIA → APRENDIZADO com 10 gates
+
+### Runtime v0.1 (executável) — `.ai/server/` (v4.1.0+)
+- [`server/README.md`](./server/README.md) — arquitetura interna + build instructions
+- [`server/aios-server.mjs`](./server/aios-server.mjs) — MCP daemon (17 tools: 12 base + 5 v0.1)
+- `server/src/analyzer/` — **Project State Engine** (stack detect + ts-morph AST + grafo + smells) → gera `context/project-state.{json,md}`
+- `server/src/packager/` — **Context Packager** (a joia: comprime projeto em representação semântica) → gera `context/packages/<slug>.{md,json}`
+- `server/src/snapshot/` — **Snapshot System** (state + SHA-256 hashes + memory snapshot) → `snapshots/<id>/`
+- Slash commands: `/analyze`, `/context --for "<intent>"`, `/snapshot <label>`
+- Decisão: [`specs/ADR/ADR-0002-typescript-runtime.md`](./specs/ADR/ADR-0002-typescript-runtime.md)
+- Setup: `cd .ai/server && npm install && npm run build`
+
+### Governance → [`./governance/`](./governance/) (v4.0.0+)
+- [engineering-principles.md](./governance/engineering-principles.md) — 10 princípios inegociáveis
+- [definition-of-ready.md](./governance/definition-of-ready.md) — DoR
+- [definition-of-done.md](./governance/definition-of-done.md) — DoD
+- [quality-gates.md](./governance/quality-gates.md) — G1..G10
+- [security-policies.md](./governance/security-policies.md) — P-SEC-1..7
+- [architecture-principles.md](./governance/architecture-principles.md) — A1..A10
+- (coding-standards: vive em `operating-system/coding-standards.md`)
+
+### Agents → [`./agents/`](./agents/) (v4.0.0+)
+- [founder.md](./agents/founder.md) — direção estratégica (humano)
+- [product-manager.md](./agents/product-manager.md) — PRD, BRD
+- [architect.md](./agents/architect.md) — SDD, ADRs, C4
+- [tech-lead.md](./agents/tech-lead.md) — task breakdown
+- [backend-engineer.md](./agents/backend-engineer.md)
+- [frontend-engineer.md](./agents/frontend-engineer.md)
+- [qa-engineer.md](./agents/qa-engineer.md)
+- [security-engineer.md](./agents/security-engineer.md)
+- [sre-engineer.md](./agents/sre-engineer.md)
+- [reviewer.md](./agents/reviewer.md)
+- [researcher.md](./agents/researcher.md)
+
+### Specs → [`./specs/`](./specs/) (v4.0.0+)
+- `PRD/`, `SDD/`, `ADR/`, `RFC/`, `BRD/`, `RUNBOOKS/`, `TASKS/` — cada um com `_TEMPLATE.md`
+
+### Context Engine → [`./context/`](./context/) (v4.0.0+)
+- [project-state.md](./context/project-state.md) — foto agora (CORE)
+- [business-context.md](./context/business-context.md)
+- [technical-context.md](./context/technical-context.md)
+- [architecture-state.md](./context/architecture-state.md)
+- [active-goals.md](./context/active-goals.md)
+- [constraints.md](./context/constraints.md)
+- [assumptions.md](./context/assumptions.md)
+- [glossary.md](./context/glossary.md)
+- [roadmap.md](./context/roadmap.md)
+- [technical-debt.md](./context/technical-debt.md)
+
+### Product → [`./product/`](./product/) (v4.0.0+)
+- [vision.md](./product/vision.md), [personas.md](./product/personas.md), [business-rules.md](./product/business-rules.md), [user-journeys.md](./product/user-journeys.md)
+
+### Architecture → [`./architecture/`](./architecture/) (v4.0.0+)
+- [system-context.md](./architecture/system-context.md) (C4 L1), [containers.md](./architecture/containers.md) (C4 L2), [components.md](./architecture/components.md), [sequence-diagrams.md](./architecture/sequence-diagrams.md), [event-flows.md](./architecture/event-flows.md), [threat-modeling.md](./architecture/threat-modeling.md), `ADR/`, `diagrams/`
+
+### Engineering → [`./engineering/`](./engineering/) (v4.0.0+)
+- `backend/`, `frontend/`, `database/`, `testing/`, `performance/`, `observability/` — guidelines por área
+- [observability/incident-response.md](./engineering/observability/incident-response.md)
+
+### Execution → [`./execution/`](./execution/) (v4.0.0+)
+- [backlog.md](./execution/backlog.md), [sprint.md](./execution/sprint.md), [roadmap.md](./execution/roadmap.md), [milestones.md](./execution/milestones.md)
+
+### Rules → [`./rules/`](./rules/)
+- [behavior.md](./rules/behavior.md) — postura, tom (CORE)
+- [dont.md](./rules/dont.md) — proibições absolutas (CORE)
+- [do.md](./rules/do.md) — obrigações
+- [execution-flow.md](./rules/execution-flow.md) — ciclo com classificação trivial/simple/complex
+
+### Bootstrap → [`./bootstrap/`](./bootstrap/)
+- [dispatcher.md](./bootstrap/dispatcher.md) — novo vs existente
+- [new-project.md](./bootstrap/new-project.md) — diálogo para projeto novo
+- [existing-project.md](./bootstrap/existing-project.md) — análise + diálogo para projeto existente
+- [discovery-questions.md](./bootstrap/discovery-questions.md) — banco de perguntas
+- [tech-mapping.md](./bootstrap/tech-mapping.md) — protocolo de organização por especificação técnica (obrigatório em ambos os fluxos)
+
+### Tools → [`./tools/`](./tools/)
+- [internet-research.md](./tools/internet-research.md)
+- [mcp-discovery.md](./tools/mcp-discovery.md)
+- [dependency-analysis.md](./tools/dependency-analysis.md)
+- [debugging.md](./tools/debugging.md)
+
+### Skills → [`./skills/`](./skills/)
+- [backend-engineering.md](./skills/backend-engineering.md)
+- [frontend-engineering.md](./skills/frontend-engineering.md)
+- [architecture-design.md](./skills/architecture-design.md)
+- [performance.md](./skills/performance.md)
+- [security.md](./skills/security.md)
+- [testing.md](./skills/testing.md)
+- [database-design.md](./skills/database-design.md)
+- [scalability.md](./skills/scalability.md)
+
+### Memory → [`./memory/`](./memory/)
+- [project-context.md](./memory/project-context.md) — CORE
+- [completed-tasks.md](./memory/completed-tasks.md) — append-only
+- [pending-tasks.md](./memory/pending-tasks.md)
+- [errors-and-solutions.md](./memory/errors-and-solutions.md) — append-only
+- [decisions.md](./memory/decisions.md) — ADRs, append-only
+- [known-issues.md](./memory/known-issues.md)
+- [_summary.md](./memory/_summary.md) — resumo rotativo dos últimos 90 dias
+- [archive/](./memory/archive/) — entradas antigas roladas
+
+### Operating System → [`./operating-system/`](./operating-system/)
+- [architecture.md](./operating-system/architecture.md)
+- [coding-standards.md](./operating-system/coding-standards.md)
+- [folder-structure.md](./operating-system/folder-structure.md)
+- [workflow.md](./operating-system/workflow.md)
+- [quality-control.md](./operating-system/quality-control.md)
+- [security-rules.md](./operating-system/security-rules.md)
+- [performance-rules.md](./operating-system/performance-rules.md)
+
+### Evolution → [`./evolution/`](./evolution/)
+- [learnings.md](./evolution/learnings.md) — promoção exige ≥3 ocorrências
+- [improvements.md](./evolution/improvements.md) — propostas pendentes
+- [patterns-discovered.md](./evolution/patterns-discovered.md)
+- [agent-evolution.md](./evolution/agent-evolution.md) — changelog do OS
+
+---
+
+## Camadas de Carregamento (Token Economy)
+
+| Tier | Conteúdo | Quando |
+|---|---|---|
+| **CORE** | INDEX + CONTRACT + ROUTER + rules/dont + rules/behavior + memory/project-context | sempre |
+| **CONDITIONAL** | Skills/tools/memory por match no ROUTER | sob trigger |
+| **ON-DEMAND** | Resto | só se citado |
+
+**Não exceder ~3k tokens em CORE.** Não carregar tier completo "por garantia" — usar o ROUTER.
+
+---
+
+## Fluxo Operacional (resumido)
+
+```
+1. Carregar CORE
+2. Classificar tarefa: trivial | simple | complex
+3. Trivial → responder direto (com OS:loaded)
+4. Simple → CORE + CONDITIONAL → executar → [OS Audit]
+5. Complex → CORE + CONDITIONAL + skills → plano → confirmar → executar → [OS Audit] + ADR
+6. Atualizar memory (sempre que aplicável)
+7. Atualizar evolution (apenas se padrão confirmado)
+```
+
+Detalhes: [`rules/execution-flow.md`](./rules/execution-flow.md). Protocolo: [`CONTRACT.md`](./CONTRACT.md).
+
+---
+
+## Hierarquia de Autoridade
+
+1. `rules/dont.md` (proibições absolutas)
+2. `CONTRACT.md`
+3. `rules/do.md`
+4. `operating-system/*`
+5. `skills/*`
+6. `evolution/*` (sugestões validadas)
+
+Instrução do usuário > regras do OS (exceto `dont.md`). Desvios DEVEM ser declarados na resposta.
+
+---
+
+## Maturidade do Projeto
+
+| Estado | Sinais | Modo |
+|---|---|---|
+| Imaturo | `project-context.md` vazio, 0 ADRs | Bootstrap dialógico |
+| Em formação | Stack conhecida, <3 ADRs | Confirmar mais; menos autonomia |
+| Maduro | ≥3 ADRs, arquitetura documentada | Autonomia razoável |
+
+---
+
+## Filosofia
+
+> A inteligência está na estrutura, não no modelo. O modelo executa; o OS pensa.
+> Memória reduz alucinação. Regras reduzem deriva. Evolução controlada impede contaminação.