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

package/ai/operating-system/folder-structure.md

@@ -0,0 +1,126 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~500
+load: setup, refactor
+triggers: estrutura, pasta, folder, organização
+---
+
+# Folder Structure
+
+> Organização canônica de diretórios. Adapte conforme stack — mas mantenha o princípio: organização por **domínio/feature**, não por **tipo de arquivo**.
+>
+> **Camada acima desta**: organização por **especificação técnica** (Frontend, Backend, BD, Infra, Integrações, Tools, APIs, MCPs). Ver [`bootstrap/tech-mapping.md`](../bootstrap/tech-mapping.md). Cada especificação pode (e deve) **internamente** ser organizada por feature/domínio conforme as regras abaixo.
+
+## Organização macro (por especificação técnica)
+
+Em projetos com múltiplas especificações, a raiz reflete as especificações que existem (não inventar):
+
+```
+projeto/
+├── frontend/         # ou src/ se for monorepo simplificado
+├── backend/          # ou server/
+├── infra/            # docker-compose.yml, k8s/, terraform/
+├── integrations/     # clients de terceiros isolados (opcional)
+├── scripts/          # tools internas (opcional)
+├── samples/          # data samples gitignored (opcional)
+├── docs/             # documentação humana (opcional)
+└── .ai/              # AI OS deste projeto
+```
+
+> Em monorepos pequenos, é comum ver `src/` (front) + `server/` (back) na raiz, sem `frontend/` explícito — aceitável; o `architecture.md` documenta o mapeamento real.
+
+---
+
+## Anti-padrão: organização por tipo
+
+```
+src/
+├── controllers/
+├── services/
+├── models/
+└── views/
+```
+
+❌ Cada feature está espalhada em 4 lugares. Mudança simples toca 4 pastas.
+
+## Padrão: organização por feature
+
+```
+src/
+├── orders/
+│   ├── order.entity.ts
+│   ├── order.service.ts
+│   ├── order.controller.ts
+│   ├── order.repository.ts
+│   └── order.test.ts
+├── users/
+│   └── ...
+└── shared/
+    ├── http/
+    ├── db/
+    └── utils/
+```
+
+✅ Tudo de "orders" no mesmo lugar. `shared/` para o que é genuinamente reutilizado.
+
+## Exemplos por Stack
+
+### Node.js / TypeScript backend
+
+```
+src/
+├── domains/              # bounded contexts
+│   ├── orders/
+│   ├── users/
+│   └── billing/
+├── infrastructure/       # adapters concretos
+│   ├── db/
+│   ├── http/
+│   └── queue/
+├── shared/               # util genuinamente cross-domain
+├── config/               # carregamento de env tipado
+└── server.ts             # bootstrap
+tests/                    # ou colocado junto do código (.test.ts)
+```
+
+### React / Next.js
+
+```
+src/
+├── app/                  # rotas (Next 13+)
+├── components/
+│   ├── ui/               # primitivos sem lógica de domínio
+│   └── feature/          # com lógica de domínio
+├── hooks/
+├── lib/                  # utils sem React
+├── styles/
+└── types/
+```
+
+### Python (FastAPI / Django)
+
+```
+src/
+├── apps/                 # por feature
+│   ├── orders/
+│   └── users/
+├── core/                 # config, db base, middlewares
+├── shared/
+└── main.py
+tests/
+```
+
+## Princípios
+
+1. **Profundidade controlada**: máximo 3-4 níveis. Acima disso, repensar.
+2. **`shared/` é caro**: só vai para lá o que é usado por 2+ domínios E não pertence a nenhum.
+3. **Testes ao lado do código** (`order.test.ts`) > tudo em `tests/` separado, especialmente em projetos grandes.
+4. **Convenção sobre configuração**: arquivos com sufixo `.entity`, `.service`, `.repository` para encontrar rápido.
+
+## Onde NÃO pôr coisa
+
+- Pasta `utils/` virando lixeira → revisar trimestralmente.
+- `helpers/` genéricos sem dono → costuma indicar má modelagem do domínio.
+- Arquivos `misc.ts`, `common.ts`, `stuff.ts` → renomear ou eliminar.

package/ai/operating-system/performance-rules.md

@@ -0,0 +1,86 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~500
+load: performance
+triggers: performance, latência, p95, p99, slo, sla, budget
+---
+
+# Performance Rules
+
+> Regras operacionais. Complementa `skills/performance.md` (que é metodológico).
+
+## Princípios
+
+1. **Medir antes de otimizar.** Sem profile, sem decisão.
+2. **Otimizar o caminho quente.** 5% do código, 95% do tempo.
+3. **Não regredir.** Performance é feature; mudança que degrada precisa ser justificada.
+
+## Orçamentos (defaults; ajustar por projeto em `memory/project-context.md`)
+
+### Backend HTTP
+- p50 < 100ms
+- p95 < 250ms
+- p99 < 500ms
+- error rate < 0.1%
+
+### Frontend (Core Web Vitals)
+- LCP < 2.5s
+- INP < 200ms
+- CLS < 0.1
+- TTFB < 800ms
+
+### Banco de dados
+- p99 query time < 100ms para queries OLTP
+- Sem query > 1s sem justificativa
+
+### Background jobs
+- SLA por tipo de job, registrado em `memory/project-context.md`
+
+## Regras Obrigatórias
+
+- **Toda chamada de rede tem timeout.** Sem exceção.
+- **Toda lista paginada.** LIMIT + cursor/offset.
+- **Sem `SELECT *`** em produção.
+- **Índice ANTES de query lenta chegar a prod** quando o padrão de acesso é conhecido.
+- **N+1 detectado em review = bloqueia merge.**
+
+## Padrões aplicáveis
+
+### Caching
+- Cache miss + invalidação errada > sem cache. Pensar invalidação antes.
+- TTL adequado ao churn dos dados.
+- Não cachear resposta de operação autenticada sem chave por usuário.
+
+### Async
+- I/O bound → async/await ou worker pool.
+- Webhook recebido → ack rápido, processar em background.
+
+### Loading
+- Frontend: lazy load de rotas, componentes pesados, imagens fora do viewport.
+- Backend: lazy init de recursos caros (DB pool já é assim por default).
+
+### Batching
+- N requisições para o mesmo serviço → batchar quando possível.
+- Inserções em loop → bulk insert.
+
+## Monitoramento
+
+- Dashboards de latência (p50/p95/p99), throughput, error rate.
+- Alerta em violação de SLO (não em CPU/memória diretamente — usar Golden Signals).
+- Trace amostrado em produção; trace completo em staging.
+
+## Anti-padrões a rejeitar
+
+- "Está rápido localmente" como prova.
+- Adicionar cache porque "vai melhorar".
+- Trocar lib por outra "mais performática" sem benchmark do caso real.
+- Otimização que reduz 10ms em endpoint de 5 req/dia.
+
+## Performance Regression
+
+Mudança que regride > 10% em alguma métrica chave:
+1. Bloqueia merge.
+2. Investigar causa.
+3. Otimizar OU justificar trade-off em ADR.

package/ai/operating-system/quality-control.md

@@ -0,0 +1,81 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~500
+load: quality, review
+triggers: review, quality, dod, definition of done, ci, lint
+---
+
+# Quality Control
+
+> Definições de "feito" e portões de qualidade. O que NÃO passar bloqueia entrega.
+
+## Definition of Done
+
+Uma tarefa só está "pronta" se:
+
+- [ ] Código implementado e revisado (auto + humano se PR).
+- [ ] Lint sem erros (warnings revisados).
+- [ ] Type-check sem erros.
+- [ ] Testes novos cobrem a mudança.
+- [ ] Suite de testes existente passa 100%.
+- [ ] Smoke-test manual em ambiente próximo ao real (se UI/runtime).
+- [ ] Documentação atualizada se contratos públicos mudaram.
+- [ ] `memory/completed-tasks.md` atualizado.
+- [ ] ADR criado se houve decisão arquitetural.
+- [ ] Sem segredo, log de PII ou debug code no diff.
+
+## Portões Automatizados (CI)
+
+| Etapa | Falha bloqueia merge? |
+|---|---|
+| Lint | sim |
+| Type-check | sim |
+| Unit tests | sim |
+| Integration tests | sim |
+| Build | sim |
+| Security scan (deps) | sim para crítico/alto |
+| Coverage | só se cair abaixo de threshold definido |
+| E2E | sim para PR para main |
+
+## Code Review — checklist
+
+### Correção
+- [ ] Faz o que diz no título do PR?
+- [ ] Cobre edge cases óbvios?
+- [ ] Erros tratados ou propagados conscientemente?
+
+### Design
+- [ ] Encaixa na arquitetura existente?
+- [ ] Acoplamento justificado?
+- [ ] Não duplica algo que já existe?
+
+### Legibilidade
+- [ ] Nomes são bons?
+- [ ] Funções têm tamanho razoável?
+- [ ] Comentários onde precisam e só onde precisam?
+
+### Testes
+- [ ] Testes cobrem o comportamento, não a implementação?
+- [ ] Testes de regressão para bugs corrigidos?
+
+### Segurança
+- [ ] Input validado?
+- [ ] Sem segredo no diff?
+- [ ] Sem PII em log?
+
+### Performance
+- [ ] Sem N+1 introduzido?
+- [ ] Sem loop síncrono sobre I/O?
+
+## Métricas de saúde
+
+- **Build time**: monitorar tendência. Lentidão crônica vira atrito.
+- **Test runtime**: testes lentos → quarentena ou otimização.
+- **Flakiness**: zero tolerância em main. Quarentena imediata, fix em <1 semana.
+- **Dívida técnica**: alocar % do tempo (10-20%) para reduzir, não esperar "tempo livre".
+
+## Quality gate de regressão
+
+Bug em prod → criar teste que **falha sem o fix** antes de fazer o fix. Garante que o teste exercita o bug.

package/ai/operating-system/security-rules.md

@@ -0,0 +1,91 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~700
+load: security
+triggers: segurança, security, auth, senha, token, compliance, lgpd, gdpr, pci
+---
+
+# Security Rules
+
+> Regras operacionais de segurança aplicadas em todo o projeto. Complementa `skills/security.md` (que é mais técnico-conceitual).
+
+## Não-negociáveis
+
+1. **Nenhum segredo em código.** Nunca. `.env` no `.gitignore`.
+2. **HTTPS sempre.** HTTP só em loopback de dev.
+3. **Auth em toda rota não-pública.** Default: privado; whitelist explícita o público.
+4. **Validação em borda.** Todo input externo (HTTP, fila, arquivo, env) passa por schema.
+5. **PII minimizada.** Coletar só o necessário; expirar / anonimizar quando o propósito acabar.
+
+## Gestão de Segredos
+
+- Cofre: AWS Secrets Manager, GCP Secret Manager, Vault, doppler, ou equivalente.
+- Injeção em runtime via env vars.
+- `.env.example` versionado com chaves vazias.
+- Rotação: trimestral mínimo; imediata se vazado.
+- Chave de longa vida (>1 ano) → exceção que exige justificativa.
+
+## Autenticação / Autorização
+
+- Senhas: argon2id (preferência) ou bcrypt cost ≥ 12.
+- MFA disponível para todos; obrigatório para roles administrativos.
+- Sessões: token opaco server-side OU JWT curto + refresh.
+- JWT em cookie `HttpOnly`, `Secure`, `SameSite=Lax`.
+- Rate limit em login, signup, password reset.
+
+## Logging
+
+- **Nunca logar**: senhas, tokens, chaves, números de cartão, CPF/SSN completos, conteúdo de mensagens privadas.
+- **Mascarar ao logar**: `email: a***@b***.com`, `card: ****1234`.
+- **Log de eventos de segurança**: login, logout, falha de auth, mudança de permissão, acesso a dado sensível.
+
+## Headers HTTP obrigatórios em produção
+
+```
+Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
+Content-Security-Policy: (configurada por projeto, default-src 'self')
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: (mínimo necessário)
+```
+
+## Input
+
+- Schema na entrada (Zod, Pydantic, JSON Schema). Reject unknown fields.
+- Limites: tamanho de payload, profundidade, tamanho de strings.
+- File upload: validar tipo por magic bytes, não só por extensão.
+
+## Dependências
+
+- Auditoria em CI (`npm audit`, `pip-audit`, `cargo audit`, Snyk, Dependabot).
+- Crítico/alto → fix em <7 dias.
+- Médio → fix no próximo ciclo.
+- Baixo → revisão trimestral.
+
+## Compliance
+
+- **LGPD** (Brasil): finalidade, mínimo, transparência, direito à exclusão.
+- **GDPR** (UE): consentimento, portabilidade, esquecimento.
+- **PCI-DSS** (cartões): nunca armazenar PAN/CVV em claro.
+- **HIPAA** (saúde EUA): criptografia, auditoria, BAA.
+
+→ Aplicabilidade registrada em `memory/project-context.md`.
+
+## Incidentes
+
+1. Detecção → rotação imediata de credenciais expostas.
+2. Contenção → desabilitar superfície atacável.
+3. Comunicação → stakeholders + (se LGPD/GDPR) autoridades em prazo legal.
+4. Erradicação → fix + verificação.
+5. Lições → registrar em `memory/errors-and-solutions.md` + `evolution/learnings.md`.
+
+## Proibições absolutas
+
+- `eval()` / equivalentes em input do usuário.
+- Desserialização de dado não confiável sem schema.
+- SQL concatenado com input.
+- Comparar segredos com `==` em vez de comparação constante.
+- Disabling de TLS verification em produção.

package/ai/operating-system/workflow.md

@@ -0,0 +1,86 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~600
+load: workflow, git, ci
+triggers: pr, pull request, merge, branch, commit, release, deploy, ci, cd
+---
+
+# Workflow
+
+> Como o trabalho flui do início (ideia/bug) à entrega.
+
+## Fluxo de Tarefa
+
+```
+1. Origem (request, bug, idea)
+        ↓
+2. Registrar em pending-tasks.md (com critério de aceite)
+        ↓
+3. Triagem (prioridade, dependências)
+        ↓
+4. Pickup → mover para "in-progress"
+        ↓
+5. Branch (feat/, fix/, chore/, refactor/)
+        ↓
+6. Implementação seguindo rules/execution-flow.md
+        ↓
+7. Auto-revisão (lint, types, tests, leitura do diff)
+        ↓
+8. PR / Review humano
+        ↓
+9. Merge
+        ↓
+10. Mover para completed-tasks.md
+        ↓
+11. Atualizar decisions.md / errors-and-solutions.md se aplicável
+```
+
+## Branches
+
+- `main` (ou `master`): sempre verde, sempre deployável.
+- `feat/<slug>`, `fix/<slug>`, `chore/<slug>`, `refactor/<slug>`, `docs/<slug>`.
+- Branch de vida curta: <1 semana ideal, <3 dias ótimo.
+- Rebase contra main antes de PR para minimizar merge commits.
+
+## Commits
+
+- Conventional Commits (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`).
+- Mensagem clara: o **quê** muda e (se não óbvio) **por quê**.
+- Atômicos: um commit = uma mudança lógica.
+
+## Pull Requests
+
+- Título: imperativo, < 70 caracteres.
+- Descrição obrigatória:
+  - **O que muda**
+  - **Por quê** (link para issue/ADR)
+  - **Como testar**
+  - **Risco / rollback**
+- Tamanho: < 400 linhas mudadas ideal. PR gigante = revisão ruim.
+
+## Review
+
+- Bloqueia: bug, segurança, perf grave, arquitetura.
+- Sugere: estilo, naming, refactor opcional.
+- Não bloquear por preferência pessoal sem fundamento.
+
+## Deploy
+
+- CI verde obrigatório antes de merge.
+- Deploy automatizado pós-merge em staging.
+- Promoção para prod: manual ou agendada, com janela definida.
+- Rollback plan documentado para mudanças críticas.
+
+## Postmortem
+
+- Incidente em prod → postmortem blameless dentro de 1 semana.
+- Registrar em `memory/errors-and-solutions.md` (sintoma + causa + correção + prevenção).
+- Padrão recorrente → `evolution/patterns-discovered.md`.
+
+## Cadência sugerida
+
+- Daily async: o que fiz, o que farei, bloqueios (curto).
+- Weekly: revisão de `pending-tasks.md` — repriorizar, descartar obsoletos.
+- Monthly: revisão de `evolution/` — promover learnings consolidados a `operating-system/`.

package/ai/product/README.md

@@ -0,0 +1,24 @@
+---
+version: 1.0.0
+updated: 2026-05-15
+tier: on_demand
+audience: humano + product-manager agent
+---
+
+# Product — Visão, personas, regras de negócio, jornadas
+
+> Artefatos de **produto** mantidos pelo `product-manager` agent (+ founder). Vivem **separados de `specs/`**: produto = "o quê e por quê"; specs = "como em detalhe".
+
+## Arquivos
+
+| Arquivo | Conteúdo |
+|---|---|
+| `vision.md` | Visão do produto (longo prazo, 1-3 anos) |
+| `personas.md` | Perfis de usuário com motivações e dores |
+| `business-rules.md` | Regras de negócio (não-funcionais centrais) |
+| `user-journeys.md` | Jornadas principais (do usuário → resultado) |
+| `requirements/PRD/` | PRDs aceitos (atalho para `specs/PRD/`) |
+| `requirements/BRD/` | BRDs aceitos (atalho para `specs/BRD/`) |
+| `requirements/RFC/` | RFCs (atalho para `specs/RFC/`) |
+
+> Diretórios `requirements/*/` são opcionalmente alimentados por link/cópia — facilita "tour de produto" em um lugar só. Se preferir ficar enxuto, deletar `requirements/` e referenciar `specs/` direto.

package/ai/product/business-rules.md

@@ -0,0 +1,26 @@
+---
+version: 1.0.0
+updated: 2026-05-15
+tier: conditional
+mutable: true
+---
+
+# Business Rules
+
+> Regras de negócio invariantes — independem da tecnologia. Mudança aqui exige discussão com Founder.
+
+## Formato
+
+```
+## BR-NNN — <nome>
+- Categoria: validação | autorização | cálculo | fluxo | compliance
+- Descrição: <regra em linguagem natural>
+- Origem: <regulação, decisão de produto, acordo comercial>
+- Onde é aplicada: <camada front/back/ambos>
+- Penalidade se violada: <multa, perda de cliente, dado corrompido>
+- Testes que cobrem: <referência>
+```
+
+## Regras ativas
+
+<!-- preencher por projeto -->

package/ai/product/personas.md

@@ -0,0 +1,29 @@
+---
+version: 1.0.0
+updated: 2026-05-15
+tier: conditional
+mutable: true
+---
+
+# Personas
+
+> Perfis arquetípicos de usuário. Cada persona = 1 segmento real com motivações, dores e contexto distintos. Personas devem ser observadas (entrevistas, dados), não inventadas.
+
+## Formato
+
+```
+## P-NNN — <nome arquetípico> (ex.: "Maria, gerente de frota")
+
+- Segmento: <em qual segmento>
+- Demografia / contexto: <idade, papel, ferramentas atuais>
+- Objetivo principal: <o que quer alcançar>
+- Dores atuais: <o que não funciona>
+- Métrica de sucesso (do ponto de vista da persona): <como mede>
+- Como usaria o produto: <cenário típico>
+- Hábitos: <quando usa, com que frequência, em qual device>
+- Não é o usuário-alvo: <persona X> — porque ...
+```
+
+## Personas ativas
+
+<!-- preencher por projeto com base em pesquisa real -->

package/ai/product/user-journeys.md

@@ -0,0 +1,30 @@
+---
+version: 1.0.0
+updated: 2026-05-15
+tier: conditional
+mutable: true
+---
+
+# User Journeys
+
+> Jornadas principais do ponto de vista da persona: do gatilho à recompensa. Mantém alinhamento entre features fragmentadas.
+
+## Formato
+
+```
+## J-NNN — <nome da jornada>
+- Persona: P-NNN (ver `personas.md`)
+- Gatilho: <o que inicia>
+- Estados:
+  1. <estado/passo>
+  2. <estado/passo>
+  3. ...
+- Recompensa: <resultado para a persona>
+- Métrica de jornada: <tempo até completar | % de conclusão | NPS pós-jornada>
+- Pontos de fricção conhecidos: <lista>
+- Features que tocam: <referências PRD-NNNN>
+```
+
+## Jornadas ativas
+
+<!-- preencher por projeto -->

package/ai/product/vision.md

@@ -0,0 +1,35 @@
+---
+version: 1.0.0
+updated: 2026-05-15
+tier: conditional
+mutable: true
+---
+
+# Vision
+
+> **Visão de 1-3 anos.** Reflete o "para onde estamos indo", não o que estamos fazendo este mês.
+
+## Norte
+1-2 frases. "Em [horizonte], queremos que [persona] consiga [ação central] de [maneira diferenciada]."
+
+## Por quê agora
+O que mudou no mundo / mercado / tecnologia que torna isso possível ou urgente?
+
+## Para quem (alto nível)
+Apontador para `personas.md`. Aqui só os 1-2 segmentos prioritários.
+
+## Critério de sucesso em 12 meses
+3-5 indicadores binários ou métricos.
+- [ ] <métrica 1>
+- [ ] <métrica 2>
+
+## Princípios de produto
+- <princípio 1 — ex.: "preferir automação a configuração">
+- <princípio 2>
+- <princípio 3>
+
+## Não-objetivos
+O que **explicitamente** não queremos virar. Evita drift.
+
+## Atualização
+Revisar a cada 3-6 meses. Mudança grande exige conversa estratégica registrada em `memory/decisions.md`.

package/ai/rules/behavior.md

@@ -0,0 +1,45 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: core
+tokens: ~400
+load: always
+---
+
+# Regras de Comportamento
+
+## Postura
+
+- **Engenheiro sênior, não assistente passivo.** Questione premissas mal formuladas antes de executar.
+- **Direto e técnico.** Sem floreios, sem auto-elogios, sem "claro!", "ótima pergunta!".
+- **Calibre confiança.** Diga "não sei" quando não souber. Diga "suposição" quando supor.
+- **Pense antes de agir.** Plano > execução cega.
+
+## Tom
+
+- Português técnico, sem gírias, sem emojis (exceto se solicitado).
+- Frases curtas. Parágrafos curtos. Cite arquivos como `caminho/arquivo.ext:linha`.
+- Não narre o que vai fazer em prosa antes de fazer — faça e relate o resultado.
+
+## Granularidade de Resposta
+
+| Tipo de pergunta | Resposta esperada |
+|---|---|
+| Pergunta factual simples | 1 frase |
+| Decisão de design | 2-3 frases + trade-off principal |
+| Implementação | Plano breve → código → validação |
+| Exploratória ("o que acha de...") | Recomendação + alternativa + razão (sem implementar) |
+| Bug | Causa raiz → correção mínima → teste |
+
+## Honestidade Operacional
+
+- Nunca afirmar que algo foi testado se não foi.
+- Nunca afirmar que um arquivo existe sem ter verificado.
+- Nunca afirmar que uma dependência funciona sem ter executado.
+- Se a tarefa é grande, dizer onde está incompleto antes de declarar "pronto".
+
+## Resposta a Conflitos
+
+- Conflito entre instrução do usuário e regra deste OS → seguir a instrução do usuário, mas avisar.
+- Conflito entre `rules/dont.md` e qualquer outra coisa → `dont.md` vence sempre.
+- Ambiguidade → perguntar, não inventar.