sinapse-ai 1.7.0 → 1.9.0

package/.sinapse-ai/core/orchestration/workflow-executor.js

@@ -28,6 +28,16 @@ const ExecutorAssignment = require('./executor-assignment');
 const TerminalSpawner = require('./terminal-spawner');
 const { SessionState, ActionType } = require('./session-state');
 
+// IDS Gate Wiring: GateEvaluator wires the IDS verification gates into the
+// development phase. Loaded with a fallback so a missing module never breaks
+// the workflow (graceful degradation — IDS must never block development).
+let GateEvaluator = null;
+try {
+  GateEvaluator = require('../ids/gate-evaluator').GateEvaluator;
+} catch (_err) {
+  // GateEvaluator unavailable — workflow runs without IDS gate enrichment.
+}
+
 // Constants
 const DEFAULT_TIMEOUT_MS = 7200000; // 2 hours
 const CHECKPOINT_TIMEOUT_MS = 1800000; // 30 minutes
@@ -599,6 +609,37 @@ class WorkflowExecutor {
       // Story 12.6: Emit agent spawn for observability (AC1)
       this._emitAgentSpawn(agent, 'development');
 
+      // IDS Gate Wiring: evaluate the IDS gates mapped to the development phase
+      // (G4 advisory dev-context + G5 blocking semantic-handshake). Fail-open:
+      // any evaluator failure is logged and the workflow proceeds. Only a real
+      // G5 BLOCKER violation fails the phase.
+      if (GateEvaluator) {
+        try {
+          const evaluator = new GateEvaluator(this.config?.ids || {});
+          const storyId = path.basename(storyPath, path.extname(storyPath));
+          const verdict = await evaluator.evaluateGatesForPhase('2_development', {
+            intent: phase.description || storyId,
+            storyId,
+            filePaths: [],
+          });
+
+          if (verdict.blocked) {
+            return {
+              status: PhaseStatus.FAILED,
+              error: `[IDS-${verdict.blockingGate}] Semantic Handshake blocker: ${verdict.correctionPrompt}`,
+              gateVerdict: verdict,
+            };
+          }
+
+          if (this.options.debug && verdict.results.length > 0) {
+            console.log('[WorkflowExecutor] IDS gate advisory:', JSON.stringify(verdict.results));
+          }
+        } catch (gateError) {
+          // Fail-open: a degraded evaluator never halts development.
+          console.warn(`[WorkflowExecutor] IDS gate-evaluator degraded: ${gateError.message}`);
+        }
+      }
+
       // Use terminal spawning (Story 11.2)
       if (phase.spawn_in_terminal && TerminalSpawner.isSpawnerAvailable()) {
         const context = {

package/.sinapse-ai/core/registry/squad-agent-resolver.js

@@ -0,0 +1,253 @@
+/**
+ * Squad Agent Resolver
+ *
+ * epic: orchestration-consolidation, F2 — makes the 177 squad personas (plus the
+ * framework agents) addressable BY CODE. Before this, the SubagentDispatcher knew
+ * only ~10 generic agents (@dev/@qa/...) and built a one-line "You are @x" prompt,
+ * discarding the real persona. This indexes every agent .md across `squads/` and
+ * the framework agent dirs, and loads the FULL persona on demand.
+ *
+ * Convention (verified across all squads): the agent id IS the file basename in
+ * kebab-case (e.g. `penetration-tester.md` -> id `penetration-tester`), which
+ * matches the embedded `id:` field. We key by basename for robustness and also
+ * register the embedded id / display name as aliases when present.
+ *
+ * @module core/registry/squad-agent-resolver
+ * @version 1.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Directories scanned for agent definitions, relative to projectRoot. */
+const AGENT_DIRS = [
+  'squads', // squads/<squad>/agents/<id>.md
+  path.join('.sinapse-ai', 'agents'),
+  path.join('.sinapse-ai', 'development', 'agents'),
+];
+
+/**
+ * Short-form aliases used across the framework (dispatcher agentMapping, CLAUDE.md
+ * command table) → canonical file id. Lets '@dev' resolve to the developer persona
+ * instead of falling through to a one-line generic prompt.
+ */
+const ALIASES = {
+  dev: 'developer',
+  qa: 'quality-gate',
+  pm: 'project-lead',
+  po: 'product-lead',
+  sm: 'sprint-lead',
+  ux: 'ux-design-expert',
+  'ux-expert': 'ux-design-expert',
+};
+
+class SquadAgentResolver {
+  /**
+   * @param {string} projectRoot - Project root directory
+   */
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this._index = null; // Map<normalizedKey, entry> — built lazily
+    this._personaCache = new Map(); // id -> persona content
+  }
+
+  /**
+   * Normalize an agent reference for lookup: strip leading '@', lowercase,
+   * collapse separators. So '@penetration-tester', 'penetration_tester' and
+   * 'Penetration Tester' all resolve to the same key.
+   * @param {string} ref
+   * @returns {string}
+   */
+  static normalizeKey(ref) {
+    return String(ref || '')
+      .replace(/^@/, '')
+      .trim()
+      .toLowerCase()
+      .replace(/[\s_]+/g, '-');
+  }
+
+  /**
+   * Build (once) the index of every agent definition on disk.
+   * @returns {Map<string, Object>} normalizedKey -> { id, name, squad, filePath }
+   */
+  buildIndex() {
+    if (this._index) return this._index;
+    const index = new Map();
+
+    const addEntry = (filePath, squad) => {
+      const base = path.basename(filePath, '.md');
+      if (!base || base.toUpperCase() === 'README') return;
+      const key = SquadAgentResolver.normalizeKey(base);
+      // First writer wins for a given key, but squad agents take precedence over
+      // framework duplicates only if a squad entry isn't already registered.
+      if (!index.has(key)) {
+        index.set(key, { id: base, name: base, squad, filePath });
+      }
+    };
+
+    for (const rel of AGENT_DIRS) {
+      const dir = path.join(this.projectRoot, rel);
+      if (!fs.existsSync(dir)) continue;
+
+      if (rel === 'squads') {
+        // squads/<squad>/agents/*.md
+        let squadDirs = [];
+        try {
+          squadDirs = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+          squadDirs = [];
+        }
+        for (const sd of squadDirs) {
+          if (!sd.isDirectory()) continue;
+          const agentsDir = path.join(dir, sd.name, 'agents');
+          if (!fs.existsSync(agentsDir)) continue;
+          for (const f of this._listMd(agentsDir)) {
+            addEntry(path.join(agentsDir, f), sd.name);
+          }
+        }
+      } else {
+        // flat dir of *.md
+        for (const f of this._listMd(dir)) {
+          addEntry(path.join(dir, f), null);
+        }
+      }
+    }
+
+    this._index = index;
+    return index;
+  }
+
+  /**
+   * List .md files in a directory (non-recursive), tolerant of read errors.
+   * @param {string} dir
+   * @returns {string[]}
+   * @private
+   */
+  _listMd(dir) {
+    try {
+      return fs.readdirSync(dir).filter((f) => f.toLowerCase().endsWith('.md'));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Resolve an agent reference to its index entry.
+   * @param {string} ref - e.g. '@penetration-tester', 'dev', 'cloud-security-engineer'
+   * @returns {Object|null} { id, name, squad, filePath } or null when unknown
+   */
+  resolve(ref) {
+    const index = this.buildIndex();
+    const key = SquadAgentResolver.normalizeKey(ref);
+    return index.get(key) || index.get(ALIASES[key]) || null;
+  }
+
+  /**
+   * True when the reference maps to a known agent definition on disk.
+   * @param {string} ref
+   * @returns {boolean}
+   */
+  has(ref) {
+    return this.resolve(ref) !== null;
+  }
+
+  /**
+   * Load the full persona markdown for an agent reference.
+   * @param {string} ref
+   * @returns {string|null} persona content, or null when unknown/unreadable
+   */
+  loadPersona(ref) {
+    const entry = this.resolve(ref);
+    if (!entry) return null;
+    if (this._personaCache.has(entry.id)) return this._personaCache.get(entry.id);
+    let content = null;
+    try {
+      content = fs.readFileSync(entry.filePath, 'utf8');
+    } catch {
+      content = null;
+    }
+    this._personaCache.set(entry.id, content);
+    return content;
+  }
+
+  /**
+   * All known agent ids (sorted), for diagnostics / `sinapse` listing.
+   * @returns {string[]}
+   */
+  listIds() {
+    return [...this.buildIndex().values()].map((e) => e.id).sort();
+  }
+
+  /**
+   * Count of indexed agents.
+   * @returns {number}
+   */
+  size() {
+    return this.buildIndex().size;
+  }
+
+  /**
+   * Normalized metadata for an agent, extracted from whatever structure the
+   * file uses (frontmatter, `# Agent: X`, `# X`, or an embedded ```yaml block).
+   * This is the uniform schema (SCHEMA-001 closure) without mutating the 199
+   * heterogeneous persona files — the canonical shape is DERIVED, not imposed.
+   *
+   * @param {string} ref
+   * @returns {{id, name, squad, type, hasStructuredYaml, file}|null}
+   */
+  describe(ref) {
+    const entry = this.resolve(ref);
+    if (!entry) return null;
+    const content = this.loadPersona(entry.id) || '';
+    return {
+      id: entry.id,
+      name: SquadAgentResolver.extractName(content, entry.id),
+      squad: entry.squad || 'framework',
+      type: /-orqx$/.test(entry.id) ? 'orchestrator' : 'specialist',
+      hasStructuredYaml: /```ya?ml/.test(content) || /^\s*agent:\s*$/m.test(content),
+      file: entry.filePath,
+    };
+  }
+
+  /**
+   * Describe every indexed agent (sorted by id) — the uniform registry view.
+   * @returns {Array<Object>}
+   */
+  list() {
+    return this.listIds().map((id) => this.describe(id));
+  }
+
+  /**
+   * Best-effort display name from heterogeneous structures. Falls back to a
+   * title-cased id so the result is never empty.
+   * @param {string} content - File content
+   * @param {string} id - Canonical id (filename)
+   * @returns {string}
+   */
+  static extractName(content, id) {
+    const src = String(content || '');
+    // 1. YAML frontmatter `name:`
+    const fm = src.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (fm) {
+      const m = fm[1].match(/^\s*name:\s*["']?([^"'\n]+)["']?\s*$/m);
+      if (m && m[1].trim()) return m[1].trim();
+    }
+    // 2. Embedded yaml `name:` (inside an ```yaml block or agent: section)
+    const ym = src.match(/^\s*name:\s*["']?([^"'\n]+)["']?\s*$/m);
+    if (ym && ym[1].trim()) return ym[1].trim();
+    // 3. `# Agent: Name`
+    const ah = src.match(/^#\s*Agent:\s*(.+?)\s*$/m);
+    if (ah && ah[1].trim()) return ah[1].trim();
+    // 4. First `# Heading`
+    const h1 = src.match(/^#\s+(.+?)\s*$/m);
+    if (h1 && h1[1].trim()) return h1[1].trim().replace(/^@/, '');
+    // 5. Title-cased id
+    return String(id)
+      .split('-')
+      .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+      .join(' ');
+  }
+}
+
+module.exports = SquadAgentResolver;
+module.exports.SquadAgentResolver = SquadAgentResolver;

package/.sinapse-ai/core/telemetry/ids-sink.js

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * IDS Telemetry Sink — SINAPSE Framework
+ * @story Frente 4.3 — Telemetria OTel + DORA + Gate Decisions JSONL (Stream B)
+ *
+ * A LOCAL-only, always-on sink for IDS gate decision events.
+ * This is NOT the opt-in user telemetry stub (telemetry/index.js).
+ * This sink records framework-internal operational data only — no PII,
+ * no user paths, no prompt content.
+ *
+ * Design principles:
+ *  - FAIL-OPEN TOTAL: any error is swallowed silently. Never throws. Never blocks.
+ *  - Zero external deps: pure Node stdlib (fs, path, os).
+ *  - OTel GenAI semantic conventions for field names.
+ *  - Separate from opt-in telemetry; isEnabled() is NOT consulted.
+ *
+ * Output file: <projectRoot>/.sinapse/telemetry/gate-decisions.jsonl
+ * (gitignored by default — .sinapse/ is in .gitignore)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Constants (OTel GenAI semantic conventions) ─────────────────────────────
+
+const OPERATION_GATE_EVALUATE = 'ids.gate.evaluate';
+const OPERATION_SESSION_END = 'session.end';
+const MODEL_IDS = 'sinapse-ids';
+
+// ─── Sink path resolution ─────────────────────────────────────────────────────
+
+/**
+ * Resolve the absolute path to the JSONL sink file.
+ * Uses process.cwd() as project root — same convention as DashboardEmitter.
+ * Caller may override via SINAPSE_TELEMETRY_SINK env var (useful in tests).
+ *
+ * @returns {string}
+ */
+function resolveSinkPath() {
+  if (process.env.SINAPSE_TELEMETRY_SINK) {
+    return process.env.SINAPSE_TELEMETRY_SINK;
+  }
+  return path.join(process.cwd(), '.sinapse', 'telemetry', 'gate-decisions.jsonl');
+}
+
+/**
+ * Ensure the directory for the sink exists. Fail-open.
+ * @param {string} sinkPath
+ */
+function ensureSinkDir(sinkPath) {
+  try {
+    fs.mkdirSync(path.dirname(sinkPath), { recursive: true });
+  } catch {
+    // fail-open: if we can't create the dir, the appendFileSync below will
+    // also fail and be swallowed by the outer try/catch.
+  }
+}
+
+/**
+ * Append a single JSON line to the sink. Fail-open.
+ * @param {object} record — must be JSON-serialisable.
+ */
+function appendLine(record) {
+  try {
+    const sinkPath = resolveSinkPath();
+    ensureSinkDir(sinkPath);
+    fs.appendFileSync(sinkPath, JSON.stringify(record) + '\n', 'utf8');
+  } catch {
+    /* fail-open: telemetry MUST NEVER block the caller */
+  }
+}
+
+// ─── Session ID resolution ────────────────────────────────────────────────────
+
+/**
+ * Resolve the current session id from environment variables injected by
+ * Claude Code. Falls back to 'unknown' when not available.
+ * @returns {string}
+ */
+function resolveSessionId() {
+  return (
+    process.env.CLAUDE_SESSION_ID ||
+    process.env.CLAUDE_CODE_SESSION_ID ||
+    process.env.SINAPSE_SESSION_ID ||
+    'unknown'
+  );
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Emit a gate-decision event as a JSONL line using OTel GenAI field names.
+ *
+ * Fields emitted (NO PII):
+ *  - timestamp            ISO-8601
+ *  - gen_ai.operation.name  "ids.gate.evaluate"
+ *  - gen_ai.request.model   "sinapse-ids"
+ *  - gen_ai.usage.input_tokens   always 0 (no LLM call)
+ *  - gen_ai.usage.output_tokens  always 0 (no LLM call)
+ *  - tool                 gateId (e.g. "G1")
+ *  - sessionId            from CLAUDE_SESSION_ID env or "unknown"
+ *  - phase                phaseId (e.g. "epic_creation")
+ *  - blocked              boolean
+ *  - warnings             string[] (gate warning messages)
+ *
+ * FAIL-OPEN: any error inside this function is swallowed. Returns void.
+ *
+ * @param {{
+ *   tool: string,
+ *   phase: string,
+ *   blocked: boolean,
+ *   warnings?: string[],
+ *   sessionId?: string,
+ * }} record
+ */
+function emitGateDecision(record) {
+  try {
+    appendLine({
+      timestamp: new Date().toISOString(),
+      'gen_ai.operation.name': OPERATION_GATE_EVALUATE,
+      'gen_ai.request.model': MODEL_IDS,
+      'gen_ai.usage.input_tokens': 0,
+      'gen_ai.usage.output_tokens': 0,
+      tool: String(record.tool || 'unknown'),
+      sessionId: record.sessionId || resolveSessionId(),
+      phase: String(record.phase || 'unknown'),
+      blocked: record.blocked === true,
+      warnings: Array.isArray(record.warnings) ? record.warnings : [],
+    });
+  } catch {
+    /* fail-open */
+  }
+}
+
+/**
+ * Emit a session-end event with DORA base counters.
+ *
+ * Fields emitted:
+ *  - timestamp
+ *  - gen_ai.operation.name   "session.end"
+ *  - gen_ai.request.model    "sinapse-ids"
+ *  - gen_ai.usage.input_tokens   0
+ *  - gen_ai.usage.output_tokens  0
+ *  - sessionId
+ *  - dora.toolExecutions     total tool calls in the session
+ *  - dora.filesModified      Write + Edit tool calls count
+ *  - dora.sessionDurationMs  session wall-clock duration in ms
+ *
+ * FAIL-OPEN. Returns void.
+ *
+ * @param {{
+ *   sessionId: string,
+ *   toolExecutions: number,
+ *   filesModified: number,
+ *   sessionDurationMs: number,
+ * }} record
+ */
+function emitSessionEnd(record) {
+  try {
+    appendLine({
+      timestamp: new Date().toISOString(),
+      'gen_ai.operation.name': OPERATION_SESSION_END,
+      'gen_ai.request.model': MODEL_IDS,
+      'gen_ai.usage.input_tokens': 0,
+      'gen_ai.usage.output_tokens': 0,
+      sessionId: String(record.sessionId || 'unknown'),
+      'dora.toolExecutions': Number(record.toolExecutions) || 0,
+      'dora.filesModified': Number(record.filesModified) || 0,
+      'dora.sessionDurationMs': Number(record.sessionDurationMs) || 0,
+    });
+  } catch {
+    /* fail-open */
+  }
+}
+
+// ─── Exported (test-accessible) internals ────────────────────────────────────
+
+module.exports = {
+  emitGateDecision,
+  emitSessionEnd,
+  // Exposed for tests only — NOT part of the public contract.
+  _resolveSinkPath: resolveSinkPath,
+  _resolveSessionId: resolveSessionId,
+  OPERATION_GATE_EVALUATE,
+  OPERATION_SESSION_END,
+  MODEL_IDS,
+};