sinapse-ai 9.3.0 → 9.5.0

package/.claude/CLAUDE.md

@@ -1,384 +1,103 @@
 # CLAUDE.md - SINAPSE
 
-Este arquivo configura o comportamento do Claude Code ao trabalhar neste repositório.
-
----
-
-<!-- FRAMEWORK-OWNED: Generated by SINAPSE installer, do not customize -->
 ## Constitution
 
-O SINAPSE possui uma **Constitution formal** com princípios inegociáveis e gates automáticos.
+Full doc: `.sinapse-ai/constitution.md`. Gates auto-block violations.
 
-**Documento completo:** `.sinapse-ai/constitution.md`
-
-**Princípios fundamentais:**
-
-| Artigo | Princípio | Severidade |
-|--------|-----------|------------|
+| Art. | Principle | Severity |
+|------|-----------|----------|
 | I | CLI First | NON-NEGOTIABLE |
 | II | Agent Authority | NON-NEGOTIABLE |
-| III | Documentation-First Development | NON-NEGOTIABLE |
+| III | Documentation-First | NON-NEGOTIABLE |
 | IV | No Invention | MUST |
 | V | Quality First | MUST |
 | VI | Absolute Imports | SHOULD |
-| VII | Ecosystem Metrics Accuracy | NON-NEGOTIABLE |
+| VII | Metrics Accuracy | NON-NEGOTIABLE |
 | VIII | Mandatory Delegation | NON-NEGOTIABLE |
 | IX | Safe Collaboration | NON-NEGOTIABLE |
 | X | Security & Data Protection | NON-NEGOTIABLE |
 
-**Gates automáticos bloqueiam violações.** Consulte a Constitution para detalhes completos.
-
----
-
-<!-- FRAMEWORK-OWNED: Generated by SINAPSE installer, do not customize -->
-## Language Configuration
-
-Language preference is handled by Claude Code's native `language` setting (v2.1.0+).
-Configure in `~/.claude/settings.json` (global) or `.claude/settings.json` (project):
-
-```json
-{ "language": "portuguese" }
-```
-
-The installer writes this automatically during `npx sinapse-ai install`. No language config in `core-config.yaml`.
-
----
-
-<!-- FRAMEWORK-OWNED: Generated by SINAPSE installer, do not customize -->
-## Premissa Arquitetural: CLI First
-
-O SINAPSE segue uma hierarquia clara de prioridades que deve guiar **TODAS** as decisões:
-
-```
-CLI First → Observability Second → UI Third
-```
-
-| Camada | Prioridade | Descrição |
-|--------|------------|-----------|
-| **CLI** | Máxima | Onde a inteligência vive. Toda execução, decisões e automação. |
-| **Observability** | Secundária | Observar e monitorar o que acontece no CLI em tempo real. |
-| **UI** | Terciária | Gestão pontual e visualizações quando necessário. |
-
-### Princípios Derivados
-
-1. **A CLI é a fonte da verdade** - Dashboards apenas observam, nunca controlam
-2. **Funcionalidades novas devem funcionar 100% via CLI** antes de ter qualquer UI
-3. **A UI nunca deve ser requisito** para operação do sistema
-4. **Observabilidade serve para entender** o que o CLI está fazendo, não para controlá-lo
-5. **Ao decidir onde implementar algo**, sempre prefira CLI > Observability > UI
-
-> **Referência formal:** Constitution Artigo I - CLI First (NON-NEGOTIABLE)
-
----
-
-<!-- FRAMEWORK-OWNED: Generated by SINAPSE installer, do not customize -->
-## Estrutura do Projeto
-
-```
-sinapse-ai/
-├── .sinapse-ai/              # Core do framework
-│   ├── core/                # Módulos principais (orchestration, memory, etc.)
-│   ├── data/                # Knowledge base, entity registry
-│   ├── development/         # Agents, tasks, templates, checklists, scripts
-│   └── infrastructure/      # CI/CD templates, scripts
-├── bin/                     # CLI executables (sinapse-init.js, sinapse.js)
-├── docs/                    # Documentação
-│   └── stories/             # Development stories (active/, completed/)
-├── packages/                # Shared packages
-├── pro/                     # Pro submodule (proprietary)
-├── squads/                  # Squad expansions
-└── tests/                   # Testes
-```
-
----
-
-<!-- FRAMEWORK-OWNED: Generated by SINAPSE installer, do not customize -->
-## Framework vs Project Boundary
-
-O SINAPSE usa um modelo de 4 camadas (L1-L4) para separar artefatos do framework e do projeto. Deny rules em `.claude/settings.json` reforçam isso deterministicamente.
-
-| Camada | Mutabilidade | Paths | Notas |
-|--------|-------------|-------|-------|
-| **L1** Framework Core | NEVER modify | `.sinapse-ai/core/`, `.sinapse-ai/constitution.md`, `bin/sinapse.js`, `bin/sinapse-init.js` | Protegido por deny rules |
-| **L2** Framework Templates | NEVER modify | `.sinapse-ai/development/tasks/`, `.sinapse-ai/development/templates/`, `.sinapse-ai/development/checklists/`, `.sinapse-ai/development/workflows/`, `.sinapse-ai/infrastructure/` | Extend-only |
-| **L3** Project Config | Mutable (exceptions) | `.sinapse-ai/data/`, `agents/*/MEMORY.md`, `core-config.yaml` | Allow rules permitem |
-| **L4** Project Runtime | ALWAYS modify | `docs/stories/`, `packages/`, `squads/`, `tests/` | Trabalho do projeto |
-
-**Toggle:** `core-config.yaml` → `boundary.frameworkProtection: true/false` controla se deny rules são ativas (default: true para projetos, false para contribuidores do framework).
-
-> **Referência formal:** `.claude/settings.json` (deny/allow rules), `.claude/rules/agent-authority.md`
+## CLI First
 
----
-
-<!-- FRAMEWORK-OWNED: Generated by SINAPSE installer, do not customize -->
-## Sistema de Agentes
-
-### Ativação de Agentes
-Use `@agent-name` ou `/SINAPSE:agents:agent-name`:
-
-| Agente | Persona | Escopo Principal |
-|--------|---------|------------------|
-| `@developer` | Pixel | Implementacao de codigo |
-| `@quality-gate` | Litmus | Testes e qualidade |
-| `@architect` | Stratum | Arquitetura e design tecnico |
-| `@project-lead` | Beacon | Product Management |
-| `@product-lead` | Axis | Product Owner, stories/epics |
-| `@sprint-lead` | Sync | Scrum Master |
-| `@analyst` | Scope | Pesquisa e analise |
-| `@data-engineer` | Tensor | Database design |
-| `@ux-design-expert` | Mosaic | UX/UI design |
-| `@devops` | Pipeline | CI/CD, git push (EXCLUSIVO) |
-
-### Comandos de Agentes
-Use prefixo `*` para comandos:
-- `*help` - Mostrar comandos disponíveis
-- `*create-story` - Criar story de desenvolvimento
-- `*task {name}` - Executar task específica
-- `*exit` - Sair do modo agente
-
-### Mapeamento Agente → Codebase
+`CLI First → Observability Second → UI Third`. New features MUST work 100% via CLI before any UI.
 
-| Agente | Diretórios Principais |
-|--------|----------------------|
-| `@developer` | `packages/`, `.sinapse-ai/core/`, `bin/` |
-| `@architect` | `docs/architecture/`, system design |
-| `@data-engineer` | `packages/db/`, migrations, schema |
-| `@quality-gate` | `tests/`, `*.test.js`, quality gates |
-| `@product-lead` | Stories, epics, requirements |
-| `@devops` | `.github/`, CI/CD, git operations |
+## Project Structure
 
----
-
-<!-- FRAMEWORK-OWNED: Generated by SINAPSE installer, do not customize -->
-## Documentation-First Development (NON-NEGOTIABLE)
-
-1. **Pipeline automatico** - Todo briefing segue: Epic → Story → Validacao → Implementacao
-2. **Story validada obrigatoria** - Nenhum codigo sem story com status >= Ready
-3. **Trabalhe a partir de stories** - Todo desenvolvimento começa com uma story em `docs/stories/`
-4. **Atualize progresso** - Marque checkboxes conforme completa: `[ ]` → `[x]`
-5. **Rastreie mudanças** - Mantenha a seção File List na story
-6. **Siga critérios** - Implemente exatamente o que os acceptance criteria especificam
-
-### Workflow de Story
 ```
-@product-lead *create-story → @developer implementa → @quality-gate testa → @devops push
+.sinapse-ai/           # Framework core, data, agents, tasks, templates
+bin/                   # CLI executables
+docs/stories/          # Development stories
+packages/              # Shared packages
+squads/                # Squad expansions
+tests/                 # Tests
 ```
 
----
-
-<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
-## Padrões de Código
+## Framework Boundary (L1-L4)
 
-### Convenções de Nomenclatura
+| Layer | Mutability | Key Paths |
+|-------|-----------|-----------|
+| L1 Core | NEVER | `.sinapse-ai/core/`, `bin/sinapse*.js` |
+| L2 Templates | NEVER | `.sinapse-ai/development/{tasks,templates,checklists,workflows}/` |
+| L3 Config | Mutable | `.sinapse-ai/data/`, `core-config.yaml` |
+| L4 Runtime | ALWAYS | `docs/stories/`, `packages/`, `squads/`, `tests/` |
 
-| Tipo | Convenção | Exemplo |
-|------|-----------|---------|
-| Componentes | PascalCase | `WorkflowList` |
-| Hooks | prefixo `use` | `useWorkflowOperations` |
-| Arquivos | kebab-case | `workflow-list.tsx` |
-| Constantes | SCREAMING_SNAKE_CASE | `MAX_RETRIES` |
-| Interfaces | PascalCase + sufixo | `WorkflowListProps` |
+## Agents
 
-### Imports
-**Sempre use imports absolutos.** Nunca use imports relativos.
-```typescript
-// ✓ Correto
-import { useStore } from '@/stores/feature/store'
+Use `@agent-name` or `/SINAPSE:agents:agent-name`. Commands: `*help`, `*create-story`, `*task {name}`, `*exit`.
 
-// ✗ Errado
-import { useStore } from '../../../stores/feature/store'
-```
-
-**Ordem de imports:**
-1. React/core libraries
-2. External libraries
-3. UI components
-4. Utilities
-5. Stores
-6. Feature imports
-7. CSS imports
+| Agent | Persona | Scope |
+|-------|---------|-------|
+| @developer | Pixel | Code implementation |
+| @quality-gate | Litmus | Testing & quality |
+| @architect | Stratum | Architecture |
+| @project-lead | Beacon | Product Management |
+| @product-lead | Axis | Product Owner |
+| @sprint-lead | Sync | Scrum Master |
+| @analyst | Scope | Research |
+| @data-engineer | Tensor | Database |
+| @ux-design-expert | Mosaic | UX/UI |
+| @devops | Pipeline | CI/CD, push (EXCLUSIVE) |
 
-### TypeScript
-- Sem `any` - Use tipos apropriados ou `unknown` com type guards
-- Sempre defina interface de props para componentes
-- Use `as const` para objetos/arrays constantes
-- Tipos de ref explícitos: `useRef<HTMLDivElement>(null)`
+## Documentation-First (NON-NEGOTIABLE)
 
-### Error Handling
-```typescript
-try {
-  // Operation
-} catch (error) {
-  logger.error(`Failed to ${operation}`, { error })
-  throw new Error(`Failed to ${operation}: ${error instanceof Error ? error.message : 'Unknown'}`)
-}
-```
+Pipeline: Epic → Story → Validation → Implementation. No code without a story at status >= Ready.
 
----
+## Code Patterns
 
-<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
-## Testes & Quality Gates
+- **Naming:** PascalCase components, `use` prefix hooks, kebab-case files, SCREAMING_SNAKE constants
+- **Imports:** Always absolute (`@/...`), never relative. Order: React → external → UI → utils → stores → features → CSS
+- **TypeScript:** No `any`, always define props interfaces, `as const` for constants
+- **Commits:** Conventional Commits + story ref: `feat: feature [Story 2.1]`
+- **Push:** Only `@devops` can push to remote
 
-### Comandos de Teste
-```bash
-npm test                    # Rodar testes
-npm run test:coverage       # Testes com cobertura
-npm run lint                # ESLint
-npm run typecheck           # TypeScript
-```
+## Tests
 
-### Quality Gates (Pre-Push)
-Antes de push, todos os checks devem passar:
 ```bash
-npm run lint        # ESLint
-npm run typecheck   # TypeScript
-npm test            # Jest
+npm test && npm run lint && npm run typecheck
 ```
 
----
-
-<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
-## Convenções Git
-
-### Commits
-Seguir Conventional Commits:
-- `feat:` - Nova funcionalidade
-- `fix:` - Correção de bug
-- `docs:` - Documentação
-- `test:` - Testes
-- `chore:` - Manutenção
-- `refactor:` - Refatoração
-
-**Referencie story ID:** `feat: implement feature [Story 2.1]`
-
-### Branches
-- `main` - Branch principal
-- `feat/*` - Features
-- `fix/*` - Correções
-- `docs/*` - Documentação
-
-### Push Authority
-**Apenas `@devops` pode fazer push para remote.**
+## Tool Usage
 
----
-
-<!-- FRAMEWORK-OWNED: Generated by SINAPSE installer, do not customize -->
-## Otimização Claude Code
-
-### Uso de Ferramentas
-| Tarefa | Use | Não Use |
-|--------|-----|---------|
-| Buscar conteúdo | `Grep` tool | `grep`/`rg` no bash |
-| Ler arquivos | `Read` tool | `cat`/`head`/`tail` |
-| Editar arquivos | `Edit` tool | `sed`/`awk` |
-| Buscar arquivos | `Glob` tool | `find` |
-| Operações complexas | `Task` tool | Múltiplos comandos manuais |
+Use Grep (not grep), Read (not cat), Edit (not sed), Glob (not find). Prefer native tools over MCP. Tool registry: `.sinapse-ai/data/tool-registry.yaml`.
 
-### Performance
-- Prefira chamadas de ferramentas em batch
-- Use execução paralela para operações independentes
-- Cache dados frequentemente acessados durante a sessão
+## Context Management
 
-### Context Management (NOG-18 + TOK-4A)
-- Use `/compact` when context feels heavy or approaching limits
-- Context brackets (SYNAPSE) replaced by native compaction
-- Agent memory persists in `.sinapse-ai/development/agents/{id}/MEMORY.md`
 - Rules with `paths:` frontmatter only load when working on matching files
-- **Agent Handoff:** On agent switch (`@agent`), previous agent is compacted to ~379-token handoff artifact. See `.claude/rules/agent-handoff.md` for full protocol. Max 3 retained summaries, oldest discarded.
-
-### Gerenciamento de Sessão
-- Rastreie progresso da story durante a sessão
-- Atualize checkboxes imediatamente após completar tasks
-- Mantenha contexto da story atual sendo trabalhada
-- Salve estado importante antes de operações longas
-
-### Recuperação de Erros
-- Sempre forneça sugestões de recuperação para falhas
-- Inclua contexto do erro em mensagens ao usuário
-- Sugira procedimentos de rollback quando apropriado
-- Documente quaisquer correções manuais necessárias
-
----
-
-<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
-## Comandos Frequentes
-
-### Desenvolvimento
-```bash
-npm run dev                 # Iniciar desenvolvimento
-npm test                    # Rodar testes
-npm run lint                # Verificar estilo
-npm run typecheck           # Verificar tipos
-npm run build               # Build produção
-```
-
-### SINAPSE
-```bash
-npx sinapse-ai install       # Instalar SINAPSE
-npx sinapse-ai doctor        # Diagnóstico do sistema
-npx sinapse-ai info          # Informações do sistema
-```
-
-### Dashboard (apps/dashboard/)
-```bash
-cd apps/dashboard
-npm install
-npm run dev                 # Desenvolvimento
-npm run build               # Build produção
-```
-
----
-
-<!-- FRAMEWORK-OWNED: Generated by SINAPSE installer, do not customize -->
-## MCP Usage
-
-Ver `.claude/rules/mcp-usage.md` para regras detalhadas.
-
-**Resumo:**
-- Preferir ferramentas nativas do Claude Code sobre MCP
-- MCP Docker Gateway apenas quando explicitamente necessário
-- `@devops` gerencia toda infraestrutura MCP
-
----
+- Agent handoff compacts to ~379 tokens on switch
+- Agent memory in `.sinapse-ai/development/agents/{id}/MEMORY.md`
+- **Memory as hints:** Memory entries are hints, NOT ground truth. Always verify against actual codebase before acting on remembered facts.
 
-<!-- PROJECT-CUSTOMIZED: Token Optimization TOK-2 -->
-## Tool Selection Guidance
+## Token Economy & Response Format (NON-NEGOTIABLE)
 
-Prefer native Claude Code tools over MCP for common operations. The tool-registry at `.sinapse-ai/data/tool-registry.yaml` defines the 3-Tier Tool Mesh:
+Auto-applied to all agents: `~/.claude/rules/token-economy.md` + `~/.claude/rules/response-format.md`. Compact at 60%, model route haiku/sonnet/opus, no preamble, no trailing summary.
 
-| Tier | When Loaded | Examples |
-|------|-------------|---------|
-| **1** (Always) | Session start | Read, Write, Edit, Bash, Grep, Glob, Task |
-| **2** (Deferred) | Agent activation | git, coderabbit, context7, supabase |
-| **3** (Deferred) | Via tool search | EXA, Playwright, Apify, Nogic, Code-Graph |
+## Delegation & Anti-Hallucination
 
-**Guidelines:**
-- Use Tier 1 native tools for file ops, search, and commands — avoid MCP equivalents
-- Tier 3 MCP tools are deferred via Tool Search — only loaded when explicitly needed
-- Limit tool search to maximum 2 searches per turn to avoid overhead
-- Essential MCP servers (nogic, code-graph) are never disabled
-- Non-essential servers (EXA, Apify, Playwright) load on-demand via tool search
-
-**Tool Examples (TOK-4B):** Concrete input examples improve tool selection accuracy by +18pp. See `.claude/rules/tool-examples.md` for examples of top-10 tools. Full registry: `.sinapse-ai/data/mcp-tool-examples.yaml`. ADR-5: examples for always-loaded tools only, search for deferred tools.
-
-**Runtime capabilities:** `.sinapse/runtime-capabilities.json` (generated by capability-detection.js)
-
----
-
-<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
-## Debug
-
-### Habilitar Debug
-```bash
-export SINAPSE_DEBUG=true
-```
-
-### Logs
-```bash
-tail -f .sinapse/logs/agent.log
-```
+- Persona switch for sequential work, sub-agent only for parallel (20K+ tokens each)
+- Model routing: `haiku` routine, `sonnet` standard, `opus` complex
+- Sub-agents announce their model for visual verification via statusline
+- `npm view {pkg}` before adding deps. Cite file:line for claims.
+- Mark uncertain claims with [NEEDS VERIFICATION]. Compact at 60%.
 
 ---
-
-*SINAPSE Claude Code Configuration v4.0*
-*CLI First | Observability Second | UI Third*
+*SINAPSE v6.0 — CLI First | Observability Second | UI Third*