sinapse-ai 9.3.0 → 9.5.0

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/checklists/agent-quality-gate.md

@@ -519,6 +519,33 @@ For Copy/Legal/Storytelling/Data:
 
 ---
 
+## Level 7: Security & Resilience (Research-Enriched)
+
+```yaml
+security_checks:
+  - id: no-hardcoded-secrets
+    check: "Agent file contains no API keys, tokens, or credentials"
+    type: blocking
+    validation: "grep for patterns: sk_, pk_, token=, password=, secret="
+
+  - id: error-handling-documented
+    check: "Agent has error recovery patterns defined"
+    type: recommended
+    validation: "objection_algorithms covers failure scenarios"
+
+  - id: input-validation
+    check: "Commands validate inputs before execution"
+    type: recommended
+    validation: "task files include input validation step"
+
+  - id: graceful-degradation
+    check: "Agent defines fallback behavior when dependencies unavailable"
+    type: recommended
+    validation: "completion_criteria includes degradation scenarios"
+```
+
+---
+
 ## Scoring
 
 | Score | Result | Action |

package/.sinapse-ai/development/checklists/brownfield-compatibility-checklist.md

@@ -73,6 +73,26 @@
 | `.github/workflows/*` | Inventory only | User decides integration |
 | `package.json` scripts | Preserve all | None |
 
+### 11. Security Posture Assessment
+- [ ] Existing RLS policies inventoried (if Supabase/Postgres)
+- [ ] Secret scanning ran on codebase (`gitleaks` or `truffleHog`)
+- [ ] `.env` files verified not committed to git history
+- [ ] API keys checked for exposure in client-side code
+- [ ] CORS configuration reviewed for overly permissive origins
+
+### 12. Architecture Alignment
+- [ ] Architecture pattern identified (monolith, modular monolith, microservices)
+- [ ] SOLID principle violations flagged in initial assessment
+- [ ] Dependency injection patterns documented
+- [ ] Import structure analyzed (absolute vs relative)
+- [ ] Test coverage baseline measured
+
+### 13. CI/CD Pipeline Assessment
+- [ ] Existing CI/CD workflows documented
+- [ ] DORA metrics baseline captured (deploy frequency, lead time, MTTR, CFR)
+- [ ] Branch protection rules reviewed
+- [ ] Automated testing pipeline identified
+
 ## Rollback Procedure
 
 If migration fails or is unwanted:

package/.sinapse-ai/development/checklists/code-review-checklist.md

@@ -0,0 +1,106 @@
+# Checklist: Code Review
+
+> Purpose: Systematic review of code changes for quality, security, and architecture
+> Used by: @quality-gate (Litmus), @developer (Pixel, self-review)
+> When: During PR review or pre-commit QA gate
+
+---
+
+## Design & Architecture
+
+- [ ] Change is well-designed and belongs in this codebase
+- [ ] Follows project architecture pattern (Clean Architecture / Modular Monolith)
+- [ ] Dependency direction correct (outer depends on inner, never reverse)
+- [ ] No circular dependencies introduced
+- [ ] Absolute imports used (no relative `../..` paths)
+- [ ] REUSE > ADAPT > CREATE principle followed (IDS check)
+- [ ] New abstractions are justified and documented
+
+## SOLID Principles
+
+- [ ] Single Responsibility: each class/function does one thing
+- [ ] Open/Closed: extended via composition, not modification of existing code
+- [ ] Liskov Substitution: subtypes are substitutable for base types
+- [ ] Interface Segregation: no fat interfaces forcing unused implementations
+- [ ] Dependency Inversion: high-level modules depend on abstractions
+
+## Functionality & Correctness
+
+- [ ] Code does what the author intended (matches story AC)
+- [ ] Edge cases handled (empty inputs, max values, null/undefined)
+- [ ] Error handling follows project pattern (try/catch with logger)
+- [ ] No race conditions in async code
+- [ ] State management is consistent (no stale state bugs)
+
+## Security (OWASP Top 10)
+
+- [ ] No hardcoded secrets, API keys, or credentials
+- [ ] User input validated and sanitized (Zod schema preferred)
+- [ ] No SQL injection vectors (parameterized queries only)
+- [ ] No XSS vulnerabilities (outputs properly escaped, CSP headers)
+- [ ] No path traversal (validate file paths)
+- [ ] RLS policies reviewed if database changes included
+- [ ] CORS restricted to known origins (no wildcard `*` in production)
+- [ ] Rate limiting on new public endpoints
+- [ ] Sensitive data not logged or exposed in error messages
+
+## Test Coverage
+
+- [ ] Unit tests added for new functions/methods
+- [ ] Edge cases have corresponding test cases
+- [ ] Error scenarios tested (failure paths, not just happy path)
+- [ ] Tests are deterministic (no flaky tests)
+- [ ] Integration tests added for cross-module interactions
+- [ ] Test coverage not decreased by this change
+- [ ] Mocks are appropriate (integration tests use real DB when needed)
+
+## Performance
+
+- [ ] No N+1 query patterns introduced
+- [ ] Database queries use indexes on filtered columns
+- [ ] Large lists are paginated
+- [ ] No unnecessary re-renders in React components (memo/useMemo)
+- [ ] Bundle size impact considered (no large new dependencies)
+- [ ] Animations use GPU-accelerated properties (transform, opacity)
+- [ ] Heavy operations are async/non-blocking
+
+## Accessibility
+
+- [ ] Semantic HTML used (proper heading hierarchy, landmarks)
+- [ ] Interactive elements have keyboard support
+- [ ] ARIA labels on non-text interactive elements
+- [ ] Color contrast meets WCAG AA (4.5:1 for text)
+- [ ] Focus management correct for dynamic content
+
+## Code Quality
+
+- [ ] Names are clear, descriptive, and follow conventions
+- [ ] No `any` types in TypeScript (use `unknown` + type guards)
+- [ ] Comments explain WHY, not WHAT
+- [ ] No commented-out code or dead code
+- [ ] No console.log or debugger statements
+- [ ] No magic numbers (use named constants)
+- [ ] Imports follow project order (React > external > internal > styles)
+
+## AI-Specific (for AI-generated code)
+
+- [ ] Logic is correct (AI may hallucinate edge cases)
+- [ ] Approach aligns with architecture decisions (not just "works")
+- [ ] No phantom packages imported (verify all imports exist)
+- [ ] Business logic matches story acceptance criteria
+- [ ] Co-Authored-By trailer present in commits
+
+## Review Comment Protocol
+
+| Prefix | Meaning | Blocking? |
+|--------|---------|-----------|
+| `nit:` | Style preference | No |
+| `suggestion:` | Alternative approach | No |
+| `question:` | Needs clarification | No |
+| `issue:` | Must fix before merge | Yes |
+| `blocker:` | Critical problem | Yes |
+| `praise:` | Excellent work | No |
+
+---
+
+*Code Review Checklist v1.0 — Sources: Google eng-practices, OWASP Top 10, SOLID, WCAG*

package/.sinapse-ai/development/checklists/issue-triage-checklist.md

@@ -25,6 +25,15 @@ For each issue being triaged, verify:
 - [ ] Related issues cross-referenced if applicable
 - [ ] No sensitive information in issue (API keys, credentials)
 
+### Security Assessment
+- [ ] Checked if issue involves security vulnerability (if yes, mark `security`)
+- [ ] Security issues assigned P1 by default unless triaged otherwise
+- [ ] Verified no PII or credentials included in issue body or screenshots
+
+### Sizing & Estimation
+- [ ] Estimated PR size (< 400 lines preferred, flag if likely > 600)
+- [ ] Identified if issue requires story (feature/enhancement) or fast-track (bug fix)
+
 ## Session Checklist
 
 After completing a triage session:

package/.sinapse-ai/development/checklists/memory-audit-checklist.md

@@ -52,3 +52,19 @@ Common patterns that typically appear in multiple agents:
 | Conventional commits format | dev, qa, devops, analyst, sm, data-engineer, ux | Already in CLAUDE.md |
 | kebab-case for files | dev, analyst, sm, data-engineer, ux | Already in CLAUDE.md |
 
+---
+
+## Step 7: Memory Health Checks (Research-Enriched)
+
+- [ ] Verify no MEMORY.md exceeds 200 lines / 25KB (size limit)
+- [ ] Check for contradictions between MEMORY.md files across agents
+- [ ] Validate entries marked as "hints" not treated as ground truth
+- [ ] Ensure stale patterns (> 90 days without validation) are flagged
+- [ ] Confirm promotion candidates have been reviewed within 7 days of flagging
+
+## Step 8: Memory-as-Hints Verification
+
+- [ ] Each MEMORY.md has disclaimer: entries are hints, verify against codebase
+- [ ] No memory entries reference deleted files or deprecated APIs
+- [ ] Active patterns align with current codebase architecture decisions
+

package/.sinapse-ai/development/checklists/pr-quality-checklist.md

@@ -0,0 +1,72 @@
+# Checklist: PR Quality Gate
+
+> Purpose: Validate pull requests meet size, convention, and review standards
+> Used by: @devops (Pipeline), @quality-gate (Litmus)
+> When: Before merging any PR to main
+
+---
+
+## PR Size & Structure
+
+- [ ] PR is under 400 lines changed (optimal: 50-200 lines)
+- [ ] If > 400 lines, justified in PR description (or split into stacked PRs)
+- [ ] PR addresses a single logical change (not multiple unrelated changes)
+- [ ] PR title follows format: `type(scope): description` (< 70 chars)
+- [ ] PR description includes Summary, Story Reference, and Test Plan
+
+## Commit Conventions
+
+- [ ] All commits follow Conventional Commits (`feat:`, `fix:`, `docs:`, etc.)
+- [ ] Commit messages have imperative mood description (< 72 chars)
+- [ ] No WIP or fixup commits in final PR (squash before merge)
+- [ ] Breaking changes use `!` suffix or `BREAKING CHANGE:` footer
+- [ ] Story ID referenced in commit or PR body
+
+## DORA Metrics Alignment
+
+- [ ] PR open-to-merge time target: < 24 hours
+- [ ] Time to first review target: < 4 hours
+- [ ] Review cycles: <= 2 rounds before approval
+- [ ] No PR blocked for > 48 hours without escalation
+
+## Code Review
+
+- [ ] At least 1 human reviewer approved
+- [ ] CODEOWNERS review satisfied (if configured)
+- [ ] Review comments use standard prefixes (`nit:`, `issue:`, `blocker:`)
+- [ ] All `blocker:` and `issue:` comments resolved before merge
+- [ ] Self-review completed by author before requesting review
+
+## CI/CD Checks
+
+- [ ] All required status checks pass (lint, typecheck, test, build)
+- [ ] No new lint warnings introduced
+- [ ] Test coverage not decreased
+- [ ] No `npm audit` critical/high vulnerabilities introduced
+- [ ] Branch is up-to-date with main (no stale merges)
+
+## AI-Specific Checks
+
+- [ ] AI-generated commits include `Co-Authored-By:` trailer
+- [ ] Agent identity clear in PR (which agent created the changes)
+- [ ] AI-generated code reviewed for hallucinated imports or APIs
+- [ ] No placeholder or template text left in generated code
+
+## Merge Strategy
+
+- [ ] Squash-and-merge used as default (clean history)
+- [ ] Merge commit used only for major features (preserves branch history)
+- [ ] Feature branch deleted after merge
+
+## Verdict
+
+| All sections pass | Decision |
+|-------------------|----------|
+| Yes | MERGE |
+| CI fails | BLOCKED — fix CI first |
+| Review pending | BLOCKED — wait for approval |
+| Size > 600 lines | BLOCKED — split PR |
+
+---
+
+*PR Quality Checklist v1.0 — Sources: Google eng-practices, DORA 2024, Graphite research*

package/.sinapse-ai/development/checklists/security-deployment-checklist.md

@@ -0,0 +1,54 @@
+# Checklist: Security Deployment Gate
+
+> Purpose: Block production deployments that violate security requirements
+> Used by: @devops (Pipeline), @quality-gate (Litmus)
+> When: Before every production deployment or `npm publish`
+
+---
+
+## Tier 1: Absolute Blockers (deploy = impossible)
+
+- [ ] RLS enabled on ALL tables with user data (`SELECT tablename FROM pg_tables WHERE NOT rowsecurity`)
+- [ ] No API keys hardcoded in source code (secret scanning hook passes)
+- [ ] `service_role` key NOT present in frontend code (`src/`, `app/`, `pages/`)
+- [ ] MFA enabled on all admin/cloud/production accounts
+- [ ] All public APIs require authentication middleware
+- [ ] No SQL string concatenation (parameterized queries only)
+- [ ] Zero critical/high vulnerabilities in dependencies (`npm audit --audit-level=high`)
+- [ ] No secrets detected in codebase (`gitleaks detect` or equivalent)
+- [ ] No default credentials in production (no admin/admin, test/test)
+- [ ] TLS/HTTPS enforced for all data in transit
+
+## Tier 2: Compliance Blockers (deploy = illegal in Brazil)
+
+- [ ] DPO/Encarregado designated (LGPD Art. 41)
+- [ ] Breach notification capability within 3 days (LGPD Resolucao 15)
+- [ ] Consent collection mechanism implemented (LGPD Art. 7-8)
+- [ ] Data subject rights portal exists (access, correct, delete) (LGPD Art. 18)
+- [ ] International data transfer with SCCs if applicable (LGPD Art. 33)
+- [ ] Children's data requires parental consent if applicable (LGPD Art. 14)
+- [ ] Privacy policy published and accessible (LGPD Art. 9)
+
+## Tier 3: Operational Blockers (deploy = irresponsible)
+
+- [ ] Asset inventory documented (CIS C1-2)
+- [ ] Centralized logging configured (CIS C8)
+- [ ] Incident response plan exists (CIS C17)
+- [ ] Backup verification within last 90 days (CIS C11)
+- [ ] Vulnerability scanning process in place (CIS C7)
+- [ ] Network segmentation applied (Zero Trust)
+- [ ] Vendor security assessment completed (CIS C15)
+- [ ] SSL enforcement on database connections
+
+## Verdict
+
+| Tier 1 | Tier 2 | Tier 3 | Decision |
+|--------|--------|--------|----------|
+| All pass | All pass | All pass | DEPLOY |
+| All pass | All pass | Gaps | DEPLOY with documented risk |
+| All pass | Gaps | Any | BLOCKED (compliance) |
+| Gaps | Any | Any | BLOCKED (absolute) |
+
+---
+
+*Security Deployment Checklist v1.0 — Sources: OWASP Top 10, NIST CSF 2.0, CIS Controls v8, LGPD/ANPD*

package/.sinapse-ai/development/checklists/self-critique-checklist.md

@@ -97,10 +97,20 @@ Be honest. Finding bugs NOW saves debugging time LATER.]]
 ### 5.5.4 Security Review
 
 - [ ] No hardcoded secrets, API keys, or credentials
-- [ ] User input is validated and sanitized
+- [ ] User input is validated and sanitized (Zod/schema preferred)
 - [ ] No SQL injection or XSS vulnerabilities introduced
 - [ ] Sensitive data is not logged or exposed in errors
 - [ ] Authentication/authorization checks are in place where needed
+- [ ] RLS policies reviewed if database tables affected
+- [ ] CORS not set to wildcard `*` in production code
+- [ ] Rate limiting considered for public-facing endpoints
+
+### 5.5.5 Architecture Review
+
+- [ ] Code follows SOLID principles (no god classes, proper abstractions)
+- [ ] Dependency direction correct (inner layers do not import outer)
+- [ ] No circular dependencies introduced
+- [ ] New abstractions justified (REUSE > ADAPT > CREATE)
 
 ---
 
@@ -172,6 +182,14 @@ DOCUMENTATION:
 - [ ] No debugging artifacts (debugger statements, test data)
 - [ ] No unused imports or variables
 
+### 6.5.6 Performance Review
+
+- [ ] No N+1 query patterns introduced
+- [ ] Database queries use appropriate indexes
+- [ ] No synchronous blocking operations on main thread
+- [ ] Bundle size impact considered for frontend changes
+- [ ] Animations use GPU-accelerated properties (transform, opacity)
+
 ---
 
 ## Verdict Determination

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.