sinapse-ai 9.4.0 → 9.5.0

package/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/core/code-intel/registry-syncer.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const yaml = require('js-yaml');
 const { getClient, isCodeIntelAvailable } = require('../code-intel');
 const { RegistryLoader, DEFAULT_REGISTRY_PATH } = require('../ids/registry-loader');
@@ -112,16 +113,68 @@ class RegistrySyncer {
       }
     }
 
-    // Update metadata
+    // Update metadata (entityCount is structural; lastUpdated is deferred to after hash check)
     registry.metadata = registry.metadata || {};
-    registry.metadata.lastUpdated = new Date().toISOString();
     registry.metadata.entityCount = allEntities.length;
 
+    // Idempotency: compute content hash excluding metadata.lastUpdated.
+    // If the on-disk registry produces the same hash, skip the write entirely
+    // so timestamp-only reruns do not churn the working tree.
+    const newHash = this._computeContentHash(registry);
+    const oldHash = this._readDiskContentHash(this._registryPath);
+
+    if (oldHash !== null && oldHash === newHash) {
+      this._logger(`[registry-syncer] Sync complete: ${this._stats.processed} processed, ${this._stats.skipped} skipped, ${this._stats.errors} errors (no content change — write skipped)`);
+      return { ...this._stats, writeSkipped: true };
+    }
+
+    // Stamp fresh timestamp only when we know we are going to write.
+    registry.metadata.lastUpdated = new Date().toISOString();
+
     // Atomic write
     this._atomicWrite(this._registryPath, registry);
 
     this._logger(`[registry-syncer] Sync complete: ${this._stats.processed} processed, ${this._stats.skipped} skipped, ${this._stats.errors} errors`);
-    return { ...this._stats };
+    return { ...this._stats, writeSkipped: false };
+  }
+
+  /**
+   * Compute a stable content hash of the registry, deliberately excluding
+   * `metadata.lastUpdated` so that timestamp-only reruns produce the same hash.
+   * @param {Object} registry - Registry object
+   * @returns {string} SHA-256 hex digest
+   * @private
+   */
+  _computeContentHash(registry) {
+    // Shallow clone + strip lastUpdated from the metadata copy only.
+    const clone = {
+      ...registry,
+      metadata: { ...(registry.metadata || {}) },
+    };
+    delete clone.metadata.lastUpdated;
+    // yaml.dump with stable key ordering produces a deterministic serialization.
+    const serialized = yaml.dump(clone, { lineWidth: 120, noRefs: true, sortKeys: true });
+    return crypto.createHash('sha256').update(serialized).digest('hex');
+  }
+
+  /**
+   * Read the existing on-disk registry and compute its content hash
+   * (excluding metadata.lastUpdated). Returns null if the file does not
+   * exist or cannot be parsed — callers should treat null as "write needed".
+   * @param {string} registryPath - Path to on-disk registry
+   * @returns {string|null} SHA-256 hex digest or null
+   * @private
+   */
+  _readDiskContentHash(registryPath) {
+    try {
+      if (!fs.existsSync(registryPath)) return null;
+      const raw = fs.readFileSync(registryPath, 'utf8');
+      const parsed = yaml.load(raw);
+      if (!parsed || typeof parsed !== 'object') return null;
+      return this._computeContentHash(parsed);
+    } catch (_error) {
+      return null;
+    }
   }
 
   /**

package/.sinapse-ai/core/doctor/checks/agent-memory.js

@@ -60,5 +60,9 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run, EXPECTED_AGENTS };
+// Story A.3: agent memory directories may not exist yet on a fresh install.
+// Treat runtime exceptions as WARN so fresh installs exit cleanly.
+const onError = 'warn';
+
+module.exports = { name, run, EXPECTED_AGENTS, onError };
 

package/.sinapse-ai/core/doctor/checks/claude-md.js

@@ -53,5 +53,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: CLAUDE.md ships with the framework; exceptions indicate corruption.
+const onError = 'fail';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/code-intel.js

@@ -128,5 +128,9 @@ async function run(context) {
   }
 }
 
-module.exports = { name, run };
+// Story A.3: code-intel is optional infrastructure; runtime exceptions are not
+// blocking and the check itself already handles missing providers gracefully.
+const onError = 'warn';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/commands-count.js

@@ -78,5 +78,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: commands dir ships with the framework.
+const onError = 'fail';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/constitution-consistency.js

@@ -115,4 +115,7 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: deep check; exceptions are real and should FAIL.
+const onError = 'fail';
+
+module.exports = { name, run, onError };

package/.sinapse-ai/core/doctor/checks/core-config.js

@@ -50,5 +50,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: core-config.yaml is a hard requirement for framework operation.
+const onError = 'fail';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/entity-registry.js

@@ -50,5 +50,10 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: entity-registry may be absent or unreadable on a fresh install
+// (before `sinapse install` populates it). Treat runtime exceptions as WARN
+// so that fresh installs do not produce false FAILs.
+const onError = 'warn';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/git-hooks.js

@@ -47,5 +47,9 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: git hooks rely on a git repo + husky install. Neither is
+// guaranteed on a fresh global install, so exceptions are treated as WARN.
+const onError = 'warn';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/graph-dashboard.js

@@ -45,5 +45,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: graph-dashboard ships with the framework.
+const onError = 'fail';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/hooks-claude-count.js

@@ -115,5 +115,9 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: Claude Code hooks live in .claude/, which may not be fully
+// populated on a fresh install. Degrade to WARN rather than FAIL.
+const onError = 'warn';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/ide-sync.js

@@ -82,5 +82,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: IDE sync mirrors agents; exceptions indicate broken install state.
+const onError = 'fail';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/node-version.js

@@ -30,5 +30,8 @@ async function run() {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: Node.js version is a hard prerequisite. Exceptions are FAIL.
+const onError = 'fail';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/npm-packages.js

@@ -75,5 +75,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: missing npm packages are always blocking. Exceptions are FAIL.
+const onError = 'fail';
+
+module.exports = { name, run, onError };