sinapse-ai 1.6.1 → 1.8.0

package/.sinapse-ai/core/ids/gate-evaluator.js

@@ -0,0 +1,318 @@
+'use strict';
+
+/**
+ * GateEvaluator — IDS Gate Wiring (Frente 4.0)
+ *
+ * Bridges the inert verification gates (G1-G5) to the live SDC workflow.
+ * Reads a phase->gates mapping from the `ids.gateEvaluation` block of
+ * core-config.yaml, instantiates the mapped gates, calls verify(context) on
+ * each, and aggregates a single PhaseVerdict.
+ *
+ * Aggregation contract:
+ *   - Advisory gates (G1-G4): collect warnings/opportunities, never block.
+ *   - Blocking gates (G3 soft, G5 hard): if a gate result reports
+ *     result.blocking === true, the verdict is marked blocked, carrying the
+ *     blocking gateId and the correctionPrompt extracted from the gate override.
+ *
+ * Fail-open is enforced at two levels:
+ *   1. VerificationGate.verify() never throws (timeout/error -> warn-and-proceed).
+ *   2. This evaluator wraps each gate.verify() in try/catch — a single broken
+ *      gate is logged and skipped; it never knocks out the other gates.
+ *
+ * Source: IDS Gate Wiring frente, ids-principles.md G1-G6 definitions.
+ */
+
+const path = require('path');
+
+const { G1EpicCreationGate } = require(path.resolve(__dirname, 'gates/g1-epic-creation.js'));
+const { G2StoryCreationGate } = require(path.resolve(__dirname, 'gates/g2-story-creation.js'));
+const { G3StoryValidationGate } = require(path.resolve(__dirname, 'gates/g3-story-validation.js'));
+const { G4DevContextGate } = require(path.resolve(__dirname, 'gates/g4-dev-context.js'));
+const { G5SemanticHandshakeGate } = require(path.resolve(__dirname, 'gates/g5-semantic-handshake.js'));
+const { G6CiIntegrityGate } = require(path.resolve(__dirname, 'gates/g6-ci-integrity.js'));
+const { RegistryLoader } = require(path.resolve(__dirname, 'registry-loader.js'));
+const { IncrementalDecisionEngine } = require(path.resolve(__dirname, 'incremental-decision-engine.js'));
+
+const DEFAULT_TIMEOUT_MS = 2000;
+
+/**
+ * Default phase->gates mapping used when the config omits `phaseGates`.
+ * Mirrors the SDC trigger points from ids-principles.md.
+ */
+const DEFAULT_PHASE_GATES = Object.freeze({
+  epic_creation: ['G1'],
+  story_creation: ['G2'],
+  story_validation: ['G3'],
+  '2_development': ['G4', 'G5'],
+  ci_cd: ['G6'],
+});
+
+/**
+ * @typedef {object} PhaseVerdict
+ * @property {string} phase                 - Phase id evaluated (e.g. '2_development').
+ * @property {Array<object>} results        - GateResult of each gate executed, in order.
+ * @property {boolean} blocked              - true only when a blocking gate failed.
+ * @property {string|null} blockingGate     - gateId of the gate that blocked, or null.
+ * @property {string|null} correctionPrompt - correction prompt of the blocking gate, or null.
+ */
+
+class GateEvaluator {
+  /**
+   * @param {object} [config]  — the `ids` block of core-config (expects config.gateEvaluation).
+   * @param {object} [deps]    — dependency injection seam for tests.
+   * @param {RegistryLoader}            [deps.registryLoader]
+   * @param {IncrementalDecisionEngine} [deps.decisionEngine]
+   * @param {object}                    [deps.engine]  — pre-configured SemanticHandshakeEngine for G5.
+   * @param {object}                    [deps.logger]  — logger with warn/info/error (defaults to console).
+   */
+  constructor(config = {}, deps = {}) {
+    const gateConfig = config.gateEvaluation || {};
+
+    this._enabled = gateConfig.enabled !== false; // default enabled
+    this._failOpen = gateConfig.failOpen !== false; // default fail-open
+    this._phaseGates = gateConfig.phaseGates || DEFAULT_PHASE_GATES;
+    this._timeoutMs = gateConfig.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this._registryPath = gateConfig.registryPath || null;
+    this._logger = deps.logger || console;
+
+    // Shared, lazily-built dependencies (mirrors FrameworkGovernor wiring).
+    this._injectedRegistryLoader = deps.registryLoader || null;
+    this._injectedDecisionEngine = deps.decisionEngine || null;
+    this._injectedEngine = deps.engine || null;
+
+    this._registryLoader = this._injectedRegistryLoader;
+    this._decisionEngine = this._injectedDecisionEngine;
+
+    // Cache of instantiated gates by gateId.
+    this._gateCache = new Map();
+  }
+
+  // ================================================================
+  // Public API
+  // ================================================================
+
+  /**
+   * Evaluate every gate mapped to `phaseId` and return the aggregated verdict.
+   *
+   * @param {string} phaseId — Phase identifier (e.g. '2_development').
+   * @param {object} [context] — Gate-specific context (intent, storyId, proposedCode, ...).
+   * @returns {Promise<PhaseVerdict>}
+   */
+  async evaluateGatesForPhase(phaseId, context = {}) {
+    const verdict = {
+      phase: phaseId,
+      results: [],
+      blocked: false,
+      blockingGate: null,
+      correctionPrompt: null,
+    };
+
+    if (!this._enabled) {
+      return verdict;
+    }
+
+    const gateIds = this._phaseGates[phaseId] || [];
+
+    for (const gateId of gateIds) {
+      const result = await this._runGate(gateId, context);
+      if (!result) {
+        // Gate could not be built/run — already logged. Skip, never block.
+        continue;
+      }
+
+      verdict.results.push(result);
+
+      // B.2 — Emit IDS telemetry gate decision (fail-open, never throws).
+      try {
+        const { emitGateDecision } = require('../telemetry/ids-sink');
+        emitGateDecision({
+          tool: gateId,
+          phase: phaseId,
+          blocked: !!(result.result && result.result.blocking === true),
+          warnings: (result.result && result.result.warnings) || [],
+        });
+      } catch { /* fail-open: telemetry must never block gate evaluation */ }
+
+      // A blocking gate that failed marks the verdict blocked.
+      if (result.result && result.result.blocking === true) {
+        verdict.blocked = true;
+        verdict.blockingGate = gateId;
+        verdict.correctionPrompt = this._extractCorrectionPrompt(result);
+        // First blocking gate wins; stop evaluating further gates for this phase.
+        return verdict;
+      }
+    }
+
+    return verdict;
+  }
+
+  /**
+   * Get the gate ids mapped to a phase (empty array if none).
+   * @param {string} phaseId
+   * @returns {string[]}
+   */
+  getGatesForPhase(phaseId) {
+    return [...(this._phaseGates[phaseId] || [])];
+  }
+
+  // ================================================================
+  // Internal helpers
+  // ================================================================
+
+  /**
+   * Run a single gate, guarding against construction/verification errors.
+   * @param {string} gateId
+   * @param {object} context
+   * @returns {Promise<object|null>} GateResult or null when the gate was skipped.
+   */
+  async _runGate(gateId, context) {
+    let gate;
+    try {
+      gate = this._getGate(gateId);
+    } catch (buildError) {
+      this._log('warn', `Gate ${gateId} could not be instantiated: ${buildError.message}`);
+      return null;
+    }
+
+    if (!gate) {
+      this._log('warn', `Gate ${gateId} is not registered. Skipping.`);
+      return null;
+    }
+
+    try {
+      // VerificationGate.verify() is itself fail-open, but we still guard here
+      // so a broken individual gate never derails the rest of the phase.
+      return await gate.verify(context);
+    } catch (verifyError) {
+      this._log('warn', `Gate ${gateId} verify() threw: ${verifyError.message}. Proceeding.`);
+      return null;
+    }
+  }
+
+  /**
+   * Lazily instantiate (and cache) the gate for a gateId.
+   * @param {string} gateId
+   * @returns {object|null}
+   */
+  _getGate(gateId) {
+    if (this._gateCache.has(gateId)) {
+      return this._gateCache.get(gateId);
+    }
+
+    const gate = this._buildGate(gateId);
+    if (gate) {
+      this._gateCache.set(gateId, gate);
+    }
+    return gate;
+  }
+
+  /**
+   * Construct the gate instance for a gateId, wiring shared dependencies.
+   * @param {string} gateId
+   * @returns {object|null}
+   */
+  _buildGate(gateId) {
+    const logger = this._logger;
+    const timeoutMs = this._timeoutMs;
+
+    switch (gateId) {
+      case 'G1':
+        return new G1EpicCreationGate({
+          decisionEngine: this._getDecisionEngine(),
+          timeoutMs,
+          logger,
+        });
+      case 'G2':
+        return new G2StoryCreationGate({
+          decisionEngine: this._getDecisionEngine(),
+          timeoutMs,
+          logger,
+        });
+      case 'G3':
+        return new G3StoryValidationGate({
+          decisionEngine: this._getDecisionEngine(),
+          registryLoader: this._getRegistryLoader(),
+          timeoutMs,
+          logger,
+        });
+      case 'G4':
+        return new G4DevContextGate({
+          decisionEngine: this._getDecisionEngine(),
+          timeoutMs,
+          logger,
+        });
+      case 'G5':
+        return new G5SemanticHandshakeGate({
+          engine: this._injectedEngine || undefined,
+          timeoutMs,
+          logger,
+        });
+      case 'G6':
+        return new G6CiIntegrityGate({
+          registryLoader: this._getRegistryLoader(),
+          registryPath: this._registryPath || undefined,
+          logger,
+        });
+      default:
+        this._log('warn', `Unknown gateId '${gateId}' in phaseGates mapping.`);
+        return null;
+    }
+  }
+
+  /**
+   * Lazily build (and memoize) the shared RegistryLoader.
+   * @returns {RegistryLoader}
+   */
+  _getRegistryLoader() {
+    if (!this._registryLoader) {
+      this._registryLoader = new RegistryLoader(this._registryPath || undefined);
+    }
+    return this._registryLoader;
+  }
+
+  /**
+   * Lazily build (and memoize) the shared IncrementalDecisionEngine.
+   * @returns {IncrementalDecisionEngine}
+   */
+  _getDecisionEngine() {
+    if (!this._decisionEngine) {
+      this._decisionEngine = new IncrementalDecisionEngine(this._getRegistryLoader());
+    }
+    return this._decisionEngine;
+  }
+
+  /**
+   * Extract the correction prompt from a blocking gate result.
+   * Falls back to a generic message when the gate did not provide one.
+   * @param {object} result — GateResult.
+   * @returns {string}
+   */
+  _extractCorrectionPrompt(result) {
+    const override = result && result.override;
+    if (override && override.correctionPrompt) {
+      return override.correctionPrompt;
+    }
+    const warnings = (result && result.result && result.result.warnings) || [];
+    if (warnings.length > 0) {
+      return warnings.join('; ');
+    }
+    return `Gate ${result && result.gateId} reported a blocking violation.`;
+  }
+
+  /**
+   * Internal logging helper.
+   * @param {string} level
+   * @param {string} message
+   */
+  _log(level, message) {
+    const prefix = '[IDS-GateEvaluator]';
+    const logFn = (this._logger && this._logger[level]) || (this._logger && this._logger.log) || console.log;
+    logFn(`${prefix} ${message}`);
+  }
+}
+
+module.exports = {
+  GateEvaluator,
+  DEFAULT_PHASE_GATES,
+  DEFAULT_TIMEOUT_MS,
+};

package/.sinapse-ai/core/ids/gates/g5-semantic-handshake.js

@@ -0,0 +1,190 @@
+'use strict';
+
+/**
+ * G5 — Semantic Handshake Gate
+ *
+ * Agent: @developer
+ * Type: Automated, Blocking
+ * Latency SLA: < 2s
+ * Blocking: YES (blocks on BLOCKER-severity constraint violations)
+ *
+ * Purpose: Converts planning constraints (from @architect / story / planning
+ * output) into executable assertions and validates proposed code against them
+ * BEFORE development execution proceeds. If a registered BLOCKER constraint is
+ * violated by the proposed code, the gate fails and returns a correction prompt.
+ *
+ * Behavior is graceful-degradation friendly (inherited from VerificationGate):
+ *   - No constraints registered  → passes (advisory note).
+ *   - Constraints but no code     → passes, surfaces constraints as opportunities.
+ *   - Code + constraints          → validates; BLOCKER violation → passed=false.
+ *
+ * Composes with SemanticHandshakeEngine (public API):
+ *   getConstraints, registerConstraints, addConstraint, clone,
+ *   validateExecutionIntent, generateComplianceReport.
+ *
+ * Source: IDS-5b (Blocking Gates), ids-principles.md G5 definition.
+ */
+
+const path = require('path');
+const { VerificationGate } = require(path.resolve(__dirname, '../verification-gate.js'));
+const { SemanticHandshakeEngine } = require(
+  path.resolve(__dirname, '../../synapse/context/semantic-handshake-engine.js'),
+);
+
+const G5_DEFAULT_TIMEOUT_MS = 2000;
+
+class G5SemanticHandshakeGate extends VerificationGate {
+  /**
+   * @param {object} options
+   * @param {SemanticHandshakeEngine} [options.engine] — Pre-configured engine instance
+   * @param {object[]} [options.constraints] — Seed constraints (used when no engine provided)
+   * @param {object} [options.circuitBreakerOptions]
+   * @param {number} [options.timeoutMs=2000]
+   * @param {Function} [options.logger]
+   */
+  constructor(options = {}) {
+    super({
+      gateId: 'G5',
+      agent: '@developer',
+      blocking: true,
+      timeoutMs: options.timeoutMs ?? G5_DEFAULT_TIMEOUT_MS,
+      circuitBreakerOptions: options.circuitBreakerOptions,
+      logger: options.logger,
+    });
+
+    this._engine = options.engine || new SemanticHandshakeEngine({
+      constraints: options.constraints || [],
+    });
+  }
+
+  /**
+   * Validate proposed code against registered + context-derived constraints.
+   *
+   * @param {object} context
+   * @param {string} [context.planningOutput] — Planning / architecture text to extract constraints from
+   * @param {string} [context.planningText]
+   * @param {string} [context.architectureText]
+   * @param {string} [context.storyText]
+   * @param {object[]} [context.constraints] — Explicit structured constraints to add
+   * @param {string} [context.proposedCode] — Proposed code to validate
+   * @param {Array} [context.files] — File list ({ path, content }) to validate
+   * @param {Array} [context.diffs]
+   * @param {Array} [context.codeFiles]
+   * @param {string} [context.source] — Constraint source label (default '@architect')
+   * @param {string} [context.storyId]
+   * @returns {Promise<object>} { passed, warnings, opportunities, override }
+   */
+  async _doVerify(context = {}) {
+    const engine = this._createScopedEngine(context);
+    const constraints = engine.getConstraints();
+
+    if (constraints.length === 0) {
+      return {
+        passed: true,
+        warnings: ['No Semantic Handshake constraints registered'],
+        opportunities: [],
+      };
+    }
+
+    if (!this._hasCodeContext(context)) {
+      return {
+        passed: true,
+        warnings: ['Semantic Handshake constraints registered, but no proposed code was provided'],
+        opportunities: constraints.map((c) => ({
+          entity: c.id,
+          recommendation: c.description,
+          severity: c.severity,
+        })),
+      };
+    }
+
+    const result = await engine.validateExecutionIntent(context);
+    const report = engine.generateComplianceReport(result);
+
+    return {
+      passed: result.passed,
+      warnings: [
+        ...result.warnings,
+        ...result.blockingViolations.map((v) => v.message),
+      ],
+      opportunities: [
+        ...result.verifiedConstraints.map((c) => ({
+          entity: c.id,
+          recommendation: 'Constraint verified',
+          severity: c.severity,
+        })),
+        ...result.violations.map((v) => ({
+          entity: v.id,
+          recommendation: v.message,
+          severity: v.severity,
+          matches: v.matches,
+        })),
+      ],
+      override: result.passed
+        ? null
+        : {
+          reason: 'Semantic Handshake blocker violation',
+          correctionPrompt: result.correctionPrompt,
+          report,
+        },
+    };
+  }
+
+  /**
+   * Build a per-invocation engine scoped to this context's constraints so the
+   * gate instance stays stateless across calls.
+   * @param {object} context
+   * @returns {SemanticHandshakeEngine}
+   */
+  _createScopedEngine(context) {
+    const engine = typeof this._engine.clone === 'function'
+      ? this._engine.clone()
+      : new SemanticHandshakeEngine();
+    this._registerContextConstraints(engine, context);
+    return engine;
+  }
+
+  /**
+   * Register constraints derived from planning text and explicit constraint
+   * objects supplied in the context.
+   * @param {SemanticHandshakeEngine} engine
+   * @param {object} context
+   */
+  _registerContextConstraints(engine, context) {
+    const planningText = [
+      context.planningOutput,
+      context.planningText,
+      context.architectureText,
+      context.storyText,
+    ].filter(Boolean).join('\n\n');
+
+    if (planningText.trim()) {
+      engine.registerConstraints(planningText, {
+        source: context.source || '@architect',
+        metadata: { storyId: context.storyId || 'unknown' },
+      });
+    }
+
+    if (Array.isArray(context.constraints)) {
+      for (const c of context.constraints) {
+        engine.addConstraint(c);
+      }
+    }
+  }
+
+  /**
+   * Determine whether the context carries any code to validate.
+   * @param {object} context
+   * @returns {boolean}
+   */
+  _hasCodeContext(context) {
+    return Boolean(
+      context.proposedCode ||
+      (Array.isArray(context.files) && context.files.length > 0) ||
+      (Array.isArray(context.diffs) && context.diffs.length > 0) ||
+      (Array.isArray(context.codeFiles) && context.codeFiles.length > 0),
+    );
+  }
+}
+
+module.exports = { G5SemanticHandshakeGate, G5_DEFAULT_TIMEOUT_MS };

package/.sinapse-ai/core/ids/gates/g6-ci-integrity.js

@@ -0,0 +1,162 @@
+'use strict';
+
+/**
+ * G6 — CI/CD Registry Integrity Gate
+ *
+ * Agent: @devops
+ * Type: Automated, Blocking
+ * Latency SLA: < 60s (registry integrity check + sync)
+ * Blocking: YES on CRITICAL, WARN on MEDIUM/LOW
+ *
+ * Purpose: The CI/CD merge gate of the IDS pipeline. Before a push/merge is
+ * accepted it (1) verifies the Entity Registry is structurally intact and
+ * (2) syncs the registry against the set of changed files — the same work the
+ * `.sinapse-ai/hooks/ids-pre-push.js` hook performs, but exposed as a first-class
+ * gate so the GateEvaluator can wire G6 into the SDC pipeline (ids-principles.md
+ * documented G6 while the code only shipped G1-G5).
+ *
+ * Severity model (ids-principles.md G6):
+ *   - CRITICAL  → registry fails to load / is corrupt / lost its `entities` root
+ *                 → passed=false → blocks merge, carries a correction prompt.
+ *   - MEDIUM/LOW → per-file sync errors → surfaced as warnings, never block.
+ *
+ * Graceful-degradation friendly (inherited from VerificationGate): a thrown
+ * error inside _doVerify is caught by the base class and converted to a
+ * warn-and-proceed, so a flaky CI environment never hard-blocks a merge by
+ * accident — only a genuine integrity violation does.
+ *
+ * Source: IDS-5b (Blocking Gates), ids-principles.md G6 definition.
+ */
+
+const path = require('path');
+const { VerificationGate } = require(path.resolve(__dirname, '../verification-gate.js'));
+const { RegistryLoader } = require(path.resolve(__dirname, '../registry-loader.js'));
+
+// G6 runs in CI; its SLA is generous (< 60s) vs the in-editor gates (< 2s).
+const G6_DEFAULT_TIMEOUT_MS = 60000;
+
+class G6CiIntegrityGate extends VerificationGate {
+  /**
+   * @param {object} options
+   * @param {RegistryLoader} [options.registryLoader] — Injected loader (tests).
+   * @param {object}         [options.registryUpdater] — Injected updater (tests);
+   *        defaults to a lazily-required RegistryUpdater instance.
+   * @param {string}         [options.registryPath] — Registry path override.
+   * @param {object}         [options.circuitBreakerOptions]
+   * @param {number}         [options.timeoutMs=60000]
+   * @param {Function}       [options.logger]
+   */
+  constructor(options = {}) {
+    super({
+      gateId: 'G6',
+      agent: '@devops',
+      blocking: true,
+      timeoutMs: options.timeoutMs ?? G6_DEFAULT_TIMEOUT_MS,
+      circuitBreakerOptions: options.circuitBreakerOptions,
+      logger: options.logger,
+    });
+
+    this._registryPath = options.registryPath || null;
+    this._injectedLoader = options.registryLoader || null;
+    this._injectedUpdater = options.registryUpdater || null;
+  }
+
+  /**
+   * Verify registry integrity and sync against changed files.
+   *
+   * @param {object} context
+   * @param {Array<object>} [context.changes] — Changed files since remote, each
+   *        `{ action: 'add'|'change'|'unlink', relativePath, filePath }`
+   *        (the shape produced by ids-pre-push.js). Optional — when absent, only
+   *        the integrity check runs.
+   * @returns {Promise<object>} { passed, warnings, opportunities, override }
+   */
+  async _doVerify(context = {}) {
+    const warnings = [];
+
+    // ── 1. Integrity check (CRITICAL) ──────────────────────────────────────
+    let entityCount = 0;
+    try {
+      const loader = this._getLoader();
+      const registry = loader.load();
+      if (!registry || !registry.entities) {
+        return this._block('Entity Registry loaded but has no `entities` root.');
+      }
+      entityCount = Object.keys(registry.entities).length;
+    } catch (error) {
+      return this._block(`Entity Registry failed to load (corrupt or unreadable): ${error.message}`);
+    }
+
+    // ── 2. Registry sync against changed files (MEDIUM/LOW → warnings) ──────
+    const changes = Array.isArray(context.changes) ? context.changes : [];
+    let synced = 0;
+    if (changes.length > 0) {
+      try {
+        const updater = this._getUpdater();
+        const result = await updater.processChanges(changes);
+        synced = (result && result.updated) || 0;
+        const errors = (result && result.errors) || [];
+        for (const err of errors) {
+          // Sync errors are MEDIUM/LOW: surface them, but do not block the merge.
+          warnings.push(`[G6] Registry sync issue (non-blocking): ${err.message || err}`);
+        }
+      } catch (error) {
+        // A sync failure is non-critical — the integrity check already passed.
+        warnings.push(`[G6] Registry sync failed (non-blocking): ${error.message}`);
+      }
+    }
+
+    return {
+      passed: true,
+      warnings,
+      opportunities: [],
+      meta: { entityCount, synced },
+    };
+  }
+
+  /**
+   * Build a blocking verdict carrying a correction prompt.
+   * @param {string} reason
+   * @returns {object}
+   * @private
+   */
+  _block(reason) {
+    const correctionPrompt =
+      `${reason}\n\nFix the Entity Registry before merging: run \`sinapse ids:health\` to ` +
+      'diagnose, restore the registry from a known-good state, and re-run the registry sync.';
+    return {
+      passed: false,
+      warnings: [`[G6] CRITICAL: ${reason}`],
+      opportunities: [],
+      override: { correctionPrompt },
+    };
+  }
+
+  /**
+   * Lazily build (and memoize) the RegistryLoader.
+   * @returns {RegistryLoader}
+   * @private
+   */
+  _getLoader() {
+    if (!this._injectedLoader) {
+      this._injectedLoader = new RegistryLoader(this._registryPath || undefined);
+    }
+    return this._injectedLoader;
+  }
+
+  /**
+   * Lazily build (and memoize) the RegistryUpdater. Required only when there are
+   * changes to sync, so the dependency stays out of the integrity-only path.
+   * @returns {object}
+   * @private
+   */
+  _getUpdater() {
+    if (!this._injectedUpdater) {
+      const { RegistryUpdater } = require(path.resolve(__dirname, '../registry-updater.js'));
+      this._injectedUpdater = new RegistryUpdater();
+    }
+    return this._injectedUpdater;
+  }
+}
+
+module.exports = { G6CiIntegrityGate, G6_DEFAULT_TIMEOUT_MS };