sinapse-ai 1.1.0 → 1.2.1

package/.claude/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md - SINAPSE
+
+## Constitution
+
+Full doc: `.sinapse-ai/constitution.md`. Gates auto-block violations.
+
+| Art. | Principle | Severity |
+|------|-----------|----------|
+| I | CLI First | NON-NEGOTIABLE |
+| II | Agent Authority | NON-NEGOTIABLE |
+| III | Documentation-First | NON-NEGOTIABLE |
+| IV | No Invention | MUST |
+| V | Quality First | MUST |
+| VI | Absolute Imports | SHOULD |
+| VII | Metrics Accuracy | NON-NEGOTIABLE |
+| VIII | Mandatory Delegation | NON-NEGOTIABLE |
+| IX | Safe Collaboration | NON-NEGOTIABLE |
+| X | Security & Data Protection | NON-NEGOTIABLE |
+| XI | Conservative Default | MUST |
+
+## CLI First
+
+`CLI First → Observability Second → UI Third`. New features MUST work 100% via CLI before any UI.
+
+## Project Structure
+
+```
+.sinapse-ai/           # Framework core, data, agents, tasks, templates
+bin/                   # CLI executables
+docs/stories/          # Development stories
+packages/              # Shared packages
+squads/                # Squad expansions
+tests/                 # Tests
+```
+
+## Framework Boundary (L1-L4)
+
+| 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/` |
+
+## Agents
+
+Use `@agent-name` or `/SINAPSE:agents:agent-name`. Commands: `*help`, `*create-story`, `*task {name}`, `*exit`.
+
+| 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) |
+
+## Documentation-First (NON-NEGOTIABLE)
+
+Pipeline: Epic → Story → Validation → Implementation. No code without a story at status >= Ready.
+
+## Code Patterns
+
+- **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
+
+## Tests
+
+```bash
+npm test && npm run lint && npm run typecheck
+```
+
+## Tool Usage
+
+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`.
+
+## Context Management
+
+- Rules with `paths:` frontmatter only load when working on matching files
+- 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.
+
+## Token Economy & Response Format (NON-NEGOTIABLE)
+
+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.
+
+## Delegation & Anti-Hallucination
+
+- 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 v6.0 — CLI First | Observability Second | UI Third*

package/.claude/hooks/README.md

@@ -0,0 +1,195 @@
+# Claude Code Hooks
+
+Sistema de governança automática para regras do CLAUDE.md.
+
+## Arquitetura
+
+```
+UserPromptSubmit Hooks
+└── (all prompts)  → synapse-engine.cjs
+
+PreToolUse Hooks
+├── Read          → read-protection.py
+├── Write|Edit    → enforce-architecture-first.py
+│                 → write-path-validation.py
+│                 → mind-clone-governance.py
+│                 → code-intel-pretool.cjs
+└── Bash          → sql-governance.py
+                  → slug-validation.py
+
+PreCompact Hooks
+└── (manual+auto)  → precompact-session-digest.cjs
+```
+
+## Hooks Disponíveis
+
+### 1. read-protection.py
+**Trigger:** `Read`
+**Comportamento:** BLOQUEIA (exit 2)
+
+Impede leitura parcial (`limit`/`offset`) em arquivos protegidos:
+- `.claude/CLAUDE.md`
+- `.claude/rules/*.md`
+- `.sinapse-ai/development/agents/*.md`
+- `supabase/docs/SCHEMA.md`
+- `package.json`, `tsconfig.json`
+- `app/components/ui/icons/icon-map.ts`
+
+### 2. enforce-architecture-first.py
+**Trigger:** `Write|Edit`
+**Comportamento:** BLOQUEIA (exit 2)
+
+Exige documentação aprovada antes de criar código em paths protegidos:
+- `supabase/functions/` → requer doc em `docs/architecture/` ou `docs/approved-plans/`
+- `supabase/migrations/` → requer doc ou permite edição de arquivo existente
+
+### 3. write-path-validation.py
+**Trigger:** `Write|Edit`
+**Comportamento:** AVISA (exit 0 + stderr)
+
+Avisa quando documentos parecem estar no path errado:
+- Sessions/handoffs → `docs/sessions/YYYY-MM/`
+- Architecture → `docs/architecture/`
+- Guides → `docs/guides/`
+
+### 4. sql-governance.py
+**Trigger:** `Bash`
+**Comportamento:** BLOQUEIA (exit 2)
+
+Intercepta comandos SQL perigosos:
+- `CREATE TABLE/VIEW/FUNCTION/TRIGGER`
+- `ALTER TABLE`
+- `DROP TABLE/VIEW/FUNCTION`
+- `CREATE TABLE AS SELECT` (backup proibido)
+
+**Exceções permitidas:**
+- `supabase migration` (CLI oficial)
+- `pg_dump` (backup/export)
+
+### 5. slug-validation.py
+**Trigger:** `Bash`
+**Comportamento:** BLOQUEIA (exit 2)
+
+Valida formato snake_case em slugs:
+- Pattern: `^[a-z0-9]+(_[a-z0-9]+)*$`
+- ✅ `jose_carlos_amorim`
+- ❌ `jose-carlos-amorim` (hyphen)
+- ❌ `JoseAmorim` (camelCase)
+
+### 6. mind-clone-governance.py
+**Trigger:** `Write|Edit`
+**Comportamento:** BLOQUEIA (exit 2)
+
+Impede criação de mind clones sem DNA extraído previamente.
+
+**O que é bloqueado:**
+- Criar novo arquivo `squads/*/agents/*.md` que pareça ser um mind clone
+- Mind clones = agents baseados em pessoas reais (não funcionais)
+
+**O que NÃO é bloqueado:**
+- Editar arquivos existentes (permite updates)
+- Agents funcionais (identificados por sufixo):
+  - `-chief`, `-orchestrator`, `-chair`
+  - `-validator`, `-calculator`, `-generator`, `-extractor`, `-analyzer`
+  - `-architect`, `-mapper`, `-designer`, `-engineer`
+  - `tools-*`, `process-*`, `workflow-*`
+
+**Locais de DNA verificados:**
+- `squads/{pack}/data/minds/{agent_id}_dna.yaml`
+- `squads/{pack}/data/minds/{agent_id}_dna.md`
+- `squads/{pack}/data/{agent_id}-dna.yaml`
+- `outputs/minds/{agent_id}/`
+
+**Solução quando bloqueado:**
+1. Execute o pipeline de extração de DNA: `/squad-creator` → `*collect-sources` → `*extract-voice-dna` → `*extract-thinking-dna`
+2. OU se é agent funcional, renomeie com sufixo apropriado
+
+## Exit Codes
+
+| Code | Significado |
+|------|-------------|
+| 0 | Permitido (operação continua) |
+| 2 | Bloqueado (operação cancelada, mostra stderr) |
+| Outro | Erro não-bloqueante |
+
+## Input Format
+
+Hooks recebem JSON via stdin:
+
+```json
+{
+  "session_id": "abc123",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Read",
+  "tool_input": {
+    "file_path": "/path/to/file",
+    "limit": 100
+  },
+  "cwd": "/Users/alan/Code/mmos"
+}
+```
+
+## Debugging
+
+Para testar um hook manualmente:
+
+```bash
+echo '{"tool_name": "Read", "tool_input": {"file_path": ".claude/CLAUDE.md", "limit": 100}}' | python3 .claude/hooks/read-protection.py
+echo $?  # Deve retornar 2 (bloqueado)
+```
+
+## Configuração
+
+Hooks são registrados em `.claude/settings.json` (framework, commitado) ou `.claude/settings.local.json` (overrides locais).
+
+**IMPORTANTE:** Claude Code NÃO usa filesystem discovery. Cada hook DEVE ser registrado explicitamente com o evento correto.
+
+### Registro de Hooks JS (.cjs)
+
+| Hook | Evento | Matcher | Descrição |
+|------|--------|---------|-----------|
+| `synapse-engine.cjs` | `UserPromptSubmit` | — | SYNAPSE context engine |
+| `code-intel-pretool.cjs` | `PreToolUse` | `Write\|Edit` | Code intelligence injection |
+| `precompact-session-digest.cjs` | `PreCompact` | — | Session digest capture |
+
+### Exemplo de Configuração
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/synapse-engine.cjs\"", "timeout": 10 }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/code-intel-pretool.cjs\"", "timeout": 10 }]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/precompact-session-digest.cjs\"", "timeout": 10 }]
+      }
+    ]
+  }
+}
+```
+
+O installer (`ide-config-generator.js`) usa `HOOK_EVENT_MAP` para registrar automaticamente cada hook no evento correto durante `npx sinapse-ai install`.
+
+## Manutenção
+
+Para adicionar novo hook:
+
+1. Criar arquivo `.claude/hooks/novo-hook.cjs` (deve ler stdin JSON, mesmo pattern do synapse-engine.cjs)
+2. Adicionar mapeamento em `HOOK_EVENT_MAP` no `ide-config-generator.js`
+3. Documentar neste README
+4. Testar com casos reais
+
+---
+
+*Criado: 2026-01-24*
+*Arquitetura: docs/architecture/claude-md-governance-system.md*
+

package/.claude/hooks/enforce-architecture-first.cjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Enforce Architecture-First Development (CJS port)
+ *
+ * RULE: Code in protected paths can only be created/edited if prior
+ *       architecture documentation exists.
+ *
+ * Protocol (Claude Code PreToolUse):
+ *   exit 0  → allow
+ *   exit 2  → block (message shown to model via stderr)
+ *
+ * Fail-open: if parsing fails or project root is unresolvable, allow.
+ *
+ * @module enforce-architecture-first
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Configuration: paths that REQUIRE prior documentation
+// ---------------------------------------------------------------------------
+
+const PROTECTED_PATHS = [
+  {
+    pattern: 'supabase/functions/',
+    docPatterns: [
+      'docs/architecture/{name}.md',
+      'docs/architecture/{name}-architecture.md',
+      'docs/approved-plans/{name}.md',
+    ],
+    extractName(p) {
+      const idx = p.indexOf('supabase/functions/');
+      if (idx === -1) return null;
+      return p.slice(idx + 'supabase/functions/'.length).split('/')[0] || null;
+    },
+  },
+  {
+    pattern: 'supabase/migrations/',
+    docPatterns: [
+      'docs/approved-plans/migration-{name}.md',
+      'docs/architecture/database-changes.md',
+    ],
+    extractName(p) {
+      const idx = p.indexOf('supabase/migrations/');
+      if (idx === -1) return null;
+      return path.basename(p, path.extname(p));
+    },
+    allowIfExists: true,
+  },
+];
+
+const ALWAYS_ALLOWED = [
+  '.claude/', 'docs/', 'outputs/', 'squads/', '.sinapse-ai/',
+  '.sinapse-custom/', 'node_modules/', '.git/',
+  'package.json', 'package-lock.json', 'tsconfig.json', '.env', 'README.md',
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function projectRoot() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function relativize(filePath, root) {
+  if (filePath.startsWith(root)) {
+    return filePath.slice(root.length).replace(/^[/\\]+/, '');
+  }
+  return filePath;
+}
+
+function isAlwaysAllowed(rel) {
+  return ALWAYS_ALLOWED.some((a) => rel.includes(a));
+}
+
+function findProtection(rel) {
+  return PROTECTED_PATHS.find((p) => rel.includes(p.pattern)) || null;
+}
+
+function docExists(rel, protection, root) {
+  const name = protection.extractName(rel);
+  if (!name) return true;
+
+  for (const dp of protection.docPatterns) {
+    const docPath = path.join(root, dp.replace('{name}', name));
+    if (fs.existsSync(docPath)) return true;
+  }
+
+  if (protection.allowIfExists) {
+    const full = path.isAbsolute(rel) ? rel : path.join(root, rel);
+    if (fs.existsSync(full)) return true;
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch {
+    process.exit(0); // fail-open
+  }
+
+  const toolName = input.tool_name || '';
+  if (toolName !== 'Write' && toolName !== 'Edit') {
+    process.exit(0);
+  }
+
+  const filePath = (input.tool_input || {}).file_path || '';
+  if (!filePath) process.exit(0);
+
+  const root = projectRoot();
+  const rel = relativize(filePath, root);
+
+  if (isAlwaysAllowed(rel)) process.exit(0);
+
+  const protection = findProtection(rel);
+  if (!protection) process.exit(0);
+
+  if (docExists(rel, protection, root)) process.exit(0);
+
+  // BLOCK
+  const name = protection.extractName(rel) || 'unknown';
+  const accepted = protection.docPatterns.map((d) => `  - ${d.replace('{name}', name)}`).join('\n');
+
+  process.stderr.write(
+    `\nARCHITECTURE-FIRST BLOCK: Documentation required before code.\n` +
+    `File: ${rel}\n` +
+    `Create one of:\n${accepted}\n` +
+    `Then retry the operation.\n`,
+  );
+  process.exit(2);
+}
+
+main();

package/.claude/hooks/enforce-architecture-first.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""
+Hook: Enforce Architecture-First Development
+
+REGRA: Código só pode ser criado/editado se existir documentação prévia.
+
+Este hook intercepta Write/Edit em paths de código e verifica se existe
+documentação aprovada antes de permitir a operação.
+
+Exit Codes:
+- 0: Permitido (doc existe ou path não requer doc)
+- 2: Bloqueado (doc não existe para path protegido)
+"""
+
+import json
+import sys
+import os
+from pathlib import Path
+
+# =============================================================================
+# CONFIGURAÇÃO: Paths que EXIGEM documentação prévia
+# =============================================================================
+
+PROTECTED_PATHS = [
+    # Edge Functions - exigem docs/architecture/{function-name}.md
+    {
+        "pattern": "supabase/functions/",
+        "doc_patterns": [
+            "docs/architecture/{name}.md",
+            "docs/architecture/{name}-architecture.md",
+            "docs/approved-plans/{name}.md",
+        ],
+        "extract_name": lambda p: p.split("supabase/functions/")[1].split("/")[0] if "supabase/functions/" in p else None,
+    },
+    # Migrations - exigem documentação de schema changes
+    {
+        "pattern": "supabase/migrations/",
+        "doc_patterns": [
+            "docs/approved-plans/migration-{name}.md",
+            "docs/architecture/database-changes.md",
+        ],
+        "extract_name": lambda p: Path(p).stem if "supabase/migrations/" in p else None,
+        "allow_if_exists": True,  # Permite editar migrations existentes
+    },
+]
+
+# Paths que são SEMPRE permitidos (não exigem doc)
+ALWAYS_ALLOWED = [
+    ".claude/",
+    "docs/",
+    "outputs/",
+    "squads/",
+    ".sinapse-ai/",
+    ".sinapse-custom/",
+    "node_modules/",
+    ".git/",
+    "package.json",
+    "package-lock.json",
+    "tsconfig.json",
+    ".env",
+    "README.md",
+]
+
+# =============================================================================
+# LÓGICA DO HOOK
+# =============================================================================
+
+def get_project_root():
+    """Obtém o root do projeto via variável de ambiente ou cwd."""
+    return os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+
+def is_always_allowed(file_path: str) -> bool:
+    """Verifica se o path está na lista de sempre permitidos."""
+    for allowed in ALWAYS_ALLOWED:
+        if allowed in file_path:
+            return True
+    return False
+
+def find_matching_protection(file_path: str) -> dict | None:
+    """Encontra a regra de proteção que corresponde ao path."""
+    for protection in PROTECTED_PATHS:
+        if protection["pattern"] in file_path:
+            return protection
+    return None
+
+def check_documentation_exists(file_path: str, protection: dict, project_root: str) -> tuple[bool, str]:
+    """
+    Verifica se existe documentação para o path protegido.
+
+    Returns:
+        (exists: bool, doc_path: str | None)
+    """
+    extract_fn = protection.get("extract_name")
+    if not extract_fn:
+        return True, None
+
+    name = extract_fn(file_path)
+    if not name:
+        return True, None
+
+    # Verificar cada padrão de documentação
+    for doc_pattern in protection["doc_patterns"]:
+        doc_path = doc_pattern.format(name=name)
+        full_doc_path = os.path.join(project_root, doc_path)
+
+        if os.path.exists(full_doc_path):
+            return True, doc_path
+
+    # Se allow_if_exists e o arquivo já existe, permitir edição
+    if protection.get("allow_if_exists"):
+        full_file_path = os.path.join(project_root, file_path) if not file_path.startswith("/") else file_path
+        if os.path.exists(full_file_path):
+            return True, "(arquivo existente)"
+
+    return False, None
+
+def format_required_docs(protection: dict, name: str) -> str:
+    """Formata a lista de documentos aceitos."""
+    docs = []
+    for pattern in protection["doc_patterns"]:
+        docs.append(f"  - {pattern.format(name=name)}")
+    return "\n".join(docs)
+
+def main():
+    # Ler input do stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        # Se não conseguir parsear, permitir (fail-open)
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    # Só processar Write e Edit
+    if tool_name not in ["Write", "Edit"]:
+        sys.exit(0)
+
+    # Normalizar path (remover prefixo absoluto se presente)
+    project_root = get_project_root()
+    relative_path = file_path
+    if file_path.startswith(project_root):
+        relative_path = file_path[len(project_root):].lstrip("/")
+
+    # Verificar se é sempre permitido
+    if is_always_allowed(relative_path):
+        sys.exit(0)
+
+    # Verificar se path está protegido
+    protection = find_matching_protection(relative_path)
+    if not protection:
+        # Path não protegido, permitir
+        sys.exit(0)
+
+    # Verificar se documentação existe
+    doc_exists, doc_path = check_documentation_exists(relative_path, protection, project_root)
+
+    if doc_exists:
+        # Documentação existe, permitir
+        sys.exit(0)
+
+    # BLOQUEAR: Documentação não existe
+    name = protection["extract_name"](relative_path) or "unknown"
+    required_docs = format_required_docs(protection, name)
+
+    error_message = f"""
+╔══════════════════════════════════════════════════════════════════════════════╗
+║  🛑 ARCHITECTURE-FIRST: Documentação obrigatória antes de código             ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                              ║
+║  Arquivo bloqueado: {relative_path[:50]:<50} ║
+║                                                                              ║
+║  REGRA: Antes de criar/editar código em paths protegidos, você DEVE:         ║
+║                                                                              ║
+║  1. Documentar o plano de arquitetura                                        ║
+║  2. Obter aprovação do usuário                                               ║
+║  3. Criar o arquivo de documentação                                          ║
+║                                                                              ║
+║  Documentos aceitos para '{name}':                                           ║
+{required_docs}
+║                                                                              ║
+║  AÇÃO: Crie um dos documentos acima com o plano aprovado, depois tente       ║
+║        novamente a operação de código.                                       ║
+║                                                                              ║
+║  DICA: Use `*create-doc architecture` para criar doc de arquitetura          ║
+║        Ou crie docs/approved-plans/{name}.md com o plano resumido             ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+"""
+
+    print(error_message, file=sys.stderr)
+    sys.exit(2)  # Exit code 2 = bloqueia o tool
+
+if __name__ == "__main__":
+    main()
+