sinapse-ai 1.16.0 → 1.19.0

package/.sinapse-ai/core/orchestration/route-command.js

@@ -0,0 +1,97 @@
+/**
+ * Route Command — read-only doc-first routing observability.
+ *
+ * Renders the deterministic routing decision for a briefing: project type →
+ * workflow → required upstream docs (exist/missing) → doc-first gate verdict.
+ *
+ * Intentionally lightweight: requires ONLY `doc-first-resolver` (fs + constants)
+ * and chalk. It does NOT pull the heavy orchestration index, so it has no side
+ * effects and no agent spawning.
+ *
+ * NOTE: a machine-readable `--json` mode was intentionally deferred — the
+ * framework emits an activation/cleanup summary to stdout on process exit
+ * (the same trailing line seen on `sinapse orchestrate`), which would corrupt
+ * strict JSON output. Programmatic consumers should require `doc-first-resolver`
+ * directly (clean, no side effects) instead of parsing this command's stdout.
+ *
+ * @module core/orchestration/route-command
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveDocFirstState } = require('./doc-first-resolver');
+
+let chalk;
+try {
+  chalk = require('chalk');
+} catch {
+  const id = (s) => s;
+  chalk = {
+    green: id, red: id, yellow: id, cyan: Object.assign(id, { bold: id }),
+    gray: id, bold: id, dim: id,
+  };
+}
+
+/**
+ * Execute the `route` command.
+ *
+ * @param {string} brief - User briefing (e.g. "criar um site pra X")
+ * @param {Object} [options]
+ * @param {string} [options.projectRoot] - Project root path
+ * @param {string} [options.type] - Explicit project_type override
+ * @returns {Promise<{success:boolean, exitCode:number, state:Object}>}
+ */
+async function route(brief, options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const state = resolveDocFirstState({ projectRoot, brief, projectType: options.type });
+
+  const ok = (b) => (b ? chalk.green('✓') : chalk.red('✗'));
+  const briefLabel = brief ? `"${brief}"` : '(no brief — using project state only)';
+
+  console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════'));
+  console.log(chalk.cyan.bold('  🧭 SINAPSE Doc-First Routing'));
+  console.log(chalk.cyan('═══════════════════════════════════════════════════════════\n'));
+
+  console.log(`Brief:        ${chalk.gray(briefLabel)}`);
+  console.log(
+    `Project type: ${chalk.bold(state.projectType)}` +
+      (state.classified ? '' : chalk.gray('  (default — not matched from brief)')),
+  );
+  console.log(`Workflow:     ${chalk.bold(state.workflow || 'SDC (no upstream re-doc)')}\n`);
+
+  if (state.artifacts.length) {
+    console.log(chalk.bold('Required upstream documents:'));
+    console.log(chalk.gray('  ┌──────────────────┬────────────────────────────────────┬────────┐'));
+    console.log(chalk.gray('  │ Document         │ Path                               │ Status │'));
+    console.log(chalk.gray('  ├──────────────────┼────────────────────────────────────┼────────┤'));
+    for (const a of state.artifacts) {
+      console.log(`  │ ${a.id.padEnd(16)} │ ${a.path.padEnd(34)} │   ${ok(a.exists)}    │`);
+    }
+    console.log(chalk.gray('  └──────────────────┴────────────────────────────────────┴────────┘\n'));
+  }
+
+  console.log(chalk.bold('Doc-first gate (required before code):'));
+  if (state.isLightType) {
+    console.log(chalk.gray('  (light task — rides on existing project; only a Ready story is required)'));
+    console.log(`  ${ok(state.gate.readyStory)} Story (status >= Ready)`);
+  } else {
+    console.log(`  ${ok(state.gate.prd)} PRD            ${chalk.gray('docs/prd.md')}`);
+    console.log(`  ${ok(state.gate.epic)} Epic           ${chalk.gray('docs/epics/')}`);
+    console.log(`  ${ok(state.gate.readyStory)} Story (Ready)  ${chalk.gray('docs/stories/')}`);
+  }
+
+  console.log('');
+  if (state.gate.satisfied) {
+    console.log(chalk.green.bold('  ✅ GATE SATISFIED — implementation may proceed.\n'));
+  } else {
+    console.log(chalk.red.bold('  🚫 GATE BLOCKED — missing: ' + state.gate.missing.join(', ')));
+    console.log(
+      chalk.gray(`     Run the ${state.workflow || 'SDC'} flow to produce these before any code.\n`),
+    );
+  }
+
+  return { success: true, exitCode: 0, state };
+}
+
+module.exports = { route };

package/.sinapse-ai/core/orchestration/session-state.js

@@ -20,6 +20,23 @@ const fsSync = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
 
+// On Windows a concurrent reader / AV / Search indexer can hold a transient lock
+// that makes fs.rename throw EPERM/EBUSY where POSIX would succeed. A short
+// bounded retry clears virtually all of these so persistence degrades gracefully.
+const TRANSIENT_LOCK_CODES = new Set(['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY']);
+async function renameWithRetry(oldPath, newPath, retries = 3, delayMs = 120) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fs.rename(oldPath, newPath);
+    } catch (err) {
+      if (!TRANSIENT_LOCK_CODES.has(err.code) || attempt >= retries) {
+        throw err;
+      }
+      await new Promise((resolve) => setTimeout(resolve, delayMs * (attempt + 1)));
+    }
+  }
+}
+
 // Constants
 const SESSION_STATE_VERSION = '1.2';
 const SESSION_STATE_FILENAME = '.session-state.yaml';
@@ -729,7 +746,7 @@ O que você quer fazer?
       for (const file of stateFiles) {
         const oldPath = path.join(this.legacyStatePath, file);
         const newPath = path.join(this.legacyStatePath, `${file}.migrated`);
-        await fs.rename(oldPath, newPath);
+        await renameWithRetry(oldPath, newPath);
       }
 
       if (this.options.debug) {
@@ -775,7 +792,7 @@ O que você quer fazer?
     if (await this.exists()) {
       // Archive instead of delete
       const archivePath = `${this.stateFilePath}.discarded.${Date.now()}`;
-      await fs.rename(this.stateFilePath, archivePath);
+      await renameWithRetry(this.stateFilePath, archivePath);
 
       if (this.options.debug) {
         console.log(`[SessionState] Session archived to: ${archivePath}`);

package/.sinapse-ai/core/orchestration/terminal-spawner.js

@@ -396,6 +396,25 @@ async function spawnInline(agent, task, options = {}) {
       });
     }, opts.timeout);
 
+    // Handle spawn failure (e.g. bash absent on Windows without Git Bash/WSL).
+    // Without an 'error' listener Node throws ENOENT as an uncaughtException and
+    // this Promise would never resolve (hang). pm.sh requires bash by design.
+    child.on('error', (err) => {
+      clearTimeout(timeoutId);
+      if (contextPath) {
+        fs.unlink(contextPath).catch(() => {});
+      }
+      resolve({
+        success: false,
+        output: '',
+        outputFile: '',
+        duration: Date.now() - startTime,
+        error: err.code === 'ENOENT'
+          ? 'bash nao encontrado (instale Git Bash ou WSL no Windows)'
+          : err.message,
+      });
+    });
+
     // Handle process completion
     child.on('close', async (code) => {
       clearTimeout(timeoutId);
@@ -772,7 +791,11 @@ function getSystemInfo() {
   // Get Docker version
   let dockerVersion = 'not installed';
   try {
-    dockerVersion = execSync('docker --version 2>/dev/null', { encoding: 'utf8' }).trim();
+    dockerVersion = execSync('docker --version', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    }).trim();
   } catch {
     // Docker not available
   }

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

@@ -43,6 +43,29 @@ const DEFAULT_TIMEOUT_MS = 7200000; // 2 hours
 const CHECKPOINT_TIMEOUT_MS = 1800000; // 30 minutes
 const STATE_SAVE_INTERVAL_MS = 300000; // 5 minutes
 
+/**
+ * Determines whether a REAL visual-terminal spawn can occur in the current environment.
+ *
+ * Combines the platform-support signal (`isSpawnerAvailable()`) with the stricter
+ * real-terminal signal (`detectEnvironment().supportsVisualTerminal`). The latter returns
+ * `false` in headless contexts (CI / SSH / Docker / VS Code integrated terminal) and `true`
+ * only in a native terminal. Without this second check, `isSpawnerAvailable()` alone returns
+ * `true` on CI / Windows-without-bash, causing `spawn('bash', [pm.sh])` to fail with ENOENT
+ * (test noise) plus a slow subprocess. When this returns `false`, phases skip the spawn and
+ * fall through to their existing "manual execution" fallback — no bash, no noise.
+ *
+ * Note: this intentionally does NOT change `TerminalSpawner.isSpawnerAvailable()` semantics
+ * (Conservative Default — Article XI); the hardening lives at the call-sites only.
+ *
+ * @returns {boolean} True only when a native visual terminal spawn is safe to attempt.
+ */
+function canSpawnVisualTerminal() {
+  return (
+    TerminalSpawner.isSpawnerAvailable() &&
+    TerminalSpawner.detectEnvironment().supportsVisualTerminal
+  );
+}
+
 /**
  * Workflow phase status
  * @enum {string}
@@ -450,6 +473,82 @@ class WorkflowExecutor {
     };
   }
 
+  /**
+   * Loads and validates an arbitrary workflow definition by path and returns it
+   * as a structured handoff for the agent-driven steps it describes.
+   *
+   * This is the GENERIC counterpart to {@link WorkflowExecutor#execute}, which is
+   * specialized for the development-cycle (it reads story metadata and runs the
+   * six hardcoded dev-cycle phases in-process). Handlers that drive multi-agent
+   * workflows — e.g. the brownfield/greenfield handlers running
+   * brownfield-discovery.yaml — use this entry point; the per-step work is then
+   * carried out by the spawned agents the workflow assigns (orchestrate-then-handoff).
+   *
+   * Validation is REAL: a missing path, a missing file, malformed YAML, or an
+   * empty definition each surface as an honest `{ success: false, error }`. The
+   * method never fabricates step output.
+   *
+   * @param {string} workflowPath - Absolute path to the workflow YAML
+   * @param {Object} [options] - Execution context
+   * @param {string} [options.projectRoot] - Project root (defaults to this.projectRoot)
+   * @param {Object} [options.techStack] - Detected tech stack threaded into the returned context
+   * @returns {Promise<Object>} `{ success, workflowPath, workflow, steps, context }`
+   *   on success, or `{ success: false, error }` on a validation failure.
+   */
+  async executeWorkflow(workflowPath, options = {}) {
+    if (!workflowPath || typeof workflowPath !== 'string') {
+      return { success: false, error: 'workflowPath is required and must be a string' };
+    }
+
+    if (!fsSync.existsSync(workflowPath)) {
+      return { success: false, error: `Workflow file not found: ${workflowPath}` };
+    }
+
+    let definition;
+    try {
+      const content = await fs.readFile(workflowPath, 'utf8');
+      definition = yaml.load(content);
+    } catch (error) {
+      return { success: false, error: `Failed to parse workflow ${workflowPath}: ${error.message}` };
+    }
+
+    const workflow = definition && definition.workflow ? definition.workflow : definition;
+    if (!workflow || typeof workflow !== 'object') {
+      return { success: false, error: `Workflow definition is empty: ${workflowPath}` };
+    }
+
+    return {
+      success: true,
+      workflowPath,
+      workflow,
+      steps: WorkflowExecutor._extractStepIds(workflow),
+      context: {
+        projectRoot: options.projectRoot || this.projectRoot,
+        techStack: options.techStack || {},
+      },
+    };
+  }
+
+  /**
+   * Extracts ordered step identifiers from a workflow definition that may model
+   * its steps as a `sequence` list (brownfield/greenfield workflows) or a
+   * `phases` object map (development-cycle).
+   * @param {Object} workflow - The `workflow` node of a parsed definition
+   * @returns {string[]} Ordered step identifiers (empty array when none declared)
+   * @private
+   */
+  static _extractStepIds(workflow) {
+    if (workflow && Array.isArray(workflow.sequence)) {
+      return workflow.sequence.map(
+        (step, index) => (step && (step.step || step.id || step.name)) || `step_${index + 1}`,
+      );
+    }
+    if (workflow && workflow.phases && typeof workflow.phases === 'object') {
+      return Object.keys(workflow.phases);
+    }
+    return [];
+  }
+
   /**
    * Executes a single workflow phase
    * @param {string} phaseId - Phase identifier
@@ -641,7 +740,7 @@ class WorkflowExecutor {
       }
 
       // Use terminal spawning (Story 11.2)
-      if (phase.spawn_in_terminal && TerminalSpawner.isSpawnerAvailable()) {
+      if (phase.spawn_in_terminal && canSpawnVisualTerminal()) {
         const context = {
           story: storyPath,
           files: [],
@@ -958,7 +1057,7 @@ class WorkflowExecutor {
       this._emitAgentSpawn(agent, 'quality_gate');
 
       // Use terminal spawning
-      if (phase.spawn_in_terminal && TerminalSpawner.isSpawnerAvailable()) {
+      if (phase.spawn_in_terminal && canSpawnVisualTerminal()) {
         const context = {
           story: storyPath,
           files: [],
@@ -1028,7 +1127,7 @@ class WorkflowExecutor {
       this._emitAgentSpawn(agent, 'push');
 
       // Use terminal spawning
-      if (phase.spawn_in_terminal && TerminalSpawner.isSpawnerAvailable()) {
+      if (phase.spawn_in_terminal && canSpawnVisualTerminal()) {
         const context = {
           story: storyPath,
           files: [],

package/.sinapse-ai/core/quality-gates/focus-area-recommender.js

@@ -124,13 +124,15 @@ class FocusAreaRecommender {
 
     for (const file of changedFiles.slice(0, 20)) {
       try {
-        // Count commits touching this file in last 30 days
-        const commitCount = execSync(
-          `git log --oneline --since="30 days ago" -- "${file}" 2>/dev/null | wc -l`,
-          { encoding: 'utf8', timeout: 5000 },
-        ).trim();
+        // Count commits touching this file in last 30 days. No shell pipe
+        // (wc -l / 2>/dev/null) — those fail on Windows cmd; count lines in JS
+        // and suppress stderr via stdio so it stays cross-platform.
+        const commitOut = execSync(
+          `git log --oneline --since="30 days ago" -- "${file}"`,
+          { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] },
+        );
 
-        const count = parseInt(commitCount, 10) || 0;
+        const count = commitOut.split('\n').filter(Boolean).length;
 
         if (count >= 5) {
           insights.hotspots.push({
@@ -140,11 +142,13 @@ class FocusAreaRecommender {
           });
         }
 
-        // Get unique contributors for this file
-        const authors = execSync(
-          `git log --format="%aN" --since="30 days ago" -- "${file}" 2>/dev/null | sort -u`,
-          { encoding: 'utf8', timeout: 5000 },
-        ).trim().split('\n').filter(Boolean);
+        // Get unique contributors for this file. Dedup in JS via Set instead of
+        // a `| sort -u` shell pipe (unavailable on Windows cmd).
+        const authorsOut = execSync(
+          `git log --format="%aN" --since="30 days ago" -- "${file}"`,
+          { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] },
+        );
+        const authors = [...new Set(authorsOut.split('\n').map((s) => s.trim()).filter(Boolean))];
 
         for (const author of authors) {
           insights.contributors.set(author, (insights.contributors.get(author) || 0) + 1);

package/.sinapse-ai/core/registry/build-registry.js

@@ -23,8 +23,9 @@ const SCAN_SOURCES = [
     category: 'task',
     taskFormat: 'TASK-FORMAT-V1',
     subcategoryExtractor: (filePath) => {
-      const parts = filePath.split('/');
-      const filename = parts[parts.length - 1];
+      // path.basename is OS-agnostic; a raw glob result on Windows uses '\\',
+      // so split('/') would return the whole path and corrupt the subcategory.
+      const filename = path.basename(filePath);
       // Extract agent prefix (e.g., dev-, qa-, po-)
       const prefixMatch = filename.match(/^([a-z]+)-/);
       if (prefixMatch) {

package/.sinapse-ai/core/synapse/scripts/generate-constitution.js

@@ -20,6 +20,7 @@ const path = require('path');
 const ROMAN_TO_ARABIC = {
   'I': 1, 'II': 2, 'III': 3, 'IV': 4, 'V': 5,
   'VI': 6, 'VII': 7, 'VIII': 8, 'IX': 9, 'X': 10,
+  'XI': 11,
 };
 
 /**

package/.sinapse-ai/core/synapse/utils/atomic-write.js

@@ -22,6 +22,28 @@ const path = require('path');
 
 const IS_WINDOWS = process.platform === 'win32';
 
+// On Windows the AV scanner, Windows Search indexer, or a concurrent reader can
+// hold a transient lock on the target, making unlink/rename throw EPERM/EBUSY
+// where POSIX would succeed. A short bounded retry clears virtually all of these.
+const TRANSIENT_LOCK_CODES = new Set(['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY']);
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function retrySync(fn, retries = 3, delayMs = 120) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return fn();
+    } catch (err) {
+      if (!TRANSIENT_LOCK_CODES.has(err.code) || attempt >= retries) {
+        throw err;
+      }
+      sleepSync(delayMs * (attempt + 1));
+    }
+  }
+}
+
 /**
  * Write data to a file atomically.
  *
@@ -49,18 +71,20 @@ function atomicWriteSync(filePath, data, encoding = 'utf8') {
 
     // Step 2: On Windows, unlink target first (rename won't overwrite)
     if (IS_WINDOWS) {
-      try {
-        fs.unlinkSync(filePath);
-      } catch (err) {
-        if (err.code !== 'ENOENT') {
-          throw err;
+      retrySync(() => {
+        try {
+          fs.unlinkSync(filePath);
+        } catch (err) {
+          if (err.code !== 'ENOENT') {
+            throw err;
+          }
+          // ENOENT = target doesn't exist yet, that's fine
         }
-        // ENOENT = target doesn't exist yet, that's fine
-      }
+      });
     }
 
-    // Step 3: Atomic rename
-    fs.renameSync(tmpPath, filePath);
+    // Step 3: Atomic rename (retried for transient Windows locks)
+    retrySync(() => fs.renameSync(tmpPath, filePath));
   } catch (error) {
     // Clean up tmp file on failure
     try {
@@ -76,5 +100,6 @@ function atomicWriteSync(filePath, data, encoding = 'utf8') {
 
 module.exports = {
   atomicWriteSync,
+  retrySync,
 };
 

package/.sinapse-ai/core-config.yaml

@@ -310,7 +310,11 @@ ideSync:
       enabled: false
       path: .codex/agents
       format: full-markdown-yaml
-  redirects: {}
+  redirects:
+    # Master alias: o id-fonte canônico é snps-orqx; sinapse-orqx aponta para ele
+    # no espelho de dogfood (.claude/). No install o command-generator gera ambos
+    # como entry points full do Imperator — isto cobre só a paridade do repo.
+    sinapse-orqx: snps-orqx
   validation:
     strictMode: true
     failOnDrift: true

package/.sinapse-ai/data/capability-detection.js

@@ -26,7 +26,7 @@ function detectToolSearch() {
   // Check Claude Code cached features for tool search availability
   const claudeJsonPath = path.join(os.homedir(), '.claude.json');
   try {
-    const config = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8'));
+    const config = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8').replace(/^\uFEFF/, ''));
     const features = config.cachedGrowthBookFeatures || {};
     return {
       available: features.tengu_mcp_tool_search === true,
@@ -54,7 +54,7 @@ function detectDeferLoading() {
 function detectProjectMcps() {
   const mcpJsonPath = path.join(PROJECT_ROOT, '.mcp.json');
   try {
-    const config = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf8'));
+    const config = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf8').replace(/^\uFEFF/, ''));
     const servers = config.mcpServers || {};
     return Object.entries(servers).map(([name, cfg]) => ({
       name,
@@ -96,7 +96,7 @@ function detectGlobalMcps() {
   // Detection: check ~/.claude/settings.json or known conventions
   const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
   try {
-    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8').replace(/^\uFEFF/, ''));
     if (settings.mcpServers) {
       for (const [name, cfg] of Object.entries(settings.mcpServers)) {
         servers.push({