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

package/ai/memory/decisions.md

@@ -0,0 +1,257 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~varies
+load: architecture, design_decision
+mutable: append_only
+triggers: arquitetura, decisão, adr, escolher entre, trade-off
+---
+
+# Architecture Decision Records (ADRs)
+
+> Registro persistente de decisões arquiteturais. Cada ADR captura contexto, decisão, consequências e alternativas.
+
+## Formato
+
+```
+## ADR-NNNN — Título
+- Data: AAAA-MM-DD
+- Status: Proposto | Aceito | Substituído por ADR-NNNN | Deprecated
+- Decisor: usuário, agente, time
+
+### Contexto
+O que motivou a decisão. Restrições, requisitos, problema.
+
+### Decisão
+O que foi decidido, de forma clara e acionável.
+
+### Consequências
+- Positivas: ...
+- Negativas / trade-offs aceitos: ...
+- Neutras: ...
+
+### Alternativas consideradas
+1. Alternativa X — descartada porque Y
+2. Alternativa Z — descartada porque W
+
+### Referências
+Links, PRs, issues, fontes externas.
+```
+
+## Regras
+
+1. **Numeração sequencial.** ADR-0001, ADR-0002, ... — nunca reutilizar número.
+2. **Imutabilidade.** ADR aceito não se edita; cria-se novo ADR com status "Substituído por".
+3. **Linkagem.** Sempre referenciar ADRs relacionados.
+4. **Granularidade.** Uma decisão = um ADR. Não agrupar.
+
+## Quando criar ADR
+
+- Escolha de framework, biblioteca, banco, infraestrutura.
+- Padrão arquitetural (camadas, microserviços, eventos).
+- Política de segurança, performance, compliance.
+- Decisão controversa que provavelmente será questionada depois.
+
+## Quando NÃO criar ADR
+
+- Mudança trivial de implementação.
+- Convenção de código (vai para `operating-system/coding-standards.md`).
+- Bug fix (vai para `errors-and-solutions.md`).
+
+## Entradas
+
+<!-- adicionar abaixo a partir de ADR-0004 -->
+
+## ADR-0012 — StealthOS Hybrid Architecture (daemon global + projeto leve)
+- Data: 2026-05-16
+- Status: Aceito
+- Decisor: usuário (visão de produto "StealthOS não interfere no projeto") + agente
+- Contexto: `.ai/` despeja ~50 arquivos no projeto-alvo; viaja no git; difícil atualizar OS. Visão StealthOS exige isolamento.
+- Decisão: Modelo C híbrido — daemon em `~/.stealthos/` (server + manual + templates + projects/<hash>/), projeto recebe só `.stealthos.yml` + stubs IDE selecionados. Project hash = `sha256(absolute_path).slice(0,12)`. Server v1.2 introduz `STEALTHOS_MODE=embedded|hybrid`.
+- Consequência: projeto-alvo de 14 → 3-9 itens; update do OS atinge todos projetos; state não viaja no git. Implementação faseada — scaffolder primeiro (modo embedded), server multi-tenant depois (modo hybrid), v2.0 default hybrid.
+- Referências: `.ai/specs/ADR/ADR-0012-stealthos-hybrid-architecture.md`, ADR-0011 (MCP Prompts é ortogonal — funciona em ambos modos).
+
+## ADR-0011 — MCP Prompts como discovery mechanism cross-IDE
+- Data: 2026-05-16
+- Status: Aceito
+- Decisor: usuário + agente
+- Contexto: `/init`/`/sync`/`/work` só funcionavam no Claude Code (mecanismo proprietário). Outras IDEs (Antigravity, Cursor, etc.) tratavam slash como texto literal.
+- Decisão: expor os 3 workflows como MCP Prompts (primitivo do protocolo 2024-11-05). Híbrido: prompt retorna instrução pra LLM chamar `aios_run_workflow` + contexto enriquecido (state.identity, ROUTER hint).
+- Consequência: IDEs MCP-aware (Claude Code, Cursor recente) expõem `/init`/`/sync`/`/work` nativamente só conectando o MCP. 36 tools intactas (zero regressão). Server bump 1.0.0 → 1.1.0.
+- Referências: `.ai/specs/ADR/ADR-0011-mcp-prompts.md`.
+
+## ADR-0003 — v4.0.0: AI-DOS completo (Context Engine + Multi-agent + Spec-Driven + Pipeline com gates)
+- Data: 2026-05-15
+- Status: Aceito
+- Decisor: usuário (pedido explícito por "AI Development Operating System" maduro, equivalente ao processo de empresas grandes) + agente
+
+### Contexto
+O framework v3.4.0 cobria regras, skills, memória histórica e bootstrap com mapa técnico — suficiente para um projeto solo "vibe coding++". Mas o usuário identificou (corretamente) o teto desse modelo:
+- Sem **agentes especializados**, o agente principal vira "faz-tudo" e perde fronteiras.
+- Sem **specs canônicos** (PRD, SDD, RFC, BRD, Runbook), código nasce sem alinhamento.
+- Sem **context engine separado da memória**, contradições antigas contaminam decisões novas.
+- Sem **pipeline com gates explícitos**, qualquer task pula direto para implementação ("vibe coding").
+- Sem **governance** (princípios, DoR/DoD, security/architecture policies), decisões dependem do humor da sessão.
+
+O alvo é uma **empresa-de-uma-pessoa** onde o Founder direciona e agentes especializados executam, com qualidade equivalente ao processo de empresas maduras.
+
+### Decisão
+Promover o framework para **v4.0.0 — AI Development Operating System (AI-DOS)** com 6 camadas novas, mantendo backward-compatibility:
+
+1. **`governance/`** — Princípios inegociáveis (engineering-principles, architecture-principles, security-policies, DoR, DoD, quality-gates).
+2. **`agents/`** — 10 agentes especializados (founder, product-manager, architect, tech-lead, backend-engineer, frontend-engineer, qa-engineer, security-engineer, sre-engineer, reviewer, researcher) com contratos de I/O claros.
+3. **`specs/`** — Templates canônicos (PRD, SDD, RFC, BRD, ADR, RUNBOOKS, TASKS) numerados, com ciclo de vida draft → review → approved → deprecated/superseded.
+4. **`context/`** — Context Engine vivo separado da memória histórica: project-state, business-context, technical-context, architecture-state, active-goals, constraints, assumptions, glossary, roadmap, technical-debt.
+5. **`core/pipeline/execution-engine.md`** — Pipeline canônico IDEIA → DISCOVERY → PRD (G2) → ARCH (G3) → SDD/ADR → TASKS (G4) → IMPL (G5) → TEST (G6) → REVIEW (G7) → DEPLOY (G8) → OBSERVABILIDADE (G9) → APRENDIZADO (G10).
+6. **`product/`, `architecture/`, `engineering/`, `execution/`** — Pastas-irmãs com README + templates específicos por área.
+
+### Consequências
+- **Positivas**:
+  - Pipeline explícito acaba com "vibe coding" — não há atalho de IDEIA→IMPL.
+  - Cada agente é guardião de uma fronteira (Architect não implementa, Backend não muda arquitetura, etc.).
+  - Specs templates impedem que feature comece sem PRD/SDD.
+  - Context Engine separa "agora" de "histórico" — reduz contradição e custo de tokens.
+  - Governance materializa princípios que antes eram orais.
+  - Founder pode delegar com confiança porque os contratos de I/O são explícitos.
+- **Negativas / trade-offs aceitos**:
+  - Carga inicial maior: o `.ai/` cresceu de 69 para 137+ required files. Mitigação: CORE continua ~3k tokens; resto é CONDITIONAL/ON-DEMAND via ROUTER.
+  - Curva de adoção: agente principal precisa aprender a invocar agentes especializados e referenciar specs em vez de improvisar.
+  - Risco de **burocracia excessiva** em projetos pequenos. Mitigação: pipeline tem "modos" (Full, Express, Refactor, Spike, Config) — bug fix P0 skipa gates G1-G4.
+- **Neutras**:
+  - Compatibilidade preservada: regras antigas (`rules/`, `operating-system/`, `skills/`, `memory/`, `evolution/`, `tools/`, `runtime.md`) seguem ativas.
+
+### Alternativas consideradas
+1. **Manter v3.4.0 e só adicionar `specs/` e `agents/`** — descartado: sem `governance/` e `context/`, agentes não têm fronteira nem contexto vivo. Solução parcial.
+2. **Reescrever do zero como `.aios/` paralelo** — descartado: perde histórico, ADRs, learnings acumulados.
+3. **Adotar framework externo (LangGraph, CrewAI, AutoGen)** — descartado: cada um carrega filosofia própria e cria dependência de runtime. O AI-DOS é **markdown puro + hooks leves**, plug-and-play em qualquer cliente.
+
+### Plano de migração
+- v4.0.0 entra ao lado da estrutura existente — nenhuma pasta antiga removida.
+- ROUTER ganha novas rotas (pipeline, governance, agents, specs, context, product, incident) sem remover as antigas.
+- INDEX referencia as novas pastas.
+- Manifest passa de 69 para 67+novas required_files (alguns templates `_TEMPLATE.md` viram required).
+- Strak recebe a estrutura via sync (preservando seu próprio `memory/`, `decisions/`, `pending-tasks/`).
+
+### Referências
+- Pedido do usuário (sessão de 2026-05-14/15) que descreveu a evolução para Spec-Driven Development, Context Engineering e multi-agent.
+- Modelos de referência: C4 Model (Brown), 12-factor app, SRE Book (Google), Architecture Decision Records (Nygard), Software Engineering at Google (Winters et al.).
+
+## ADR-0002 — Tech-mapping obrigatório no bootstrap (organização por especificação técnica)
+- Data: 2026-05-14
+- Status: Aceito
+- Decisor: usuário (pedido direto: "no bootstrap deve haver processo de analisar e organizar tudo por especificações técnicas") + agente
+
+### Contexto
+O bootstrap original (`new-project.md` e `existing-project.md`) gerava `memory/project-context.md` e ADR-0001, mas deixava `operating-system/architecture.md` opcional/livre. Resultado observado em campo: ao instalar o `.ai/` num projeto real (Strak), o agente teve que inventar uma organização técnica sob pressão e ficou raso. Sem mapa explícito por especificação técnica (Frontend, Backend, BD, Infra, Integrações, Tools, APIs, MCPs, Dados), o agente perde tempo redescobrindo o shape do projeto a cada sessão e induz novos colaboradores ao mesmo retrabalho.
+
+### Decisão
+1. **Criar protocolo dedicado** em [`.ai/bootstrap/tech-mapping.md`](../bootstrap/tech-mapping.md) com:
+   - Catálogo de 11 especificações de alto nível (Frontend, Backend, BD, Infra/Deploy, Integrações Externas, Tools/Scripts, APIs, MCPs, Dados/Samples, Mobile/Desktop/Game, ML/Pipelines).
+   - Regra de descoberta de subespecificações (via `Glob`/`Read`, não invenção).
+   - Template canônico de `operating-system/architecture.md` numerado por especificação (com seção "10. Pendências de Mapeamento" cap 10 itens).
+   - Checklist do agente ao gerar.
+2. **Tornar obrigatório** chamar este protocolo em ambos os fluxos:
+   - `bootstrap/existing-project.md` — passo 5 do TL;DR e passo 5 do "Popular Memória" exigem aplicar `tech-mapping.md`.
+   - `bootstrap/new-project.md` — passo 3 do "Após Confirmação" exige aplicar `tech-mapping.md`; checklist final de "bootstrap completo" inclui linha "architecture.md populado via tech-mapping".
+3. **Promover folder-structure.md** para diferenciar duas camadas:
+   - **Macro** = organização por especificação técnica (Frontend/Backend/Infra...) — referência ao `tech-mapping.md`.
+   - **Micro** = organização interna por feature/domínio (regras pré-existentes).
+4. **Registrar a nova rota** no `ROUTER.md`: trigger "mapa técnico / tech-mapping / organizar projeto / especifica" → carrega `tech-mapping.md` + `architecture.md` + `folder-structure.md`.
+5. **Manifesto** (`manifest.json`): `tech-mapping.md` adicionado a `required_files`.
+6. **INDEX**: listar `tech-mapping.md` na seção Bootstrap.
+
+### Consequências
+- **Positivas**:
+  - Sempre que um projeto adota o `.ai/`, sai com **mapa técnico explícito por especificação**. Onboarding (humano ou agente) cai radicalmente.
+  - Reduz alucinação: o agente consulta `architecture.md` antes de propor mudança de módulo/integração.
+  - Padronização cross-project: todo `architecture.md` tem o mesmo esqueleto numerado.
+  - Pendências viram trabalho concreto (seção 10), não buraco invisível.
+- **Negativas / trade-offs aceitos**:
+  - Primeiro bootstrap em projeto existente fica mais longo (~10-30 min a mais para inventariar). Aceito porque amortiza nas próximas N sessões.
+  - Risco de o template virar fóssil se ninguém atualizar — mitigação: regra `tech-mapping.md` "toda PR que mexer em arquitetura atualiza este doc"; auditoria trimestral.
+- **Neutras**:
+  - Projetos novos começam com seções quase vazias mas com esqueleto; mais valor à medida que crescem.
+
+### Alternativas consideradas
+1. **Deixar `architecture.md` livre, só dar exemplos** — descartado: já era o estado anterior e mostrou que vira raso.
+2. **Categorizar por feature em vez de especificação técnica** — descartado: feature é a **camada micro**; sem a macro, perde-se a visão "onde mora o backend?" / "quais integrações temos?". Os dois níveis coexistem.
+3. **Forçar uma estrutura de pastas física por especificação** (raiz com `frontend/`, `backend/` etc.) — descartado: muitos monorepos pequenos têm `src/` + `server/` por razões históricas; impor reorganização física quebra projetos legados. O `architecture.md` documenta o mapeamento.
+
+### Referências
+- Caso real que motivou: instalação do `.ai/` no subprojeto **Strak** (`sistema-de-diesel/`) — ver `memory/completed-tasks.md` entrada de 2026-05-14.
+- Arquivos tocados: `.ai/bootstrap/tech-mapping.md` (novo), `.ai/bootstrap/existing-project.md`, `.ai/bootstrap/new-project.md`, `.ai/operating-system/folder-structure.md`, `.ai/INDEX.md`, `.ai/manifest.json`, `.ai/ROUTER.md`.
+
+## ADR-0001 — Guard-edit cobre Bash + bypass via `.claude/.unlock`
+- Data: 2026-05-14
+- Status: Aceito
+- Decisor: usuário (autorização explícita "pode realizar essa pendencia") + agente
+
+### Contexto
+IMP-001 (proposto em 2026-05-14) identificou que o hook `guard-edit.{ps1,sh}` registrado com matcher `Edit|Write|NotebookEdit` deixava passar edições via `Bash` (`Set-Content`, redirects, `fs.writeFileSync`, etc.) em arquivos protegidos (`CONTRACT.md`, `settings.json`, hooks, etc.). Além disso, os dois scripts de guard estavam **corrompidos** desde alguma edição anterior — arrays de regex sem fechamento e lógica duplicada 3x.
+
+### Decisão
+1. **Reescrever** `guard-edit.ps1` e `guard-edit.sh` limpos (substring match em lower-case, sem regex frágil).
+2. **Adicionar branch Bash** ao guard: detecta verbos de escrita (`Set-Content`, `Out-File`, `Add-Content`, `Clear-Content`, `Tee-Object`, `New-Item`, `Remove-Item`, `Move-Item`, `Copy-Item`, `fs.writeFile*`, `fs.appendFile*`, `fs.unlink*`, `fs.rm*`, `rm `, `mv `, `cp `, `tee `, `sed -i`, `> path`, `>> path`) cruzados com lista de paths protegidos. Bloqueia se houver match.
+3. **Override autorizado via sentinela**: se `.claude/.unlock` existe (qualquer conteúdo, basta a existência), o guard sai com `exit 0` imediatamente. Usuário cria com `New-Item .claude/.unlock` ou `touch .claude/.unlock`; remove com `Remove-Item .claude/.unlock` para restaurar proteção.
+4. **Atualizar matcher** em `.claude/settings.json` e `.claude/settings.unix.json` de `Edit|Write|NotebookEdit` para `Edit|Write|NotebookEdit|Bash`.
+
+### Consequências
+- **Positivas**:
+  - Fecha o bypass descrito em IMP-001.
+  - Corrige a corrupção pré-existente nos guards.
+  - Mantém UX: usuário pode autorizar mudança pontual sem editar manualmente o hook (`.unlock`).
+  - Auditável: criação/remoção de `.unlock` é visível no filesystem.
+- **Negativas / trade-offs aceitos**:
+  - Falsos positivos possíveis em Bash quando o comando contém um verbo de escrita + nome de path protegido sem intenção destrutiva (ex: `grep "Set-Content" .claude/settings.json` bloqueia). Mitigação: `.unlock` resolve em 1 comando.
+  - `.unlock` é um interruptor global (não por-path). Decisão consciente em favor da simplicidade — escopo por-path foi descartado por complicar parsing/expiração.
+- **Neutras**:
+  - O guard agora roda em **todo** Bash, não só os com Edit/Write. Custo: ~10-30ms por chamada de Bash. Aceitável.
+
+### Alternativas consideradas
+1. **Apenas branch Bash, sem `.unlock`** — descartado porque deixaria o usuário sem escape hatch quando o agente legitimamente precisa modificar um protegido.
+2. **`.unlock` com TTL/timestamp e lista de paths** — descartado por complexidade desproporcional ao ganho; existência simples atende.
+3. **Lista de comandos seguros (allowlist) em vez de detecção de verbos de escrita** — descartado: lista cresce indefinidamente; detecção de verbos cobre 95% dos casos com menor manutenção.
+
+### Referências
+- IMP-001 em `evolution/improvements.md` (status: aplicado por ADR-0001).
+- Arquivos tocados: `.ai/hooks/guard-edit.ps1`, `.ai/hooks/guard-edit.sh`, `.claude/settings.json`, `.claude/settings.unix.json`.
+
+## ADR-0002 — TypeScript + ts-morph + commander para Runtime v0.1
+- Data: 2026-05-15
+- Status: Aceito
+- Decisor: usuário (autorização explícita via AskUserQuestion: "TypeScript + deps controladas — Recomendado") + agente
+
+### Contexto
+O AI Operating System (v4.0.0) entregou estrutura passiva sólida: 91+ arquivos markdown + MCP daemon Node.js (`aios-server.mjs`) com 12 tools de lookup/leitura. Toda a "inteligência" estava em **documentos**, não em **código executável**. Pesquisa do Founder (refs do mercado AI-DOS / Devin / OpenHands) identificou três componentes de alto ROI ausentes: Context Packager (semantic compression), Project State Engine (AST + grafo + smells), Snapshot System. Implementar AST decente em TS/JS sem parser real é inviável (regex falha em re-exports, barrel files, type-only imports).
+
+### Decisão
+Adotar TypeScript + dependências controladas para o Runtime v0.1, mantendo `aios-server.mjs` como entry `.mjs` puro que importa `dist/index.mjs` (bundle único gerado por esbuild). Stack:
+- `ts-morph@^22` (runtime) — AST tipado sobre tsc.
+- `commander@^12` (runtime) — CLI tipada para futuros entrypoints.
+- `typescript@^5.4`, `esbuild@^0.21`, `@types/node@^20` (devDeps).
+
+Estrutura: `.ai/server/src/{types,index}.ts` + `analyzer/` + `packager/` + `snapshot/`. Build via `npm install && npm run build` → `.ai/server/dist/index.mjs`. Daemon faz `import()` opcional do bundle: se ausente, as 12 tools base continuam funcionando (graceful degradation), as 5 v0.1 retornam erro descritivo.
+
+### Consequências
+- **Positivas**:
+  - AST parsing confiável (ts-morph cobre o que tsc cobre).
+  - TypeScript em dev → menos bugs por type-error em código complexo (analyzer/packager).
+  - Bundle único `dist/index.mjs` — runtime continua sem `node_modules` em produção quando build é feito.
+  - `aios-server.mjs` permanece `.mjs` puro, sem build próprio.
+- **Negativas / trade-offs aceitos**:
+  - Quebra a regra "NUNCA instalar dependência nova sem justificar e pedir confirmação" do CLAUDE.md global. Mitigação: este ADR + aprovação explícita via AskUserQuestion.
+  - Requer `npm install` + `npm run build` na primeira vez. Mitigação: `start-os.{ps1,sh}` detecta ausência de `dist/` e orienta. Daemon continua útil mesmo sem build (12 tools base).
+- **Neutras**:
+  - `dist/` gerado (gitignored). `package-lock.json` versionado para reprodutibilidade.
+
+### Alternativas consideradas
+1. **Manter zero-deps (`.mjs` puro)** — descartado porque AST decente em Node nativo é inviável; resultado seria menos confiável que o status quo.
+2. **TypeScript + ts-morph sem bundler** — descartado: `node_modules/` em produção (>500 arquivos), divergência dev/prod, mais difícil de auditar.
+3. **SQLite (better-sqlite3) para storage** — descartado para v0.1; JSON sidecar + Markdown atende. SQLite só se justifica quando queries complexas (ranking, joins, FTS) virarem necessárias.
+
+### Referências
+- ADR completo: `.ai/specs/ADR/ADR-0002-typescript-runtime.md`.
+- IMP-003 em `evolution/improvements.md` (status: aplicado por ADR-0002).
+- Arquivos tocados: `.ai/server/package.json`, `.ai/server/tsconfig.json`, `.ai/server/.gitignore`, `.ai/server/src/**`, `.ai/server/README.md`, `.ai/server/aios-server.mjs` (wiring), `.ai/manifest.json` (bump 4.0.0 → 4.1.0 + capabilities), `.ai/INDEX.md`, `.ai/ROUTER.md` (3 novas rotas), `.claude/commands/{analyze,context,snapshot}.md`.
+- Plano completo: arquivado no histórico local do Claude Code (não versionado).

package/ai/memory/errors-and-solutions.md

@@ -0,0 +1,41 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~varies
+load: bugs
+mutable: append_only
+triggers: bug, erro, error, falha
+---
+
+# Errors and Solutions
+
+> Catálogo de erros observados + correções validadas. Antes de debugar, conferir aqui.
+
+## Formato
+
+```
+## ERR-NNN — Título curto do sintoma
+- Data: AAAA-MM-DD
+- Contexto: onde aconteceu (módulo, arquivo, ambiente)
+- Sintoma: mensagem de erro, comportamento observado
+- Causa raiz: explicação técnica do POR QUÊ
+- Correção: o que foi feito (com referência a commit/PR se houver)
+- Reprodução: passos mínimos para reproduzir (se aplicável)
+- Prevenção: teste/lint/check que impede regressão
+```
+
+## Regras
+
+1. Só registrar erro com **causa raiz identificada**. Sintoma sem causa vai para `known-issues.md`.
+2. Se o mesmo erro reaparecer, atualizar a entrada (incrementar contador de ocorrências).
+3. Se a causa raiz se repete em 3+ entradas distintas → considerar `evolution/patterns-discovered.md`.
+4. Linkar para `decisions.md` se a correção envolveu decisão arquitetural.
+
+## Anti-padrão
+
+- "Resolvi reiniciando" não é solução — é workaround. Registrar como `known-issues.md` até causa raiz.
+
+## Entradas
+
+<!-- adicionar abaixo -->

package/ai/memory/known-issues.md

@@ -0,0 +1,40 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~varies
+load: bugs
+mutable: true
+triggers: bug, erro, problema conhecido
+---
+
+# Known Issues
+
+> Problemas conhecidos SEM solução definitiva. Workarounds, limitações, débitos.
+
+## Formato
+
+```
+## ISSUE-NNN — Título
+- Data: AAAA-MM-DD (primeira observação)
+- Severidade: baixa | média | alta | crítica
+- Frequência: rara | ocasional | frequente | constante
+- Sintoma: o que se observa
+- Impacto: a quem afeta, com que magnitude
+- Hipóteses de causa: lista (marcar "confirmado" ou "especulação")
+- Workaround atual: como contornar enquanto não há fix
+- Tentativas anteriores: o que já foi testado e NÃO resolveu
+- Próximos passos: investigação pendente
+- Issue tracker: link externo (Jira, GitHub) se houver
+```
+
+## Regras
+
+1. Quando causa raiz é identificada → MOVER para `errors-and-solutions.md` (com referência ao ISSUE-NNN original).
+2. Se o issue persiste >3 meses sem progresso → reclassificar severidade e impacto.
+3. Registrar tentativas falhadas para evitar repeti-las.
+4. Não confundir com `pending-tasks.md`: aqui é problema sem fix; lá é trabalho planejado.
+
+## Entradas
+
+<!-- adicionar abaixo -->

package/ai/memory/pending-tasks.md

@@ -0,0 +1,37 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: on_demand
+tokens: ~varies
+load: backlog_review
+mutable: true
+---
+
+# Pending Tasks
+
+> Backlog ativo. Itens em andamento ou esperando para começar.
+
+## Formato
+
+```
+## [PRIORIDADE] Título
+- Criado: AAAA-MM-DD
+- Origem: bug, feature request, refactor, débito técnico, ...
+- Critério de aceite: como sabemos que está pronto
+- Dependências: outras tasks ou condições
+- Owner sugerido: usuário, agente, ...
+- Status: backlog | in-progress | blocked
+```
+
+Prioridades: **P0** (crítico), **P1** (alto), **P2** (médio), **P3** (baixo).
+
+## Regras
+
+1. Mover para `completed-tasks.md` ao finalizar.
+2. Se bloqueado >7 dias → registrar motivo + mover para `known-issues.md` se for problema real.
+3. Não duplicar entre arquivos.
+4. Revisar prioridades periodicamente — task de 6 meses na P0 não é P0.
+
+## Entradas
+
+<!-- adicionar abaixo -->

package/ai/memory/project-context.md

@@ -0,0 +1,67 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: core
+tokens: ~varies
+load: always
+mutable: true
+---
+
+# Project Context
+
+> Contexto validado do projeto. NÃO escrever hipóteses aqui — apenas fatos confirmados.
+
+## Identificação
+
+- **Nome do projeto**: _(preencher)_
+- **Stakeholder principal**: _(preencher)_
+- **Objetivo de negócio**: _(preencher)_
+- **Data de início**: _(preencher)_
+
+## Stack Técnica (confirmada)
+
+- **Linguagens**: _(preencher quando conhecido)_
+- **Frameworks**: _(preencher)_
+- **Banco de dados**: _(preencher)_
+- **Infraestrutura**: _(preencher)_
+- **CI/CD**: _(preencher)_
+
+## Ambientes
+
+| Ambiente | URL | Branch | Notas |
+|---|---|---|---|
+| dev | | | |
+| staging | | | |
+| prod | | | |
+
+## Ferramentas disponíveis ao agente
+
+- MCPs ativos: _(listar conforme descoberto via `tools/mcp-discovery.md`)_
+- Acesso a: _(GitHub? GCP? AWS? Slack? ...)_
+
+## Convenções específicas deste projeto
+
+- _(adicionar conforme validado)_
+
+## Restrições
+
+- Janela de deploy: _(preencher)_
+- Janelas de blackout: _(preencher)_
+- Compliance / regulação: _(preencher — LGPD, PCI, HIPAA, etc.)_
+
+## Pessoas
+
+| Papel | Nome | Contato |
+|---|---|---|
+| Product Owner | | |
+| Tech Lead | | |
+| DevOps | | |
+
+---
+
+## Regras de manutenção deste arquivo
+
+1. Só registrar o que foi **confirmado** (lido em código, dito explicitamente pelo usuário, ou observado em execução).
+2. Marcar com `?` qualquer item não 100% certo.
+3. Remover seções inteiras se não se aplicam — não deixar placeholders eternos.
+4. Em conflito com a realidade observada → atualizar este arquivo antes de prosseguir.

package/ai/operating-system/architecture.md

@@ -0,0 +1,54 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~400
+load: architecture
+triggers: arquitetura, architecture, design
+---
+
+# Operating System: Architecture
+
+> Visão arquitetural do projeto. Deve ser lida no carregamento inicial pelo agente.
+
+## Diagrama de Alto Nível
+
+_(preencher conforme o projeto se materializa — manter atualizado)_
+
+```
+[ Client ] → [ API Gateway ] → [ Services ] → [ DB / Cache / Queue ]
+```
+
+## Camadas
+
+| Camada | Responsabilidade | Pode depender de |
+|---|---|---|
+| Presentation | UI / HTTP handlers | Application |
+| Application | Casos de uso, orquestração | Domain, Infrastructure (via interfaces) |
+| Domain | Regras de negócio puras | (nada externo) |
+| Infrastructure | DB, HTTP clients, filas, FS | (implementa interfaces de Application) |
+
+**Regra de dependência**: setas só apontam para dentro (Clean / Hexagonal).
+
+## Boundaries
+
+- Cada bounded context tem seu próprio módulo / pacote.
+- Comunicação entre contextos: eventos > chamada direta.
+- Modelos de domínio NÃO são DTOs de API — usar mappers.
+
+## Cross-cutting
+
+- Logging, tracing, autenticação, autorização → middleware/decorators, não duplicado.
+- Configuração: variáveis de ambiente carregadas em um único módulo de config tipado.
+- Erros: hierarquia de classes (DomainError, ValidationError, NotFoundError, ...) mapeadas para HTTP no Presentation.
+
+## Trade-offs Aceitos
+
+_(listar conforme decisões registradas em `memory/decisions.md`)_
+
+## Reversibilidade
+
+- Decisões reversíveis: estilo, estrutura de pastas internas, libs utilitárias.
+- Difíceis de reverter: banco escolhido, modelo de auth, formato de IDs, tenancy model.
+
+→ Decisões difíceis exigem ADR e análise de alternativas registrada.

package/ai/operating-system/coding-standards.md

@@ -0,0 +1,84 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~600
+load: coding, refactor
+triggers: refactor, naming, convenção, style, lint, prettier, eslint
+---
+
+# Coding Standards
+
+## Princípios Gerais
+
+- **Legível > clever.** Código é lido 10x mais do que escrito.
+- **Nomes explícitos.** `usersAwaitingApproval`, não `temp` ou `data2`.
+- **Funções pequenas.** Se passa de ~50 linhas ou >3 níveis de indentação, quebrar.
+- **Sem comentários óbvios.** Comentar o **por quê**, não o **o quê**.
+
+## Naming
+
+- Constantes: `SCREAMING_SNAKE_CASE`
+- Funções/variáveis: `camelCase` (JS/TS) | `snake_case` (Python)
+- Classes/Tipos: `PascalCase`
+- Booleans: prefixo `is_`, `has_`, `should_`, `can_`
+- Arquivos: convenção do ecossistema (kebab-case em web; snake_case em python; PascalCase em componentes React)
+
+## Estrutura de arquivo
+
+- Imports no topo, agrupados: stdlib → terceiros → projeto.
+- Exports no fim ou inline.
+- Uma responsabilidade clara por arquivo.
+
+## Funções
+
+- Argumentos: ≤ 4. Mais que isso → objeto/struct.
+- Sem efeitos colaterais ocultos. Side effect intencional → nome do método indica.
+- Retorno consistente — mesmo tipo em todos os caminhos.
+
+## Tipos
+
+- TS estrito (`strict: true`). `any` proibido sem comentário justificando.
+- Python com type hints em todo código novo.
+- Tipos em boundaries (entrada/saída de função pública) sempre.
+
+## Erros
+
+- Lançar erros tipados, com contexto suficiente.
+- Não engolir erros (`catch (e) {}` proibido sem comentário).
+- Erros esperados → retorno `Result<T, E>` ou equivalente; inesperados → throw.
+
+## Imports
+
+- Sem imports circulares.
+- Sem wildcards (`import *`).
+- Caminhos absolutos para módulos do projeto (`@/foo`) > relativos longos (`../../../foo`).
+
+## Comentários
+
+- Permitidos: motivo de hack, link para issue, invariante não-óbvio, edge case.
+- Proibidos: explicar código óbvio, TODOs sem owner+data, comentário de versão antiga.
+
+## Formatação
+
+- Prettier / Black / Ruff / equivalente — configurado, rodando em pre-commit.
+- Sem debate de espaços vs tabs no PR — config é fonte da verdade.
+
+## Git
+
+- Commits atômicos. Mensagem no imperativo: "Add X", não "Added X".
+- Sem `WIP` em main. Sem `git commit -am "fix"` sem descrição.
+- PR descrito: o que muda, por quê, como testar.
+
+## Linguagem-específico
+
+_(adicionar seções abaixo conforme stack do projeto)_
+
+### TypeScript
+- `strict: true`, `noUncheckedIndexedAccess: true`.
+- Prefira `interface` para shape de objeto; `type` para union/intersection.
+
+### Python
+- PEP 8 via ruff/black.
+- `from __future__ import annotations` em arquivos com typing.
+- Evitar mutable default arguments.