sinapse-ai 9.3.0 → 9.5.0

package/.codex/handoff-packet.schema.json

@@ -2,18 +2,19 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Codex Handoff Packet",
   "type": "object",
-  "additionalProperties": false,
+  "additionalProperties": true,
   "required": [
     "mission",
-    "phase",
     "owner",
     "inputs",
     "outputs",
-    "validators",
-    "shared-surface-risk",
-    "next-handoff"
+    "validators"
   ],
   "properties": {
+    "routeId": {
+      "type": "string",
+      "minLength": 1
+    },
     "mission": {
       "type": "string",
       "minLength": 1
@@ -26,6 +27,12 @@
       "type": "string",
       "minLength": 1
     },
+    "classification": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "string"
+    },
     "inputs": {
       "type": "array",
       "minItems": 1,
@@ -50,14 +57,31 @@
         "minLength": 1
       }
     },
+    "sharedSurfaceRisk": {
+      "type": "string"
+    },
     "shared-surface-risk": {
       "type": "string",
-      "enum": ["none", "codex-only", "shared-review-required"]
+      "enum": ["none", "codex-only", "shared-review-required", "low"]
+    },
+    "nextHandoff": {
+      "type": "object",
+      "properties": {
+        "to": { "type": "string" },
+        "artifact": { "type": "string" }
+      }
     },
     "next-handoff": {
       "type": "string",
       "minLength": 1
     },
+    "delegationChain": {
+      "type": "array"
+    },
+    "resources": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
     "notes": {
       "type": "array",
       "items": {

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 };
 

package/.sinapse-ai/core/doctor/checks/rules-files.js

@@ -58,5 +58,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run, EXPECTED_RULES };
+// Story A.3: rules files ship with the framework; exceptions indicate real damage.
+const onError = 'fail';
+
+module.exports = { name, run, EXPECTED_RULES, onError };
 

package/.sinapse-ai/core/doctor/checks/settings-json.js

@@ -118,5 +118,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: .claude/settings.json is a hard requirement. Exceptions are FAIL.
+const onError = 'fail';
+
+module.exports = { name, run, onError };
 

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

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

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

@@ -1,12 +1,23 @@
 /**
  * SINAPSE Doctor — Environment Health Check Orchestrator
  *
- * Runs 12 modular checks against the SINAPSE environment and returns
+ * Runs modular checks against the SINAPSE environment and returns
  * structured results with optional --fix, --json, and --dry-run support.
  *
+ * Exception Classification (Story A.3):
+ * Each check module may export an `onError` field with one of:
+ *   - 'fail' (default) — thrown exceptions map to a FAIL verdict
+ *   - 'warn'           — thrown exceptions map to a WARN verdict
+ *   - 'skip'           — thrown exceptions cause the check to be excluded
+ *                        from results entirely
+ *
+ * This replaces the previous behavior where the generic catch block
+ * marked every exception as FAIL, producing false alarms on fresh
+ * installs (no git repo, empty registry, missing agent memory dirs).
+ *
  * @module sinapse-ai/doctor
- * @version 2.0.0
- * @story INS-4.1
+ * @version 2.1.0
+ * @story INS-4.1, A.3
  */
 
 const path = require('path');
@@ -15,7 +26,46 @@ const { formatText } = require('./formatters/text');
 const { formatJson } = require('./formatters/json');
 const { applyFixes } = require('./fix-handler');
 
-const DOCTOR_VERSION = '2.0.0';
+const DOCTOR_VERSION = '2.1.0';
+
+const VALID_ON_ERROR = new Set(['fail', 'warn', 'skip']);
+
+/**
+ * Map a check module's `onError` field to the verdict produced when
+ * the check itself throws. Falls back to 'fail' for safety.
+ *
+ * @param {Object} checkModule
+ * @returns {'fail' | 'warn' | 'skip'}
+ */
+function resolveOnError(checkModule) {
+  const declared = checkModule && checkModule.onError;
+  if (declared && VALID_ON_ERROR.has(declared)) {
+    return declared;
+  }
+  return 'fail';
+}
+
+/**
+ * Build a structured result entry for a thrown exception, based on
+ * the check's declared error policy. Returns null if the policy is
+ * 'skip' (excluded from results).
+ *
+ * @param {Object} checkModule
+ * @param {Error} error
+ * @returns {Object|null}
+ */
+function buildErrorResult(checkModule, error) {
+  const policy = resolveOnError(checkModule);
+  if (policy === 'skip') {
+    return null;
+  }
+  return {
+    check: checkModule.name || 'unknown',
+    status: policy === 'warn' ? 'WARN' : 'FAIL',
+    message: `Check threw error: ${error.message}`,
+    fixCommand: null,
+  };
+}
 
 /**
  * Run all doctor checks
@@ -26,7 +76,7 @@ const DOCTOR_VERSION = '2.0.0';
  * @param {boolean} [options.dryRun=false] - Show what --fix would do
  * @param {boolean} [options.quiet=false] - Minimal output
  * @param {string} [options.projectRoot] - Project root (defaults to cwd)
- * @returns {Promise<Object>} Doctor results
+ * @returns {Promise<Object>} Doctor results (includes `internalError` when the runner itself crashes)
  */
 async function runDoctorChecks(options = {}) {
   const {
@@ -38,58 +88,115 @@ async function runDoctorChecks(options = {}) {
     projectRoot = process.cwd(),
   } = options;
 
-  const context = {
-    projectRoot,
-    frameworkRoot: path.resolve(__dirname, '..', '..', '..'),
-    options: { fix, json, dryRun, quiet, deep },
-  };
+  try {
+    const context = {
+      projectRoot,
+      frameworkRoot: path.resolve(__dirname, '..', '..', '..'),
+      options: { fix, json, dryRun, quiet, deep },
+    };
+
+    // Load and run all checks (deep checks only with --deep flag)
+    const checks = loadChecks({ deep });
+    const results = [];
 
-  // Load and run all checks (deep checks only with --deep flag)
-  const checks = loadChecks({ deep });
-  const results = [];
-
-  for (const checkModule of checks) {
-    try {
-      const result = await checkModule.run(context);
-      results.push(result);
-    } catch (error) {
-      results.push({
-        check: checkModule.name || 'unknown',
-        status: 'FAIL',
-        message: `Check threw error: ${error.message}`,
-        fixCommand: null,
-      });
+    for (const checkModule of checks) {
+      try {
+        const result = await checkModule.run(context);
+        results.push(result);
+      } catch (error) {
+        const errorResult = buildErrorResult(checkModule, error);
+        if (errorResult !== null) {
+          results.push(errorResult);
+        }
+        // policy === 'skip' → silently exclude
+      }
     }
-  }
 
-  // Apply fixes if requested
-  let fixResults = null;
-  if (fix || dryRun) {
-    fixResults = await applyFixes(results, context);
-  }
+    // Apply fixes if requested
+    let fixResults = null;
+    if (fix || dryRun) {
+      fixResults = await applyFixes(results, context);
+    }
 
-  // Build summary
-  const summary = {
-    pass: results.filter((r) => r.status === 'PASS').length,
-    warn: results.filter((r) => r.status === 'WARN').length,
-    fail: results.filter((r) => r.status === 'FAIL').length,
-    info: results.filter((r) => r.status === 'INFO').length,
-  };
+    // Build summary
+    const summary = {
+      pass: results.filter((r) => r.status === 'PASS').length,
+      warn: results.filter((r) => r.status === 'WARN').length,
+      fail: results.filter((r) => r.status === 'FAIL').length,
+      info: results.filter((r) => r.status === 'INFO').length,
+    };
 
-  const output = {
-    version: DOCTOR_VERSION,
-    timestamp: new Date().toISOString(),
-    summary,
-    checks: results,
-    fixResults,
-  };
+    const output = {
+      version: DOCTOR_VERSION,
+      timestamp: new Date().toISOString(),
+      summary,
+      checks: results,
+      fixResults,
+      internalError: null,
+    };
+
+    // Format output
+    if (json) {
+      return { formatted: formatJson(output), data: output };
+    }
+
+    return { formatted: formatText(output, { quiet }), data: output };
+  } catch (runnerError) {
+    // Runner itself crashed (not a check throwing). Surface as exit code 3.
+    const summary = { pass: 0, warn: 0, fail: 0, info: 0 };
+    const errorPayload = {
+      message: runnerError.message,
+      stack: runnerError.stack,
+    };
+    const output = {
+      version: DOCTOR_VERSION,
+      timestamp: new Date().toISOString(),
+      summary,
+      checks: [],
+      fixResults: null,
+      internalError: errorPayload,
+    };
+
+    const formatted = json
+      ? formatJson(output)
+      : `SINAPSE Doctor v${DOCTOR_VERSION} — internal error: ${runnerError.message}`;
 
-  // Format output
-  if (json) {
-    return { formatted: formatJson(output), data: output };
+    return { formatted, data: output };
   }
+}
 
-  return { formatted: formatText(output, { quiet }), data: output };
+/**
+ * Resolve a doctor result object into a canonical exit code.
+ *
+ * Story A.3 exit code mapping:
+ *   0 — PASS (no FAILs, no WARNs)
+ *   1 — WARN only (no FAILs)
+ *   2 — at least one FAIL
+ *   3 — internal runner error (runDoctorChecks itself crashed)
+ *
+ * @param {Object} result - Return value from runDoctorChecks()
+ * @returns {0 | 1 | 2 | 3}
+ */
+function resolveExitCode(result) {
+  if (!result || !result.data) {
+    return 3;
+  }
+  if (result.data.internalError) {
+    return 3;
+  }
+  const summary = result.data.summary || {};
+  if ((summary.fail || 0) > 0) {
+    return 2;
+  }
+  if ((summary.warn || 0) > 0) {
+    return 1;
+  }
+  return 0;
 }
 
-module.exports = { runDoctorChecks, DOCTOR_VERSION };
+module.exports = {
+  runDoctorChecks,
+  resolveExitCode,
+  resolveOnError,
+  DOCTOR_VERSION,
+};

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

@@ -483,10 +483,15 @@ class RegistryUpdater {
   }
 
   _writeRegistry(registryData) {
+    // Story 10.24 — sortKeys: true makes the YAML output deterministic.
+    // Without it, key order follows JS object insertion order, which means
+    // semantically-identical writes can produce textually-different files
+    // and cause endless `M entity-registry.yaml` churn in `git status`.
+    // The registry is machine-managed so alphabetical key order is fine.
     const yamlStr = yaml.dump(registryData, {
       lineWidth: 120,
       noRefs: true,
-      sortKeys: false,
+      sortKeys: true,
     });
 
     const dir = path.dirname(this._registryPath);