grimoire-framework 1.0.0

package/.claude/CLAUDE.md

@@ -0,0 +1,318 @@
+# CLAUDE.md - Grimoire
+
+Este arquivo configura o comportamento do Claude Code ao trabalhar neste repositório.
+
+---
+
+## Constitution
+
+O grimoire possui uma **Constitution formal** com princípios inegociáveis e gates automáticos.
+
+**Documento completo:** `.grimoire/constitution.md`
+
+**Princípios fundamentais:**
+
+| Artigo | Princípio | Severidade |
+|--------|-----------|------------|
+| I | CLI First | NON-NEGOTIABLE |
+| II | Agent Authority | NON-NEGOTIABLE |
+| III | Story-Driven Development | MUST |
+| IV | No Invention | MUST |
+| V | Quality First | MUST |
+| VI | Absolute Imports | SHOULD |
+
+**Gates automáticos bloqueiam violações.** Consulte a Constitution para detalhes completos.
+
+---
+
+## 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 grimoire install`. No language config in `core-config.yaml`.
+
+---
+
+## Premissa Arquitetural: CLI First
+
+O Grimoire 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)
+
+---
+
+## Estrutura do Projeto
+
+```
+grimoire/
+├── .grimoire/              # 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 (grimoire-init.js, grimoire.js)
+├── docs/                    # Documentação
+│   └── stories/             # Development stories (active/, completed/)
+├── packages/                # Shared packages
+├── pro/                     # Pro submodule (proprietary)
+├── squads/                  # Squad expansions
+└── tests/                   # Testes
+```
+
+---
+
+## Sistema de Agentes
+
+### Ativação de Agentes
+Use `@agent-name` ou `/grimoire:agents:agent-name`:
+
+| Agente | Persona | Escopo Principal |
+|--------|---------|------------------|
+| `@dev` | Dex | Implementação de código |
+| `@qa` | Quinn | Testes e qualidade |
+| `@architect` | Aria | Arquitetura e design técnico |
+| `@pm` | Morgan | Product Management |
+| `@po` | Pax | Product Owner, stories/epics |
+| `@sm` | River | Scrum Master |
+| `@analyst` | Alex | Pesquisa e análise |
+| `@data-engineer` | Dara | Database design |
+| `@ux-design-expert` | Uma | UX/UI design |
+| `@devops` | Gage | 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
+
+| Agente | Diretórios Principais |
+|--------|----------------------|
+| `@dev` | `packages/`, `.grimoire/core/`, `bin/` |
+| `@architect` | `docs/architecture/`, system design |
+| `@data-engineer` | `packages/db/`, migrations, schema |
+| `@qa` | `tests/`, `*.test.js`, quality gates |
+| `@po` | Stories, epics, requirements |
+| `@devops` | `.github/`, CI/CD, git operations |
+
+---
+
+## Story-Driven Development
+
+1. **Trabalhe a partir de stories** - Todo desenvolvimento começa com uma story em `docs/stories/`
+2. **Atualize progresso** - Marque checkboxes conforme completa: `[ ]` → `[x]`
+3. **Rastreie mudanças** - Mantenha a seção File List na story
+4. **Siga critérios** - Implemente exatamente o que os acceptance criteria especificam
+
+### Workflow de Story
+```
+@po *create-story → @dev implementa → @qa testa → @devops push
+```
+
+---
+
+## Padrões de Código
+
+### Convenções de Nomenclatura
+
+| 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` |
+
+### Imports
+**Sempre use imports absolutos.** Nunca use imports relativos.
+```typescript
+// ✓ Correto
+import { useStore } from '@/stores/feature/store'
+
+// ✗ 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
+
+### 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)`
+
+### 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'}`)
+}
+```
+
+---
+
+## Testes & Quality Gates
+
+### Comandos de Teste
+```bash
+npm test                    # Rodar testes
+npm run test:coverage       # Testes com cobertura
+npm run lint                # ESLint
+npm run typecheck           # TypeScript
+```
+
+### Quality Gates (Pre-Push)
+Antes de push, todos os checks devem passar:
+```bash
+npm run lint        # ESLint
+npm run typecheck   # TypeScript
+npm test            # Jest
+```
+
+---
+
+## 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.**
+
+---
+
+## 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 |
+
+### Performance
+- Prefira chamadas de ferramentas em batch
+- Use execução paralela para operações independentes
+- Cache dados frequentemente acessados durante a sessão
+
+### 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
+
+---
+
+## 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
+```
+
+### grimoire
+```bash
+npx grimoire install       # Instalar grimoire
+npx grimoire doctor        # Diagnóstico do sistema
+npx grimoire info          # Informações do sistema
+```
+
+### Dashboard (apps/dashboard/)
+```bash
+cd apps/dashboard
+npm install
+npm run dev                 # Desenvolvimento
+npm run build               # Build produção
+```
+
+---
+
+## 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
+
+---
+
+## Debug
+
+### Habilitar Debug
+```bash
+export grimoire_DEBUG=true
+```
+
+### Logs
+```bash
+tail -f .grimoire/logs/agent.log
+```
+
+---
+
+*Grimoire Claude Code Configuration v4.0*
+*CLI First | Observability Second | UI Third*
+
+

package/.claude/hooks/README.md

@@ -0,0 +1,170 @@
+# Claude Code Hooks
+
+Sistema de governança automática para regras do CLAUDE.md.
+
+## Arquitetura
+
+```
+PreToolUse Hooks
+├── Read          → read-protection.py
+├── Write|Edit    → enforce-architecture-first.py
+│                 → write-path-validation.py
+│                 → mind-clone-governance.py
+└── Bash          → sql-governance.py
+                  → slug-validation.py
+```
+
+## 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`
+- `.grimoire/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 configurados em `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/read-protection.py\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Manutenção
+
+Para adicionar novo hook:
+
+1. Criar arquivo `.claude/hooks/novo-hook.py`
+2. Adicionar entrada em `.claude/settings.local.json`
+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.py

@@ -0,0 +1,198 @@
+#!/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/",
+    ".grimoire/",
+    ".grimoire-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()
+
+