sinapse-ai 9.5.0 → 10.0.0-rc.10

package/.claude/CLAUDE.md

@@ -16,6 +16,7 @@ Full doc: `.sinapse-ai/constitution.md`. Gates auto-block violations.
 | VIII | Mandatory Delegation | NON-NEGOTIABLE |
 | IX | Safe Collaboration | NON-NEGOTIABLE |
 | X | Security & Data Protection | NON-NEGOTIABLE |
+| XI | Conservative Default | MUST |
 
 ## CLI First
 

package/.claude/hooks/enforce-nsn-guard.cjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Enforce NSN Mode (Never Say Never) Guard
+ *
+ * RULE (.claude/rules/nsn-mode.md): Agents must NOT tell the user to
+ * manually perform a step that the agent itself could automate via
+ * Chrome Brain, MCP, or a direct CLI call. Writing such instructions
+ * into docs, stories, or code comments propagates the anti-pattern.
+ *
+ * Scope: matches `Write` and `Edit` PreToolUse on `.md`, `.mdx`, `.txt`
+ * files. Scans the content being written for known NSN violation
+ * phrases. Emits a WARN on stderr (exit 0) so the agent can see the
+ * feedback but is not hard-blocked — false positives would be more
+ * damaging than the leak.
+ *
+ * Protocol (Claude Code PreToolUse):
+ *   exit 0            → allow (with optional stderr warning)
+ *   exit 2            → block (reserved for a future strict mode)
+ *
+ * Fail-open: any parsing error → exit 0 (allow). Reason: a broken
+ * guard should never block legitimate writes.
+ *
+ * @module enforce-nsn-guard
+ * @story 10.44 (Fix 3 from pre-GA blockers)
+ */
+
+const readStdin = () => new Promise((resolve) => {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (c) => { data += c; });
+  process.stdin.on('end', () => resolve(data));
+  // Fail-open on timeout — don't hang Claude Code
+  setTimeout(() => resolve(data), 4500);
+});
+
+const TARGET_TOOLS = new Set(['Write', 'Edit']);
+const TARGET_EXTENSIONS = ['.md', '.mdx', '.txt'];
+
+// NSN violation phrases — ordered from high-confidence to lower.
+// Written as regexes (case-insensitive) so common morphological
+// variants are caught without adding dozens of entries.
+const NSN_PATTERNS = [
+  {
+    id: 'open-dashboard-manually',
+    regex: /(abra|abre|you should open|please open)\s+(o\s+)?dashboard.*manual/i,
+    hint: 'Agents should offer Chrome Brain before telling users to open a dashboard by hand.',
+  },
+  {
+    id: 'follow-steps-manually',
+    regex: /(siga|follow)\s+esses\s+passos\s+manualmente/i,
+    hint: 'Replace manual step-lists with an automated Chrome Brain / MCP call.',
+  },
+  {
+    id: 'cannot-access-interface',
+    regex: /(infelizmente\s+)?n[ãa]o\s+consigo\s+acessar\s+a\s+interface/i,
+    hint: 'NSN Mode: try Chrome Brain, dev-browser, or claude-in-chrome before claiming you cannot access UI.',
+  },
+  {
+    id: 'you-need-to-click',
+    regex: /(voc[êe]\s+precisa\s+(abrir|clicar))|(you\s+need\s+to\s+click)/i,
+    hint: 'Agents should drive UI clicks via Chrome Brain, not instruct the user.',
+  },
+  {
+    id: 'i-cant-do-this',
+    regex: /\b(i\s+can'?t\s+do\s+this|n[ãa]o\s+consigo\s+fazer\s+isso)\b/i,
+    hint: 'NSN Mode forbids "I can\'t" without having tried 3+ alternatives first.',
+  },
+];
+
+async function main() {
+  try {
+    const raw = await readStdin();
+    if (!raw) { process.exit(0); }
+
+    let payload;
+    try { payload = JSON.parse(raw); } catch { process.exit(0); }
+
+    const toolName = payload.tool_name || payload.toolName;
+    if (!TARGET_TOOLS.has(toolName)) { process.exit(0); }
+
+    const input = payload.tool_input || payload.toolInput || {};
+    const filePath = input.file_path || input.filePath || '';
+    if (!filePath) { process.exit(0); }
+
+    const ext = filePath.slice(filePath.lastIndexOf('.')).toLowerCase();
+    if (!TARGET_EXTENSIONS.includes(ext)) { process.exit(0); }
+
+    // Extract the text about to land in the file
+    const content = input.content
+      || input.new_string
+      || input.newString
+      || '';
+    if (!content || typeof content !== 'string') { process.exit(0); }
+
+    const hits = [];
+    for (const pattern of NSN_PATTERNS) {
+      if (pattern.regex.test(content)) {
+        hits.push(pattern);
+      }
+    }
+
+    if (hits.length === 0) { process.exit(0); }
+
+    // WARN mode — print hints to stderr so the agent sees them, exit 0.
+    const lines = [
+      '',
+      '[NSN-Guard] Detected NSN Mode anti-patterns in content being written to',
+      `  ${filePath}`,
+      '',
+    ];
+    for (const h of hits) {
+      lines.push(`  - ${h.id}: ${h.hint}`);
+    }
+    lines.push('');
+    lines.push('Reference: .claude/rules/nsn-mode.md');
+    lines.push('');
+    process.stderr.write(lines.join('\n'));
+    process.exit(0);
+  } catch {
+    // Fail-open
+    process.exit(0);
+  }
+}
+
+main();

package/.claude/rules/hook-governance.md

@@ -24,6 +24,7 @@ paths:
 | `enforce-architecture-first.cjs` | Art. III — Docs before protected code | BLOCK (exit 2) |
 | `write-path-validation.cjs` | Convention — Warn wrong doc paths | WARN (exit 0) |
 | `enforce-story-gate.cjs` | Art. III — Story required for code | BLOCK (exit 2) |
+| `enforce-nsn-guard.cjs` | NSN Mode — Warn on "open dashboard / follow steps manually" anti-patterns in .md/.mdx/.txt | WARN (exit 0) |
 | `slug-validation.py` | Convention — Validate naming | WARN (exit 0) |
 | `mind-clone-governance.py` | Cloning — DNA required | BLOCK (exit 2) |
 | `enforce-delegation.cjs` | Art. VIII — Orchestrators can't execute | BLOCK (exit 2) |

package/.claude/rules/mcp-usage.md

@@ -24,15 +24,21 @@ Other agents (Dev, Architect, etc.) are MCP **consumers**, not administrators. I
 
 ## MCP Configuration Architecture
 
-SINAPSE uses Docker MCP Toolkit as the primary MCP infrastructure:
+SINAPSE supports two MCP deployment paths. The right choice depends on the user's environment; neither is required for the core framework to work.
+
+### Direct in Claude Code (local ~/.claude.json)
+
+The default path — MCPs run as local processes declared in `~/.claude.json`. Typical entries on a SINAPSE install:
 
-### Direct in Claude Code (global ~/.claude.json)
 | MCP | Purpose |
 |-----|---------|
-| **playwright** | Browser automation, screenshots, web testing |
-| **desktop-commander** | Docker container operations via docker-gateway |
+| **chrome-devtools** | Chrome CDP (installed by Chrome Brain, Phase 7 of `npx sinapse-ai install`) |
+| **dev-browser** | Playwright-backed browser (installed by Chrome Brain) |
+| **terminal-bus** | Cross-terminal messaging (user-installed, optional) |
+
+### Docker MCP Toolkit (optional acceleration layer, via docker-gateway)
 
-### Inside Docker Desktop (via docker-gateway)
+An opt-in deployment that runs EXA, Context7, and Apify inside Docker for isolation. Requires Docker Desktop + the MCP Toolkit extension. **Not installed by `npx sinapse-ai install` and not required** — use only if the acceleration layer is wanted.
 
 | MCP | Purpose |
 |-----|---------|

package/.claude/rules/nsn-mode.md

@@ -34,6 +34,28 @@ When ANY agent encounters a barrier (technical limitation, permission denied, to
 
 6. **Escalate** — After 5 cycles, report to user with detailed log of what was tried
 
+## Browser / UI Protocol (MANDATORY)
+
+Se a tarefa requer interação com browser ou UI (clicks, forms, dashboard config, navegação, screenshots, upload, download, preencher campos):
+
+1. **NUNCA** mande usuário fazer manualmente sem antes oferecer Chrome Brain
+2. **Formato obrigatório de oferta**:
+
+   > "Posso fazer isso via Chrome Brain (browser automation — automático) ou você prefere fazer manualmente?"
+
+3. **Default**: se usuário não responder explicitamente "manualmente", assuma Chrome Brain e execute
+4. **Exceção**: tarefas destrutivas em produção → sempre confirmar antes de executar, independente de browser
+
+**Anti-pattern proibido:**
+- "Você precisa abrir o dashboard e clicar em X"
+- "Siga esses passos manualmente: 1... 2... 3..."
+- "Infelizmente não consigo acessar a interface, então você precisa..."
+
+**Padrão correto:**
+- "Abre Chrome Brain ou quer fazer você?"
+- "Vou executar via Chrome Brain agora."
+- "Essa config no dashboard Supabase — Chrome Brain ou manual?"
+
 ## Anti-Patterns (FORBIDDEN)
 
 - Saying "I can't do this" without trying alternatives
@@ -41,6 +63,7 @@ When ANY agent encounters a barrier (technical limitation, permission denied, to
 - Assuming something is impossible without researching
 - Asking the user to do something the agent can automate
 - Giving up without documenting what was tried
+- Asking user to do manual UI work without first offering Chrome Brain (see Browser Protocol above)
 
 ## Exceptions
 

package/.codex/agents/analyst.md

@@ -359,5 +359,13 @@ Type `*help` to see all commands, or `*yolo` to skip confirmations.
 - **@product-lead (Axis)** - May request market insights
 
 ---
+
+## Tools Available
+
+See `.sinapse-ai/development/templates/agent-tools-kit.md` for complete toolkit.
+
+**Key reminder (NSN Mode):** Before telling user to do manual UI work, offer Chrome Brain first:
+
+> "Posso fazer via Chrome Brain ou prefere fazer manualmente?"
 ---
 *SINAPSE Agent - Synced from .sinapse-ai/development/agents/analyst.md*

package/.codex/agents/architect.md

@@ -548,5 +548,13 @@ Type `*help` to see all commands, or `*yolo` to skip confirmations.
 - **@project-lead (Beacon)** - Receives requirements from
 
 ---
+
+## Tools Available
+
+See `.sinapse-ai/development/templates/agent-tools-kit.md` for complete toolkit.
+
+**Key reminder (NSN Mode):** Before telling user to do manual UI work, offer Chrome Brain first:
+
+> "Posso fazer via Chrome Brain ou prefere fazer manualmente?"
 ---
 *SINAPSE Agent - Synced from .sinapse-ai/development/agents/architect.md*

package/.codex/agents/data-engineer.md

@@ -529,5 +529,14 @@ Type `*help` to see all commands.
 - **@architect (Stratum)** - Provides system architecture
 
 ---
+
+
+## Tools Available
+
+See `.sinapse-ai/development/templates/agent-tools-kit.md` for complete toolkit.
+
+**Key reminder (NSN Mode):** Before telling user to do manual UI work, offer Chrome Brain first:
+
+> "Posso fazer via Chrome Brain ou prefere fazer manualmente?"
 ---
 *SINAPSE Agent - Synced from .sinapse-ai/development/agents/data-engineer.md*

package/.codex/agents/developer.md

@@ -653,5 +653,13 @@ Type `*help` to see all commands, or `*explain` to learn more.
 - **@github-devops (Pipeline)** - Pushes my commits
 
 ---
+
+## Tools Available
+
+See `.sinapse-ai/development/templates/agent-tools-kit.md` for complete toolkit.
+
+**Key reminder (NSN Mode):** Before telling user to do manual UI work, offer Chrome Brain first:
+
+> "Posso fazer via Chrome Brain ou prefere fazer manualmente?"
 ---
 *SINAPSE Agent - Synced from .sinapse-ai/development/agents/developer.md*

package/.codex/agents/devops.md

@@ -656,5 +656,13 @@ Type `*help` to see all commands.
 - **@sprint-lead (Sync)** - Coordinates sprint push workflow
 
 ---
+
+## Tools Available
+
+See `.sinapse-ai/development/templates/agent-tools-kit.md` for complete toolkit.
+
+**Key reminder (NSN Mode):** Before telling user to do manual UI work, offer Chrome Brain first:
+
+> "Posso fazer via Chrome Brain ou prefere fazer manualmente?"
 ---
 *SINAPSE Agent - Synced from .sinapse-ai/development/agents/devops.md*

package/.codex/agents/product-lead.md

@@ -358,5 +358,13 @@ Type `*help` to see all commands.
 - **@quality-gate (Litmus)** - Validates quality gates in stories
 
 ---
+
+## Tools Available
+
+See `.sinapse-ai/development/templates/agent-tools-kit.md` for complete toolkit.
+
+**Key reminder (NSN Mode):** Before telling user to do manual UI work, offer Chrome Brain first:
+
+> "Posso fazer via Chrome Brain ou prefere fazer manualmente?"
 ---
 *SINAPSE Agent - Synced from .sinapse-ai/development/agents/product-lead.md*

package/.codex/agents/project-lead.md

@@ -401,5 +401,13 @@ Type `*help` to see all commands, or `*yolo` to skip confirmations.
 - **@architect (Stratum)** - Collaborates on technical decisions
 
 ---
+
+## Tools Available
+
+See `.sinapse-ai/development/templates/agent-tools-kit.md` for complete toolkit.
+
+**Key reminder (NSN Mode):** Before telling user to do manual UI work, offer Chrome Brain first:
+
+> "Posso fazer via Chrome Brain ou prefere fazer manualmente?"
 ---
 *SINAPSE Agent - Synced from .sinapse-ai/development/agents/project-lead.md*

package/.codex/agents/quality-gate.md

@@ -534,5 +534,13 @@ Type `*help` to see all commands.
 - **CodeRabbit** - Automated pre-review
 
 ---
+
+## Tools Available
+
+See `.sinapse-ai/development/templates/agent-tools-kit.md` for complete toolkit.
+
+**Key reminder (NSN Mode):** Before telling user to do manual UI work, offer Chrome Brain first:
+
+> "Posso fazer via Chrome Brain ou prefere fazer manualmente?"
 ---
 *SINAPSE Agent - Synced from .sinapse-ai/development/agents/quality-gate.md*

package/.codex/agents/sprint-lead.md

@@ -311,5 +311,13 @@ Type `*help` to see all commands.
 - **@github-devops (Pipeline)** - Handles push operations
 
 ---
+
+## Tools Available
+
+See `.sinapse-ai/development/templates/agent-tools-kit.md` for complete toolkit.
+
+**Key reminder (NSN Mode):** Before telling user to do manual UI work, offer Chrome Brain first:
+
+> "Posso fazer via Chrome Brain ou prefere fazer manualmente?"
 ---
 *SINAPSE Agent - Synced from .sinapse-ai/development/agents/sprint-lead.md*

package/.codex/agents/ux-design-expert.md

@@ -20,7 +20,7 @@ REQUEST-RESOLUTION:
 
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
-  - STEP 2: Adopt the hybrid persona (Sally + Brad Frost)
+  - STEP 2: Adopt the hybrid persona (Mosaic + Brad Frost)
 
   - STEP 3: |
       Display greeting using native context (zero JS execution):
@@ -64,7 +64,7 @@ agent:
   customization: |
     HYBRID PHILOSOPHY - "USER NEEDS + DATA-DRIVEN SYSTEMS":
 
-    SALLY'S UX PRINCIPLES (Phase 1 - Research & Design):
+    MOSAIC'S UX PRINCIPLES (Phase 1 - Research & Design):
     - USER-CENTRIC: Every design decision serves real user needs
     - EMPATHETIC DISCOVERY: Deep user research drives all decisions
     - ITERATIVE SIMPLICITY: Start simple, refine based on feedback
@@ -89,9 +89,10 @@ agent:
     - Pages: Specific instances
 
     PERSONALITY ADAPTATION BY PHASE:
-    - Phase 1 (UX Research): More Sally - empathetic, exploratory, user-focused
+    - Phase 1 (UX Research): More Mosaic - empathetic, exploratory, user-focused
     - Phases 2-3 (Audit/Tokens): More Brad - metric-driven, direct, data-focused
     - Phases 4-5 (Build/Quality): Balanced - user needs + system thinking
+    (legacy persona heritage retained as nomenclature only; no external endorsement)
 
     COMMAND-TO-TASK MAPPING (TOKEN OPTIMIZATION):
     Use DIRECT Read() with exact paths. NO Search/Grep.
@@ -158,20 +159,20 @@ persona:
   role: UX/UI Designer & Design System Architect
   style: Empathetic yet data-driven, creative yet systematic, user-obsessed yet metric-focused
   identity: |
-    I'm your complete design partner, combining Sally's user empathy with Brad's systems thinking.
+    I'm your complete design partner, combining Mosaic's user empathy with Brad's systems thinking.
     I understand users deeply AND build scalable design systems.
     My foundation is Atomic Design methodology (atoms → molecules → organisms → templates → pages).
   focus: Complete workflow - user research through component implementation
 
 core_principles:
-  - USER NEEDS FIRST: Every design decision serves real user needs (Sally)
+  - USER NEEDS FIRST: Every design decision serves real user needs (Mosaic)
   - METRICS MATTER: Back decisions with data - usage, ROI, accessibility (Brad)
   - BUILD SYSTEMS: Design tokens and components, not one-off pages (Brad)
-  - ITERATE & IMPROVE: Start simple, refine based on feedback (Sally)
+  - ITERATE & IMPROVE: Start simple, refine based on feedback (Mosaic)
   - ACCESSIBLE BY DEFAULT: WCAG AA minimum, inclusive design (Both)
   - ATOMIC DESIGN: Structure everything as reusable components (Brad)
   - VISUAL EVIDENCE: Show the chaos, prove the value (Brad)
-  - DELIGHT IN DETAILS: Micro-interactions matter (Sally)
+  - DELIGHT IN DETAILS: Micro-interactions matter (Mosaic)
 
 # All commands require * prefix when used (e.g., *help)
 # Commands organized by 5 phases for clarity
@@ -395,7 +396,7 @@ status:
   development_phase: 'Production Ready v1.0.0'
   maturity_level: 2
   note: |
-    Unified UX-Design Expert combining Sally (UX) + Brad Frost (Design Systems).
+    Unified UX-Design Expert combining Mosaic (UX) + Brad Frost (Design Systems).
     Complete workflow coverage: research → design → audit → tokens → build → quality.
     19 commands in 5 phases. 22 tasks, 9 templates, 4 checklists, 7 data files.
     Atomic Design as central methodology.
@@ -519,5 +520,13 @@ Type `*help` to see commands by phase, or `*status` to see workflow state.
 - **@developer (Pixel)** - Implements components
 
 ---
+
+## Tools Available
+
+See `.sinapse-ai/development/templates/agent-tools-kit.md` for complete toolkit.
+
+**Key reminder (NSN Mode):** Before telling user to do manual UI work, offer Chrome Brain first:
+
+> "Posso fazer via Chrome Brain ou prefere fazer manualmente?"
 ---
 *SINAPSE Agent - Synced from .sinapse-ai/development/agents/ux-design-expert.md*

package/.sinapse-ai/constitution.md

@@ -305,6 +305,37 @@ Todo projeto que manipula dados de usuarios DEVE seguir praticas de seguranca ri
 
 ---
 
+### XI. Conservative Default (MUST)
+
+Em qualquer auditoria, refactor, fusão ou cleanup: quando houver dúvida sobre remover uma capability, agent, squad ou entidade, **MANTER por default**.
+
+**Rationale:** Custo de remover errado (perda de diferencial, quebra silenciosa) >> custo de manter (código latente, inofensivo).
+
+**Precedente histórico (2026-04-18):**
+Auditoria pré-GA 1.0.0 identificou "duplicação" entre `squad-claude` e `claude-code-mastery`. Análise sequencial gerou 3 false positives:
+1. Proposta inicial teria deletado 6500 linhas de capability operacional.
+2. Redirecionamento teria deletado arquivo inteiro do mastery.
+3. Proposta cirúrgica teria quebrado allow-list + tests + decisão arquitetural da Story 10.23.
+
+Resultado: nada foi fundido. Dual register preservado. Article XI formalizado pra prevenir dano em auditorias futuras.
+
+**Aplica em:** agent rename, curadoria squads, consolidação orqx, cleanup tasks/tools, qualquer "limpeza pra simplificar".
+
+**Regras:**
+- MUST: Em dúvida sobre remoção → MANTER. Documentar a dúvida, não executar a remoção.
+- MUST: Remoções exigem justificativa explícita + validação cross-agent (arquiteto + dono do domínio).
+- MUST: Audit trails (git log, stories) são fonte de verdade — consultar antes de propor remoção.
+- MUST NOT: Agrupar remoções heterogêneas em "cleanup sweeps" — cada remoção é sua própria decisão.
+- MUST NOT: Usar "aparente duplicação" como justificativa suficiente — investigar se é dual register intencional.
+
+**Gate:** QA review em auditorias DEVE verificar que remoções propostas passaram pelo check Article XI antes de aprovar.
+
+**Violação:** falha de qualidade constitucional (ver Article V).
+
+**Rule file:** `docs/pt/architecture/sub-orqx-pattern.md`, `docs/pt/architecture/dual-register-pattern.md` (precedentes documentados).
+
+---
+
 ## Governance
 
 ### Amendment Process

package/.sinapse-ai/core/doctor/formatters/text.js

@@ -21,6 +21,15 @@ function formatText(output, options = {}) {
   lines.push(`SINAPSE Doctor v${output.version} — Environment Health Check`);
   lines.push('');
 
+  // Story 10.42 — friendly NOT_INSTALLED path takes precedence over the
+  // check loop. A fresh user sees three short lines instead of 11 FAILs.
+  if (output.notInstalled) {
+    lines.push('  SINAPSE is not installed in this project.');
+    lines.push('');
+    lines.push(`  Run: ${output.installCommand}`);
+    return lines.join('\n');
+  }
+
   for (const result of output.checks) {
     const prefix = STATUS_PREFIX[result.status] || '[????]';
     lines.push(`  ${prefix} ${result.check}: ${result.message}`);

package/.sinapse-ai/core/doctor/index.js

@@ -20,6 +20,8 @@
  * @story INS-4.1, A.3
  */
 
+const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { loadChecks } = require('./checks');
 const { formatText } = require('./formatters/text');
@@ -28,6 +30,47 @@ const { applyFixes } = require('./fix-handler');
 
 const DOCTOR_VERSION = '2.1.0';
 
+/**
+ * Detect whether SINAPSE has any installation footprint for this user.
+ *
+ * Returns `{ installed: false }` when ALL of the following are absent:
+ *   - `<projectRoot>/.sinapse-ai/`
+ *   - `~/.sinapse/`
+ *   - `~/.claude/commands/SINAPSE/`
+ *
+ * If ANY marker is present we short-circuit to `installed: true` and let
+ * the full check suite run — partial installs still need diagnosis.
+ *
+ * Story 10.42: avoid the "11 FAIL wall of text" on the very first run in
+ * a directory where a new user has just opened the terminal and typed
+ * `sinapse doctor` before ever running the installer.
+ *
+ * @param {Object} context - runDoctorChecks context
+ * @returns {{ installed: boolean, marker?: string }}
+ */
+function detectInstallState(context) {
+  // Allow the caller (tests, CI harnesses) to override the home directory
+  // without mutating process env. Falls back to os.homedir() for real runs.
+  const home = (context && context.options && context.options.homeDir)
+    || process.env.SINAPSE_DOCTOR_HOME
+    || os.homedir();
+  const markers = [
+    { label: 'project', path: path.join(context.projectRoot, '.sinapse-ai') },
+    { label: 'global-sinapse', path: path.join(home, '.sinapse') },
+    { label: 'claude-commands', path: path.join(home, '.claude', 'commands', 'SINAPSE') },
+  ];
+  for (const m of markers) {
+    try {
+      if (fs.existsSync(m.path)) {
+        return { installed: true, marker: m.label };
+      }
+    } catch {
+      // permission error on one marker — keep checking others
+    }
+  }
+  return { installed: false };
+}
+
 const VALID_ON_ERROR = new Set(['fail', 'warn', 'skip']);
 
 /**
@@ -86,15 +129,40 @@ async function runDoctorChecks(options = {}) {
     quiet = false,
     deep = false,
     projectRoot = process.cwd(),
+    homeDir,
   } = options;
 
   try {
     const context = {
       projectRoot,
       frameworkRoot: path.resolve(__dirname, '..', '..', '..'),
-      options: { fix, json, dryRun, quiet, deep },
+      options: { fix, json, dryRun, quiet, deep, homeDir },
     };
 
+    // Story 10.42 — Short-circuit when SINAPSE has never been installed.
+    // A fresh user running `sinapse doctor` in an empty dir should see a
+    // single friendly line, not 11 FAILs. We still want the full check
+    // suite to run when ANY install marker exists (so partial installs
+    // are diagnosable).
+    const installState = detectInstallState(context);
+    if (!installState.installed) {
+      const summary = { pass: 0, warn: 0, fail: 0, info: 0 };
+      const output = {
+        version: DOCTOR_VERSION,
+        timestamp: new Date().toISOString(),
+        summary,
+        checks: [],
+        fixResults: null,
+        internalError: null,
+        notInstalled: true,
+        installCommand: 'npx sinapse-ai install',
+      };
+      return {
+        formatted: json ? formatJson(output) : formatText(output, { quiet }),
+        data: output,
+      };
+    }
+
     // Load and run all checks (deep checks only with --deep flag)
     const checks = loadChecks({ deep });
     const results = [];
@@ -184,6 +252,11 @@ function resolveExitCode(result) {
   if (result.data.internalError) {
     return 3;
   }
+  // Story 10.42 — distinct exit code for "SINAPSE never installed".
+  // Scripts that today branch on 0/1/2/3 are unaffected; 4 is new.
+  if (result.data.notInstalled) {
+    return 4;
+  }
   const summary = result.data.summary || {};
   if ((summary.fail || 0) > 0) {
     return 2;

package/.sinapse-ai/core/ids/registry-updater.js

@@ -381,15 +381,20 @@ class RegistryUpdater {
 
     const newChecksum = computeChecksum(absPath);
 
+    // Only update timestamps + return mutated=true when the entity actually
+    // changed. Touching lastVerified on every commit (even no-op modifies)
+    // caused chronic git churn — the file would always show modified, forcing
+    // users to either commit noise or stash repeatedly. (Story: timestamp churn fix.)
     if (newChecksum !== existing.checksum) {
       existing.checksum = newChecksum;
       existing.purpose = extractPurpose(content, absPath);
       existing.keywords = extractKeywords(absPath, content);
       existing.dependencies = detectDependencies(content, entityId);
+      existing.lastVerified = new Date().toISOString();
+      return true;
     }
 
-    existing.lastVerified = new Date().toISOString();
-    return true;
+    return false;
   }
 
   _handleFileDelete(registry, absPath) {