mega-brain-ai 1.1.0

package/system/protocols/HOOK-SECURITY-THREAT-MODEL.md

@@ -0,0 +1,152 @@
+# Hook Security Threat Model
+
+> **Version:** 1.0.0
+> **Created:** 2026-02-18
+> **Source:** Quality Uplift SEC-001
+> **Scope:** All 33 hooks in `.claude/hooks/`
+
+---
+
+## 1. Current State
+
+### Hook Inventory (33 hooks)
+
+| Category | Count | Hooks |
+|----------|-------|-------|
+| Session lifecycle | 4 | session_start, session_end, session_autosave_v2, session-source-sync |
+| Agent memory | 4 | skill_router, memory_hints_injector, agent_memory_persister, memory_updater |
+| Pipeline enforcement | 5 | post_batch_cascading, enforce_dual_location, enforce_plan_mode, quality_watchdog, post_write_validator |
+| Validation | 4 | creation_validator, post_output_validator, stop_hook_completeness, claude_md_guard |
+| Tracking | 5 | post_tool_use, pending_tracker, subagent_tracker, pattern_analyzer, token_checkpoint |
+| Utility | 5 | jarvis_briefing, checkpoint_writer, inbox_age_alert, notification_system, ledger_updater |
+| Indexing | 2 | skill_indexer, auto_formatter |
+| Agent system | 3 | multi_agent_hook, agent_doctor, ralph_wiggum |
+
+### Execution Context
+
+All hooks run as **Python scripts** invoked by Claude Code's hook system with:
+- **Full filesystem access** (read/write to any path the user can access)
+- **Full network access** (no restrictions on outbound connections)
+- **User-level privileges** (same as the Claude Code process)
+- **No process isolation** (no containers, chroot, or namespaces)
+- **30-second timeout** (configurable per hook)
+
+---
+
+## 2. Threat Analysis
+
+### T1: Path Traversal (MEDIUM)
+
+**Risk:** A hook could read/write files outside the mega-brain directory.
+
+**Current mitigations:**
+- All hooks use env-based paths (`CLAUDE_PROJECT_DIR` with `.` fallback)
+- `claude_md_guard.py` validates CLAUDE.md paths specifically
+- No hooks accept arbitrary user-controlled paths
+
+**Assessment:** LOW actual risk. Hooks are written by the system owner and are not user-facing. Path traversal is only a concern if hooks process untrusted input.
+
+### T2: Credential Exposure (HIGH)
+
+**Risk:** Hooks could accidentally log or expose credentials.
+
+**Current mitigations:**
+- `.env` is in `.gitignore`
+- Token files (`token.json`, `token_write.json`) now untracked (Quality Uplift SEC-002)
+- Hooks read state files, not credential files directly
+
+**Assessment:** MEDIUM residual. OAuth tokens were in git history (now untracked but not purged). Recommend `git filter-branch` or BFG to clean history.
+
+### T3: Unintended State Corruption (MEDIUM)
+
+**Risk:** Multiple hooks writing to the same state files concurrently.
+
+**Current mitigations:**
+- Hooks run sequentially within each lifecycle event
+- State files use JSON (atomic write via temp file + rename)
+- `post_batch_cascading.py` has explicit state locking
+
+**Assessment:** LOW actual risk. Claude Code runs hooks sequentially per event.
+
+### T4: Hook Chain Amplification (LOW)
+
+**Risk:** A hook could trigger actions that trigger other hooks (cascade).
+
+**Current mitigations:**
+- Claude Code hook system does not re-trigger hooks from hook actions
+- Hooks output to stdout/stderr, not tool calls
+
+**Assessment:** NOT APPLICABLE. Hook system is non-recursive by design.
+
+### T5: Denial of Service (LOW)
+
+**Risk:** A hook could hang or consume excessive resources.
+
+**Current mitigations:**
+- 30-second timeout per hook
+- Hooks are lightweight Python scripts
+- No hooks perform heavy computation or long network calls
+
+**Assessment:** ACCEPTABLE. Timeout is sufficient protection.
+
+---
+
+## 3. Sandboxing Decision
+
+### Recommendation: NO ADDITIONAL SANDBOXING REQUIRED
+
+**Rationale:**
+
+1. **Single-user system.** Mega Brain is operated by one user. Hooks are authored by the system owner, not untrusted third parties.
+
+2. **Claude Code enforces sequential execution.** No parallel hook execution means no race conditions.
+
+3. **Cost vs benefit.** Containerizing or sandboxing 33 hooks would add complexity and latency with minimal security benefit for a single-user development environment.
+
+4. **Existing mitigations are sufficient:**
+   - `claude_md_guard.py` for write protection
+   - `.gitignore` for credential protection
+   - 30s timeouts for DoS protection
+   - Sequential execution for consistency
+
+### Recommended Actions (Non-Sandboxing)
+
+| Action | Priority | Status |
+|--------|----------|--------|
+| Untrack credential files from git | HIGH | DONE (SEC-002) |
+| Purge credentials from git history | HIGH | PENDING (requires user approval) |
+| Keep `.env.example` updated | MEDIUM | DONE (STATE-002) |
+| Document hook write paths | LOW | DONE (GOVERNANCE-MAP.md) |
+| Review hooks annually | LOW | Schedule for 2027-02-18 |
+
+---
+
+## 4. Audit Trail
+
+### Current Logging
+
+| Hook | Logs to | Format |
+|------|---------|--------|
+| post_batch_cascading | `.claude/mission-control/batch-logs/` | JSON |
+| session_autosave_v2 | `.claude/mission-control/AUTOSAVE-STATE.json` | JSON |
+| skill_router | stdout (visible in session) | Text |
+| quality_watchdog | stdout | Text |
+| token_checkpoint | `.claude/jarvis/TOKEN-CHECKPOINT.json` | JSON |
+| pattern_analyzer | `.claude/learning-system/` | YAML |
+
+### Gaps
+
+- No centralized audit log for hook executions
+- No logging of hook failures (only stdout/stderr)
+- Recommendation: Add `logs/hooks/` directory for structured hook execution logs in future iteration
+
+---
+
+## 5. References
+
+| Document | Path |
+|----------|------|
+| CONSTITUTION.md | `system/protocols/CONSTITUTION.md` |
+| GOVERNANCE-MAP.md | `system/protocols/GOVERNANCE-MAP.md` |
+| ENFORCEMENT.md | `system/protocols/system/ENFORCEMENT.md` |
+| settings.json | `.claude/settings.json` (hook registrations) |

package/system/protocols/ORQUESTRACAO-PROTOCOL.md

@@ -0,0 +1,215 @@
+# ORQUESTRAÇÃO-PROTOCOL: Fluxo Completo do Sistema
+
+> **Versão:** 1.0.0
+> **Função:** Governar o fluxo desde pergunta até resposta final
+
+---
+
+## ARQUITETURA DE 3 CAMADAS
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                                                                                 │
+│                        CAMADA 1: CONSTITUIÇÃO BASE                              │
+│                                                                                 │
+│   Filosofia: Empirismo, Pareto, Inversão, Antifragilidade                      │
+│   Path: /system/protocols/CONSTITUICAO-BASE.md                              │
+│   Aplica-se: TODOS os agentes                                                  │
+│                                                                                 │
+└─────────────────────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                                                                                 │
+│                      CAMADA 2: AGENTES ESPECIALIZADOS                           │
+│                                                                                 │
+│   CARGO (Híbrido):                                                             │
+│   • C-LEVEL: CRO, CFO, CMO, COO                                                │
+│   • SALES: CLOSER, BDR, SDS, LNS, SALES-MANAGER, etc.                         │
+│   Path: /agents/cargo/                                                      │
+│                                                                                 │
+│   PERSONS (Solo - só via /consult):                                            │
+│   Path: /agents/persons/                                                    │
+│                                                                                 │
+│                                                                                 │
+└─────────────────────────────────────────────────────────────────────────────────┘
+                                       │
+                                       │ (debate entre agentes)
+                                       ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                                                                                 │
+│                        CAMADA 3: COUNCIL (Meta-avaliação)                       │
+│                                                                                 │
+│   1º CRÍTICO METODOLÓGICO → Avalia qualidade do processo                       │
+│   2º ADVOGADO DO DIABO → Ataca premissas e riscos                              │
+│   3º SINTETIZADOR → Integra em decisão final                                   │
+│                                                                                 │
+│   Path: /agents/council/                                                    │
+│   Protocol: /system/protocols/conclave/CONCLAVE-PROTOCOL.md                 │
+│                                                                                 │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## FLUXO DE DECISÃO DO MASTER-AGENT
+
+```
+                              ENTRADA
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           CLASSIFICAÇÃO                                          │
+│                                                                                 │
+│   ┌───────────────────┬─────────────────────────────────────┬───────────────┐  │
+│   │ TIPO              │ EXEMPLO                             │ COUNCIL?      │  │
+│   ├───────────────────┼─────────────────────────────────────┼───────────────┤  │
+│   │ A: /consult       │ /consult cole "Como fazer pitch?"   │ NÃO           │  │
+│   │ B: /board         │ /board "Contratar SM agora?"        │ SIM           │  │
+│   │ C: Simples        │ "Qual benchmark de close rate?"     │ NÃO           │  │
+│   │ D: Complexa       │ "Como escalar de 1M para 5M?"       │ SIM           │  │
+│   │ E: Operacional    │ /process-video                      │ NÃO           │  │
+│   └───────────────────┴─────────────────────────────────────┴───────────────┘  │
+│                                                                                 │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## FLUXOS DETALHADOS
+
+### TIPO A: /consult (Consulta Direta)
+
+```
+/consult {pessoa} "{pergunta}"
+         │
+         ▼
+Identificar AGENT-PERSON
+         │
+         ▼
+Carregar: AGENT → SOUL → DNA-CONFIG → MEMORY
+         │
+         ▼
+Responder na VOZ da pessoa
+         │
+         ▼
+OUTPUT DIRETO (sem Council)
+```
+
+### TIPO B: /board (Conselho de Experts)
+
+```
+/board "{pergunta}"
+         │
+         ▼
+         │
+         ▼
+Debate entre PERSONS
+         │
+         ▼
+COUNCIL avalia:
+  1. Crítico Metodológico
+  2. Advogado do Diabo
+  3. Sintetizador
+         │
+         ▼
+DECISÃO DO COUNCIL
+```
+
+### TIPO C: Pergunta Simples
+
+```
+"{pergunta de domínio específico}"
+         │
+         ▼
+Identificar domínio → Selecionar 1 AGENT-CARGO
+         │
+         ▼
+Carregar: AGENT → SOUL → DNA-CONFIG → MEMORY
+         │
+         ▼
+         │
+         ▼
+OUTPUT DIRETO (sem Council)
+```
+
+### TIPO D: Pergunta Complexa
+
+```
+"{pergunta multi-domínio ou decisão significativa}"
+         │
+         ▼
+Identificar domínios → Selecionar 2-4 AGENT-CARGO
+         │
+         ▼
+DEBATE entre agentes (posições, evidências, recomendações)
+         │
+         ▼
+COUNCIL avalia:
+  1. Crítico Metodológico
+  2. Advogado do Diabo
+  3. Sintetizador
+         │
+         ▼
+DECISÃO DO COUNCIL
+```
+
+---
+
+## REGRA FUNDAMENTAL: CARGO vs PERSON
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                                                                                 │
+│                                                                                 │
+│   Pergunta: "Como fechar venda high-ticket?"                                   │
+│   → CLOSER responde (tem DNA Cole 95% + Hormozi 85%)                           │
+│   → NÃO roteia para AGENT-PERSON                                               │
+│                                                                                 │
+│   AGENT-PERSON só via:                                                         │
+│   • /consult cole "pergunta"                                                   │
+│   • /consult hormozi "pergunta"                                                │
+│   • /board "pergunta"                                                          │
+│   • Menção explícita "como Cole faria"                                         │
+│                                                                                 │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## QUANDO ACIONAR COUNCIL
+
+```
+COUNCIL É ACIONADO SE:
+✅ 2+ agentes CARGO participam do debate
+✅ Há divergência significativa
+✅ Decisão tem impacto relevante
+✅ Usuário pede /board
+
+COUNCIL NÃO É ACIONADO SE:
+❌ Pergunta simples (1 agente)
+❌ /consult direto a PERSON
+❌ Comando operacional
+❌ Consenso total entre agentes
+```
+
+---
+
+## PROTOCOLOS RELACIONADOS
+
+| Protocolo | Path |
+|-----------|------|
+| CONSTITUIÇÃO BASE | `/system/protocols/CONSTITUICAO-BASE.md` |
+| AGENT-COGNITION | `/agents/protocols/AGENT-COGNITION-PROTOCOL.md` |
+| CONCLAVE-PROTOCOL | `/system/protocols/conclave/CONCLAVE-PROTOCOL.md` |
+| DEBATE-PROTOCOL | `/system/protocols/conclave/DEBATE-PROTOCOL.md` |
+| EPISTEMIC | `/agents/protocols/EPISTEMIC-PROTOCOL.md` |
+| MEMORY | `/agents/protocols/MEMORY-PROTOCOL.md` |
+
+---
+
+## AGENT-INDEX
+
+Path: `/agents/AGENT-INDEX.yaml`
+
+Contém índice completo de todos os agentes para roteamento rápido.

package/system/protocols/_archive/CHUNKING-PROTOCOL.md

@@ -0,0 +1,207 @@
+# CHUNKING PROTOCOL (Prompt 1.1)
+
+> **Versão:** 1.0.0
+> **Pipeline:** Jarvis → Etapa 1.1
+> **Output:** `/processing/chunks/CHUNKS-{SOURCE}-{DATE}.json`
+
+---
+
+## PROPÓSITO
+
+Transformar conteúdo bruto em chunks semânticos preservando:
+- Contexto suficiente para compreensão isolada
+- Metadados de rastreabilidade
+- Estrutura para processamento downstream
+
+---
+
+## INPUT
+
+```
+{
+  "source": {
+    "source_id": "unique_id",
+    "source_type": "call|video|doc|meeting",
+    "source_title": "Título do conteúdo",
+    "source_datetime": "YYYY-MM-DD HH:MM",
+    "source_duration_minutes": N,
+    "corpus": "empresa|pessoal|cursos",
+    "participants": ["Nome1", "Nome2"]
+  },
+  "raw_content": "Conteúdo completo da transcrição ou documento..."
+}
+```
+
+---
+
+## TAREFA
+
+### 1. Identificação de Quebras Naturais
+
+Identificar pontos de quebra onde:
+- Muda o tópico principal sendo discutido
+- Muda o speaker (em transcrições)
+- Há conclusão de um argumento/ideia
+- Inicia nova seção/capítulo (em docs)
+
+### 2. Criação de Chunks
+
+Para cada segmento identificado, criar chunk com:
+
+```json
+{
+  "id_chunk": "chunk_{source_id}_{sequential_number}",
+  "content": "Texto do segmento...",
+  "timestamp_start": "HH:MM:SS",
+  "timestamp_end": "HH:MM:SS",
+  "speaker": "Nome ou null",
+  "topic_hint": "Descrição curta do tópico (5-10 palavras)",
+  "mentions": {
+    "persons": ["Nome1", "Nome2"],
+    "companies": ["Empresa1"],
+    "themes": ["tema1", "tema2"]
+  },
+  "metadata": {
+    "word_count": N,
+    "has_numbers": true|false,
+    "has_framework": true|false,
+    "sentiment": "positive|negative|neutral",
+    "actionability": "high|medium|low"
+  }
+}
+```
+
+### 3. Regras de Tamanho
+
+| Tipo de Conteúdo | Tamanho Ideal | Máximo |
+|------------------|---------------|--------|
+| Transcrição call | 200-400 palavras | 600 palavras |
+| Vídeo longo | 300-500 palavras | 800 palavras |
+| Documento | 400-600 palavras | 1000 palavras |
+
+### 4. Regras de Contexto
+
+- **Overlap:** Se necessário, incluir 1-2 frases do chunk anterior para contexto
+- **Referências:** Se chunk menciona "isso" ou "aquilo", incluir contexto suficiente
+- **Completude:** Chunk deve ser compreensível isoladamente
+
+---
+
+## OUTPUT
+
+```json
+{
+  "chunking_result": {
+    "source": { /* cópia do input source */ },
+    "processing_datetime": "YYYY-MM-DD HH:MM:SS",
+    "chunks_total": N,
+    "chunks": [
+      {
+        "id_chunk": "chunk_source123_001",
+        "content": "...",
+        "timestamp_start": "00:01:30",
+        "timestamp_end": "00:03:45",
+        "speaker": "Alex Hormozi",
+        "topic_hint": "Estrutura de comissionamento para closers",
+        "mentions": {
+          "persons": ["Alex Hormozi"],
+          "companies": ["Alex Hormozi"],
+          "themes": ["comissionamento", "closer", "high-ticket"]
+        },
+        "metadata": {
+          "word_count": 287,
+          "has_numbers": true,
+          "has_framework": false,
+          "sentiment": "neutral",
+          "actionability": "high"
+        }
+      },
+      /* ... mais chunks ... */
+    ],
+    "summary": {
+      "total_words": N,
+      "avg_chunk_size": N,
+      "unique_speakers": ["Nome1", "Nome2"],
+      "main_topics": ["topic1", "topic2", "topic3"]
+    }
+  }
+}
+```
+
+---
+
+## REGRAS DE QUALIDADE
+
+### FAZER:
+- Preservar citações exatas quando relevantes
+- Manter números e métricas precisos
+- Incluir contexto suficiente para compreensão
+- Identificar todos os speakers mencionados
+- Extrair temas mesmo que implícitos
+
+### NÃO FAZER:
+- Quebrar no meio de uma ideia/argumento
+- Criar chunks muito pequenos (<100 palavras) exceto se for citação importante
+- Remover contexto que deixaria chunk ambíguo
+- Inferir informações não presentes no texto
+
+---
+
+## EXEMPLO DE CHUNKING
+
+### Input (trecho):
+```
+[00:12:30] Alex Hormozi: "A estrutura de comissão que funciona é simples:
+25-30% do valor do deal para o closer. Não complique. Se você está pagando
+menos que isso em high-ticket, seus melhores closers vão embora.
+
+[00:13:15] O que eu vejo muito é empresa querendo pagar 10-15% e depois
+reclamando que não consegue reter talento. É óbvio. Você está competindo
+com quem paga o dobro.
+
+[00:14:00] Entrevistador: E como você estrutura o ramp-up de novos closers?
+
+[00:14:10] Alex Hormozi: Primeiro, dou 90 dias de garantia. O cara recebe
+um salário base garantido enquanto está aprendendo o processo..."
+```
+
+### Output (chunk):
+```json
+{
+  "id_chunk": "chunk_hormozi_podcast_001",
+  "content": "Alex Hormozi: \"A estrutura de comissão que funciona é simples: 25-30% do valor do deal para o closer. Não complique. Se você está pagando menos que isso em high-ticket, seus melhores closers vão embora. O que eu vejo muito é empresa querendo pagar 10-15% e depois reclamando que não consegue reter talento. É óbvio. Você está competindo com quem paga o dobro.\"",
+  "timestamp_start": "00:12:30",
+  "timestamp_end": "00:13:45",
+  "speaker": "Alex Hormozi",
+  "topic_hint": "Estrutura de comissão para closers high-ticket",
+  "mentions": {
+    "persons": ["Alex Hormozi"],
+    "companies": [],
+    "themes": ["comissionamento", "closer", "high-ticket", "retenção"]
+  },
+  "metadata": {
+    "word_count": 89,
+    "has_numbers": true,
+    "has_framework": false,
+    "sentiment": "neutral",
+    "actionability": "high"
+  }
+}
+```
+
+---
+
+## SALVAMENTO
+
+Salvar output em:
+```
+/processing/chunks/CHUNKS-{SOURCE_ID}-{YYYYMMDD}.json
+```
+
+Exemplo: `CHUNKS-HORMOZI-PODCAST-234-20251215.json`
+
+---
+
+## PRÓXIMA ETAPA
+
+Output alimenta **Prompt 1.2: Entity Resolution** para canonicalização de entidades.