sinapse-ai 7.7.10 → 8.0.0

package/docs/pt/roadmap.md

@@ -28,7 +28,7 @@ Estabilização do framework principal e infraestrutura da comunidade:
 
 - [x] Configuração do GitHub Discussions
 - [x] Guias de contribuição (CONTRIBUTING.md, COMMUNITY.md)
-- [x] Processo de solicitação de features (FEATURE_PROCESS.md)
+- [x] Processo de solicitação de features (feature-process.md)
 - [x] Roadmap público (este documento!)
 - [ ] Registro de Squads
 
@@ -75,7 +75,7 @@ Para features significativas que precisam de design detalhado, [submeta um RFC](
 
 ### 4. Contribua Diretamente
 
-Encontrou algo que quer implementar? Veja nosso [Guia de Contribuição](CONTRIBUTING-PT.md) e [Processo de Features](docs/FEATURE_PROCESS.md).
+Encontrou algo que quer implementar? Veja nosso [Guia de Contribuição](CONTRIBUTING-PT.md) e [Processo de Features](docs/feature-process.md).
 
 ## Changelog
 

package/docs/pt/security.md

@@ -1,124 +1,260 @@
-# Política de Segurança
+# Guia de Seguranca SINAPSE-AI
 
-> 🇺🇸 [English Version](SECURITY.md)
+> Para reportar vulnerabilidades, veja [SECURITY.md](../../SECURITY.md)
 
-## Versões Suportadas
+---
 
-Lançamos patches para vulnerabilidades de segurança nas seguintes versões:
+## Indice
 
-| Versão | Suportada          |
-| ------ | ------------------ |
-| 2.1.x  | :white_check_mark: |
-| < 2.1  | :x:                |
+1. [Visao Geral da Arquitetura de Seguranca](#visao-geral-da-arquitetura-de-seguranca)
+2. [Gestao de Secrets](#gestao-de-secrets)
+3. [Modelo de Confianca MCP](#modelo-de-confianca-mcp)
+4. [Limites de Seguranca dos Agentes](#limites-de-seguranca-dos-agentes)
+5. [Arquitetura de Hooks](#arquitetura-de-hooks)
+6. [Boas Praticas para Usuarios](#boas-praticas-para-usuarios)
+7. [Aplicacao Constitucional](#aplicacao-constitucional)
 
-## Reportando uma Vulnerabilidade
+---
 
-Levamos a segurança a sério na SinapseAI. Se você descobrir uma vulnerabilidade de segurança no SINAPSE, por favor reporte de forma responsável.
+## Visao Geral da Arquitetura de Seguranca
+
+O SINAPSE-AI implementa um modelo de seguranca em profundidade com multiplas camadas de aplicacao:
+
+```
+Constitution (Artigo X)
+  |
+  +-- 25 Bloqueadores Pre-Deploy (3 tiers)
+  |     +-- Tier 1: Bloqueadores Absolutos (deploy impossivel)
+  |     +-- Tier 2: Bloqueadores de Compliance (LGPD)
+  |     +-- Tier 3: Bloqueadores Operacionais
+  |
+  +-- 19 Hooks Claude Code (aplicacao em tempo real)
+  |     +-- Varredura de secrets
+  |     +-- Governanca SQL
+  |     +-- Gates de arquitetura primeiro
+  |     +-- Controle de autoridade de push
+  |
+  +-- Quality Gates (pre-commit, PR, revisao humana)
+```
+
+Seguranca nao e opcional no SINAPSE-AI. E aplicada no nivel constitucional (Artigo X -- NON-NEGOTIABLE) e automatizada atraves de hooks e gates que bloqueiam violacoes antes de chegarem a producao.
 
-### Como Reportar
+---
 
-**NÃO** crie uma issue pública no GitHub para vulnerabilidades de segurança.
+## Gestao de Secrets
 
-Em vez disso, reporte vulnerabilidades de segurança através de um destes canais:
+### Como o SINAPSE-AI Trata Secrets
 
-1. **GitHub Security Advisories** (Preferido)
-   - Vá para [Security Advisories](https://github.com/SinapseAI/sinapse-ai/security/advisories)
-   - Clique em "Report a vulnerability"
-   - Preencha o formulário com detalhes
+O SINAPSE-AI usa um sistema de varredura de secrets baseado em hooks que roda em toda operacao de escrita e commit.
 
-2. **GitHub Issues (Privado)**
-   - Abra um [security advisory privado](https://github.com/SinapseAI/sinapse-ai/security/advisories)
-   - Use a linha de assunto: `[SECURITY] Breve descrição`
+**Hook ativo:** `secret-scanning.cjs`
 
-### O Que Incluir
+**Padroes varridos incluem:**
+- Chaves de acesso e secrets AWS
+- Chaves de API Stripe (live e teste)
+- Chaves privadas SSH (RSA, ED25519, ECDSA)
+- Tokens GitHub (pessoal, OAuth, app)
+- Chaves de API e credenciais OAuth Google
+- Tokens e webhooks Slack
+- Strings de conexao de banco com credenciais embutidas
+- Tokens JWT e Bearer
+- Strings genericas de alta entropia que correspondem a padroes de chaves
 
-Por favor, inclua o seguinte em seu relatório:
+**Comportamento na deteccao:**
+- O commit e **bloqueado** imediatamente
+- O agente e notificado com o arquivo e padrao especificos
+- O arquivo e removido do staging
+- O usuario e avisado para rotacionar a credencial detectada
 
-- **Descrição**: Uma descrição clara da vulnerabilidade
-- **Impacto**: O que um atacante poderia conseguir com esta vulnerabilidade?
-- **Passos para Reproduzir**: Passos detalhados para reproduzir o problema
-- **Versões Afetadas**: Quais versões são afetadas?
-- **Possível Correção**: Se você tiver sugestões de como corrigir o problema
-- **Suas Informações**: Nome/identificador para reconhecimento (opcional)
+### Regras de Variaveis de Ambiente
 
-### O Que Esperar
+| Regra | Aplicacao |
+|-------|----------|
+| Arquivos `.env` devem estar no `.gitignore` | Hook bloqueia commits contendo `.env` |
+| `.env.example` deve usar placeholders | Revisao manual durante QA gate |
+| Variaveis `NEXT_PUBLIC_*` sao publicas | Nunca coloque secrets em `NEXT_PUBLIC_*` |
+| Chaves `service_role` nunca no frontend | Hook varre diretorios `src/`, `app/`, `pages/` |
 
-1. **Confirmação**: Confirmaremos o recebimento em até 48 horas
-2. **Avaliação Inicial**: Forneceremos uma avaliação inicial em até 5 dias úteis
-3. **Atualizações**: Manteremos você informado sobre nosso progresso
-4. **Resolução**: Visamos resolver problemas críticos em até 30 dias
-5. **Divulgação**: Coordenaremos o timing da divulgação com você
+---
 
-### Safe Harbor
+## Modelo de Confianca MCP
 
-Consideramos pesquisa de segurança conduzida de acordo com esta política como:
+O SINAPSE-AI usa uma abordagem em camadas para confianca de servidores MCP (Model Context Protocol):
 
-- Autorizada em relação a quaisquer leis anti-hacking aplicáveis
-- Autorizada em relação a quaisquer leis anti-circumvenção relevantes
-- Isenta de restrições em nossos Termos de Serviço que interfeririam na condução de pesquisa de segurança
+### Isolamento Docker
 
-Não perseguiremos ação civil nem iniciaremos reclamação às autoridades para violações acidentais e de boa fé desta política.
+Servidores MCP que requerem autenticacao ou acessam servicos externos rodam dentro de containers Docker via Docker MCP Toolkit. Isso fornece:
 
-## Melhores Práticas de Segurança
+- **Isolamento de processo:** Servidores MCP nao podem acessar o filesystem do host diretamente
+- **Segmentacao de rede:** Cada container tem seu proprio namespace de rede
+- **Isolamento de credenciais:** Chaves de API sao injetadas via variaveis de ambiente Docker, nao armazenadas em arquivos do projeto
 
-Ao usar o SINAPSE Framework, recomendamos:
+### Preferencia por Ferramentas Nativas
 
-### Variáveis de Ambiente
+O SINAPSE-AI sempre prefere ferramentas nativas do Claude Code sobre equivalentes MCP:
 
-- Nunca commite arquivos `.env` para controle de versão
-- Use `.env.example` como template sem valores reais
-- Rotacione chaves de API e segredos regularmente
+| Tarefa | Ferramenta Preferida | Motivo |
+|--------|---------------------|--------|
+| Leitura/escrita de arquivos | Read, Write, Edit | Executa localmente, sem rede |
+| Busca | Grep, Glob | Mais rapido, sem chamadas externas |
+| Comandos | Bash | Execucao direta no host |
 
-### Segurança de Servidores MCP
+Servidores MCP so sao usados quando ferramentas nativas nao podem fornecer a capacidade requerida (busca web, automacao de navegador, acesso a APIs externas).
 
-- Habilite apenas servidores MCP de fontes confiáveis
-- Revise o código do servidor MCP antes de habilitar
-- Use ambientes de execução em sandbox quando disponíveis
-- Limite permissões do servidor MCP ao mínimo necessário
+### Governanca MCP
 
-### Segurança de Agentes IA
+Apenas o agente DevOps (`@devops` / Pipeline) tem autoridade para:
+- Adicionar ou remover servidores MCP
+- Configurar credenciais MCP
+- Gerenciar infraestrutura Docker MCP
+
+Outros agentes sao apenas consumidores -- nao podem modificar a configuracao MCP.
+
+---
 
-- Tenha cuidado com comandos de agentes que executam operações de sistema
-- Revise código gerado antes de executar em produção
-- Use controles de acesso apropriados para operações sensíveis
+## Limites de Seguranca dos Agentes
 
-### Gerenciamento de Dependências
+### Camadas de Protecao do Framework (L1-L4)
 
-- Mantenha dependências atualizadas
-- Execute `npm audit` regularmente
-- Revise mudanças de dependências em pull requests
+O SINAPSE-AI aplica um modelo de fronteira de 4 camadas que controla o que agentes podem e nao podem modificar:
 
-## Considerações de Segurança Conhecidas
+| Camada | Protecao | O Que Contem |
+|--------|----------|-------------|
+| **L1** Core do Framework | NUNCA modificar | Modulos core, Constitution, binarios CLI |
+| **L2** Templates do Framework | NUNCA modificar | Tasks, templates, checklists, workflows |
+| **L3** Config do Projeto | Controlado | Arquivos de dados, memoria de agentes, config |
+| **L4** Runtime do Projeto | Aberto | Stories, packages, testes |
 
-### Arquitetura do Framework
+Essas fronteiras sao aplicadas deterministicamente atraves de deny rules em `.claude/settings.json`, nao pelo sistema de honra dos agentes.
 
-O SINAPSE Framework executa código e comandos gerados por IA. Usuários devem:
+### Matriz de Autoridade dos Agentes
 
-- Entender que agentes IA podem executar código arbitrário
-- Usar sandboxing apropriado para ambientes não confiáveis
-- Revisar saídas geradas por IA antes de deploy em produção
+Cada agente tem permissoes explicitas definindo quais operacoes pode executar:
+
+| Agente | Pode Fazer | Nao Pode Fazer |
+|--------|-----------|----------------|
+| `@developer` | Escrever codigo, commit local | Push para remote, criar PRs |
+| `@devops` | Push, criar PRs, gerenciar CI | Escrever codigo de aplicacao |
+| `@architect` | Decisoes de design | Escrever codigo de implementacao |
+| `@data-engineer` | Design de schema, migracoes | Codigo de aplicacao, git push |
+
+O hook `enforce-delegation.cjs` bloqueia agentes orquestradores de executar trabalho de dominio diretamente, aplicando a matriz de delegacao em tempo de execucao.
+
+### Autoridade de Git Push
+
+Apenas `@devops` (Pipeline) pode executar `git push`. O hook `enforce-git-push-authority.sh` intercepta todos os comandos Bash e bloqueia qualquer tentativa de push de outros agentes.
+
+---
 
-### Tratamento de Dados
+## Arquitetura de Hooks
 
-- SINAPSE pode processar dados sensíveis através de provedores de IA
-- Revise as políticas de tratamento de dados do seu provedor de IA
-- Considere a classificação de dados ao usar recursos de IA
+O SINAPSE-AI usa 19 hooks Claude Code organizados por evento de trigger:
 
-## Atualizações de Segurança
+### Mapa de Eventos dos Hooks
 
-Atualizações de segurança são anunciadas através de:
+| Evento | Hook | Proposito | Comportamento |
+|--------|------|-----------|---------------|
+| **UserPromptSubmit** | `synapse-wrapper.cjs` | Injecao de contexto | Permitir |
+| **PreToolUse (Bash)** | `enforce-git-push-authority.sh` | Bloquear push nao autorizado | Bloquear |
+| **PreToolUse (Bash)** | `sql-governance.py` | Bloquear SQL perigoso | Bloquear |
+| **PreToolUse (Bash)** | `enforce-delegation.cjs` | Bloquear trabalho direto de orquestradores | Bloquear |
+| **PreToolUse (Write/Edit)** | `enforce-architecture-first.cjs` | Exigir docs antes de codigo | Bloquear |
+| **PreToolUse (Write/Edit)** | `write-path-validation.cjs` | Avisar sobre paths errados | Avisar |
+| **PreToolUse (Write/Edit)** | `enforce-story-gate.cjs` | Exigir story para codigo | Bloquear |
+| **PreToolUse (Write/Edit)** | `slug-validation.py` | Validar nomenclatura | Avisar |
+| **PreToolUse (Write/Edit)** | `mind-clone-governance.py` | Exigir DNA para clones | Bloquear |
+| **PreToolUse (Write/Edit)** | `enforce-delegation.cjs` | Bloquear trabalho direto de orquestradores | Bloquear |
+| **PreToolUse (Read)** | `read-protection.py` | Controlar acesso a arquivos sensiveis | Avisar |
+| **PreCompact** | `precompact-wrapper.cjs` | Captura de digest de sessao | Permitir |
 
-- [GitHub Security Advisories](https://github.com/SinapseAI/sinapse-ai/security/advisories)
-- [CHANGELOG.md](./CHANGELOG.md)
-- GitHub Releases
+### Principios de Design
 
-## Reconhecimentos
+1. **Fail-open** -- Se um hook falha ou nao consegue parsear a entrada, sai com codigo 0 (permitir). Isso previne que bugs em hooks bloqueiem todo o desenvolvimento.
+2. **Rapido** -- Cada hook deve completar em menos de 5 segundos.
+3. **Silencioso no sucesso** -- Hooks so produzem saida ao bloquear ou avisar.
+4. **Deterministico** -- Mesma entrada sempre produz a mesma saida.
+5. **Sem efeitos colaterais** -- Hooks leem estado mas nao o modificam.
 
-Agradecemos aos seguintes pesquisadores por divulgar responsavelmente problemas de segurança:
+### Protocolo de Exit Code
+
+| Codigo | Significado | Efeito |
+|--------|------------|--------|
+| 0 | Permitir | Operacao procede normalmente |
+| 2 | Bloquear | Operacao negada, mensagem exibida |
+| Outro | Ignorado | Tratado como 0 (permitir) |
+
+---
+
+## Boas Praticas para Usuarios
+
+### Apos Instalar o SINAPSE-AI
+
+1. **Verificar instalacao de hooks**: Execute `npx sinapse-ai doctor` para confirmar que todos os hooks estao registrados
+2. **Checar `.gitignore`**: Garanta que `.env`, `.sinapse/`, e outros paths sensiveis estao listados
+3. **Revisar servidores MCP**: Habilite apenas servidores MCP em que voce confia e precisa
+4. **Configurar protecao de branch**: Habilite protecao de branch em `main` nas configuracoes do GitHub
+
+### Durante o Desenvolvimento
+
+1. **Nunca commite arquivos `.env`** -- Use `.env.example` com valores placeholder
+2. **Use queries parametrizadas** -- Nunca use interpolacao de strings para SQL
+3. **Revise codigo gerado** -- Codigo gerado por IA deve ser revisado antes de producao
+4. **Mantenha dependencias atualizadas** -- Execute `npm audit` regularmente
+5. **Use feature branches** -- O SINAPSE-AI cria branches automaticamente e nunca trabalha em `main`
+
+### Para Deploys em Producao
+
+1. **Habilite RLS em todas as tabelas** com dados de usuarios (veja [Padroes RLS](../../.sinapse-ai/data/rls-security-patterns.md))
+2. **Nunca exponha chaves `service_role`** em codigo frontend
+3. **Configure CORS** com origens explicitas (nunca use `origin: '*'` em producao)
+4. **Adicione rate limiting** em todos os endpoints publicos de API
+5. **Configure headers de seguranca** usando helmet ou middleware equivalente
+
+---
 
-*Nenhum relatório ainda - seja o primeiro!*
+## Aplicacao Constitucional
+
+A Constitution do SINAPSE-AI (Artigo X -- Seguranca e Protecao de Dados) define 25 bloqueadores obrigatorios de pre-deploy:
+
+### Tier 1: Bloqueadores Absolutos (10 itens)
+
+Tornam o deploy impossivel se violados:
+- Tabelas sem RLS habilitado
+- Chaves de API hardcoded no codigo fonte
+- `service_role` exposto no frontend
+- MFA ausente em contas admin
+- APIs sem autenticacao
+- SQL com concatenacao de strings
+- Vulnerabilidades critical/high em dependencias
+- Secrets detectados no codebase
+- Credenciais default em producao
+- Criptografia TLS ausente
+
+### Tier 2: Bloqueadores de Compliance (7 itens)
+
+Tornam o deploy ilegal no Brasil (LGPD):
+- DPO/Encarregado ausente
+- Sem capacidade de notificacao de breach
+- Mecanismo de consentimento ausente
+- Sem portal de direitos do titular
+- Transferencia internacional sem SCCs
+- Dados de criancas sem consentimento dos pais
+- Politica de privacidade nao publicada
+
+### Tier 3: Bloqueadores Operacionais (8 itens)
+
+Tornam o deploy irresponsavel:
+- Sem inventario de ativos
+- Sem logging centralizado
+- Sem plano de resposta a incidentes
+- Sem verificacao de backup
+- Sem varredura de vulnerabilidades
+- Sem segmentacao de rede
+- Sem avaliacao de seguranca de vendors
+- Sem aplicacao de SSL no banco de dados
+
+Para o checklist completo e detalhes de implementacao, veja a Constitution em `.sinapse-ai/constitution.md`.
 
 ---
 
-*Esta política de segurança está em vigor desde dezembro de 2024.*
-*Última atualização: 2025-12-15*
+*Ultima atualizacao: 2026-04-03*

package/docs/roadmap.md

@@ -28,7 +28,7 @@ Core framework stabilization and community infrastructure:
 
 - [x] GitHub Discussions setup
 - [x] Contribution guides (CONTRIBUTING.md, COMMUNITY.md)
-- [x] Feature request process (FEATURE_PROCESS.md)
+- [x] Feature request process (feature-process.md)
 - [x] Public roadmap (this document!)
 - [ ] Starter squad registry
 
@@ -93,7 +93,7 @@ For significant features that need detailed design, [submit an RFC](/.github/RFC
 
 ### 4. Contribute Directly
 
-Found something you want to implement? Check our [Contributing Guide](CONTRIBUTING.md) and [Feature Process](docs/FEATURE_PROCESS.md).
+Found something you want to implement? Check our [Contributing Guide](CONTRIBUTING.md) and [Feature Process](docs/feature-process.md).
 
 ## Changelog
 

package/docs/security/{PR_SECURITY_CHECKLIST.md → pr-security-checklist.md}

@@ -12,7 +12,7 @@ This PR implements comprehensive security hardening for the post-install validat
 | `src/installer/manifest-signature.js`            | **New**      | Ed25519 signature verification module    |
 | `bin/sinapse-init.js`                               | **Modified** | Added `requireSignature` option          |
 | `tests/installer/post-install-validator.test.js` | **New**      | Security test suite                      |
-| `docs/security/MANIFEST_SIGNING.md`              | **New**      | Signing workflow documentation           |
+| `docs/security/manifest-signing.md`              | **New**      | Signing workflow documentation           |
 
 ## Security Controls Implemented