sinapse-ai 9.3.0 → 9.4.0

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/skills/debug.md

@@ -0,0 +1,57 @@
+---
+name: debug
+description: Structured debugging assistance when agent is stuck
+trigger: On repeated failure or explicit invocation
+agents: [developer, quality-gate]
+---
+
+# Debug Skill
+
+## Usage
+
+Invoke with `*debug` or `/debug` when stuck on an error after 2+ failed attempts.
+
+## Protocol
+
+### 1. Capture Context
+- Current error message (full stack trace)
+- What was attempted (last 2-3 actions)
+- Expected vs actual behavior
+- Relevant file paths and line numbers
+
+### 2. Classify Error
+| Category | Examples | First Action |
+|----------|----------|-------------|
+| Syntax | SyntaxError, unexpected token | Check recent edits for typos |
+| Type | TypeError, undefined is not | Trace variable origin, check types |
+| Runtime | ENOENT, ECONNREFUSED | Verify paths, ports, services |
+| Logic | Wrong output, infinite loop | Add logging, isolate with minimal repro |
+| Config | Module not found, env missing | Check package.json, .env, tsconfig |
+| Test | Assertion failed, timeout | Compare expected vs actual values |
+
+### 3. Investigate (max 5 minutes)
+1. Read the error source file at the failing line
+2. Check recent git diff for unintended changes
+3. Search codebase for similar patterns that work
+4. Check if dependency versions match (package.json vs lock)
+5. Verify environment (Node version, env vars)
+
+### 4. Fix or Escalate
+- If root cause found — apply fix, verify, continue
+- If unclear after 5 min — document findings, escalate to user
+- Never loop on the same approach more than twice
+
+## Anti-Patterns
+- Guessing without reading the actual error
+- Changing multiple things at once (isolate changes)
+- Ignoring stack traces (read bottom-up for root cause)
+- Retrying the exact same command expecting different results
+
+## Output
+```
+## Debug Report
+- Error: {error_type}: {message}
+- Root Cause: {explanation}
+- Fix Applied: {description of change}
+- Verified: {how it was confirmed working}
+```

package/.sinapse-ai/development/skills/fast-review.md

@@ -0,0 +1,69 @@
+---
+name: fast-review
+description: Quick code review focused on common issues
+trigger: Before commit or on demand
+agents: [developer, quality-gate]
+---
+
+# Fast Review Skill
+
+## Usage
+
+Invoke with `*fast-review` or `/fast-review` before committing changes.
+
+## What It Checks
+
+### 1. Code Quality (auto)
+- Unused imports or variables
+- Console.log / debugger statements left in code
+- TODO/FIXME/HACK comments without ticket reference
+- Functions exceeding 50 lines
+- Files exceeding 300 lines
+
+### 2. TypeScript (auto)
+```bash
+npx tsc --noEmit 2>&1 | head -20
+```
+
+### 3. Lint (auto)
+```bash
+npx eslint --quiet {changed_files} 2>&1 | head -30
+```
+
+### 4. Pattern Checks (read-only)
+- Relative imports (should be absolute per Constitution Art. VI)
+- `any` type usage (should use proper types)
+- Missing error handling in async functions
+- API calls without try/catch
+
+### 5. Test Coverage (if tests exist)
+- New functions should have corresponding tests
+- Modified functions — existing tests still pass
+
+## Execution
+
+1. Get changed files: `git diff --name-only --cached` (staged) or `git diff --name-only` (unstaged)
+2. Run checks 1-4 on changed files only
+3. Summarize findings
+
+## Output Format
+
+```
+## Fast Review — {n} files checked
+
+| Category | Issues | Severity |
+|----------|--------|----------|
+| Quality | 2 console.logs | LOW |
+| TypeScript | 0 errors | - |
+| Lint | 1 warning | LOW |
+| Patterns | 1 relative import | MEDIUM |
+
+Verdict: CLEAN | MINOR_ISSUES | NEEDS_FIX
+```
+
+## Rules
+- CLEAN = no issues found, safe to commit
+- MINOR_ISSUES = proceed but consider fixing (LOW severity only)
+- NEEDS_FIX = MEDIUM+ issues must be resolved before commit
+- This is lighter than full CodeRabbit — use for quick iterations
+- For PR-level review, use CodeRabbit instead

package/.sinapse-ai/development/skills/research-synthesis.md

@@ -0,0 +1,77 @@
+---
+name: research-synthesis
+description: Synthesize findings from multiple sources into actionable summary
+trigger: After research phase or on demand
+agents: [analyst, architect, project-lead]
+---
+
+# Research Synthesis Skill
+
+## Usage
+
+Invoke with `*research-synthesis` or `/research-synthesis` after gathering research data.
+
+## Input
+
+Accepts any combination of:
+- Web search results (from EXA or manual search)
+- Documentation excerpts
+- Code analysis findings
+- Competitor analysis data
+- File paths containing raw research
+
+## Protocol
+
+### 1. Collect
+- Gather all source materials (files, search results, notes)
+- Tag each source with origin and confidence level
+
+### 2. Deduplicate
+- Remove redundant findings across sources
+- Keep the most authoritative version of each fact
+
+### 3. Categorize
+| Category | Description |
+|----------|-------------|
+| Facts | Verified, multiple sources agree |
+| Insights | Patterns or conclusions derived from facts |
+| Risks | Potential problems or concerns identified |
+| Opportunities | Actionable improvements or options |
+| Unknowns | Questions that remain unanswered |
+
+### 4. Synthesize
+- Cross-reference findings for consistency
+- Identify contradictions between sources
+- Rank by relevance to the current objective
+
+### 5. Output
+
+```
+## Research Synthesis — {topic}
+
+### Key Findings
+1. {finding with source reference}
+2. {finding with source reference}
+
+### Recommendations
+- {actionable recommendation}
+
+### Risks
+- {risk with mitigation suggestion}
+
+### Open Questions
+- {question needing further investigation}
+
+### Sources
+| # | Source | Confidence |
+|---|--------|------------|
+| 1 | {url or file} | HIGH |
+| 2 | {url or file} | MEDIUM |
+```
+
+## Rules
+- Every finding must reference its source
+- Confidence levels: HIGH (multiple sources), MEDIUM (single reliable), LOW (unverified)
+- Contradictions must be explicitly called out, not silently resolved
+- Keep synthesis under 500 words — link to raw data for details
+- Save output to `docs/research/` if part of a formal research task

package/.sinapse-ai/development/skills/security-scan.md

@@ -0,0 +1,73 @@
+---
+name: security-scan
+description: Run security checks from the 25 deployment blockers
+trigger: Before deploy, on demand, or during QA gate
+agents: [developer, quality-gate, devops]
+---
+
+# Security Scan Skill
+
+## Usage
+
+Invoke with `*security-scan` or `/security-scan` before any deployment.
+
+## Automated Checks (Tier 1 — Absolute Blockers)
+
+Run these checks in order. Any failure = BLOCKED.
+
+### 1. Secrets in Code
+```bash
+# Check for hardcoded keys, tokens, passwords
+grep -rn "sk-\|sk_live\|password\s*=\s*['\"]" src/ app/ pages/ --include="*.ts" --include="*.js" --include="*.tsx"
+# Check for service_role in frontend
+grep -rn "service_role" src/ app/ pages/ --include="*.ts" --include="*.js"
+```
+
+### 2. Dependencies
+```bash
+npm audit --audit-level=high
+```
+
+### 3. Environment Files
+```bash
+# Verify .env is gitignored
+git check-ignore .env
+# Verify .env.example exists (if .env exists)
+test -f .env.example
+```
+
+### 4. SQL Safety
+- Scan for string concatenation in SQL queries
+- Verify parameterized queries or ORM usage
+
+### 5. RLS Check (if Supabase project)
+- Verify all user-data tables have RLS enabled
+- Check for policies on each RLS-enabled table
+
+## Quick Scan vs Full Scan
+
+| Mode | Checks | When |
+|------|--------|------|
+| Quick (`*security-scan quick`) | 1-3 only | Before every commit |
+| Full (`*security-scan full`) | All 1-5 + CORS + headers | Before deploy |
+
+## Output Format
+
+```
+## Security Scan — {timestamp}
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Secrets | PASS | No hardcoded secrets found |
+| Deps | WARN | 2 moderate vulnerabilities |
+| Env | PASS | .env gitignored, .env.example present |
+| SQL | PASS | All queries parameterized |
+| RLS | N/A | No Supabase detected |
+
+Verdict: PASS | WARN | BLOCKED
+```
+
+## Rules
+- BLOCKED verdict prevents deploy — no override without user confirmation
+- WARN allows deploy but must be documented as tech debt
+- Reference: Constitution Article X, `.claude/rules/security-data-protection.md`

package/.sinapse-ai/development/skills/verify.md

@@ -0,0 +1,53 @@
+---
+name: verify
+description: Verify implementation matches story acceptance criteria
+trigger: After implementation, before QA gate
+agents: [developer, quality-gate]
+---
+
+# Verify Skill
+
+## Usage
+
+Invoke with `*verify` or `/verify` after completing implementation.
+
+## Steps
+
+1. Read the active story file
+2. Extract all acceptance criteria (Given/When/Then)
+3. For each criterion:
+   - Check if implementation exists (grep for relevant code)
+   - Run relevant test if available (`npm test -- --grep "AC description"`)
+   - Mark as PASS / FAIL / PARTIAL
+4. Generate verification report
+5. If all PASS — recommend proceeding to QA gate
+6. If any FAIL — list specific gaps with file paths and line numbers
+
+## Output Format
+
+```
+## Verification Report — Story {story_id}
+
+| AC   | Status  | Evidence                              |
+|------|---------|---------------------------------------|
+| AC-1 | PASS    | test-auth.test.js line 42             |
+| AC-2 | FAIL    | No implementation found for edge case |
+| AC-3 | PARTIAL | Logic exists but no test coverage     |
+
+### Summary
+- Total: {n} | Pass: {p} | Fail: {f} | Partial: {pt}
+- Recommendation: {PROCEED_TO_QA | FIX_REQUIRED}
+```
+
+## Rules
+
+- Never mark PASS without evidence (test result or code reference)
+- PARTIAL means logic exists but lacks test or handles only happy path
+- If no story is active, prompt user for story path
+- Do not modify any code — this skill is read-only verification
+
+## Integration
+
+- Called automatically at end of `dev-develop-story` task
+- Can be called standalone by any agent for spot-checks
+- Output can feed into QA gate as pre-verification artifact

package/.sinapse-ai/development/templates/squad/agent-template.md

@@ -21,10 +21,23 @@ agent:
   whenToUse: "Use this agent when {{USECASE}}"
 
 persona:
-  role: "Describe the agent's primary role and responsibilities"
-  style: "Communication style (e.g., systematic, empathetic, analytical)"
-  identity: "What makes this agent unique"
-  focus: "Primary focus areas"
+  # 4-Layer Persona Design (research-backed)
+  layer_1_identity:
+    role: "Primary role and responsibilities"
+    archetype: "Domain archetype (e.g., The Strategist, The Builder)"
+    voice: "Tone and communication style"
+  layer_2_expertise:
+    domain: "Core domain expertise"
+    frameworks: "Key frameworks this agent uses"
+    tools: "Preferred tools and methods"
+  layer_3_behavior:
+    decision_style: "How this agent makes decisions"
+    collaboration: "How it works with other agents"
+    quality_bar: "What quality standard it enforces"
+  layer_4_boundaries:
+    can_do: "Operations this agent CAN perform"
+    cannot_do: "Operations delegated to other agents"
+    escalation: "When and to whom to escalate"
 
 core_principles:
   - "Principle 1: Define the first guiding principle"

package/.sinapse-ai/development/templates/squad/checklist-template.md

@@ -57,13 +57,21 @@ After completion, verify:
 
 ---
 
+## Scoring (research-backed)
+
+| Metric | Value |
+|--------|-------|
+| Total items | {{TOTAL}} |
+| Passed | {{PASSED}} |
+| Score | {{PASSED}}/{{TOTAL}} ({{PERCENTAGE}}%) |
+| Gate | PASS (>=80%) / CONCERNS (60-79%) / FAIL (<60%) |
+
 ## Sign-off
 
-| Role | Name | Date | Signature |
-|------|------|------|-----------|
-| Creator | | | |
-| Reviewer | | | |
-| Approver | | | |
+| Role | Name | Date | Verdict |
+|------|------|------|---------|
+| Executor | | | |
+| Reviewer | | | PASS / CONCERNS / FAIL |
 
 ---
 

package/.sinapse-ai/development/templates/squad/task-template.md

@@ -22,6 +22,13 @@ Checklist:
   - "[ ] Step 1: Describe first step"
   - "[ ] Step 2: Describe second step"
   - "[ ] Step 3: Describe third step"
+
+# Execution mode (research-backed, gap 4.1)
+# fast-track: trivial fixes < 50 lines, auto-validated story
+# standard: normal features, full SDC workflow
+# heavy: complex initiatives, spec pipeline first
+execution_mode: standard
+complexity_estimate: S|M|L|XL
 ---
 
 # {{COMPONENTNAME}}

package/.sinapse-ai/development/templates/squad/workflow-template.yaml

@@ -114,6 +114,12 @@ workflow:
       notify: true
       rollback: true
 
+  # Complexity-adaptive execution (research gap 4.1)
+  complexity:
+    class: STANDARD  # SIMPLE (3 phases) | STANDARD (all) | COMPLEX (+ revision)
+    estimated_tokens: null  # Filled at runtime
+    fast_track_eligible: false  # true for trivial fixes
+
   validation:
     pre_run:
       - "Check all required inputs are provided"
@@ -121,4 +127,5 @@ workflow:
     post_run:
       - "Verify output is valid"
       - "Log completion metrics"
+      - "Report DORA metrics (lead time, failure rate)"