sinapse-ai 9.4.0 → 9.5.0

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

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

@@ -532,6 +532,34 @@ When starting a new project or module, select architecture by context:
 
 **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

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:

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

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/ -->

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

@@ -187,6 +187,34 @@ autoClaude:
 
 ---
 
+## Anti-Hallucination Protocol
+
+Hallucination is mathematically inevitable in LLMs (arXiv:2401.11817). Apply these defenses when creating stories:
+
+**1. Chain-of-Verification (CoVe) — 50-70% hallucination reduction:**
+1. Draft the story content from PRD/epic sources
+2. List verification questions: Does each AC trace to a PRD requirement? Are dependencies real?
+3. Answer each verification question INDEPENDENTLY against source documents
+4. Produce final story with only verified, traceable content
+
+**2. Phantom Package Prevention (Slopsquatting):**
+- When stories reference specific libraries or packages, verify they exist via `npm view {package}`
+- 19.7% of packages recommended by LLMs are fabricated
+- Flag any unverified dependency in story notes as [NEEDS VERIFICATION]
+
+**3. Fact Grounding — Cite What You See:**
+- When referencing architecture decisions, cite the source document path and section
+- Use Read tool to verify PRD content before including in stories
+- NEVER invent acceptance criteria not traceable to requirements
+- Cross-reference existing stories to avoid duplicate scope
+
+**4. Confidence Signaling:**
+- Mark uncertain scope items with [NEEDS VERIFICATION]
+- When unsure about technical feasibility or dependency availability, flag it
+- Prefer explicit "requires architect input" over fabricating technical details
+
+---
+
 ## Quick Commands
 
 **Story Management:**

package/.sinapse-ai/development/agents/squad-creator.md

@@ -209,6 +209,64 @@ autoClaude:
 
 ---
 
+## Enhanced Squad Creation Protocol
+
+### 1. 4-Layer Persona Model (Mandatory for All New Agents)
+
+Every agent created by `*create-squad` or `*extend-squad` MUST define all 4 layers:
+
+| Layer | Contents | Required Fields |
+|-------|----------|-----------------|
+| **L1: Identity** | Role, archetype, voice, icon | `name`, `role`, `archetype`, `tone`, `icon` |
+| **L2: Expertise** | Domain knowledge, frameworks, tools | `focus`, `core_principles[]`, `tools[]` |
+| **L3: Behavior** | Decision style, collaboration patterns, quality bar | `style`, `customization`, `coderabbit_integration` |
+| **L4: Boundaries** | Can do, cannot do, escalation paths | `commands[]`, `security_notes[]`, Agent Collaboration section |
+
+Validation: `*validate-squad` checks all agents for 4-layer completeness. Missing layers produce a FAIL verdict.
+
+### 2. Auto-KB Generation
+
+When creating a new squad, automatically generate knowledge base scaffolding:
+
+**Step 1 — Research Discovery:**
+- Check `squads/*/knowledge-base/` for existing patterns in similar domains
+- Check `.sinapse-ai/development/knowledge-base/` for cross-cutting references
+- If `caioimori-pesquisas` research exists for the domain, extract key patterns
+
+**Step 2 — KB Skeleton Generation:**
+Generate at minimum 3 knowledge-base files per squad:
+
+```
+squads/{squad-name}/knowledge-base/
+  {domain}-fundamentals.md        # Core concepts and terminology
+  {domain}-patterns.md            # Proven patterns and anti-patterns
+  {domain}-tool-reference.md      # Tools, frameworks, and integrations
+```
+
+**Step 3 — Cross-Squad Integration:**
+- Add routing catalog entry in squad's `squad.yaml` under `routing`
+- Define cross-squad patterns (which squads this one collaborates with)
+- Update `.claude/rules/squad-awareness.md` delegation map
+
+### 3. Quality Checklist (Every New Squad Must Pass)
+
+Before a squad is considered complete, ALL items must be checked:
+
+- [ ] All agents have 4-layer personas (L1-L4 complete)
+- [ ] Knowledge base has at least 3 reference files
+- [ ] All tasks have pre-conditions and post-conditions defined
+- [ ] Workflows connect all agents (no orphan agents)
+- [ ] Anti-hallucination protocol present on all agents that generate domain output
+- [ ] `squad.yaml` manifest passes JSON Schema validation
+- [ ] README.md exists with activation instructions
+- [ ] At least one workflow defined in `workflows/`
+- [ ] Cross-squad routing documented if applicable
+- [ ] Agent collaboration section defines handoff patterns
+
+Run `*validate-squad {name}` to execute this checklist automatically.
+
+---
+
 ## Quick Commands
 
 **Squad Design & Creation:**

package/.sinapse-ai/development/agents/ux-design-expert.md

@@ -418,6 +418,34 @@ autoClaude:
 
 ---
 
+## Anti-Hallucination Protocol
+
+Hallucination is mathematically inevitable in LLMs (arXiv:2401.11817). Apply these defenses on every design task:
+
+**1. Chain-of-Verification (CoVe) — 50-70% hallucination reduction:**
+1. Draft your design recommendation, audit finding, or component specification
+2. List verification questions: Do referenced components exist? Are metric claims sourced? Are accessibility standards correct?
+3. Answer each verification question INDEPENDENTLY — check actual codebase, WCAG docs, or design tokens
+4. Produce final deliverable with only verified claims and references
+
+**2. Phantom Package Prevention (Slopsquatting):**
+- When recommending UI libraries or design tools, verify packages exist: `npm view {package}`
+- 19.7% of packages recommended by LLMs are fabricated
+- Verify Tailwind plugins, Radix components, and icon libraries exist before specifying them
+
+**3. Fact Grounding — Cite What You See:**
+- When auditing patterns, cite specific file paths and line numbers for each finding
+- Use Grep/Glob to verify component counts — never estimate without scanning
+- NEVER claim a design token exists without checking `tokens.yaml` or equivalent
+- Cross-reference WCAG criteria by standard number (e.g., WCAG 2.1 SC 1.4.3)
+
+**4. Confidence Signaling:**
+- Mark uncertain ROI calculations or pattern counts with [NEEDS VERIFICATION]
+- When unsure about browser support or CSS feature availability, say so
+- Prefer "let me scan the codebase" over fabricating audit metrics
+
+---
+
 ## Quick Commands
 
 **UX Research:**

package/.sinapse-ai/development/knowledge-base/agent-communication-protocol.md

@@ -0,0 +1,127 @@
+# Agent Communication Protocol — Scratchpad & Messaging
+
+> Version 1.1 | Enforcement layer for agent-handoff.md Scratchpad Protocol
+
+## Purpose
+
+Enable persistent inter-agent knowledge sharing within a story context using the stigmergy pattern (indirect communication through environment modification, inspired by swarm intelligence). Agents leave traces in a shared scratchpad that subsequent agents read, avoiding redundant discovery and preserving institutional knowledge across handoffs.
+
+## Scratchpad Structure
+
+```
+.sinapse/scratchpad/{story-id}/
+  {agent-id}.md          # Per-agent discovery file (max 2KB)
+  _summary.md            # Auto-generated cross-agent summary (optional)
+```
+
+Example:
+```
+.sinapse/scratchpad/6.1.4/
+  developer.md           # Pixel's discoveries during implementation
+  quality-gate.md        # Litmus's findings during QA
+  architect.md           # Stratum's design decisions
+  _summary.md            # Merged summary for quick onboarding
+```
+
+## What to Write
+
+Each agent's scratchpad file MUST contain ONLY actionable information:
+
+```markdown
+# {Agent Name} — Story {story-id} Scratchpad
+
+## Key Discoveries
+- {Finding that would save the next agent time}
+- {Unexpected behavior or edge case found}
+
+## Decisions Made
+- {Decision}: {Rationale} (alternatives considered: {list})
+
+## Files Modified
+- `path/to/file.ext` — {what changed and why}
+
+## Blockers Found
+- {Blocker description} — Status: {resolved|active|escalated}
+
+## Warnings for Next Agent
+- {Gotcha or trap that the next agent should know about}
+```
+
+## When to Write
+
+| Event | Action | Required? |
+|-------|--------|-----------|
+| Before agent handoff (`@agent` switch) | Write scratchpad file | YES |
+| After resolving a non-obvious blocker | Append to scratchpad | SHOULD |
+| After making an architectural decision | Append to scratchpad | SHOULD |
+| After discovering unexpected behavior | Append to scratchpad | SHOULD |
+
+## When to Read
+
+| Event | Action | Required? |
+|-------|--------|-----------|
+| Agent activation (incoming) | Read ALL files in story scratchpad | YES |
+| Before making a decision that might conflict | Check scratchpad for prior decisions | SHOULD |
+| Before investigating a bug | Check if already documented | SHOULD |
+
+## File Size Limits
+
+| Constraint | Limit |
+|------------|-------|
+| Per-agent file | 2KB max |
+| Total scratchpad per story | 10KB max |
+| Max agent files per story | 6 |
+
+If a file approaches 2KB, prioritize: Warnings > Blockers > Decisions > Discoveries > Files Modified.
+
+## Cleanup Protocol
+
+| Event | Action |
+|-------|--------|
+| Story status changes to `Done` | Archive scratchpad to `.sinapse/scratchpad/archive/{story-id}/` |
+| Story status changes to `Done` + 7 days | Delete archived scratchpad (optional) |
+| Manual cleanup | `rm -rf .sinapse/scratchpad/{story-id}/` |
+
+Archive preserves knowledge for future reference (similar bugs, patterns) while keeping the active scratchpad directory clean.
+
+## Cross-Agent Messaging via Terminal Bus
+
+For **real-time** communication between agents running in separate terminals, use the Terminal Bus (`.claude/rules/terminal-bus.md`):
+
+| Need | Mechanism |
+|------|-----------|
+| Persistent knowledge sharing | Scratchpad (this protocol) |
+| Real-time notifications | Terminal Bus (`mcp__terminal-bus__send_message`) |
+| Status broadcasts | Terminal Bus (`mcp__terminal-bus__broadcast`) |
+| Context sharing | Terminal Bus (`mcp__terminal-bus__share_context`) |
+
+### Integration Pattern
+
+When an agent writes a critical blocker to the scratchpad AND another agent is known to be active in a different terminal:
+
+1. Write to scratchpad (persistent record)
+2. Send Terminal Bus message (real-time alert):
+   ```
+   "BLOCKER found in story {id}: {brief description}. See scratchpad for details."
+   ```
+
+## Stigmergy Pattern Reference
+
+This protocol implements **stigmergy** from swarm intelligence research:
+- Agents modify the environment (scratchpad files) rather than communicating directly
+- Subsequent agents observe environmental changes and adapt behavior
+- No central coordinator needed for knowledge transfer
+- Knowledge persists beyond individual agent sessions
+- Scales naturally as more agents participate in a story
+
+## Anti-Patterns
+
+- Writing raw logs or verbose output to scratchpad (use summaries)
+- Writing scratchpad entries for trivial findings (must save next agent real time)
+- Reading scratchpad but ignoring its contents (rediscovering known issues)
+- Deleting another agent's scratchpad file (append-only within a story lifecycle)
+- Using scratchpad for inter-story communication (scope is per-story)
+
+## .gitignore
+
+The `.sinapse/` directory (including `scratchpad/`) is gitignored by default. Scratchpad data is ephemeral runtime state, not version-controlled artifacts.