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

package/ai/README.md

@@ -0,0 +1,434 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: on_demand
+tokens: ~2400
+load: never_auto
+audience: humano
+---
+
+# AI Operating System — README
+
+> Cérebro persistente para LLMs, desacoplado do modelo. Este README é para humanos. O agente NÃO carrega este arquivo — ele lê `INDEX.md`.
+
+---
+
+## 1. O que é
+
+O **AI OS** é uma estrutura de arquivos em `.ai/` que dá a qualquer LLM (Claude, Gemini, GPT, etc.) três coisas que ela não tem por padrão:
+
+1. **Memória persistente entre sessões** — decisões, tarefas concluídas, erros já resolvidos.
+2. **Regras de comportamento estáveis** — proibições, obrigações, fluxo de execução.
+3. **Roteamento determinístico de contexto** — para cada tarefa, o agente carrega só os arquivos relevantes (não o repositório inteiro).
+
+Resultado: respostas mais consistentes, menos alucinação, menos retrabalho, custo de tokens controlado.
+
+> **Princípio**: a inteligência está na estrutura, não no modelo. O modelo executa; o OS pensa.
+
+---
+
+## 2. Para quem é
+
+- Quem usa LLM para programar dia a dia e cansou de repetir contexto a cada sessão.
+- Quem trabalha em projeto longo onde decisões antigas importam.
+- Quem quer trocar de modelo (Claude → Gemini → GPT) sem perder histórico.
+- Quem precisa que o agente respeite restrições (segurança, compliance, convenções).
+
+Funciona com:
+- **Claude Code** (CLI) — enforcement total via hooks.
+- **Claude via API/Chat** — enforcement via system prompt + self-audit.
+- **Gemini, GPT, outros** — mesmo princípio, entry points próprios (`GEMINI.md`, `GPT.md`).
+- **IDEs com MCP** (VSCode, Cursor, Windsurf, TRAE AI, Antigravity) — via daemon `aios-server.mjs`.
+
+---
+
+## 3. Como funciona em 30 segundos
+
+```
+Usuário pergunta → Agente lê CLAUDE.md (ou GEMINI.md/GPT.md)
+                 → CLAUDE.md aponta para .ai/INDEX.md
+                 → .ai/INDEX.md manda carregar CORE (6 arquivos, ~3k tokens)
+                 → .ai/ROUTER.md decide o que mais carregar pelas palavras-chave da pergunta
+                 → Agente classifica: trivial | simple | complex
+                 → Executa seguindo .ai/rules/execution-flow.md
+                 → Termina com bloco [OS Audit] declarando o que tocou
+                 → Atualiza .ai/memory/ se aplicável
+```
+
+A primeira linha de toda resposta do agente é:
+
+```
+OS:loaded(INDEX,CONTRACT,ROUTER,rules/dont,rules/behavior,context tier:core)
+Task class: simple
+```
+
+Se essa linha não aparecer, o agente violou o contrato. Você pode pedir `/audit` (Claude Code) ou simplesmente "refaça seguindo o contrato".
+
+---
+
+## 4. Estrutura do `.ai/`
+
+```
+.ai/
+├── INDEX.md              # ponto de entrada — sempre carregado primeiro
+├── CONTRACT.md           # protocolo inquebrável (tag OS:loaded, audit, classes)
+├── ROUTER.md             # query → arquivos a carregar (determinístico)
+├── README.md             # este arquivo (humano)
+├── runtime.md            # daemon MCP + slash commands
+├── manifest.json         # fonte da verdade estrutural
+│
+├── rules/
+│   ├── dont.md           # proibições absolutas (CORE) — vence tudo, até o usuário
+│   ├── behavior.md       # postura e tom (CORE)
+│   ├── do.md             # obrigações em tarefas simple/complex
+│   └── execution-flow.md # ciclo de 11 etapas
+│
+├── bootstrap/
+│   ├── dispatcher.md         # roteia novo vs existente
+│   ├── new-project.md        # diálogo para projeto novo
+│   ├── existing-project.md   # diálogo para projeto existente
+│   └── discovery-questions.md# banco de perguntas
+│
+├── memory/                   # cérebro vivo do projeto
+│   ├── project-context.md    # CORE — fatos confirmados sobre o projeto
+│   ├── completed-tasks.md    # append-only — o que foi feito
+│   ├── pending-tasks.md      # backlog
+│   ├── decisions.md          # ADRs — append-only
+│   ├── errors-and-solutions.md
+│   ├── known-issues.md
+│   ├── _summary.md           # resumo rotativo (últimos 90 dias)
+│   └── archive/              # entradas antigas roladas
+│
+├── operating-system/         # padrões específicos do projeto
+│   ├── architecture.md
+│   ├── coding-standards.md
+│   ├── folder-structure.md
+│   ├── workflow.md
+│   ├── quality-control.md
+│   ├── security-rules.md
+│   └── performance-rules.md
+│
+├── skills/                   # conhecimento por domínio (sob demanda)
+│   ├── backend-engineering.md
+│   ├── frontend-engineering.md
+│   ├── architecture-design.md
+│   ├── performance.md
+│   ├── security.md
+│   ├── testing.md
+│   ├── database-design.md
+│   └── scalability.md
+│
+├── tools/                    # como o agente usa ferramentas externas
+│   ├── debugging.md
+│   ├── dependency-analysis.md
+│   ├── internet-research.md
+│   └── mcp-discovery.md
+│
+├── evolution/                # aprendizado controlado do OS
+│   ├── learnings.md          # promovido após ≥3 ocorrências
+│   ├── improvements.md       # propostas de mudança no OS
+│   ├── patterns-discovered.md
+│   └── agent-evolution.md    # changelog do próprio OS
+│
+├── evals/
+│   └── protocol-tests.md     # casos sintéticos para validar conformidade
+│
+├── hooks/                    # scripts que o Claude Code invoca
+│   ├── inject-os-reminder.{ps1,sh}
+│   ├── guard-edit.{ps1,sh}
+│   └── enforce-audit.{ps1,sh}
+│
+├── scripts/
+│   ├── init-ai-os.{ps1,sh}   # aplica o OS num projeto
+│   ├── detect-stack.{ps1,sh} # inspeciona stack
+│   ├── lint-os.{ps1,sh}      # valida integridade
+│   └── start-os.{ps1,sh}     # inicia daemon
+│
+└── server/
+    ├── aios-server.mjs       # daemon MCP (Node ≥ 18, zero deps)
+    └── package.json
+```
+
+---
+
+## 5. Camadas de carregamento (Token Economy)
+
+| Tier | Conteúdo | Quando carrega | Custo aprox. |
+|---|---|---|---|
+| **CORE** | INDEX, CONTRACT, ROUTER, rules/dont, rules/behavior, memory/project-context | **sempre** | ~3k tokens |
+| **CONDITIONAL** | Skills/tools/memory por trigger do ROUTER | sob match | varia |
+| **ON-DEMAND** | Resto | só se explicitamente citado | varia |
+
+Limite máximo de CORE: **3000 tokens**. Não carregar tier inteiro "por garantia".
+
+---
+
+## 6. Hierarquia de autoridade
+
+```
+rules/dont.md  >  CONTRACT.md  >  rules/do.md  >  operating-system/*  >  skills/*  >  evolution/*
+```
+
+- Instrução direta do usuário **vence** o OS, **exceto** `dont.md` (que é inviolável).
+- Quando o agente desobedece uma regra do OS por ordem sua, ele declara o desvio na resposta.
+
+---
+
+## 7. Classes de tarefa
+
+O agente classifica toda tarefa antes de executar:
+
+| Classe | Critério | Ciclo |
+|---|---|---|
+| **trivial** | pergunta 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, contrato público, nova dependência | CORE + CONDITIONAL + skills → plano → confirmação → execução → audit + ADR |
+
+---
+
+## 8. Como instalar em um projeto
+
+### 8.1. Pré-requisitos
+
+- Node ≥ 18 (apenas se for usar o daemon MCP — opcional).
+- Windows com PowerShell 5.1+ OU macOS/Linux com bash.
+
+### 8.2. Projeto novo
+
+```powershell
+# Windows
+powershell -ExecutionPolicy Bypass -File .\.ai\scripts\init-ai-os.ps1
+```
+
+```bash
+# macOS / Linux
+chmod +x .ai/scripts/*.sh
+./.ai/scripts/init-ai-os.sh
+```
+
+O script copia `.ai/`, `CLAUDE.md`, `GEMINI.md`, `GPT.md` para o projeto-alvo e detecta a stack.
+
+### 8.3. Projeto existente
+
+Mesmo comando. Na primeira mensagem ao agente, ele vai disparar o **bootstrap dialógico** (`.ai/bootstrap/existing-project.md`):
+
+1. Te pergunta o que o projeto faz.
+2. Inspeciona `package.json`, `pyproject.toml`, etc.
+3. Preenche `memory/project-context.md` com fatos confirmados.
+4. Sugere 1-3 melhorias se houver lacunas.
+
+### 8.4. Validar integridade
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\.ai\scripts\lint-os.ps1
+```
+
+```bash
+./.ai/scripts/lint-os.sh
+```
+
+Saída esperada: `Errors: 0  Warnings: 0`.
+
+---
+
+## 9. Daemon MCP (opcional, mas recomendado)
+
+O daemon expõe o OS como ferramentas MCP (`aios_*`), evitando 6 reads no início de cada sessão.
+
+### Iniciar
+
+```powershell
+# Windows
+.\.ai\scripts\start-os.ps1            # stdio (foreground)
+.\.ai\scripts\start-os.ps1 -Http      # HTTP background, porta 47781
+.\.ai\scripts\start-os.ps1 -Status
+.\.ai\scripts\start-os.ps1 -Stop
+```
+
+```bash
+# macOS / Linux
+./.ai/scripts/start-os.sh
+./.ai/scripts/start-os.sh --http
+./.ai/scripts/start-os.sh --status
+./.ai/scripts/start-os.sh --stop
+```
+
+### Conectar pelo cliente
+
+- **Claude Code**: já configurado em `.claude/settings.json` — apenas reinicie.
+- **VSCode (Cline / Continue)**:
+  ```json
+  "cline.mcpServers": {
+    "ai-os": {
+      "command": "node",
+      "args": ["${workspaceFolder}/.ai/server/aios-server.mjs"]
+    }
+  }
+  ```
+- **Cursor**: `Preferences → MCP → Add Server` (command: `node`, args: caminho para `aios-server.mjs`).
+- **Windsurf / TRAE AI / Antigravity**: mesma config MCP genérica via stdio.
+
+### Tools expostas
+
+| Tool | Função |
+|---|---|
+| `aios_get_core_bundle` | CORE em 1 call |
+| `aios_route_query` | Query → lista de arquivos |
+| `aios_classify_task` | Query → trivial/simple/complex |
+| `aios_read` / `aios_list` | Leitura no `.ai/` |
+| `aios_search_memory` | Grep em `memory/` |
+| `aios_get_summary` | Resumo rotativo |
+| `aios_lint` | Roda lint |
+| `aios_detect_stack` | Detecta stack |
+| `aios_validate_audit` | Valida formato `[OS Audit]` |
+| `aios_health` | Status do daemon |
+
+Detalhes: [runtime.md](./runtime.md).
+
+---
+
+## 10. Slash commands (Claude Code)
+
+Disponíveis automaticamente em projetos com `.claude/commands/`:
+
+| Comando | Função |
+|---|---|
+| `/load-os` | Recarrega CORE + rotas para o query atual |
+| `/audit` | Auto-auditoria do turno corrente vs CONTRACT |
+| `/os-status` | Versão, integridade, daemon, maturidade |
+| `/promote-learning LRN-NNN` | Promove learning validada |
+| `/compact-memory [days]` | Rola memória antiga para `archive/` |
+
+Em outros clientes, peça por extenso ("rode um audit do turno atual").
+
+---
+
+## 11. Hooks (Claude Code)
+
+Configurados em `.claude/settings.json`. Executam automaticamente:
+
+| Evento | Hook | O que faz |
+|---|---|---|
+| `UserPromptSubmit` | `inject-os-reminder` | Injeta lembrete do protocolo a cada mensagem |
+| `PreToolUse (Edit\|Write)` | `guard-edit` | Bloqueia edição em arquivos protegidos do OS |
+| `Stop` | `enforce-audit` | Exige bloco `[OS Audit]` se houve edições |
+
+Limitação conhecida: o guard cobre Edit/Write, não Bash (`Set-Content`, redirects). Veja `evolution/improvements.md` → IMP-001.
+
+---
+
+## 12. Memória — como o agente usa
+
+### Regras de manutenção
+
+- `memory/decisions.md`, `memory/completed-tasks.md`, `evolution/learnings.md` → **append-only**. Nunca apagar entradas antigas.
+- `memory/project-context.md` → só **fatos confirmados**. Hipótese marca-se com `?`.
+- Entrada em `learnings.md` exige **≥3 ocorrências** OU validação humana explícita.
+- Rotação: `_summary.md` consolida os últimos 90 dias; mais antigo vai para `archive/`.
+
+### Ciclo de vida de um aprendizado
+
+```
+agente observa padrão → improvements.md (IMP-NNN)
+→ usuário aprova → learnings.md (LRN-NNN)
+→ ≥3 ocorrências ou validação → /promote-learning move para operating-system/*
+```
+
+---
+
+## 13. Quando o agente PARA e pergunta
+
+- Intenção ambígua (≥2 leituras plausíveis).
+- Vai instalar dependência nova.
+- Vai modificar `.env`, CI/CD, contratos públicos.
+- Decisão arquitetural sem ADR prévio.
+- Operação destrutiva (`rm -rf`, `git reset --hard`, `force push`).
+- Custo estimado > 10k tokens.
+
+Ele oferece ≤3 opções por pergunta.
+
+---
+
+## 14. Bloco [OS Audit]
+
+Toda resposta de tarefa simple/complex termina com:
+
+```
+[OS Audit]
+- Files touched: <lista de paths>
+- Memory updated: <quais arquivos de memory/> ou n/a
+- Validations: <lint/types/tests rodados ou motivo>
+- Decisions: <ADR-NNNN se houve, ou n/a>
+- Open items: <pendências honestas ou none>
+```
+
+Tarefas triviais declaram `[OS Audit] skipped: trivial`.
+
+Ausência do bloco = violação de protocolo. Peça `/audit` ou refazer.
+
+---
+
+## 15. Validação rápida (checklist)
+
+Antes de considerar um projeto pronto com o OS instalado:
+
+- [ ] `.ai/` está presente e completo (rodar `lint-os` → 0 errors).
+- [ ] `CLAUDE.md`, `GEMINI.md`, `GPT.md` na raiz do projeto.
+- [ ] `.claude/settings.json` configurado (se Claude Code).
+- [ ] `memory/project-context.md` preenchido com a stack real do projeto.
+- [ ] Primeira mensagem ao agente: ele emite `OS:loaded(...)` + classe.
+- [ ] Daemon opcional rodando (se quiser ganho de tokens via MCP).
+
+---
+
+## 16. Customização por projeto
+
+Após instalado, o `.ai/` é seu — pode (e deve) ser adaptado:
+
+- **`operating-system/*`** é o lugar natural para padrões específicos (arquitetura, código, performance).
+- **`skills/*`** pode receber arquivo novo para domínio específico (ex: `ml-pipelines.md`).
+- **`ROUTER.md`** pode ganhar rotas novas — basta seguir o formato existente.
+
+**NUNCA** edite manualmente:
+- `CONTRACT.md` — exige ADR.
+- `rules/dont.md`, `rules/do.md` — exige revisão humana registrada.
+- `manifest.json` — gerado/curado.
+
+Mudanças que exigem ADR ficam listadas em `manifest.json → evolution_gates.require_human_approval_for`.
+
+---
+
+## 17. Troubleshooting
+
+| Sintoma | Causa provável | Ação |
+|---|---|---|
+| Agente não emite `OS:loaded` | system prompt não carregou CLAUDE.md | reiniciar IDE, conferir `.claude/settings.json` |
+| `lint-os` reclama de arquivo ausente | OS incompleto | rodar `init-ai-os` de novo |
+| Daemon não conecta | porta ocupada | usa `--http` com auto-fallback (47782, 47783, ...) |
+| Hooks não disparam (Claude Code) | path errado no settings.json | conferir `.claude/settings.json → hooks.*.command` |
+| Memória inchada | rotação não executou | `/compact-memory 90` |
+| Agente cita arquivo que não existe | alucinação | pedir `/audit`; conferir `rules/dont.md` regra 1 |
+
+---
+
+## 18. Filosofia
+
+- **Memória reduz alucinação.** Decisões antigas estão no disco, não na cabeça do modelo.
+- **Regras reduzem deriva.** O CONTRACT é o mesmo entre sessões e modelos.
+- **Evolução controlada impede contaminação.** Nada vira regra a partir de um caso isolado.
+- **Densidade > volume.** Contexto curado pequeno vence dump bruto.
+- **Diff > arquivo inteiro. Referência > cópia.**
+
+---
+
+## 19. Versão e changelog
+
+Veja `evolution/agent-evolution.md` para o histórico completo do OS.
+
+Versão atual: **v3.1.0** (ver `manifest.json`).
+
+---
+
+## 20. Licença e uso
+
+O OS é um conjunto de arquivos de texto. Use, fork, adapte. Sem garantias. Reporte problemas via `evolution/improvements.md` no seu próprio projeto.