sinapse-ai 9.4.0 → 10.0.0-rc.2

package/.claude/CLAUDE.md

@@ -87,11 +87,17 @@ Use Grep (not grep), Read (not cat), Edit (not sed), Glob (not find). Prefer nat
 - 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.
 
-## Delegation Model
+## Token Economy & Response Format (NON-NEGOTIABLE)
 
-- **Persona switch:** For sequential agent work in same context (lightweight)
-- **Sub-agent (Agent tool):** Only for parallel/isolated work (min ~20K tokens overhead)
-- **Never** spawn sub-agents for simple sequential tasks — use persona switch instead
+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/enforce-git-push-authority.sh

@@ -1,13 +1,34 @@
 #!/bin/bash
 # enforce-git-push-authority.sh
-# PreToolUse hook: blocks "git push" commands in Bash tool
-# Only meant to run when agent is NOT @devops
+# PreToolUse hook: blocks "git push" commands in Bash tool unless active agent is @devops
+# Detects active agent via .sinapse/session-state.json (same pattern as enforce-delegation.cjs)
 # Uses node (not jq) for JSON parsing — works on Windows/Git Bash
-# FAIL-CLOSED: if parsing fails, blocks the command (exit 2)
-# Hardened v2: also detects indirect execution via script files and pipes
+# FAIL-CLOSED: if parsing fails OR session-state is missing/unreadable, blocks the command
+# Hardened v3: adds real agent detection (Story 10.15), retains indirect-execution checks
 
 INPUT=$(cat)
 
+# Resolve project root consistently with other hooks
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Detect active agent from session state (fail-closed: empty string on any error)
+AGENT=$(node -e "
+  const fs = require('fs');
+  const path = require('path');
+  try {
+    const p = path.join(process.argv[1], '.sinapse', 'session-state.json');
+    const s = JSON.parse(fs.readFileSync(p, 'utf8'));
+    console.log(s.lastAgent || '');
+  } catch (e) {
+    console.log('');
+  }
+" "$PROJECT_ROOT" 2>/dev/null)
+
+# If active agent is @devops, allow the command immediately (AC 1)
+if [ "$AGENT" = "devops" ]; then
+  exit 0
+fi
+
 # Extract command from JSON using node (available on all SINAPSE systems)
 COMMAND=$(echo "$INPUT" | node -e "
   let d='';

package/.claude/hooks/verify-packages.cjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * verify-packages.cjs — Slopsquatting Prevention Hook
+ *
+ * Blocks `npm install`/`npm add` commands that reference packages
+ * not found on the npm registry. Prevents installation of hallucinated
+ * (fabricated) packages that attackers may register with malicious code.
+ *
+ * Research: 19.7% of packages recommended by LLMs are fabricated.
+ * Source: arXiv study, 576K samples across 16 models.
+ *
+ * Hook type: PreToolUse (Bash)
+ * Exit 0 = allow, Exit 2 = block
+ */
+'use strict';
+
+const { execSync } = require('child_process');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (d) => { input += d; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const command = (data.tool_input && data.tool_input.command) || '';
+
+    // Only check direct npm install/add commands (not text in PR bodies, etc.)
+    // Skip if command is gh, curl, echo, or other non-npm commands
+    const trimmed = command.trim();
+    if (trimmed.startsWith('gh ') || trimmed.startsWith('curl ') || trimmed.startsWith('echo ')) process.exit(0);
+    const installMatch = trimmed.match(/^npm\s+(install|add|i)\s+(.+)/m);
+    if (!installMatch) process.exit(0);
+
+    const argsStr = installMatch[2];
+
+    // Extract package names, skipping flags (--save-dev, -D, etc.)
+    const tokens = argsStr.split(/\s+/).filter(t => !t.startsWith('-'));
+    if (tokens.length === 0) process.exit(0);
+
+    const failed = [];
+    for (const token of tokens) {
+      // Strip version specifier: pkg@1.0.0 -> pkg, @org/pkg@^2 -> @org/pkg
+      let pkgName;
+      if (token.startsWith('@')) {
+        // Scoped package: @org/pkg@version
+        const slashIdx = token.indexOf('/');
+        if (slashIdx === -1) continue; // malformed, skip
+        const afterSlash = token.substring(slashIdx + 1);
+        const atIdx = afterSlash.indexOf('@');
+        pkgName = atIdx > 0
+          ? token.substring(0, slashIdx + 1 + atIdx)
+          : token;
+      } else {
+        const atIdx = token.indexOf('@');
+        pkgName = atIdx > 0 ? token.substring(0, atIdx) : token;
+      }
+
+      // Skip if it looks like a local path or URL
+      if (pkgName.startsWith('.') || pkgName.startsWith('/') || pkgName.includes('://')) continue;
+      if (pkgName.endsWith('.tgz') || pkgName.endsWith('.tar.gz')) continue;
+
+      try {
+        execSync(`npm view "${pkgName}" name`, { timeout: 8000, stdio: 'pipe' });
+      } catch {
+        failed.push(pkgName);
+      }
+    }
+
+    if (failed.length > 0) {
+      const names = failed.map(n => `'${n}'`).join(', ');
+      const msg = failed.length === 1
+        ? `BLOCKED: Package ${names} not found on npm. This may be a hallucinated package (slopsquatting).`
+        : `BLOCKED: Packages ${names} not found on npm. These may be hallucinated packages (slopsquatting).`;
+      process.stderr.write(msg + '\n');
+      process.exit(2);
+    }
+
+    process.exit(0);
+  } catch {
+    // Fail-open: if hook crashes, allow the operation
+    process.exit(0);
+  }
+});

package/.claude/rules/hook-governance.md

@@ -14,6 +14,7 @@ paths:
 | Hook | Purpose | Behavior |
 |------|---------|----------|
 | `enforce-git-push-authority.sh` | Art. II — Only @devops can push | BLOCK (deny) |
+| `verify-packages.cjs` | Security — Block hallucinated npm packages (slopsquatting) | BLOCK (exit 2) |
 | `sql-governance.py` | Security — Block dangerous SQL | BLOCK (exit 2) |
 | `enforce-delegation.cjs` | Art. VIII — Orchestrators can't execute | BLOCK (exit 2) |
 

package/.claude/rules/mandatory-delegation.md

@@ -91,6 +91,30 @@ Everything OUTSIDE their orchestration domain MUST be delegated.
 - Saying "vou fazer isso eu mesmo" instead of delegating
 - Absorbing a request and executing it instead of routing
 
+## Universal Auto-Routing (users should NEVER call agents manually)
+
+Users are NOT AI experts. The system MUST understand natural language and route automatically.
+
+**On EVERY user message (not just orchestrator):**
+1. Detect the domain of the request
+2. If a specialist exists → delegate automatically (no confirmation needed)
+3. Brief acknowledgment: "Delegando para @specialist..."
+4. Return the result to the user
+
+**Auto-detect project state on first interaction:**
+- Check for `.sinapse-ai/` → SINAPSE-managed (continue SDC)
+- Check for `package.json` or `.git` → Brownfield (run quick tech scan first)
+- Empty directory → Greenfield (ask project type, scaffold)
+
+**Cross-agent handoff (automatic, never ask user):**
+- Agent needs git push → auto-delegate to @devops
+- Agent needs tests → auto-delegate to @quality-gate
+- Agent needs schema → auto-delegate to @data-engineer
+- Agent needs story → auto-create via fast-track or @sprint-lead
+- Agent needs architecture decision → auto-delegate to @architect
+
 ## Enforcement
 
 Any response from an orchestrator that contains direct domain work (code, schema, copy, etc.) without having first delegated to the appropriate specialist is a **constitutional violation** and must be corrected immediately.
+
+Any response that asks the user to manually invoke an agent (showing `@agent-name` or `/SINAPSE:agents:...` commands) instead of auto-routing is a **UX violation** — the system should just do it.

package/.claude/rules/project-intelligence.md

@@ -0,0 +1,63 @@
+# Project Intelligence — Auto-Detection (NON-NEGOTIABLE)
+
+> Applies to ALL agents, ALL sessions. Users NEVER configure project type manually.
+
+## Auto-Detect on First Interaction
+
+Before ANY work, silently detect project state:
+
+```
+1. Check: does .sinapse-ai/ exist?
+   YES → SINAPSE-managed project. Read core-config.yaml for context.
+   NO  → Continue to step 2.
+
+2. Check: is directory empty (or only has .git)?
+   YES → GREENFIELD. Ask project type, then scaffold.
+   NO  → Continue to step 3.
+
+3. Check: does package.json or .git exist?
+   YES → BROWNFIELD. Run quick tech scan, then proceed.
+   NO  → UNKNOWN. Ask user what they want to build.
+```
+
+## Quick Tech Scan (BROWNFIELD, < 5 seconds)
+
+When brownfield detected, silently check:
+
+| Check | How | Sets Context |
+|-------|-----|-------------|
+| Framework | package.json dependencies | next/react/vue/angular/express |
+| Language | tsconfig.json exists? | typescript/javascript |
+| Database | supabase/, prisma/, .env | supabase/prisma/drizzle/none |
+| Tests | jest.config, vitest.config | jest/vitest/none |
+| CI | .github/workflows/ | github-actions/none |
+
+Report to user in ONE line: "Projeto Next.js + TypeScript + Supabase detectado."
+
+## Behavior Adaptation by State
+
+### Greenfield Behavior
+- Prioritize: scaffolding, architecture decisions, project setup
+- Workflow: setup → story → implement (no brownfield discovery needed)
+- Auto-apply: infra templates (PR template, CI, .env.example, CODEOWNERS)
+- Ask: "Que tipo de projeto? (web app, API, SaaS, landing page)"
+
+### Brownfield Behavior
+- Prioritize: understanding existing code before changing anything
+- First action: read README, package.json, folder structure
+- Workflow: quick scan → understand → then proceed with user request
+- NEVER rewrite or refactor without understanding existing patterns
+- Respect existing conventions (naming, folder structure, testing framework)
+
+### SINAPSE-Managed Behavior
+- Check for active story in docs/stories/
+- Resume where last session left off
+- Follow SDC workflow (story → implement → QA → push)
+
+## Anti-Patterns (FORBIDDEN)
+
+- Asking user "is this a new or existing project?"
+- Asking user to set `projectType` in config
+- Starting implementation in brownfield without reading existing code first
+- Applying greenfield templates to a brownfield project (overwriting existing CI/configs)
+- Ignoring existing patterns and imposing SINAPSE conventions forcefully

package/.claude/rules/safe-collaboration.md

@@ -91,8 +91,10 @@ Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
 After push, the agent MUST:
 ```
 1. gh pr create with clear title and description (uses PR template)
-2. Auto-assign the OTHER person as reviewer
-3. Inform the user: "PR criado, {outro} precisa aprovar"
+2. Auto-assign reviewer based on who is pushing:
+   - Caio's PR → Caio can merge directly (admin bypass)
+   - Matheus's PR → Assign @caioimori as reviewer (required approval)
+3. Inform the user: "PR criado"
 ```
 
 ### 6. After PR Merge — Cleanup

package/.claude/rules/security-data-protection.md

@@ -98,6 +98,24 @@ db.query('SELECT * FROM users WHERE name = $1', [input]);
 supabase.from('users').select('*').eq('name', input);
 ```
 
+### RLS Performance Optimization (research-backed, ~95% improvement)
+
+```sql
+-- SLOW: auth.uid() called per-row (function call overhead)
+CREATE POLICY "bad" ON items USING (auth.uid() = user_id);
+
+-- FAST: subselect evaluates once per query (~95% faster)
+CREATE POLICY "good" ON items USING ((SELECT auth.uid()) = user_id);
+```
+
+**Index strategy:** Create indexes on EVERY column used in RLS USING/WITH CHECK clauses:
+```sql
+CREATE INDEX idx_items_user ON items(user_id);
+CREATE INDEX idx_items_org ON items(org_id);
+```
+
+**Anti-patterns:** No `EXISTS` subqueries in RLS, no JOINs in policies, no RLS on tables accessed >1000 req/s without indexes.
+
 ### Least Privilege
 - Each service uses a dedicated role with minimal permissions
 - Read-only services get SELECT only

package/.claude/rules/squad-awareness.md

@@ -4,70 +4,96 @@ paths:
   - ".sinapse-ai/development/agents/**"
 ---
 
-# Sinapse — Orchestration Rules
-
-> **CRITICAL:** This project has specialized AI agent squads installed. When a user request falls within a domain covered by a squad, you MUST delegate to the appropriate specialist agent instead of handling it yourself.
-
-## Delegation Rule
-
-When a user request matches a squad domain (see table below):
-1. **Acknowledge** the domain is covered by a specialized squad
-2. **Recommend** activating the squad's orchestrator or specialist agent
-3. **Provide** the invocation command (e.g., `/ca:agents:ca-orchestrator`)
-4. **Do NOT** handle the request yourself if a dedicated agent exists
-
-**Exception:** If the user explicitly asks you to handle it anyway, proceed — but note the specialized squad exists.
-
-## Squads Instaladas
-
-| Squad | Capacidade |
-|-------|-----------|
-
-
-## Mapa de Delegacao por Dominio
-
-| Dominio | Squad | Agente Lead | Invocacao |
-|---------|-------|-------------|-----------|
-| Branding e identidade visual | squad-brand | brand-orchestrator (Meridian) | `/brand:agents:brand-orchestrator` |
-| Vendas e estrategia comercial | squad-commercial | cs-orchestrator (Pipeline) | `/commercial:agents:cs-orchestrator` |
-| Conteudo e editorial | squad-content | content-orchestrator | `/content:agents:content-orchestrator` |
-| Copywriting e persuasao | squad-copy | copy-strategist (Quill) | `/copywriting:agents:copy-strategist` |
-| Animacoes web, Three.js, shaders, motion | squad-animations | ca-orchestrator (Kinetic) | `/ca:agents:ca-orchestrator` |
-| UX/UI e experiencia digital | squad-design | dx-orchestrator (Nexus) | `/digital-experience:agents:dx-orchestrator` |
-| Inteligencia financeira e pricing | squad-finance | fi-orchestrator (Ledger) | `/finance:agents:fi-orchestrator` |
-| Growth organico, SEO e analytics | squad-growth | ga-orchestrator (Catalyst) | `/growth:agents:ga-orchestrator` |
-| Midia paga (Meta Ads, Google Ads, CRO) | squad-paidmedia | pm-orchestrator (Apex) | `/pm:agents:pm-orchestrator` |
-| Produto e discovery | squad-product | ps-orchestrator (Vector) | `/product:agents:ps-orchestrator` |
-| Pesquisa e inteligencia competitiva | squad-research | research-orchestrator (Prism) | `/research:agents:research-orchestrator` |
-| Claude Code mastery e automacao | squad-claude | cm-orchestrator (Orion) | `/claude:agents:cm-orchestrator` |
-| Conselho estrategico e modelos mentais | squad-council | council-orchestrator (Zenith) | `/council:agents:council-orchestrator` |
-| Narrativa, storytelling e pitch | squad-storytelling | narrative-orchestrator (Arc) | `/narrative:agents:narrative-orchestrator` |
-| Seguranca cibernetica e compliance | squad-cybersecurity | cyber-orchestrator (Fortress) | `/cyber:agents:cyber-orchestrator` |
-
-## Quando Delegar
-
-| Situacao | Squad |
-|----------|-------|
-| Animacao/motion/Three.js/shader | squad-animations |
-| Copy/headline/persuasao | squad-copy |
-| Branding/identidade/logo | squad-brand |
-| Pesquisa/benchmark/analise competitiva | squad-research |
-| Conteudo/editorial/blog/social media | squad-content |
-| UX/UI/design system/wireframe | squad-design |
-| Growth/SEO/analytics/metricas organicas | squad-growth |
-| Vendas/proposta/pitch/CRM | squad-commercial |
-| Financeiro/pricing/P&L/budget | squad-finance |
-| Midia paga/Meta Ads/Google Ads/CRO | squad-paidmedia |
-| Produto/discovery/roadmap | squad-product |
-| Claude Code/prompt engineering/MCP | squad-claude |
-| Conselho estrategico/modelos mentais/decisao | squad-council |
-| Storytelling/narrativa/pitch/apresentacao | squad-storytelling |
-| Seguranca/pentest/compliance/incident response | squad-cybersecurity |
-
-## Handoff Protocol
-
-1. **Identificar** o dominio do pedido
-2. **Informar** qual squad cobre e como invocar: `/{prefix}:agents:{agent-id}`
-3. **Fornecer contexto** do handoff se necessario
-4. Squads sao **autonomas** — o orchestrator coordena internamente
-5. Squads possuem **knowledge bases**, **tasks** e **workflows** proprios em `./squads/{squad-name}/`
+# Sinapse — Intelligent Auto-Routing (NON-NEGOTIABLE)
+
+> Users are NOT AI experts. They should NEVER need to know agent names, commands, or squad structures.
+> The system MUST understand natural language and route automatically.
+
+## Golden Rule
+
+**User types anything → SINAPSE understands → Routes to the right specialist → Delivers result.**
+
+The user NEVER needs to:
+- Know which agent handles what
+- Type `@agent-name` or `/SINAPSE:agents:...`
+- Understand greenfield vs brownfield
+- Know about squads, orchestrators, or handoffs
+
+## Auto-Detection at Session Start
+
+On EVERY session start, automatically detect:
+1. **Project State:** Greenfield (empty/new) | Brownfield (existing code) | SINAPSE-managed
+2. **Tech Stack:** Framework, language, database, testing, CI/CD
+3. **Maturity:** Score 0-10 based on tests, docs, CI presence
+
+Use this context to adjust behavior:
+- **Greenfield:** Start with scaffolding, architecture decisions, project setup
+- **Brownfield:** Start with discovery, tech debt assessment, understanding existing code
+- **SINAPSE-managed:** Continue normal SDC workflow
+
+## Automatic Request Routing
+
+When ANY user message arrives, classify and route:
+
+| User Says (examples) | Route To | How |
+|----------------------|----------|-----|
+| "cria um site", "novo projeto", "scaffold" | @architect → @developer | Greenfield workflow |
+| "arruma esse bug", "fix isso" | @developer | Fast-track if trivial |
+| "cria uma marca", "logo", "identidade" | squad-brand | Auto-delegate |
+| "escreve um copy", "headline", "landing page" | squad-copy | Auto-delegate |
+| "pesquisa sobre X", "analise competitiva" | squad-research | Auto-delegate |
+| "faz deploy", "publica", "push" | @devops | Exclusive authority |
+| "testa isso", "quality check" | @quality-gate | QA gate |
+| "cria uma story", "nova feature" | @sprint-lead → @product-lead | SDC workflow |
+| "animacao", "three.js", "shader" | squad-animations | Auto-delegate |
+| "SEO", "growth", "analytics" | squad-growth | Auto-delegate |
+| "ads", "campanha", "meta ads" | squad-paidmedia | Auto-delegate |
+| "financeiro", "pricing", "P&L" | squad-finance | Auto-delegate |
+| "seguranca", "pentest", "LGPD" | squad-cybersecurity | Auto-delegate |
+| "conteudo", "blog", "editorial" | squad-content | Auto-delegate |
+| "design system", "UI", "wireframe" | squad-design | Auto-delegate |
+| "estrategia", "conselho", "decisao" | squad-council | Auto-delegate |
+| "storytelling", "pitch", "narrativa" | squad-storytelling | Auto-delegate |
+| "vende isso", "proposta", "CRM" | squad-commercial | Auto-delegate |
+| "produto", "roadmap", "discovery" | squad-product | Auto-delegate |
+
+## Handoff Protocol (Automatic)
+
+When routing between agents/squads:
+1. **Never ask permission** — just route
+2. **Provide context** — pass the user's original request + project state
+3. **Confirm briefly** — "Delegando para @specialist que e o expert nisso."
+4. **Return result** — bring the deliverable back to the user
+
+## Brownfield Auto-Behavior
+
+When project is detected as BROWNFIELD and user hasn't run discovery:
+1. **First interaction:** "Detectei um projeto existente. Vou analisar a estrutura antes de comecar."
+2. **Auto-run:** Quick tech stack scan (< 30 seconds, not full brownfield discovery)
+3. **Inform:** "Projeto {framework} com {database}. Pronto para trabalhar."
+4. **Then proceed** with the user's original request
+
+## Greenfield Auto-Behavior
+
+When project is detected as GREENFIELD:
+1. **First interaction:** "Projeto novo detectado. Vou configurar a estrutura ideal."
+2. **Ask minimal:** "Que tipo de projeto? (web app, API, landing page)"
+3. **Auto-scaffold:** Apply templates, CI/CD, .env.example
+4. **Then proceed** with implementation
+
+## Tool & Command Handoff
+
+When ANY agent encounters a task outside its domain:
+- **Git push needed** → Auto-delegate to @devops (NEVER ask user)
+- **Database work** → Auto-delegate to @data-engineer
+- **Test needed** → Auto-delegate to @quality-gate
+- **Architecture decision** → Auto-delegate to @architect
+- **Story needed** → Auto-create via fast-track (trivial) or @sprint-lead (complex)
+
+## Anti-Patterns (FORBIDDEN)
+
+- Asking user "which agent should handle this?"
+- Showing agent invocation commands to the user
+- Requiring user to type `@agent-name` for routing
+- Leaving a task unfinished because "that's another agent's job" without auto-delegating
+- Asking user if project is greenfield or brownfield (auto-detect it)

package/.codex/agents/analyst.md

@@ -203,6 +203,96 @@ autoClaude:
 
 ---
 
+## Research-Backed Frameworks
+
+### Knowledge Architecture (GraphRAG)
+
+Modern knowledge systems combine three retrieval paradigms for maximum accuracy:
+
+```
+[Query]
+  --> BM25 (keyword search) --> Top-K results
+  --> Dense Embeddings (semantic) --> Top-K results
+  --> Knowledge Graph (structured) --> Entities/Relations
+  --> Reciprocal Rank Fusion (RRF) --> Merged & Ranked
+  --> Cross-Encoder Reranking --> Final Top-N
+  --> LLM Generation with Context
+```
+
+**Why hybrid matters:** BM25 alone misses semantic similarity. Embeddings alone miss exact terms (product codes, acronyms, legal terms). Graph alone misses nuance. Hybrid search reduces errors by 35-60% vs semantic-only retrieval.
+
+### Context Engineering (Karpathy 2025)
+
+**Definition (Andrej Karpathy):** "Context engineering is the delicate art and science of filling the context window with just the right information for the next step."
+
+**Mental model:** Think of the LLM as a CPU. The context window is RAM. Your job is analogous to an OS: load working memory with exactly the right code and data for the task.
+
+| Memory Tier | Analogy | Function | Cost |
+|-------------|---------|----------|------|
+| HOT | Working memory | Active task info in context window | Direct tokens |
+| WARM | Short-term | Retrievable in <300ms via vector/graph search | Low |
+| COLD | Long-term | On-demand from filesystem/archive | Minimal |
+
+**Token budget principle:** A well-managed memory system cuts token costs by ~90% and latency by ~91% vs sending full history.
+
+### Research Synthesis Framework
+
+When conducting research, apply the FINDING-IMPLICATION-RECOMMENDATION pattern:
+
+1. **FINDING:** Objective fact with source attribution
+2. **IMPLICATION:** What this means for the project/decision
+3. **RECOMMENDATION:** Actionable next step
+
+Example:
+- **FINDING:** 82% of container users run K8s in production (CNCF 2025)
+- **IMPLICATION:** K8s is mainstream, not bleeding-edge risk for SINAPSE projects
+- **RECOMMENDATION:** Include K8s patterns in architect knowledge base
+
+### Organization Frameworks for Knowledge
+
+| Framework | Structure | Best For |
+|-----------|-----------|----------|
+| Zettelkasten | Network of atomic interlinked notes | Research, writing, idea emergence |
+| PARA | Projects / Areas / Resources / Archives | Action-oriented productivity |
+| Evergreen Notes | Conceptual notes that evolve over time | Deep reflection, lasting knowledge |
+| MOC (Maps of Content) | Index notes aggregating themes | Navigation in large vaults |
+| Knowledge Graph | Entities + relations + attributes | Agent reasoning, inference |
+
+### Vector Database Selection (2026)
+
+| Database | Best For | Max Scale | Compliance |
+|----------|----------|-----------|------------|
+| Pinecone | Enterprise production | Billions | SOC 2 II, ISO 27001 |
+| Weaviate | Native hybrid search | Hundreds of millions | SOC 2 II, HIPAA |
+| Qdrant | Performance/cost ratio | Hundreds of millions | SOC 2 II |
+| pgvector | PostgreSQL integration (Supabase) | 5-100M | Inherits from PG |
+| Chroma | Rapid prototyping | Millions | Open-source |
+
+**Strategy:** Start with pgvector/Chroma for prototype, migrate to Pinecone/Weaviate for production.
+
+### Agentic RAG Patterns
+
+Modern RAG systems are not simple retrieve-then-generate. State of the art (2026):
+
+1. **Plan:** Decompose query into sub-queries
+2. **Retrieve:** Hybrid search (BM25 + embeddings + graph traversal)
+3. **Reason:** Evaluate retrieved context for relevance and sufficiency
+4. **Critique:** Self-assess if answer is grounded or needs more retrieval
+5. **Refine:** Loop until confidence threshold met (max N iterations)
+
+**LazyGraphRAG (Microsoft):** Achieves indexing at 0.1% the cost of full GraphRAG with comparable quality for global queries.
+
+### Multi-Agent Research Orchestration
+
+| Agent Pattern | Description | When to Use |
+|---------------|-------------|-------------|
+| ReAct | Reason + Act in loop | Tasks with tools (search, edit) |
+| Tree of Thought | Explore multiple reasoning paths | Problems with multiple valid solutions |
+| Graph of Thought | Reasoning as graph, merge/refine | Complex synthesis from multiple sources |
+| Reflection | Agent evaluates own output | Quality assurance, self-correction |
+
+---
+
 ## Quick Commands
 
 **Research & Analysis:**

package/.codex/agents/architect.md

@@ -253,6 +253,11 @@ dependencies:
     # Execution Engine (Epic 4)
     - plan-create-implementation.md
     - plan-create-context.md
+    # Infrastructure & Observability (Infra Research 2026-04)
+    - infrastructure-assessment.md
+    - observability-blueprint.md
+  knowledge_bases:
+    - infrastructure-decision-framework.md
   scripts:
     # Memory Layer (Epic 7)
     - codebase-mapper.js
@@ -388,6 +393,79 @@ autoClaude:
 
 ---
 
+## Research-Backed Frameworks
+
+### Cloud Provider Decision Matrix
+
+| Criterion | AWS | Azure | GCP | Cloudflare |
+|-----------|-----|-------|-----|------------|
+| Breadth of services | Largest (200+) | Large | Medium | Focused (edge) |
+| AI/ML | Bedrock + SageMaker | OpenAI + Copilot | Vertex AI + TPUs | Workers AI |
+| Enterprise integration | Strong | Strongest | Medium | Weak |
+| Data warehouse | Redshift | Synapse | BigQuery (best) | N/A |
+| Edge compute | Lambda@Edge | Front Door | Cloud Run | Workers (leader) |
+| Brazilian region | sa-east-1 (SP, 3 AZs) | Brazil South (SP, 3 AZs) | southamerica-east1 (SP) | POPs in SP, RJ, Fortaleza |
+| Egress fees | High | High | High | Zero (R2) |
+
+**Default for SINAPSE projects:** Vercel (frontend) + Supabase (backend) + Cloudflare (CDN/edge). Escalate to hyperscalers only for specific workloads (GPU, compliance, enterprise integration).
+
+### Kubernetes Patterns (When Applicable)
+
+- **82% of container users run K8s in production** (CNCF 2025); it is the de facto "OS for AI"
+- **Managed K8s:** GKE (most mature, fastest version adoption) > EKS (largest ecosystem) > AKS (best for Microsoft shops)
+- **Anti-patterns to block:** Cluster-as-monolith, pods without resource limits, RBAC over-permissive, secrets in ConfigMaps, no PodDisruptionBudgets
+- **Service Mesh decision:** Linkerd (performance-first, small teams) > Istio (feature-rich, multi-cluster) > Cilium (eBPF, high-throughput fintech)
+
+### Infrastructure as Code (IaC) Decision
+
+| Criterion | OpenTofu | Pulumi | Crossplane |
+|-----------|----------|--------|------------|
+| License | MPL 2.0 (OSS) | Apache 2.0 | Apache 2.0 (CNCF Graduated) |
+| Language | HCL | Python, TS, Go, C#, Java | YAML (K8s CRDs) |
+| Best for | New OSS default (Terraform successor) | Dev teams wanting real language + unit tests | Platform teams, K8s-heavy orgs |
+| Learning curve | Medium | Low (if language known) | High (K8s + IaC) |
+
+**Recommendation:** OpenTofu as default IaC (50% of Spacelift deployments already). Pulumi for teams with strong TypeScript culture. Avoid Terraform BSL lock-in post-IBM acquisition.
+
+### Observability Stack
+
+**OpenTelemetry is the universal standard** (2nd most active CNCF project after K8s). 57% orgs use it for metrics, 50% for traces, 48% for logs (Grafana Survey 2025).
+
+| Signal | Tool | Purpose |
+|--------|------|---------|
+| Metrics | Prometheus + Grafana | Time-series, alerting, dashboards |
+| Traces | Tempo (Grafana) or Jaeger | Distributed request tracing |
+| Logs | Loki (Grafana) | Log aggregation and correlation |
+| Profiling | Pyroscope | Continuous CPU/memory profiling via eBPF |
+| Errors | Sentry | Exception tracking, replay on error |
+
+**Architecture pattern:** Instrument with OTel SDKs -> OTel Collector (process/export) -> Backend (Grafana stack or Datadog). This eliminates vendor lock-in at the instrumentation layer.
+
+### Platform Engineering (Backstage)
+
+Backstage (Spotify, CNCF) has 3,000+ adopters and 270+ orgs in production. Use as Internal Developer Portal when team exceeds 10 developers. Provides: service catalog, scaffolder templates, TechDocs, and plugin ecosystem.
+
+### SRE Error Budgets
+
+The most impactful SRE concept for architecture decisions:
+
+| SLO | Error Budget | Meaning |
+|-----|-------------|---------|
+| 99.9% | 0.1% (~43 min/month) | Budget full -> deploy freely. Empty -> freeze releases, fix stability |
+| 99.95% | 0.05% (~22 min/month) | Typical for internal tools |
+| 99.99% | 0.01% (~4.3 min/month) | Financial systems, auth services |
+
+**Formula:** `Error Budget = 1 - SLO`. When budget is consumed, product velocity pauses and engineering focuses on reliability. This programmatically aligns product (speed) and SRE (stability) incentives.
+
+### FinOps Quick Rules
+
+- 50% of orgs put "waste reduction" as priority #1 (FinOps Foundation 2025)
+- 63% now manage AI spend as a distinct cost category
+- H100 GPU prices dropped 64% in 2025 -- GPU compute is now a manageable cost, not a fixed tax
+- **Cloudflare R2 eliminates egress fees** -- consider for any S3-compatible storage workload
+
+---
+
 ## Quick Commands
 
 **Architecture Design:**