sinapse-ai 1.7.0 → 1.8.0

package/.sinapse-ai/development/tasks/github-devops-pre-push-quality-gate.md

@@ -318,45 +318,64 @@ If conflicts detected, fail with message:
 Resolve conflicts before pushing.
 ```
 
-### 4. Run npm run lint (if script exists)
+### 4. Run Layer 1 Quality Gate (lint + test + typecheck) — CANONICAL
 
-```javascript
-function runNpmScript(scriptName, projectRoot) {
-  const packageJsonPath = path.join(projectRoot, 'package.json');
-  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+> **Do NOT reimplement lint/test/typecheck here.** The framework already ships
+> the canonical Layer 1 pre-commit gate (`core/quality-gates/layer1-precommit.js`),
+> exposed via the CLI. Calling it keeps a single source of truth for the quality
+> checks (Constitution Art. I — CLI First) instead of forking the logic.
 
-  if (!packageJson.scripts || !packageJson.scripts[scriptName]) {
-    console.log(`⚠️  Script "${scriptName}" not found - skipping`);
-    return { skipped: true };
-  }
+```bash
+sinapse qa run --layer=1
+```
 
+Layer 1 runs **lint (ESLint), unit tests (Jest), and typecheck** — fast local
+checks — and gracefully skips any check whose npm script is absent. Exit code:
+`0` = PASS, non-zero = FAIL.
+
+```javascript
+const { execSync } = require('child_process');
+
+function runLayer1QualityGate(projectRoot) {
   try {
-    execSync(`npm run ${scriptName}`, {
-      cwd: projectRoot,
-      stdio: 'inherit'
-    });
-    console.log(`✓ ${scriptName} PASSED`);
+    // The canonical 3-check Layer 1 gate. stdio:'inherit' streams its report.
+    execSync('sinapse qa run --layer=1', { cwd: projectRoot, stdio: 'inherit' });
+    console.log('✓ Layer 1 (lint + test + typecheck) PASSED');
     return { passed: true };
   } catch (error) {
-    console.error(`❌ ${scriptName} FAILED`);
+    console.error('❌ Layer 1 quality gate FAILED');
     return { passed: false, error };
   }
 }
 ```
 
-### 5. Run npm test (if script exists)
+### 5. Run npm run build (if script exists)
 
-Same logic as lint, but for `npm test`.
+Build is outside Layer 1's scope (Layer 1 is the fast lint/test/typecheck pass),
+so it stays a separate step. Skips gracefully when the `build` script is absent.
 
-### 6. Run npm run typecheck (if script exists)
-
-Same logic as lint, but for `npm run typecheck`.
+```javascript
+function runBuild(projectRoot) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
 
-### 7. Run npm run build (if script exists)
+  if (!packageJson.scripts || !packageJson.scripts.build) {
+    console.log('⚠️  Script "build" not found - skipping');
+    return { skipped: true };
+  }
 
-Same logic as lint, but for `npm run build`.
+  try {
+    execSync('npm run build', { cwd: projectRoot, stdio: 'inherit' });
+    console.log('✓ build PASSED');
+    return { passed: true };
+  } catch (error) {
+    console.error('❌ build FAILED');
+    return { passed: false, error };
+  }
+}
+```
 
-### 8. Run CodeRabbit CLI Review (TR-3.14.12)
+### 6. Run CodeRabbit CLI Review (TR-3.14.12)
 
 ```javascript
 const { execSync } = require('child_process');
@@ -503,7 +522,7 @@ if (coderabbitResult.gateImpact === 'CONCERNS') {
 }
 ```
 
-### 9. Run Security Scan (TR-3.14.11)
+### 7. Run Security Scan (TR-3.14.11)
 
 ```javascript
 const { execSync } = require('child_process');
@@ -630,7 +649,7 @@ function determineSecurityGate(results) {
 }
 ```
 
-### 9.1 Impact Analysis (Code Intelligence — Advisory Only)
+### 7.1 Impact Analysis (Code Intelligence — Advisory Only)
 
 > **Added by:** Story NOG-7 (DevOps Pre-Push Impact Analysis)
 > **Behavior:** Advisory only — NEVER blocks push. Auto-skips if code intelligence unavailable.
@@ -688,7 +707,7 @@ Impact Analysis:
 
 ---
 
-### 10. Verify Story Status (Optional - if using story-driven workflow)
+### 8. Verify Story Status (Optional - if using story-driven workflow)
 
 ```javascript
 function checkStoryStatus(storyPath) {
@@ -735,9 +754,7 @@ Mode:        {framework-development | project-development}
 Quality Checks:
   ✓ No uncommitted changes
   ✓ No merge conflicts
-  ✓ npm run lint         PASSED
-  ✓ npm test             PASSED
-  ✓ npm run typecheck    PASSED
+  ✓ Layer 1 (lint+test+typecheck)  PASSED   (via `sinapse qa run --layer=1`)
   ✓ npm run build        PASSED
   ✓ Security scan        PASSED
   ⚠️ Story status         SKIPPED (no story file)

package/.sinapse-ai/development/tasks/update-sinapse.md

@@ -1,11 +1,11 @@
 # Task: Update SINAPSE Framework
 
-> **Version:** 4.0.0
+> **Version:** 5.2.0
 > **Created:** 2026-01-29
-> **Updated:** 2026-01-31
+> **Updated:** 2026-06-15
 > **Type:** SYNC (git-native framework synchronization)
 > **Agent:** @devops (Pipeline) or @sinapse (Orion)
-> **Execution:** Simple bash script (~15 lines)
+> **Execution:** Bash script (~150 lines)
 
 ## Purpose
 

package/.sinapse-ai/hooks/sinapse-brand-grounding.cjs

@@ -39,15 +39,12 @@ function readStdin() {
   });
 }
 
+// Story 10.47: delegate to the shared grounding config loader instead of
+// duplicating the read+parse. The require is guarded so the hook stays
+// fail-open even if the shared module is somehow absent at runtime.
 function loadConfig() {
   try {
-    if (!fs.existsSync(CONFIG_PATH)) return null;
-    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
-    let yaml;
-    try { yaml = require('js-yaml'); } catch { return null; }
-    const parsed = yaml.load(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
-    return parsed;
+    return require('../core/grounding/config-loader.cjs').loadGroundingConfig(CONFIG_PATH);
   } catch {
     return null;
   }

package/.sinapse-ai/hooks/sinapse-ds-grounding.cjs

@@ -66,15 +66,12 @@ function readStdin() {
   });
 }
 
+// Story 10.47: delegate to the shared grounding config loader instead of
+// duplicating the read+parse. The require is guarded so the hook stays
+// fail-open even if the shared module is somehow absent at runtime.
 function loadConfig() {
   try {
-    if (!fs.existsSync(CONFIG_PATH)) return null;
-    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
-    let yaml;
-    try { yaml = require('js-yaml'); } catch { return null; }
-    const parsed = yaml.load(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
-    return parsed;
+    return require('../core/grounding/config-loader.cjs').loadGroundingConfig(CONFIG_PATH);
   } catch {
     return null;
   }

package/.sinapse-ai/hooks/sinapse-vault-grounding.cjs

@@ -54,15 +54,12 @@ function readStdin() {
   });
 }
 
+// Story 10.47: delegate to the shared grounding config loader instead of
+// duplicating the read+parse. The require is guarded so the hook stays
+// fail-open even if the shared module is somehow absent at runtime.
 function loadConfig() {
   try {
-    if (!fs.existsSync(CONFIG_PATH)) return null;
-    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
-    let yaml;
-    try { yaml = require('js-yaml'); } catch { return null; }
-    const parsed = yaml.load(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
-    return parsed;
+    return require('../core/grounding/config-loader.cjs').loadGroundingConfig(CONFIG_PATH);
   } catch {
     return null;
   }

package/.sinapse-ai/infrastructure/integrations/ai-providers/ai-provider-factory.js

@@ -42,7 +42,10 @@ const DEFAULT_CONFIG = {
     },
   },
   claude: {
-    model: 'claude-3-5-sonnet',
+    // No hardcoded model: stale IDs get rejected by the CLI ("model may not
+    // exist"). null → omit --model and use the user's CLI default, which is
+    // always a valid, current model.
+    model: null,
     timeout: 300000,
     dangerouslySkipPermissions: false,
   },

package/.sinapse-ai/infrastructure/integrations/ai-providers/claude-provider.js

@@ -7,8 +7,11 @@
  * @see Epic GEMINI-INT - Story 2: AI Provider Factory Pattern
  */
 
-const { spawn, execSync } = require('child_process');
+const { execSync } = require('child_process');
 const { AIProvider } = require('./ai-provider');
+// runSafe (cross-spawn): resolves claude.cmd on Windows and delivers the prompt
+// via stdin/argv — same hardened spawn path used by the SubagentDispatcher.
+const { runSafe } = require('../../../core/utils/spawn-safe');
 
 /**
  * Claude Code provider implementation
@@ -20,7 +23,7 @@ class ClaudeProvider extends AIProvider {
   /**
    * Create a Claude provider
    * @param {Object} [config={}] - Provider configuration
-   * @param {string} [config.model='claude-3-5-sonnet'] - Model to use
+   * @param {string} [config.model] - Model override; omitted → CLI default model
    * @param {number} [config.timeout=300000] - Execution timeout
    * @param {boolean} [config.dangerouslySkipPermissions=false] - Skip permission prompts
    */
@@ -31,7 +34,9 @@ class ClaudeProvider extends AIProvider {
       timeout: config.timeout || 300000,
       maxRetries: config.maxRetries || 3,
       options: {
-        model: config.model || 'claude-3-5-sonnet',
+        // No hardcoded model: stale IDs break the CLI. Only pass --model when
+        // a caller explicitly configures one; otherwise use the CLI's default.
+        model: config.model || null,
         dangerouslySkipPermissions: config.dangerouslySkipPermissions || false,
         ...config,
       },
@@ -82,59 +87,56 @@ class ClaudeProvider extends AIProvider {
       args.push('--model', options.model || this.options.model);
     }
 
-    return new Promise((resolve, reject) => {
-      let stdout = '';
-      let stderr = '';
-
-      // Spawn claude directly without shell interpolation (safer)
-      const child = spawn(this.command, args, {
-        cwd: workingDir,
-        env: { ...process.env, ...options.env },
-        windowsHide: true,
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-
-      // Write prompt via stdin to avoid shell injection
-      child.stdin.write(prompt);
-      child.stdin.end();
-
-      const timeoutId = setTimeout(() => {
-        child.kill('SIGTERM');
-        reject(new Error(`Claude execution timed out after ${timeout}ms`));
-      }, timeout);
-
-      child.stdout.on('data', (data) => {
-        stdout += data.toString();
-      });
-
-      child.stderr.on('data', (data) => {
-        stderr += data.toString();
-      });
-
-      child.on('close', (code) => {
-        clearTimeout(timeoutId);
-        const duration = Date.now() - startTime;
-
-        if (code === 0) {
-          resolve({
-            success: true,
-            output: stdout.trim(),
-            metadata: {
-              duration,
-              provider: 'claude',
-              model: options.model || this.options.model,
-            },
-          });
-        } else {
-          reject(new Error(`Claude exited with code ${code}: ${stderr || stdout}`));
-        }
-      });
-
-      child.on('error', (error) => {
-        clearTimeout(timeoutId);
-        reject(new Error(`Claude spawn error: ${error.message}`));
-      });
+    // runSafe: argv-based spawn via cross-spawn (resolves claude.cmd on Windows),
+    // prompt delivered through stdin — shell injection structurally impossible.
+    const result = await runSafe(this.command, args, {
+      cwd: workingDir,
+      env: { ...process.env, ...options.env },
+      timeout,
+      input: prompt,
     });
+
+    const duration = Date.now() - startTime;
+
+    const stdout = (result.stdout || '').trim();
+    const stderr = (result.stderr || '').trim();
+
+    if (result.success) {
+      return {
+        success: true,
+        output: stdout,
+        metadata: {
+          duration,
+          provider: 'claude',
+          model: options.model || this.options.model || 'cli-default',
+        },
+      };
+    }
+
+    if (result.signal) {
+      throw new Error(
+        `Claude killed by signal ${result.signal} (timeout ${timeout}ms?): ${stderr || stdout}`,
+      );
+    }
+
+    // User-environment hooks (SessionEnd etc.) can fail AFTER the model already
+    // printed its full response, poisoning the exit code. In --print mode a
+    // non-empty stdout + hook-related stderr means the work was done — accept it
+    // (with a warning) instead of discarding paid output and retrying.
+    if (stdout.length > 0 && /hook/i.test(stderr)) {
+      return {
+        success: true,
+        output: stdout,
+        metadata: {
+          duration,
+          provider: 'claude',
+          model: options.model || this.options.model || 'cli-default',
+          warning: `non-zero exit (${result.code}) caused by environment hook failure: ${stderr.slice(0, 200)}`,
+        },
+      };
+    }
+
+    throw new Error(`Claude exited with code ${result.code}: ${stderr || stdout}`);
   }
 
   /**

package/.sinapse-ai/infrastructure/scripts/ide-sync/gemini-commands.js

@@ -0,0 +1,298 @@
+'use strict';
+
+/**
+ * Gemini Commands Sync — generates .gemini/commands/*.toml from parsed agent data.
+ *
+ * Writes one TOML file per agent plus a sinapse-menu.toml launcher.
+ * Called by index.js after agents are parsed; the index.js caller is responsible
+ * for registering this as the Gemini IDE target handler.
+ *
+ * @story 5.1 - IDE Sync Expansion
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+const FALLBACK_DESCRIPTION = 'Agente especializado SINAPSE';
+const MAX_DESCRIPTION_CONTEXT = 120;
+
+const MENU_ORDER = [
+  'sinapse-orqx',
+  'analyst',
+  'architect',
+  'data-engineer',
+  'developer',
+  'devops',
+  'project-lead',
+  'product-lead',
+  'quality-gate',
+  'sprint-lead',
+  'squad-creator',
+  'ux-design-expert',
+];
+
+/**
+ * Strip the sinapse- prefix so the slug is short and readable.
+ * @param {string} agentId
+ * @returns {string}
+ */
+function commandSlugForAgent(agentId) {
+  if (agentId.startsWith('sinapse-')) {
+    return agentId.replace(/^sinapse-/, '');
+  }
+  return agentId;
+}
+
+/**
+ * Return the Gemini slash-command name for an agent.
+ * Example: "developer" → "/sinapse-developer"
+ * @param {string} agentId
+ * @returns {string}
+ */
+function menuCommandName(agentId) {
+  return `/sinapse-${commandSlugForAgent(agentId)}`;
+}
+
+/**
+ * Collapse internal whitespace and trim.
+ * @param {string} text
+ * @returns {string}
+ */
+function normalizeText(text) {
+  if (!text || typeof text !== 'string') return '';
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Truncate to maxLen characters with an ellipsis.
+ * @param {string} text
+ * @param {number} [maxLen]
+ * @returns {string}
+ */
+function truncateText(text, maxLen = MAX_DESCRIPTION_CONTEXT) {
+  if (!text || text.length <= maxLen) return text;
+  return `${text.slice(0, maxLen - 1).trimEnd()}…`;
+}
+
+/**
+ * Extract a concise one-liner from a whenToUse block.
+ * Drops redirect/negative-guidance sections before truncating.
+ * @param {string} whenToUse
+ * @returns {string}
+ */
+function summarizeWhenToUse(whenToUse) {
+  const normalized = normalizeText(whenToUse);
+  if (!normalized) return '';
+
+  // Drop redirect/negative guidance sections that are useful for routing, not for menu labels.
+  const withoutNegativeSection = normalized.split(/\b(?:NOT\s+for|NÃO\s+para)\b/i)[0].trim();
+  const primary = withoutNegativeSection || normalized;
+
+  // Keep only the first sentence/chunk for concise autocomplete labels.
+  const firstChunk = primary.split(/[.;!?](?:\s|$)/)[0].trim();
+  return truncateText(firstChunk || primary);
+}
+
+/**
+ * Escape a string for embedding inside a TOML double-quoted scalar.
+ * @param {string} text
+ * @returns {string}
+ */
+function escapeTomlString(text) {
+  return String(text || '').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Build a human-readable one-liner description for an agent entry.
+ * Prefers title + whenToUse summary; falls back to SINAPSE generic.
+ * @param {object} agent - Parsed agent object from agent-parser
+ * @returns {string}
+ */
+function buildAgentDescription(agent) {
+  const agentData = agent.agent || {};
+  const title = normalizeText(agentData.title);
+  const whenToUseSummary = summarizeWhenToUse(agentData.whenToUse);
+
+  if (title && whenToUseSummary) {
+    return `${title} (${whenToUseSummary})`;
+  }
+  if (title) {
+    return title;
+  }
+  if (whenToUseSummary) {
+    return whenToUseSummary;
+  }
+  return `Ativar agente SINAPSE ${agent.id}`;
+}
+
+/**
+ * Build the activation prompt stored in each agent's TOML file.
+ * References the agent definition at .gemini/rules/SINAPSE/agents/{id}.md.
+ * @param {string} agentId
+ * @returns {string}
+ */
+function buildAgentCommandPrompt(agentId) {
+  return [
+    `Ative o agente ${agentId}:`,
+    `1. Leia a definição completa em .gemini/rules/SINAPSE/agents/${agentId}.md`,
+    '2. Siga as activation-instructions do bloco YAML',
+    `3. Renderize o greeting via: node .sinapse-ai/development/scripts/generate-greeting.js ${agentId}`,
+    '   Se shell nao disponivel, exiba o greeting de persona_profile.communication.greeting_levels.named',
+    '4. Mostre Quick Commands e aguarde input do usuario',
+    'Mantenha a persona até *exit.',
+  ].join('\n');
+}
+
+/**
+ * Build the TOML content for a single agent command file.
+ * @param {string} agentId
+ * @param {string} [description]
+ * @returns {{ filename: string, content: string, agentId: string, description: string }}
+ */
+function buildAgentCommandFile(agentId, description = FALLBACK_DESCRIPTION) {
+  const slug = commandSlugForAgent(agentId);
+
+  const prompt = buildAgentCommandPrompt(agentId);
+  const content = [
+    `description = "${escapeTomlString(description)}"`,
+    'prompt = """',
+    prompt,
+    '"""',
+    '',
+  ].join('\n');
+
+  return {
+    filename: `sinapse-${slug}.toml`,
+    content,
+    agentId,
+    description,
+  };
+}
+
+/**
+ * Build the multi-line prompt that lists all agents in the launcher menu.
+ * @param {Array<{ agentId: string, description: string }>} commandFiles
+ * @returns {string}
+ */
+function buildMenuPrompt(commandFiles) {
+  const lines = [
+    'Você está no launcher SINAPSE para Gemini.',
+    '',
+    'Mostre a lista de agentes abaixo em formato numerado, explicando em 1 linha quando usar cada um:',
+  ];
+
+  let index = 1;
+  for (const commandFile of commandFiles) {
+    lines.push(`${index}. ${menuCommandName(commandFile.agentId)} - ${commandFile.description}`);
+    index += 1;
+  }
+
+  lines.push('');
+  lines.push('No final, peça para o usuário escolher um número ou digitar o comando direto.');
+  return lines.join('\n');
+}
+
+/**
+ * Build the sinapse-menu.toml launcher file that lists all agents.
+ * @param {Array<{ agentId: string, description: string }>} commandFiles
+ * @returns {{ filename: string, content: string }}
+ */
+function buildMenuCommandFile(commandFiles) {
+  const content = [
+    'description = "Menu rápido SINAPSE (lista agentes e orienta qual ativar)"',
+    'prompt = """',
+    buildMenuPrompt(commandFiles),
+    '"""',
+    '',
+  ].join('\n');
+
+  return {
+    filename: 'sinapse-menu.toml',
+    content,
+  };
+}
+
+/**
+ * Resolve the display order for agent IDs.
+ * MENU_ORDER entries come first (in declared order), extras are sorted alphabetically.
+ * @param {string[]} agentIds
+ * @returns {string[]}
+ */
+function resolveAgentOrder(agentIds) {
+  const unique = [...new Set(agentIds)];
+  const known = MENU_ORDER.filter((id) => unique.includes(id));
+  const extra = unique.filter((id) => !MENU_ORDER.includes(id)).sort();
+  return [...known, ...extra];
+}
+
+/**
+ * Build the full set of TOML command files for all valid agents.
+ * Returns an array of { filename, content, agentId, description } entries,
+ * with sinapse-menu.toml prepended as the first item.
+ * @param {object[]} agents - Array of parsed agent objects from agent-parser
+ * @returns {Array<{ filename: string, content: string, agentId: string, description: string }>}
+ */
+function buildGeminiCommandFiles(agents) {
+  const validAgents = agents
+    .filter((agent) => !agent.error)
+    .map((agent) => ({
+      id: agent.id,
+      description: buildAgentDescription(agent),
+    }));
+
+  const ordered = resolveAgentOrder(validAgents.map((agent) => agent.id));
+  const byId = new Map(validAgents.map((agent) => [agent.id, agent]));
+  const files = ordered.map((id) => {
+    const meta = byId.get(id);
+    const description = meta?.description || FALLBACK_DESCRIPTION;
+    return buildAgentCommandFile(id, description);
+  });
+  files.unshift(buildMenuCommandFile(files));
+  return files;
+}
+
+/**
+ * Write all Gemini command TOML files to {projectRoot}/.gemini/commands/.
+ * In dry-run mode the directory is not created and files are not written,
+ * but the return value still lists what would have been written.
+ * @param {object[]} agents - Parsed agents
+ * @param {string} projectRoot - Absolute path to the project root
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{ commandsDir: string, files: Array<{ filename: string, path: string, content: string }> }}
+ */
+function syncGeminiCommands(agents, projectRoot, options = {}) {
+  const commandsDir = path.join(projectRoot, '.gemini', 'commands');
+  const files = buildGeminiCommandFiles(agents);
+  const written = [];
+
+  if (!options.dryRun) {
+    fs.ensureDirSync(commandsDir);
+  }
+
+  for (const file of files) {
+    const targetPath = path.join(commandsDir, file.filename);
+    if (!options.dryRun) {
+      fs.writeFileSync(targetPath, file.content, 'utf8');
+    }
+    written.push({
+      filename: path.join('commands', file.filename),
+      path: targetPath,
+      content: file.content,
+    });
+  }
+
+  return { commandsDir, files: written };
+}
+
+module.exports = {
+  FALLBACK_DESCRIPTION,
+  MENU_ORDER,
+  commandSlugForAgent,
+  menuCommandName,
+  buildAgentDescription,
+  summarizeWhenToUse,
+  truncateText,
+  escapeTomlString,
+  buildGeminiCommandFiles,
+  syncGeminiCommands,
+};