sinapse-ai 10.0.0-rc.8 → 10.0.0

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

@@ -1,197 +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()
-
+#!/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()
+

package/.claude/hooks/enforce-nsn-guard.cjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Enforce NSN Mode (Never Say Never) Guard
+ *
+ * RULE (.claude/rules/nsn-mode.md): Agents must NOT tell the user to
+ * manually perform a step that the agent itself could automate via
+ * Chrome Brain, MCP, or a direct CLI call. Writing such instructions
+ * into docs, stories, or code comments propagates the anti-pattern.
+ *
+ * Scope: matches `Write` and `Edit` PreToolUse on `.md`, `.mdx`, `.txt`
+ * files. Scans the content being written for known NSN violation
+ * phrases. Emits a WARN on stderr (exit 0) so the agent can see the
+ * feedback but is not hard-blocked — false positives would be more
+ * damaging than the leak.
+ *
+ * Protocol (Claude Code PreToolUse):
+ *   exit 0            → allow (with optional stderr warning)
+ *   exit 2            → block (reserved for a future strict mode)
+ *
+ * Fail-open: any parsing error → exit 0 (allow). Reason: a broken
+ * guard should never block legitimate writes.
+ *
+ * @module enforce-nsn-guard
+ * @story 10.44 (Fix 3 from pre-GA blockers)
+ */
+
+const readStdin = () => new Promise((resolve) => {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (c) => { data += c; });
+  process.stdin.on('end', () => resolve(data));
+  // Fail-open on timeout — don't hang Claude Code
+  setTimeout(() => resolve(data), 4500);
+});
+
+const TARGET_TOOLS = new Set(['Write', 'Edit']);
+const TARGET_EXTENSIONS = ['.md', '.mdx', '.txt'];
+
+// NSN violation phrases — ordered from high-confidence to lower.
+// Written as regexes (case-insensitive) so common morphological
+// variants are caught without adding dozens of entries.
+const NSN_PATTERNS = [
+  {
+    id: 'open-dashboard-manually',
+    regex: /(abra|abre|you should open|please open)\s+(o\s+)?dashboard.*manual/i,
+    hint: 'Agents should offer Chrome Brain before telling users to open a dashboard by hand.',
+  },
+  {
+    id: 'follow-steps-manually',
+    regex: /(siga|follow)\s+esses\s+passos\s+manualmente/i,
+    hint: 'Replace manual step-lists with an automated Chrome Brain / MCP call.',
+  },
+  {
+    id: 'cannot-access-interface',
+    regex: /(infelizmente\s+)?n[ãa]o\s+consigo\s+acessar\s+a\s+interface/i,
+    hint: 'NSN Mode: try Chrome Brain, dev-browser, or claude-in-chrome before claiming you cannot access UI.',
+  },
+  {
+    id: 'you-need-to-click',
+    regex: /(voc[êe]\s+precisa\s+(abrir|clicar))|(you\s+need\s+to\s+click)/i,
+    hint: 'Agents should drive UI clicks via Chrome Brain, not instruct the user.',
+  },
+  {
+    id: 'i-cant-do-this',
+    regex: /\b(i\s+can'?t\s+do\s+this|n[ãa]o\s+consigo\s+fazer\s+isso)\b/i,
+    hint: 'NSN Mode forbids "I can\'t" without having tried 3+ alternatives first.',
+  },
+];
+
+async function main() {
+  try {
+    const raw = await readStdin();
+    if (!raw) { process.exit(0); }
+
+    let payload;
+    try { payload = JSON.parse(raw); } catch { process.exit(0); }
+
+    const toolName = payload.tool_name || payload.toolName;
+    if (!TARGET_TOOLS.has(toolName)) { process.exit(0); }
+
+    const input = payload.tool_input || payload.toolInput || {};
+    const filePath = input.file_path || input.filePath || '';
+    if (!filePath) { process.exit(0); }
+
+    const ext = filePath.slice(filePath.lastIndexOf('.')).toLowerCase();
+    if (!TARGET_EXTENSIONS.includes(ext)) { process.exit(0); }
+
+    // Extract the text about to land in the file
+    const content = input.content
+      || input.new_string
+      || input.newString
+      || '';
+    if (!content || typeof content !== 'string') { process.exit(0); }
+
+    const hits = [];
+    for (const pattern of NSN_PATTERNS) {
+      if (pattern.regex.test(content)) {
+        hits.push(pattern);
+      }
+    }
+
+    if (hits.length === 0) { process.exit(0); }
+
+    // WARN mode — print hints to stderr so the agent sees them, exit 0.
+    const lines = [
+      '',
+      '[NSN-Guard] Detected NSN Mode anti-patterns in content being written to',
+      `  ${filePath}`,
+      '',
+    ];
+    for (const h of hits) {
+      lines.push(`  - ${h.id}: ${h.hint}`);
+    }
+    lines.push('');
+    lines.push('Reference: .claude/rules/nsn-mode.md');
+    lines.push('');
+    process.stderr.write(lines.join('\n'));
+    process.exit(0);
+  } catch {
+    // Fail-open
+    process.exit(0);
+  }
+}
+
+main();