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

package/ai/specs/SDD/_TEMPLATE.md

@@ -0,0 +1,104 @@
+---
+id: SDD-NNNN
+slug: <slug-kebab>
+status: draft  # draft | review | approved | deprecated | superseded-by-NNNN
+owner: architect
+created: AAAA-MM-DD
+updated: AAAA-MM-DD
+supersedes: null
+related:
+  - PRD-NNNN
+  - ADR-NNNN, ADR-NNNN+1
+  - RFC-NNNN (se mudança em decisão prévia)
+---
+
+# SDD-NNNN — <Título técnico>
+
+## 1. Resumo executivo
+3-5 frases: o que será construído, principais escolhas técnicas, riscos top-3.
+
+## 2. Contexto
+Resumo do PRD-NNNN. Restrições adicionais de `context/constraints.md`.
+
+## 3. Visão de containers (C4 Level 2)
+
+```
+[diagrama ASCII simples mostrando containers + tecnologia + interações]
+```
+
+## 4. Componentes (C4 Level 3 — opcional, só se complexidade justifica)
+
+| Componente | Responsabilidade | Tecnologia | Localização |
+|---|---|---|---|
+| ... | ... | ... | ... |
+
+## 5. Contratos
+
+### 5.1 APIs HTTP
+```
+POST /api/v1/foo
+Headers: Authorization: Bearer <jwt>
+Body: { ... } (zod schema)
+Response 200: { ... }
+Response 4xx: { error, code, details }
+```
+
+### 5.2 Eventos / Filas
+| Evento | Payload | Producer | Consumer | Retry |
+|---|---|---|---|---|
+| ... | ... | ... | ... | ... |
+
+### 5.3 Schema DB
+```sql
+-- migration NNN
+CREATE TABLE ...;
+CREATE INDEX ...;
+```
+
+## 6. Decisões técnicas (ADRs vinculadas)
+- **ADR-NNNN**: <decisão crítica X> — escolhemos Y, descartamos Z.
+- **ADR-NNNN+1**: ...
+
+## 7. Resiliência
+| Chamada cross-system | Timeout | Retry | Circuit breaker | Fallback |
+|---|---|---|---|---|
+| ... | ... | ... | ... | ... |
+
+## 8. Segurança (threat model leve — STRIDE)
+- **Spoofing**: <vetor> → <mitigação>
+- **Tampering**: ...
+- **Repudiation**: ...
+- **Information disclosure**: ...
+- **Denial of service**: ...
+- **Elevation of privilege**: ...
+
+## 9. Escalabilidade
+- **Hot path**: <qual operação tem mais tráfego>
+- **Bottleneck previsto**: <DB? CPU? rede?>
+- **Estratégia**: <cache, índice, partição, sharding, read replica, queue>
+- **Quando reavaliar**: <métrica + threshold>
+
+## 10. Observabilidade
+- **Logs**: prefixo `[<MODULE>]`, campos estruturados (request_id, user_id, latency_ms, status)
+- **Métricas**: <lista de métricas custom>
+- **Traces**: <span por hop>
+- **Dashboards**: <link>
+- **Alertas**: <métrica + threshold + runbook>
+
+## 11. Riscos
+| Risco | Impacto | Probabilidade | Mitigação |
+|---|---|---|---|
+| ... | A/M/B | A/M/B | ... |
+
+## 12. Trade-offs aceitos
+- Aceitamos <X negativo> para ganhar <Y positivo> porque <razão>.
+
+## 13. Plano de implementação (high-level — `tech-lead` detalha)
+1. Fase 1: <entregável A>
+2. Fase 2: <entregável B>
+3. Fase 3: ...
+
+## 14. Aprovação
+- [ ] Architect concluiu
+- [ ] Founder aprovou (G3)
+- [ ] Pronto para entregar ao `tech-lead` (G4)

package/ai/specs/TASKS/_TEMPLATE.md

@@ -0,0 +1,52 @@
+---
+id: TASK-NNNN
+slug: <slug-kebab>
+status: ready  # ready | in-progress | review | done | blocked | cancelled
+owner: backend-engineer | frontend-engineer | qa-engineer | ...
+size: S | M | L
+priority: P0 | P1 | P2 | P3
+created: AAAA-MM-DD
+related:
+  - SDD-NNNN §X
+  - PRD-NNNN
+  - depends-on: TASK-NNNN
+---
+
+# TASK-NNNN — <Título acionável>
+
+## Origem
+SDD-NNNN §X.Y / bug #XYZ / débito técnico em `context/technical-debt.md`
+
+## Critério de aceite (Gherkin)
+- **Dado** <contexto>
+- **Quando** <ação>
+- **Então** <resultado verificável>
+
+## Arquivos a tocar
+- `path/foo.ts` — <o que muda>
+- `path/bar.tsx` — <o que muda>
+- `tests/foo.test.ts` — <novo teste>
+
+## Dependências
+- Bloqueado por: TASK-NNNN, ADR-NNNN
+- Bloqueia: TASK-NNNN
+
+## Testes
+- Unit: <descrição>
+- Integration: <descrição>
+- E2E: <descrição ou n/a>
+
+## Observabilidade a instrumentar
+- Métrica: `<nome>` — quando incrementa, qual unit
+- Log: prefixo `[<MODULE>]`, evento "<X>"
+- Alerta: <se aplicável>
+
+## Notas
+<contexto adicional, links, screenshots>
+
+## Done quando
+- [ ] Critério de aceite verificado
+- [ ] Build verde
+- [ ] Tests novos passam
+- [ ] DoD (`governance/definition-of-done.md`) cumprido
+- [ ] PR aprovada (G7)

package/ai/tools/debugging.md

@@ -0,0 +1,64 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~500
+load: bugs, errors
+triggers: bug, erro, error, falha, crash, exception, stacktrace
+---
+
+# Tool: Protocolo de Debug
+
+## Princípio
+
+> Causa raiz > sintoma. Reproduzir > supor. Bisecção > tentativa cega.
+
+## Fluxo
+
+### 1. Reproduzir
+- Não debugue o que não reproduz. Se intermitente → registrar condições e frequência.
+- Reproduzir no menor cenário possível (input mínimo).
+
+### 2. Isolar
+- Bisecar: dividir o pipeline em metades, isolar a metade que falha, repetir.
+- `git bisect` para regressões introduzidas por commit recente.
+- Comentar/desativar blocos para isolar.
+
+### 3. Observar
+- Logs com timestamp e nível.
+- `console.log`/`print` temporários — REMOVER antes de commitar.
+- Debugger > prints quando o estado é complexo.
+- Network/DB queries quando o erro envolve I/O.
+
+### 4. Hipotetizar
+- Listar 2-3 hipóteses ordenadas por probabilidade.
+- Para cada uma: como confirmar/refutar em 1 passo.
+
+### 5. Corrigir
+- Corrigir a CAUSA, não o sintoma.
+- Se for paliativo, comentar "WORKAROUND:" + razão + link para issue.
+
+### 6. Testar
+- Teste que falha sem a correção e passa com ela.
+- Rodar suite completa para regressão.
+
+### 7. Registrar
+- Sintoma + causa + correção em `memory/errors-and-solutions.md`.
+- Se padrão recorrente → considerar `evolution/patterns-discovered.md` após 3+ ocorrências.
+
+## Anti-padrões
+
+- "Funciona localmente" sem investigar diferença de ambiente.
+- Aumentar timeout para mascarar race condition.
+- try/catch genérico engolindo o erro.
+- Reescrever do zero antes de entender o bug.
+- "Reiniciar o servidor resolve" como solução definitiva.
+
+## Sinais de causa raiz não encontrada
+
+- A correção exige número mágico.
+- A correção quebra outra coisa "aleatoriamente".
+- Você não consegue explicar POR QUE funciona.
+- O bug "volta" depois de algum tempo.
+
+Nesses casos → recuar, registrar como `known-issues.md`, escalar.

package/ai/tools/dependency-analysis.md

@@ -0,0 +1,46 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~450
+load: deps_changes
+triggers: dependência, dependency, npm, pip, cargo, pacote, upgrade
+---
+
+# Tool: Análise de Dependências
+
+## Antes de adicionar uma dependência
+
+1. **Justificar.** Pode resolver com 20-50 linhas próprias? Se sim, prefira código.
+2. **Auditar.**
+   - Idade do último release (> 1 ano = risco de abandono)
+   - Número de mantenedores ativos
+   - Issues abertas vs. fechadas
+   - Tamanho (`bundlephobia` para JS)
+   - Licença (MIT/Apache OK; GPL/AGPL exige análise)
+3. **Verificar duplicação.** Já existe outra lib no projeto que cobre o caso?
+4. **Pin version.** Não usar `^` ou `~` em libs críticas de produção sem lockfile robusto.
+
+## Antes de atualizar uma dependência
+
+1. Ler CHANGELOG entre versão atual e alvo.
+2. Identificar breaking changes.
+3. Subir em isolamento (uma lib por commit) para bisect simples se quebrar.
+4. Rodar suite completa de testes.
+
+## Antes de remover uma dependência
+
+1. Buscar uso em todo o repositório (`grep -r`).
+2. Verificar imports indiretos (algumas libs são re-exportadas).
+3. Atualizar lockfile e rodar testes.
+
+## Auditoria de segurança
+
+- Rodar `npm audit` / `pip-audit` / `cargo audit` em CI.
+- Vulnerabilidades críticas/altas → corrigir imediatamente, registrar em `memory/decisions.md`.
+- Vulnerabilidades médias/baixas → avaliar exposição real antes de upgrade forçado.
+
+## Registro
+
+- Dependência adicionada/removida → entrada em `memory/decisions.md` com motivo.
+- Upgrade com breaking change → `memory/completed-tasks.md` + nota em `memory/errors-and-solutions.md` se houve correção.

package/ai/tools/internet-research.md

@@ -0,0 +1,42 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~350
+load: research, docs, latest
+triggers: documentação, docs, latest, recente, mudou, release
+---
+
+# Tool: Pesquisa na Internet
+
+## Quando usar
+
+- Documentação de biblioteca/API que você não tem certeza sobre versão atual.
+- Erro com mensagem específica que não está em `memory/errors-and-solutions.md`.
+- Mudança recente em ecossistema (ex: nova versão de framework liberada após knowledge cutoff).
+- Comparação de bibliotecas/abordagens para uma decisão arquitetural.
+
+## Quando NÃO usar
+
+- Pergunta respondível lendo o próprio repositório.
+- Conhecimento já validado em `memory/` ou `evolution/`.
+- Sintaxe básica de linguagem (verifique se realmente não sabe antes de buscar).
+
+## Protocolo
+
+1. **Formular query específica.** "react 19 use hook" > "react hooks".
+2. **Priorizar fontes oficiais**: docs do projeto > GitHub releases/issues > Stack Overflow recente > blogs.
+3. **Verificar data.** Resultado de >2 anos para ecossistema rápido (JS, Python ML) provavelmente desatualizado.
+4. **Cruzar 2+ fontes** antes de aplicar mudança não-trivial.
+5. **Citar fonte** na resposta ao usuário se a decisão depende dela.
+
+## Registro
+
+- Se a pesquisa levou a uma decisão arquitetural → registrar em `memory/decisions.md` com link da fonte.
+- Se resolveu um erro → `memory/errors-and-solutions.md` com link.
+
+## Anti-padrões
+
+- Aceitar primeiro resultado sem ler.
+- Copiar código de Stack Overflow sem entender.
+- Buscar quando o repositório local já responde.

package/ai/tools/mcp-discovery.md

@@ -0,0 +1,44 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~300
+load: tooling, mcp, browser
+triggers: mcp, tool, ferramenta, automação, browser, chrome, computer-use
+---
+
+# Tool: Descoberta e Uso de MCPs
+
+MCP = Model Context Protocol. Servidores MCP expõem ferramentas adicionais ao agente (browser, computer-use, GitHub, bancos de dados, etc.).
+
+## Inventário
+
+Antes de assumir que uma ferramenta não existe:
+1. Listar MCPs disponíveis na sessão atual.
+2. Conferir se algum cobre o domínio da tarefa.
+3. Preferir MCP dedicado > MCP genérico > shell + biblioteca.
+
+## Hierarquia de Escolha
+
+| Tarefa | Preferência |
+|---|---|
+| Operar app web | MCP dedicado do app (Slack, Linear...) → Chrome MCP → computer-use |
+| Operar app nativo | computer-use |
+| Operar terminal/IDE | Bash/PowerShell direto (computer-use é restrito nesses) |
+| Manipular planilha/doc | Skill especializado (xlsx/docx/pdf) > script manual |
+
+## Antes de chamar um MCP
+
+- Verificar se há permissão concedida (alguns exigem `request_access`).
+- Verificar tier (read/click/full) — alguns MCPs têm restrições por categoria de app.
+- Para web: verificar se o link é seguro antes de clicar.
+
+## Registro
+
+Se descobrir capacidade nova ou limitação não-óbvia de um MCP, registrar em `memory/project-context.md` na seção "Ferramentas disponíveis".
+
+## Segurança
+
+- Nunca seguir links suspeitos via computer-use — abrir via browser MCP que permite inspecionar URL.
+- Nunca executar ações financeiras automatizadas.
+- Confirmar com humano antes de operações destrutivas mesmo via MCP.

package/ai/workflows/_schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AI OS Workflow",
+  "type": "object",
+  "required": ["id", "version", "description", "steps"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{1,32}$" },
+    "version": { "type": "string" },
+    "description": { "type": "string" },
+    "phase_advance": {
+      "type": "string",
+      "description": "Phase string a definir em state.lifecycle.phase após execução bem-sucedida. Use steps explícitos `aios_state_advance` se quiser também trocar mode."
+    },
+    "guarantees": {
+      "type": "array",
+      "description": "Invariantes que devem ser cumpridos ao final. Engine valida contra GUARANTEE_PROVIDERS. Não-cumpridos vão para report.unmet_guarantees.",
+      "items": {
+        "enum": [
+          "snapshot_created",
+          "state_updated",
+          "context_compiled",
+          "lint_clean",
+          "stack_detected",
+          "project_analyzed",
+          "core_loaded",
+          "memory_searched",
+          "query_routed",
+          "task_classified"
+        ]
+      }
+    },
+    "safety": {
+      "type": "object",
+      "properties": {
+        "project_files_readonly": {
+          "type": "boolean",
+          "description": "Declarativo (Fase 2): true significa que workflow não deve editar arquivos fora de .ai/. Engine reporta no relatório; futuro: bloqueio ativo."
+        }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "tool": { "type": "string", "pattern": "^aios_[a-z_]+$" },
+          "args": {
+            "type": "object",
+            "description": "Args para a tool. Strings suportam substituição ${input.X}, ${state.X}, ${timestamp}, ${resumed_input.X}, com fallback literal 'foo'."
+          },
+          "on_error": { "enum": ["abort", "continue"], "default": "abort" },
+          "pause_for": {
+            "type": "object",
+            "description": "Faz workflow pausar antes/depois deste step para coletar input do usuário. Engine retorna status='paused' + execution_id; cliente externo chama aios_resume_workflow para continuar.",
+            "properties": {
+              "when": { "enum": ["before", "after"], "default": "before" },
+              "reason": { "type": "string" },
+              "prompt": { "type": "string" },
+              "expected_input": { "type": "string" }
+            },
+            "required": ["reason", "prompt"]
+          },
+          "branches": {
+            "type": "array",
+            "description": "Lista de branches condicionais. Primeiro com 'when' verdadeiro executa; senão o 'default:true'. Expressão simples: <dotted.path> <op> <literal>. Operadores: ==, !=, in.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "when": { "type": "string", "description": "Ex.: 'state.identity.maturity == \"empty\"'" },
+                "default": { "type": "boolean" },
+                "steps": { "type": "array" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/ai/workflows/init.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "./_schema.json",
+  "id": "init",
+  "version": "3.0.0",
+  "description": "Inicializa o conhecimento do projeto. Ramifica entre Discovery Runtime (projeto novo, state.identity.maturity=='empty') e Reverse Engineering Runtime (projeto existente). Read-only no código do projeto (só edita .ai/).",
+  "safety": { "project_files_readonly": true },
+  "guarantees": [
+    "stack_detected",
+    "project_analyzed",
+    "context_compiled",
+    "snapshot_created",
+    "core_loaded",
+    "state_updated"
+  ],
+  "steps": [
+    {
+      "id": "init_branch",
+      "branches": [
+        {
+          "when": "state.identity.maturity == \"empty\"",
+          "steps": [
+            {
+              "id": "discovery_intro",
+              "tool": "aios_state_set",
+              "args": { "path": "lifecycle.mode", "value": "analysis" },
+              "on_error": "continue"
+            },
+            {
+              "id": "ask_project_name",
+              "tool": "aios_state_set",
+              "args": { "path": "rotating.active_focus", "value": "discovery: ask project name + domain" },
+              "on_error": "continue",
+              "pause_for": {
+                "when": "after",
+                "reason": "discovery_questionnaire",
+                "prompt": "Projeto novo detectado. Qual o nome do projeto e o domínio (ex.: 'TripPlanner — viagens com IA')?",
+                "expected_input": "string"
+              }
+            },
+            {
+              "id": "record_identity",
+              "tool": "aios_state_set",
+              "args": { "path": "identity.project_name", "value": "${resumed_input}" },
+              "on_error": "continue"
+            },
+            {
+              "id": "promote_to_minimal",
+              "tool": "aios_state_set",
+              "args": { "path": "identity.maturity", "value": "minimal" },
+              "on_error": "continue"
+            },
+            {
+              "id": "detect_stack",
+              "tool": "aios_detect_stack",
+              "args": {},
+              "on_error": "continue"
+            },
+            {
+              "id": "analyze_project",
+              "tool": "aios_analyze_project",
+              "args": { "write": true },
+              "on_error": "abort"
+            },
+            {
+              "id": "build_initial_context",
+              "tool": "aios_build_context_package",
+              "args": {
+                "intent": "${input.intent || 'discovery baseline'}",
+                "max_modules": 12,
+                "write": true
+              },
+              "on_error": "continue"
+            },
+            {
+              "id": "baseline_snapshot",
+              "tool": "aios_snapshot",
+              "args": { "label": "discovery-${timestamp}" },
+              "on_error": "continue"
+            },
+            {
+              "id": "load_core",
+              "tool": "aios_get_core_bundle",
+              "args": {},
+              "on_error": "abort"
+            },
+            {
+              "id": "advance_lifecycle",
+              "tool": "aios_state_advance",
+              "args": { "phase": "discovery", "mode": "analysis" },
+              "on_error": "continue"
+            }
+          ]
+        },
+        {
+          "default": true,
+          "steps": [
+            {
+              "id": "detect_stack",
+              "tool": "aios_detect_stack",
+              "args": {},
+              "on_error": "continue"
+            },
+            {
+              "id": "analyze_project",
+              "tool": "aios_analyze_project",
+              "args": { "write": true },
+              "on_error": "abort"
+            },
+            {
+              "id": "build_initial_context",
+              "tool": "aios_build_context_package",
+              "args": {
+                "intent": "${input.intent || 'reverse engineering baseline'}",
+                "max_modules": 12,
+                "write": true
+              },
+              "on_error": "continue"
+            },
+            {
+              "id": "baseline_snapshot",
+              "tool": "aios_snapshot",
+              "args": { "label": "init-${timestamp}" },
+              "on_error": "continue"
+            },
+            {
+              "id": "load_core",
+              "tool": "aios_get_core_bundle",
+              "args": {},
+              "on_error": "abort"
+            },
+            {
+              "id": "compile_context",
+              "tool": "aios_compile_runtime_context",
+              "args": { "write": true },
+              "on_error": "continue"
+            },
+            {
+              "id": "advance_lifecycle",
+              "tool": "aios_state_advance",
+              "args": { "mode": "execution" },
+              "on_error": "continue"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/ai/workflows/sync.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "./_schema.json",
+  "id": "sync",
+  "version": "3.0.0",
+  "description": "Sincroniza o estado do projeto após mudanças: re-detecta stack, re-analisa, atualiza context package, valida integridade, gera snapshot, compila runtime-context, detecta drift, atualiza state. Use após bloco de desenvolvimento, antes de pausar, ou periodicamente. Read-only no código do projeto.",
+  "safety": { "project_files_readonly": true },
+  "guarantees": [
+    "stack_detected",
+    "project_analyzed",
+    "context_compiled",
+    "lint_clean",
+    "snapshot_created",
+    "runtime_context_compiled",
+    "drift_checked",
+    "state_updated"
+  ],
+  "steps": [
+    {
+      "id": "detect_stack",
+      "tool": "aios_detect_stack",
+      "args": {},
+      "on_error": "continue"
+    },
+    {
+      "id": "analyze_project",
+      "tool": "aios_analyze_project",
+      "args": { "write": true },
+      "on_error": "abort"
+    },
+    {
+      "id": "rebuild_context",
+      "tool": "aios_build_context_package",
+      "args": {
+        "intent": "${input.intent || 'periodic sync after development'}",
+        "max_modules": 12,
+        "write": true
+      },
+      "on_error": "continue"
+    },
+    {
+      "id": "lint_os",
+      "tool": "aios_lint",
+      "args": {},
+      "on_error": "continue"
+    },
+    {
+      "id": "snapshot",
+      "tool": "aios_snapshot",
+      "args": { "label": "${input.label || 'sync'}-${timestamp}" },
+      "on_error": "continue"
+    },
+    {
+      "id": "compile_runtime_context",
+      "tool": "aios_compile_runtime_context",
+      "args": { "max_modules": 10, "max_decisions": 5, "write": true },
+      "on_error": "continue"
+    },
+    {
+      "id": "detect_drift",
+      "tool": "aios_detect_drift",
+      "args": {},
+      "on_error": "continue"
+    },
+    {
+      "id": "record_sync_focus",
+      "tool": "aios_state_set",
+      "args": { "path": "rotating.active_focus", "value": "${input.intent || 'periodic sync'}" },
+      "on_error": "continue"
+    }
+  ]
+}