sinapse-ai 9.3.0 → 9.5.0

package/.sinapse-ai/development/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/.sinapse-ai/development/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/.sinapse-ai/development/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/.sinapse-ai/development/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:**

package/.sinapse-ai/development/agents/devops.md

@@ -278,6 +278,10 @@ dependencies:
     - remove-worktree.md
     - cleanup-worktrees.md
     - merge-worktree.md
+    # Environment & Deployment (Infra Research 2026-04)
+    - environment-promotion-pipeline.md
+  knowledge_bases:
+    - environment-deployment-patterns.md
   workflows:
     - auto-worktree.yaml
   templates:
@@ -450,6 +454,123 @@ autoClaude:
 
 ---
 
+## Research-Backed Frameworks
+
+### Modified GitHub Flow for AI Teams
+
+GitHub Flow is the correct base strategy for SINAPSE. Do NOT use GitFlow (too complex for 2 humans), trunk-based (too risky without comprehensive test suite), or release branches (single npm package does not need them).
+
+```
+main (protected, always deployable)
+  |
+  +-- caio/feat/{description}        Human: Caio
+  +-- soier/feat/{description}       Human: Matheus
+  +-- agent/{squad}/{agent-id}/{desc}  AI agent (traceability)
+  +-- release/v{X.Y.Z}              Release candidate (major versions only)
+```
+
+**AI agent branch rules:**
+1. Always include agent ID in branch name (avoid agent-to-agent collision)
+2. Never reuse branch names
+3. Always branch from latest main (fetch + pull before branching)
+4. One concern per branch (never mix features)
+5. Short-lived: merge or close within 24 hours
+
+### OIDC Trusted Publishing for NPM
+
+Eliminate long-lived NPM tokens by using GitHub as identity provider:
+
+```yaml
+# In release workflow
+permissions:
+  contents: write
+  id-token: write  # OIDC for NPM trusted publishing
+
+steps:
+  - run: npm publish --provenance
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+| Security Practice | Description |
+|------------------|-------------|
+| OIDC Trusted Publishing | No long-lived tokens; GitHub is identity provider for NPM |
+| Provenance | `npm publish --provenance` signs package with Sigstore |
+| 2FA | FIDO-based 2FA mandatory (TOTP deprecated by NPM) |
+| Granular Tokens | NPM Granular Access Tokens (legacy tokens sunset 2025) |
+| npm ci | Strict lockfile, fails on inconsistency |
+
+### DORA Metrics (2025 Benchmarks)
+
+Track these four metrics to measure engineering performance:
+
+| Metric | Top 15% (Elite) | Median | Bottom 15% |
+|--------|-----------------|--------|------------|
+| Deployment Frequency | Multiple/day | Weekly-Monthly | < Monthly |
+| Change Lead Time | < 1 day | 1-7 days | > 1 month |
+| Change Failure Rate | < 4% | 10-15% | > 30% |
+| Failed Deploy Recovery | < 1 hour | 1-7 days | > 1 month |
+
+**Key finding:** Only 16.2% of orgs deploy on-demand (multiple/day). PR Size is the single most significant driver of velocity -- smaller PRs = faster cycles.
+
+### PR-Level Metrics (LinearB 2025, 6.1M+ PRs)
+
+| Metric | Elite | Average | Poor |
+|--------|-------|---------|------|
+| PR Cycle Time | < 1 day | 7 days | > 14 days |
+| Pickup Time | < 2 hours | 4 days | > 7 days |
+| Review Time | < 4 hours | 4 days | > 7 days |
+| PR Size (lines) | < 100 | 200-400 | > 1,000 |
+
+### Graphite Stacked PRs
+
+For large features, decompose into a stack of small dependent PRs:
+
+```bash
+gt branch create feat-auth-types
+gt commit create -m "feat: add auth type definitions"
+gt branch create feat-auth-logic
+gt commit create -m "feat: implement auth logic"
+gt stack submit  # Creates chained PRs
+gt stack sync    # Keeps stack synced with main
+```
+
+**Impact:** Shopify saw 33% more PRs merged/dev. Asana engineers saved 7 hours/week and shipped 21% more code.
+
+### Semantic Release vs Changesets
+
+| Tool | Best For | Automation Level |
+|------|----------|-----------------|
+| semantic-release | Single package, full automation | Fully automatic from commit messages |
+| Changesets | Monorepo with multiple packages | Semi-automatic, explicit version intent |
+
+**SINAPSE recommendation:** Changesets for monorepo packages, semantic-release for single-package projects.
+
+### Git Safety Nets for Autonomous Agents
+
+| Safety Net | Implementation |
+|-----------|---------------|
+| Branch protection on main | GitHub branch rules (no direct push) |
+| Required CI checks | All tests must pass before merge |
+| Secret scanning | Pre-commit hook + GitHub secret scanning |
+| File path validation | Hook rejects writes to protected paths |
+| Commit message validation | commitlint + conventional commits |
+| Max PR size | Bot warns if PR > 400 lines |
+| Required human approval | At least 1 human must approve every PR |
+| Audit trail | Co-Authored-By on every AI commit |
+
+### GitHub Actions Best Practices (2025)
+
+1. **Fail fast:** Lint and test first before expensive build steps
+2. **Use `npm ci`:** Respects lockfile exactly (reproducibility)
+3. **Aggressive caching:** `actions/setup-node` with `cache: 'npm'`
+4. **Protected environments:** Production requires manual approval
+5. **Pin actions by SHA:** Prevent supply chain attacks (tj-actions incident 2025)
+6. **OIDC federation:** Eliminate static cloud provider secrets
+7. **Reusable workflows:** DRY pattern for shared CI/CD logic
+
+---
+
 ## Quick Commands
 
 **Repository Management:**

package/.sinapse-ai/development/agents/product-lead.md

@@ -227,6 +227,33 @@ autoClaude:
 
 ---
 
+## Anti-Hallucination Protocol
+
+Hallucination is mathematically inevitable in LLMs (arXiv:2401.11817). Apply these defenses when validating stories:
+
+**1. Chain-of-Verification (CoVe) — 50-70% hallucination reduction:**
+1. Draft your validation assessment
+2. List verification questions: Does each AC match PRD? Are scope items traceable? Are estimates grounded?
+3. Answer each verification question INDEPENDENTLY by re-reading source documents
+4. Produce final validation with only verified claims
+
+**2. Phantom Package Prevention (Slopsquatting):**
+- During story validation, flag any referenced library/package that hasn't been verified
+- If a story lists a dependency, confirm it exists: `npm view {package}`
+- 19.7% of packages recommended by LLMs are fabricated — catch them at validation gate
+
+**3. Fact Grounding — Cite What You See:**
+- When validating, cite specific PRD sections and line numbers supporting each AC
+- Use Read tool to verify source document content — never rely on memory alone
+- Cross-check story dependencies against existing stories and architecture docs
+
+**4. Confidence Signaling:**
+- Mark uncertain validation items with [NEEDS VERIFICATION]
+- When unsure about business value claims or technical feasibility, request evidence
+- NO-GO stories that contain unverifiable claims until evidence is provided
+
+---
+
 ## Quick Commands
 
 **Backlog Management:**

package/.sinapse-ai/development/agents/project-lead.md

@@ -274,6 +274,34 @@ autoClaude:
 
 ---
 
+## Anti-Hallucination Protocol
+
+Hallucination is mathematically inevitable in LLMs (arXiv:2401.11817). Apply these defenses when creating PRDs and epics:
+
+**1. Chain-of-Verification (CoVe) — 50-70% hallucination reduction:**
+1. Draft requirements or epic structure from stakeholder input and research
+2. List verification questions: Are market claims sourced? Are technical assumptions validated?
+3. Answer each verification question INDEPENDENTLY — consult research docs, not your draft
+4. Produce final document with only verified, traceable requirements
+
+**2. Phantom Package Prevention (Slopsquatting):**
+- When PRDs specify technology choices, verify each package exists: `npm view {package}`
+- 19.7% of packages recommended by LLMs are fabricated
+- Mark unverified technology references with [NEEDS VERIFICATION] in PRD
+
+**3. Fact Grounding — Cite What You See:**
+- Every requirement in PRD must trace to stakeholder input, research finding, or business goal
+- Cite source documents, meeting notes, or research paths for each major requirement
+- NEVER invent market data, user statistics, or competitive analysis without sources
+- Use Read tool to verify existing architecture docs before referencing them
+
+**4. Confidence Signaling:**
+- Mark uncertain requirements with [NEEDS VERIFICATION]
+- When market data or competitive claims lack sources, flag them explicitly
+- Prefer "requires research validation" over fabricating supporting evidence
+
+---
+
 ## Quick Commands
 
 **Document Creation:**

package/.sinapse-ai/development/agents/quality-gate.md

@@ -226,6 +226,10 @@ dependencies:
     - qa-evidence-requirements.md
     - qa-false-positive-detection.md
     - qa-browser-console-check.md
+    # Load Testing & Security (Infra Research 2026-04)
+    - load-testing-setup.md
+  knowledge_bases:
+    - security-pre-deploy-checklist.md
   templates:
     - qa-gate-tmpl.yaml
     - story-tmpl.yaml
@@ -360,6 +364,91 @@ autoClaude:
 
 ---
 
+## Research-Backed Frameworks
+
+### Verification-First Architecture (7-Layer Defense)
+
+Hallucination is a mathematically inevitable property of LLMs (arXiv:2401.11817). No single technique eliminates it. Apply defense in depth:
+
+```
+Layer 1: Prompt Engineering     — Allow "I don't know", citation anchoring, CoVe (50-70% reduction)
+Layer 2: Tool Grounding         — Read/Grep BEFORE generating (Read-before-Edit pattern)
+Layer 3: Type Checking          — TypeScript strict mode catches phantom APIs
+Layer 4: Linting                — ESLint catches incorrect patterns
+Layer 5: Test Execution         — Vitest/Playwright catches logic errors
+Layer 6: Code Review            — CodeRabbit + human review catches architectural issues
+Layer 7: Quality Gates          — Automated gates before merge (this agent's domain)
+```
+
+**Key insight (Simon Willison):** Code hallucinations are the LEAST dangerous type because execution reveals them immediately. The real danger is **logic errors that compile and run but produce incorrect results**. Focus QA effort on logic verification, not just syntax.
+
+### Hallucination Detection Patterns for Code
+
+| Type | Detection Method | Tool |
+|------|-----------------|------|
+| Phantom APIs | Type checking | `tsc --strict` |
+| Ghost packages | Dependency audit | `npm audit`, verify against registry |
+| Version confusion | Lock file validation | `npm ci` (strict lockfile) |
+| File path hallucination | Glob verification | Read tool before Edit |
+| Config hallucination | Schema validation | Zod schemas for config |
+| Logic errors | Test execution + review | Vitest + manual review of edge cases |
+
+**Slopsquatting risk:** 19.7% of packages recommended by LLMs are fabricated. 58% are repeated across runs (deterministic hallucination). Always verify packages exist in registry before installation.
+
+### AI Code Quality Metrics (2025 Benchmarks)
+
+| Metric | AI-Generated Code | Implication |
+|--------|-------------------|-------------|
+| Security vulnerabilities | 29-45% contain vulns | Security review is mandatory |
+| Package hallucination | 19.7% recommend fake packages | Dependency audit is mandatory |
+| Major issues (CodeRabbit, 470 PRs) | 1.7x more than human code | Automated review catches most |
+| Misconfigurations | 75% more than human code | Config validation gates needed |
+| SWE-bench accuracy (best model) | 80.9% | 1 in 5 tasks needs human intervention |
+
+### Testing Pyramid with Concrete Tools
+
+| Layer | Tools | What to Test | Coverage Target |
+|-------|-------|-------------|----------------|
+| Unit (70%) | Vitest | Domain logic, validators, transforms, pure functions | > 80% line coverage |
+| Integration (20%) | Vitest + MSW + Testing Library | Component interactions, API contracts, DB queries | Critical paths |
+| E2E (10%) | Playwright | Login, checkout, core user journeys | Happy path + main error paths |
+
+**Adjustments by context:** Prototypes: reduce E2E, focus unit. Fintech: increase integration + E2E. Safety-critical: test everything extensively.
+
+### Code Churn as Quality Signal
+
+**Code churn** = percentage of recently changed code changed again within 2-3 weeks.
+
+| Churn Level | Interpretation | Action |
+|-------------|---------------|--------|
+| < 15% | Healthy | Normal review |
+| 15-25% | Moderate | Watch for unclear requirements |
+| > 25% | Red flag | Investigate: unclear specs, poor implementation, scope creep |
+
+### Self-Healing Loop Pattern (TDAD)
+
+Test-Driven AI Development reduces regressions by 70% (6.08% to 1.82%):
+
+```
+1. Tests define "correct" (human writes or validates test specs)
+2. AI implements code to pass tests
+3. Tests auto-execute after each change
+4. Failures feed back to agent for correction
+5. Max N iterations, then escalate
+6. Trust scoring with fallback reduces failure rates by 50%
+```
+
+### Chain-of-Verification (CoVe) for QA Reviews
+
+When reviewing AI-generated deliverables, apply CoVe to reduce factual hallucinations by 50-70%:
+
+1. **Draft:** Read the code/document
+2. **Plan:** Formulate verification questions (Does this API exist? Is this pattern correct for this framework version?)
+3. **Execute:** Answer each question INDEPENDENTLY (without bias from the draft)
+4. **Revise:** Final assessment based on verified facts
+
+---
+
 ## Quick Commands
 
 **Code Review & Analysis:**

package/.sinapse-ai/development/agents/sprint-lead/MEMORY.md

@@ -21,6 +21,14 @@
 - Story naming: `story-{PREFIX}-{N}-{slug}.md`
 - Epic INDEX.md tracks all stories with status
 - Stories flow: Draft → Ready → InProgress → InReview → Done
+- Epic 10 stories use frontmatter YAML header + numbered flat filename (e.g., `10.17-slug.story.md`)
+- 10.15 = InReview, 10.16 = Done (as of 2026-04-11); next available = 10.17
+
+### Authorial Hygiene Rules
+- ZERO external framework references in committed files — the exact forbidden-terms regex lives in `scripts/validate-no-external-refs.js` (case-insensitive `\b` word-boundary match)
+- Allow-list of files that may legitimately contain such terms: `LICENSE` (legal MIT attribution) and `docs/research-synthesis-for-upgrade.md` (historical process document) — hardcoded in the same validator
+- Story 10.17 created the CI guard (`external-refs-validation` job) that enforces this permanently on every PR
+- Drafting rule for @sprint-lead: when writing story notes about this policy, NEVER repeat the forbidden terms as literal text — reference `scripts/validate-no-external-refs.js` instead
 
 ## Promotion Candidates
 <!-- Patterns seen across 3+ agents — candidates for CLAUDE.md or .claude/rules/ -->