sinapse-ai 9.4.0 → 9.5.0

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/.claude/rules/token-economy.md

@@ -0,0 +1,148 @@
+# Token Economy & Response Format — NON-NEGOTIABLE
+
+> Consolidado: economia de contexto + formato de resposta em uma única regra.
+> Princípio: desperdício de contexto degrada qualidade E custa caro. Mesmo inimigo.
+> Detalhes: `.sinapse-ai/development/knowledge-base/token-economy-guide.md`.
+
+---
+
+## 1. Compactação
+
+| Trigger | Threshold |
+|---|---|
+| Auto-compact | **60%** do contexto (não 83%) |
+| Manual `/compact` | Troca de agente; pós-leitura de arquivo grande |
+| Pre-agent-switch | Handoff artifact (~379 tok) via `agent-handoff.md` |
+
+60%: acima disso perde coerência sobre instruções iniciais ("context amnesia").
+
+---
+
+## 2. Model Routing (MUST)
+
+**Regra zero:** Execute direto sempre que der. Sub-agente custa ~20K mínimo.
+
+**Opus 4.7:** Effort default `xhigh`. `thinking_budget` fixo NÃO suportado — adaptive.
+
+| Task | Modelo | Effort |
+|---|---|---|
+| Arquitetura cross-system, debug complexo, refactor multi-file | **opus** | `xhigh` |
+| Spec Pipeline COMPLEX (score >= 16) | **opus** | `max` |
+| Feature do spec, code review, bug fix, testes, stories | **sonnet** | `high` |
+| Análise single-file, pergunta factual | **sonnet** | `medium` |
+| Lint, rename, YAML, lookup, bulk | **haiku** | `low` |
+
+- Em dúvida: menor tier. Escala se falhar.
+- Nunca opus pra task que haiku resolve. Nunca `max` fora de COMPLEX.
+- Sub-agente anuncia modelo ao spawnar.
+
+---
+
+## 3. Subagent Threshold (Opus 4.7)
+
+Spawn APENAS se: `>= 8 tool calls` previstos OU fan-out paralelo real. Abaixo → inline.
+
+---
+
+## 4. Anti-Patterns (FORBIDDEN)
+
+| Anti-Pattern | Fix |
+|---|---|
+| Ler mesmo arquivo 2x | Uma vez, guarda line numbers |
+| Re-ler após Edit/Write | Edit confirma sucesso, não releia |
+| Persona completo em agent switch | Handoff protocol |
+| Grep/Glob sem `head_limit` | Sempre setar |
+| Sub-agente pra task <8 tool calls | Inline |
+| Sequential reads independentes | Paralelo (uma mensagem, N calls) |
+| Cole payload bruto no raciocínio | Extrai só relevante |
+| `thinking_budget` fixo em 4.7 | Adaptive — não suportado |
+| Preamble ("Claro!", "Vou te ajudar...") | Ação direta |
+| Trailing summary ("Em resumo...") | Só próximo passo, 1 linha |
+| Narração de plano | Executa em paralelo |
+| Restating da pergunta | Responde direto |
+
+---
+
+## 5. Hierarquia de Tool (MANDATORY)
+
+```
+Caminho conhecido → Read   (não Bash cat)
+Padrão conhecido  → Grep   (não Bash grep)
+Lista de arquivos → Glob   (não Bash find)
+Edição pontual    → Edit   (não Write)
+```
+
+Bash só pra operações que nenhuma tool dedicada cobre. Leitura cirúrgica: `offset`+`limit`.
+
+---
+
+## 6. Response Format
+
+### Comprimento por complexidade
+
+| Task | Máximo |
+|---|---|
+| Confirmação / Yes-No | 1 linha |
+| Pergunta factual | 1-3 linhas |
+| Task simples concluída | 5-10 linhas |
+| Multi-step | Só o que mudou |
+| Análise profunda | Estruturado, sem padding |
+
+### Padrão requerido
+
+```
+[ação ou resposta direta]
+[detalhe crítico se não-óbvio]
+[próximo passo se aplicável, 1 linha]
+```
+
+### Formato por situação
+
+| Situação | Use |
+|---|---|
+| Comparação, métrica | Tabela |
+| Sequência de passos | Lista numerada |
+| Itens sem ordem | Bullets |
+| Código | Code block |
+| Narrativa | Parágrafo curto (máx 3 frases) |
+
+Default: tabela ou bullet.
+
+---
+
+## 7. Linguagem
+
+- **Português** pra Caio e Matheus
+- Sem jargão ("salvei" não "commitei no HEAD")
+- Sem nomes de agentes em conversa (usuário vê "implementei", não "@developer")
+- Sem comandos pro usuário rodar — agentes fazem tudo (Safe Collaboration)
+
+**Exceção:** usuário pede explicitamente ("explica em detalhes", "modo educativo"). Mesmo assim, sem preamble nem trailing summary.
+
+---
+
+## 8. Budget de Contexto (200K)
+
+| Alocação | Target | % |
+|---|---:|---:|
+| System + CLAUDE.md + Rules | ~10K | 5% |
+| Agente + tools | ~5K | 3% |
+| Working memory | **≤80K** | 40% |
+| Histórico | ~58K | 29% |
+| Safety buffer (compacta 60%) | ~40K | 20% |
+
+Working memory >80K = sinal pra compactar.
+
+---
+
+## 9. Memory Anti-Patterns
+
+- Não salvar estado efêmero (PR atual, task de hoje)
+- Não salvar o que já tá em código/git
+- Memory = fatos que surpreenderiam uma sessão futura
+
+---
+
+## Enforcement
+
+NON-NEGOTIABLE. Violação = falha de qualidade (Constitution Art. V).

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:**

package/.codex/agents/data-engineer.md

@@ -193,6 +193,9 @@ dependencies:
     # Utilities
     - execute-checklist.md
     - create-deep-research-prompt.md
+  knowledge_bases:
+    # Database Scaling (Infra Research 2026-04)
+    - database-scaling-patterns.md
 
   # Deprecated tasks (Story 6.1.2.3 - backward compatibility v2.0→v3.0, 6 months):
   #   - db-rls-audit.md → security-audit.md {scope=rls}
@@ -406,6 +409,41 @@ autoClaude:
 
 ---
 
+## Anti-Hallucination Protocol
+
+Hallucination is mathematically inevitable in LLMs (arXiv:2401.11817). Apply these defenses on every database task:
+
+**0. Schema-First Rule (MANDATORY before ANY SQL output):**
+- ALWAYS introspect the current schema before writing queries — never assume table or column names
+- NEVER generate migration SQL without reading the current schema state first (via `\dt`, `\d table`, migration files, or `information_schema`)
+- Verify PostgreSQL extensions exist before using them: `SELECT * FROM pg_available_extensions WHERE name = '{ext}'`
+- Verify RLS policies exist before claiming they do: `SELECT * FROM pg_policies WHERE tablename = '{table}'`
+- If introspection is impossible (no DB access), mark ALL schema references with [NEEDS VERIFICATION]
+
+**1. Chain-of-Verification (CoVe) — 50-70% hallucination reduction:**
+1. Draft your schema design, migration, or query optimization plan
+2. List verification questions: Do referenced tables exist? Are column types correct? Do functions exist?
+3. Answer each verification question INDEPENDENTLY by querying the actual database or reading migration files
+4. Produce final SQL/schema with only verified references
+
+**2. Phantom Package Prevention (Slopsquatting):**
+- When recommending PostgreSQL extensions, verify they exist: check `pg_available_extensions`
+- When suggesting npm packages for database tooling, run `npm view {package}` first
+- 19.7% of packages recommended by LLMs are fabricated
+
+**3. Fact Grounding — Cite What You See:**
+- When referencing existing tables/columns, verify via schema introspection or migration files
+- Cite specific migration file paths and line numbers when discussing schema state
+- NEVER assume a table, column, or index exists — verify with Read or SQL query
+- Cross-reference RLS policies against actual table structure before creating new ones
+
+**4. Confidence Signaling:**
+- Mark uncertain schema assumptions with [NEEDS VERIFICATION]
+- When unsure about PostgreSQL version-specific features, say so explicitly
+- Prefer "let me verify the current schema" over assuming structure from memory
+
+---
+
 ## Quick Commands
 
 **Architecture & Design:**

package/.codex/agents/developer.md

@@ -465,6 +465,103 @@ autoClaude:
 
 ---
 
+## Research-Backed Frameworks
+
+### Architecture Decision Tree
+
+When starting a new project or module, select architecture by context:
+
+| Project Type | Architecture | When |
+|-------------|-------------|------|
+| Landing Page | JAMstack (SSG + Edge) | Static content, SEO-critical |
+| SaaS B2B | Modular Monolith + Clean Architecture | 3-15 devs, medium complexity |
+| E-commerce | Modular Monolith + CQRS | Read-heavy, catalog browsing |
+| Fintech | Modular Monolith + DDD + Event Sourcing | Audit trail, complex domain |
+| Real-time App | Event-Driven + WebSockets + Edge | Chat, collab, notifications |
+| MVP/Prototype | Monolith (well-structured) | <= 5 devs, speed priority |
+
+**Default:** Start with Modular Monolith. Extract microservices ONLY when independent scaling is proven necessary.
+
+### SOLID in TypeScript (Quick Reference)
+
+| Principle | Pattern | Anti-Pattern |
+|-----------|---------|-------------|
+| **S**ingle Responsibility | One class = one reason to change. Domain events for side effects | God classes doing everything |
+| **O**pen/Closed | Strategy + Factory for extensibility without modification | if/else chains for each new variant |
+| **L**iskov Substitution | Composition over inheritance | Subtypes breaking parent contracts |
+| **I**nterface Segregation | Small focused interfaces (`Workable`, `Feedable`) | Fat interfaces with unused methods |
+| **D**ependency Inversion | Constructor injection, both levels depend on abstractions | `new PostgresDB()` in services |
+
+### TypeScript Quality Patterns
+
+- **Branded Types:** `type UserId = string & { __brand: 'UserId' }` -- prevents ID mixups at compile time
+- **Discriminated Unions:** `{ ok: true; value: T } | { ok: false; error: E }` for exhaustive handling
+- **Zod Schemas:** Single source of truth for runtime validation + `z.infer` for type inference
+- **Result Type (neverthrow):** Replace try/catch with `Result<T, E>` for explicit error paths
+- **Strict tsconfig:** `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `strict: true`
+
+### Testing Pyramid (Concrete Tools)
+
+| Layer | Tools | What to Test | Ratio |
+|-------|-------|-------------|-------|
+| Unit | Vitest | Pure functions, domain logic, validators | 70% |
+| Integration | Vitest + MSW + Testing Library | Component interactions, API | 20% |
+| E2E | Playwright | Login, checkout, critical paths only | 10% |
+
+**MSW (Mock Service Worker):** Intercepts network requests at service worker level for realistic API mocking.
+
+### State Management Stack (2025-2026)
+
+| State Type | Tool | Note |
+|-----------|------|------|
+| Server State | TanStack Query | 40-60% fewer requests vs Redux |
+| Client State | Zustand | Global UI without boilerplate |
+| URL State | nuqs | Filters, pagination, search params |
+| Form State | React Hook Form + Zod | Complex forms with validation |
+| Local State | useState/useReducer | Simple component-level state |
+
+### Animation Principles (Disney 12 for Web)
+
+| Principle | Web Implementation |
+|-----------|-------------------|
+| Squash & Stretch | `scale()` transforms on interaction |
+| Anticipation | Pre-movement before main action (hover before click) |
+| Follow Through | Elements overshoot then settle |
+| Ease In/Out | Always `cubic-bezier`, never linear for UI |
+| Secondary Action | Supporting animations complementing primary |
+
+**Targets:** LCP < 2.5s, INP < 200ms, CLS < 0.1. Always respect `prefers-reduced-motion`.
+
+### Anti-Hallucination Protocol
+
+Hallucination is mathematically inevitable in LLMs (arXiv:2401.11817). Apply these defenses on every task:
+
+**1. Chain-of-Verification (CoVe) — 50-70% hallucination reduction:**
+1. Draft your implementation plan or answer
+2. List verification questions to fact-check the draft
+3. Answer each verification question INDEPENDENTLY (no bias from draft)
+4. Produce final revised output incorporating verified facts
+
+**2. Phantom Package Prevention (Slopsquatting):**
+- ALWAYS run `npm view {package}` before adding ANY new dependency
+- 19.7% of packages recommended by LLMs are fabricated — 58% are persistent across runs
+- If `npm view` returns 404/error, the package does NOT exist — do not install it
+- Check package popularity, last publish date, and maintainer before adopting
+
+**3. Fact Grounding — Cite What You See:**
+- When making claims about code, cite the file path and line number
+- Use Read/Grep tools to verify before asserting file contents or structure
+- NEVER reference a file path without confirming it exists (use Glob)
+- NEVER suggest an import without verifying the module exports it
+
+**4. Confidence Signaling:**
+- Mark uncertain claims with [NEEDS VERIFICATION]
+- When unsure about API behavior, library compatibility, or version-specific features, say so
+- Prefer "I don't have enough information" over fabricating an answer
+- After generating code, self-review for phantom APIs and ghost imports
+
+---
+
 ## Quick Commands
 
 **Story Development:**