sinapse-ai 1.19.2 → 1.20.1

package/bin/cli.js

@@ -29,6 +29,11 @@ const KNOWN_COMMANDS = [
   'ideate',
   'agents',
   'chrome-brain',
+  // Story onda2-p3 (audit AF-20260702 item 2.4) — the orchestration engine,
+  // reachable from the canonical binary users actually install.
+  'orchestrate',
+  'spec',
+  'plan',
   'help',
 ];
 const {
@@ -160,6 +165,30 @@ function runRouter() {
       cmdDoctor(doctorOpts).catch(e => { logger.error(`${RED}Erro no doctor:${NC} ${e.message}`); process.exit(1); });
       break;
     }
+    case 'orchestrate':
+    case 'spec':
+    case 'plan': {
+      // Story onda2-p3 (audit AF-20260702 item 2.4) — the orchestration engine
+      // (the one capability validated by the HYBRID verdict) was unreachable
+      // from the canonical binary: users who install as the README teaches
+      // (`npx sinapse-ai ...`) never discover bin/sinapse.js. Delegates via
+      // spawnSync to bin/sinapse.js, which owns the arg parsing — same
+      // single-source-of-truth pattern as `init` (cli→sinapse) and the
+      // S1/#321 `agents`/`ideate` delegation (sinapse→cli).
+      const { spawnSync } = require('child_process');
+      const result = spawnSync(
+        process.execPath,
+        [path.join(__dirname, 'sinapse.js'), ...args],
+        { stdio: 'inherit' },
+      );
+      if (result.error) {
+        logger.error(`${RED}Erro no ${command}:${NC} ${result.error.message}`);
+        logger.error(`Tente: ${CYAN}npx sinapse-ai ${command} --help${NC}`);
+        process.exit(1);
+      }
+      process.exit(result.status ?? 0);
+    }
+    // eslint-disable-next-line no-fallthrough -- process.exit above terminates; same pattern as `init`.
     case 'chrome-brain': {
     // Story 10.13 — chrome-brain is the canonical sub-capability for browser
     // automation. Delegating to the shared chrome-brain-installer module keeps

package/bin/commands/help.js

@@ -19,6 +19,11 @@ function cmdHelp() {
   logger.always('');
   logger.always(`  ${DIM}Funciona em CI / ambientes não-interativos (usa defaults sensatos).${NC}`);
   logger.always('');
+  logger.always(`${BOLD}Motor de orquestração (avançado — 1 story por vez):${NC}\n`);
+  logger.always(`  ${CYAN}npx sinapse-ai spec <story-id>${NC}        Gera a spec REAL de uma story (para antes de plano/build/QA)`);
+  logger.always(`  ${CYAN}npx sinapse-ai plan <story-id>${NC}        Spec + plano de implementação REAL (para antes de build/QA)`);
+  logger.always(`  ${CYAN}npx sinapse-ai orchestrate <story-id>${NC} Pipeline completo de 1 story (${DIM}--dry-run pra prever${NC})`);
+  logger.always('');
   logger.always(`${BOLD}Diagnóstico:${NC}\n`);
   logger.always(`  ${CYAN}npx sinapse-ai status${NC}           Mostra estado da instalação`);
   logger.always(`  ${CYAN}npx sinapse-ai doctor${NC}           Roda health checks (--fix --dry-run --json --deep)`);

package/bin/commands/install.js

@@ -27,6 +27,7 @@ const {
   copyDirSync,
   rmDirSync,
   syncDirSync,
+  atomicWriteFileSync,
   toForwardSlash,
 } = require('../lib/fs-utils');
 const {
@@ -112,7 +113,7 @@ async function cmdInstallGlobal(opts = {}) {
     }
     if (!parseFailed) {
       settings.language = language === 'pt' ? 'portuguese' : 'english';
-      fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + '\n');
+      atomicWriteFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + '\n');
     }
   } catch { /* non-critical */ }
 
@@ -587,7 +588,7 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
   if (isUpsert) {
     meta.updatedAt = nowIso;
   }
-  fs.writeFileSync(path.join(SINAPSE_HOME, 'metadata.json'), JSON.stringify(meta, null, 2));
+  atomicWriteFileSync(path.join(SINAPSE_HOME, 'metadata.json'), JSON.stringify(meta, null, 2));
 
   return { writtenAgents, totalAgents, totalDelta, squadsRefreshed, squadsAdded, meta };
 }
@@ -735,14 +736,14 @@ function createLauncher() {
 exec claude --add-dir "${sinapsePathForBash}" --agent sinapse-orqx "$@"
 `;
   const bashPath = path.join(BIN_DIR, 'sinapse');
-  fs.writeFileSync(bashPath, bashLauncher);
+  atomicWriteFileSync(bashPath, bashLauncher);
   try { fs.chmodSync(bashPath, 0o755); } catch { /* chmod is best-effort (no-op on non-POSIX) */ }
   logger.always(`  ${GREEN}OK${NC} ~/bin/sinapse`);
 
   // Windows CMD launcher
   if (IS_WIN) {
     const cmdLauncher = '@echo off\r\nclaude --add-dir "%USERPROFILE%\\.sinapse" --agent sinapse-orqx %*\r\n';
-    fs.writeFileSync(path.join(BIN_DIR, 'sinapse.cmd'), cmdLauncher);
+    atomicWriteFileSync(path.join(BIN_DIR, 'sinapse.cmd'), cmdLauncher);
     logger.always(`  ${GREEN}OK${NC} ~/bin/sinapse.cmd`);
   }
 }

package/bin/commands/uninstall.js

@@ -183,6 +183,11 @@ async function cmdUninstall(opts = {}) {
     [path.join(HOME, '.claude', 'commands', 'SINAPSE'), '~/.claude/commands/SINAPSE/'],
     [path.join(BIN_DIR, 'sinapse'), '~/bin/sinapse'],
     [path.join(BIN_DIR, 'sinapse.cmd'), '~/bin/sinapse.cmd'],
+    // Story onda2-p9 — project-level context-engine runtime at cwd (parity
+    // with runUninstall in bin/sinapse.js). Fully SINAPSE-generated
+    // (constitution derived from .sinapse-ai/constitution.md + sessions/
+    // metrics runtime state); regenerated by any future install.
+    [path.join(process.cwd(), '.synapse'), './.synapse/ (context engine runtime)'],
   ];
 
   for (const [p, label] of ownedItems) {

package/bin/lib/command-generator.js

@@ -11,7 +11,7 @@ const path = require('path');
 
 const { SINAPSE_HOME, CLAUDE_COMMANDS_DIR, ROOT } = require('./constants');
 const { extractAgentMeta } = require('./squads');
-const { toForwardSlash } = require('./fs-utils');
+const { toForwardSlash, atomicWriteFileSync } = require('./fs-utils');
 
 // Framework "core" agents (developer, architect, quality-gate, devops, …) live
 // OUTSIDE the squads/ tree, under .sinapse-ai/development/agents/*.md. `scripts/
@@ -239,7 +239,7 @@ function regenerateAgentCommands(deps = {}) {
       const agentId = file.replace('.md', '');
       const meta = extractAgentMeta(path.join(agentsDir, file));
       const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, squad.name, squadPath, file);
-      fs.writeFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
+      atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
       writtenAgents.add(file);
     }
   }
@@ -254,7 +254,7 @@ function regenerateAgentCommands(deps = {}) {
         const meta = extractAgentMeta(path.join(masterAgentsDir, file));
         const squadPath = `${sinapseBase}/sinapse`;
         const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, 'sinapse', squadPath, file);
-        fs.writeFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
+        atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
         writtenAgents.add(file);
       }
     }
@@ -274,7 +274,7 @@ function regenerateAgentCommands(deps = {}) {
     for (const [id, personaFile] of masterEntryPoints) {
       const personaPath = `${masterSquadPath}/agents/${personaFile}`;
       const stub = generateMasterStub(id, personaPath, masterSquadPath, squads);
-      fs.writeFileSync(path.join(commandsDir, `${id}.md`), stub);
+      atomicWriteFileSync(path.join(commandsDir, `${id}.md`), stub);
       writtenAgents.add(`${id}.md`);
     }
   }

package/bin/lib/fs-utils.js

@@ -97,6 +97,23 @@ function syncDirSync(src, dest, delta = { added: 0, updated: 0, unchanged: 0, re
   return delta;
 }
 
+// atomicWriteFileSync — Onda B2 (AF-20260703): tmp+rename via the canonical
+// core util so a crash or concurrent reader never sees a torn config file.
+// Fail-open: if the util can't be loaded, fall back to a plain write (the
+// pre-hardening behavior) rather than breaking the installer.
+let _atomicWriteSync = null;
+try {
+  _atomicWriteSync = require('../../.sinapse-ai/core/synapse/utils/atomic-write').atomicWriteSync;
+} catch { /* fallback below */ }
+
+function atomicWriteFileSync(filePath, data, encoding = 'utf8') {
+  if (_atomicWriteSync) {
+    _atomicWriteSync(filePath, data, encoding);
+  } else {
+    fs.writeFileSync(filePath, data, encoding);
+  }
+}
+
 function toForwardSlash(p) {
   return p.replace(/\\/g, '/');
 }
@@ -112,6 +129,7 @@ module.exports = {
   copyDirSync,
   rmDirSync,
   syncDirSync,
+  atomicWriteFileSync,
   toForwardSlash,
   toPosixPath,
 };

package/bin/lib/setup-statusline.js

@@ -30,6 +30,7 @@
 const os = require('os');
 const path = require('path');
 const fse = require('fs-extra');
+const { atomicWriteFileSync } = require('./fs-utils');
 
 /**
  * Resolve the canonical source paths for the statusline templates.
@@ -182,7 +183,8 @@ async function setupStatusline(opts = {}) {
     }
 
     await fse.ensureDir(path.dirname(globalSettingsPath));
-    await fse.writeFile(globalSettingsPath, JSON.stringify(settings, null, 2), 'utf8');
+    // Atomic (tmp+rename): a crash mid-write must never leave a torn settings.json
+    atomicWriteFileSync(globalSettingsPath, JSON.stringify(settings, null, 2), 'utf8');
 
     result.installed = true;
     return result;

package/bin/modules/chrome-brain-installer.js

@@ -12,6 +12,7 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 const { execSync } = require('child_process');
+const { atomicWriteFileSync } = require('../lib/fs-utils');
 
 // ============================================================================
 // Constants
@@ -134,7 +135,8 @@ function readJson(filePath) {
 function writeJson(filePath, data) {
   const dir = path.dirname(filePath);
   fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  // Atomic (tmp+rename): these are user config files (settings.json, .mcp.json)
+  atomicWriteFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
 }
 
 function mergeHooks(settingsPath, hookDefs) {
@@ -432,7 +434,7 @@ function createMinimalKB() {
   fs.mkdirSync(kbDir, { recursive: true });
   const kbPath = path.join(kbDir, 'chrome-brain.md');
   if (!fs.existsSync(kbPath)) {
-    fs.writeFileSync(kbPath, [
+    atomicWriteFileSync(kbPath, [
       '# Chrome Brain — Browser Automation Capability',
       '',
       '> Cross-squad capability for browser automation.',
@@ -462,7 +464,7 @@ function createMinimalKB() {
   // Create claude-in-chrome.md KB (Story 7.4.2)
   const cicKbPath = path.join(kbDir, 'claude-in-chrome.md');
   if (!fs.existsSync(cicKbPath)) {
-    fs.writeFileSync(cicKbPath, [
+    atomicWriteFileSync(cicKbPath, [
       '# claude-in-chrome — Chrome Extension for Visual Browser Interaction',
       '',
       '> Manual install required. This extension cannot be auto-installed via CLI.',

package/bin/modules/mcp-installer.js

@@ -18,6 +18,7 @@ const path = require('path');
 const { exec } = require('child_process');
 const { promisify } = require('util');
 const chalk = require('chalk');
+const { atomicWriteFileSync } = require('../lib/fs-utils');
 
 const execAsync = promisify(exec);
 
@@ -322,12 +323,8 @@ async function addMCPToConfig(mcpId, config, configPath) {
   // Add new MCP config
   mcpConfig.mcpServers[mcpId] = config;
 
-  // Write updated config
-  await fse.writeFile(
-    configPath,
-    JSON.stringify(mcpConfig, null, 2) + '\n',
-    'utf8',
-  );
+  // Write updated config — atomic (tmp+rename): .mcp.json must never be torn
+  atomicWriteFileSync(configPath, JSON.stringify(mcpConfig, null, 2) + '\n', 'utf8');
 }
 
 /**

package/bin/postinstall.js

@@ -45,6 +45,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { atomicWriteFileSync } = require('./lib/fs-utils');
 
 const PROJECT_ROOT = path.resolve(__dirname, '..');
 
@@ -161,7 +162,7 @@ function markFirstRunDone() {
     }
     const flag = firstRunFlag();
     if (!fs.existsSync(flag)) {
-      fs.writeFileSync(flag, `${new Date().toISOString()}\n`, 'utf8');
+      atomicWriteFileSync(flag, `${new Date().toISOString()}\n`, 'utf8');
     }
     return true;
   } catch {
@@ -361,6 +362,13 @@ function stepCreateRuntimeDirs() {
  * UserPromptSubmit context engine actually injects rules. Without this, the
  * engine is inert (the hook silently emits no context). Tolerant + non-critical:
  * the wrapper always exits 0 and the engine degrades gracefully if absent.
+ *
+ * NOTE (Story onda2-p9 / DEC-01 option A): user-facing installs now get
+ * .synapse/ from the CANONICAL path — packages/installer/src/installer/
+ * synapse-runtime-installer.js, wired into the wizard (covers `install` and
+ * `init`). This step remains for the repo-source `npm run setup` flow (it
+ * writes at PROJECT_ROOT, i.e. the package/repo itself — see DEC-01 evidence).
+ * Do NOT delete without a deliberate DEC-03-like decision.
  */
 function stepGenerateSynapse() {
   if (isGlobalInstall()) {

package/bin/sinapse-init.js

@@ -24,7 +24,8 @@ const path = require('path');
 const fs = require('fs');
 const fse = require('fs-extra');
 const yaml = require('js-yaml');
-const { execSync, exec, spawn } = require('child_process');
+const { exec, spawn } = require('child_process');
+const { atomicWriteFileSync } = require('./lib/fs-utils');
 const { promisify } = require('util');
 const inquirer = require('inquirer');
 const chalk = require('chalk');
@@ -172,8 +173,8 @@ async function main() {
         author: '',
         license: 'ISC',
       };
-      // INS-2 Performance: Use async write instead of sync
-      await fse.writeFile(packageJsonPath, JSON.stringify(defaultPackage, null, 2));
+      // Atomic (tmp+rename): never leave a torn package.json
+      atomicWriteFileSync(packageJsonPath, JSON.stringify(defaultPackage, null, 2));
       console.log(chalk.green('✓') + ' package.json created');
     }
 
@@ -582,7 +583,8 @@ async function main() {
               const existing = await fse.readFile(targetRules, 'utf8');
               const incoming = await fse.readFile(sourceRules, 'utf8');
               const mergeResult = await markdownMerger.merge(existing, incoming);
-              await fse.writeFile(targetRules, mergeResult.content, 'utf8');
+              // Atomic (tmp+rename): merged user rules must never be half-written
+              atomicWriteFileSync(targetRules, mergeResult.content, 'utf8');
               console.log(
                 chalk.green('✓') +
                   ` ${ide.charAt(0).toUpperCase() + ide.slice(1)} rules merged (existing content preserved)`
@@ -830,7 +832,6 @@ See .sinapse-ai/user-guide.md for complete documentation.
   // INS-2 Performance: Add spinner for validation (AC9)
   const validationSpinner = ora('Validating installation integrity...').start();
 
-  let validationPassed = true;
   try {
     const { PostInstallValidator } = require('../packages/installer/src/installer/post-install-validator');
     const validator = new PostInstallValidator(context.projectRoot, context.frameworkLocation, {
@@ -851,7 +852,6 @@ See .sinapse-ai/user-guide.md for complete documentation.
       report.stats.missingFiles > 0 ||
       report.stats.corruptedFiles > 0
     ) {
-      validationPassed = false;
       validationSpinner.warn('Installation validation found issues:');
       console.log(chalk.dim(`   - Missing files: ${report.stats.missingFiles}`));
       console.log(chalk.dim(`   - Corrupted files: ${report.stats.corruptedFiles}`));
@@ -868,7 +868,6 @@ See .sinapse-ai/user-guide.md for complete documentation.
     // Log validation errors but don't fail installation
     // This allows installation to proceed even if validator module has issues
     // However, users should investigate validation errors manually
-    validationPassed = false;
     validationSpinner.warn('Post-installation validation encountered an error');
     console.log(chalk.dim(`   Error: ${validationError.message}`));
     if (process.env.DEBUG || process.env.SINAPSE_DEBUG) {
@@ -972,8 +971,8 @@ async function updateGitIgnore(mode, projectRoot) {
 
     if (!hasFrameworkSection) {
       gitignore += frameworkRules.join('\n');
-      // INS-2 Performance: Use async write
-      await fse.writeFile(gitignorePath, gitignore);
+      // Atomic (tmp+rename): appended .gitignore must never be half-written
+      atomicWriteFileSync(gitignorePath, gitignore);
     }
   }
 }

package/bin/sinapse.js

@@ -11,6 +11,10 @@ const fs = require('fs');
 const os = require('os');
 const { execSync, spawnSync } = require('child_process');
 const { emitDeprecationWarning } = require('./utils/deprecation-warning');
+// Story onda2-p6 — shared, TTY-detection used by `init` to fall back to the
+// wizard's quiet/default path in non-interactive shells (see shouldRunInitQuiet below).
+const { detectInteractiveMode } = require('./lib/detection');
+const { atomicWriteFileSync } = require('./lib/fs-utils');
 
 // Story A.2 — unified logger. Levels: error/warn/info/debug.
 // Flags: --verbose, --debug, --quiet, --json. Default level: warn.
@@ -112,6 +116,8 @@ USAGE:
   sinapse validate                    # Validate installation integrity
   sinapse info                        # Show system info
   sinapse doctor                      # Run diagnostics
+  sinapse agents list                 # List all framework agents (roster)
+  sinapse ideate                      # Run self-improvement analyzers (IdeationEngine)
   sinapse telemetry status            # Show telemetry state (disabled by default)
   sinapse telemetry enable            # Opt in to anonymized telemetry
   sinapse telemetry disable           # Opt out of telemetry
@@ -159,8 +165,16 @@ GENERATE & CREATE:
   sinapse create <agent|task|workflow>        # Scaffold a new framework component
 
 ORCHESTRATION:
+  sinapse spec <story-id>                   # Story assistant: generate the REAL spec for one story
+                                             # (stops before plan/build/QA)
+  sinapse plan <story-id>                   # Story assistant: real spec + implementation PLAN
+                                             # (stops before build/QA)
   sinapse orchestrate <story-id>            # Run the autonomous dev pipeline for a story
+  sinapse orchestrate <story-id> --dry-run  # Preview the pipeline (epics + tech stack), no execution
   sinapse orchestrate --status              # Show / --stop / --resume a running pipeline
+                                             # Scope: 1 story per run — sequential multi-story in the
+                                             # same directory is not supported (measured limitation;
+                                             # see docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md)
   sinapse route "<brief>"                   # Doc-first routing: type -> workflow -> what's missing
   sinapse build "<brief>"                    # Guided orchestration: RUN the route (--dry-run, --type)
   sinapse mode [explore|ask|auto]           # Show or set the agent permission mode (--cycle)
@@ -493,7 +507,8 @@ function cleanGitignore(gitignorePath) {
   }
 
   if (removedLines > 0) {
-    fs.writeFileSync(gitignorePath, newLines.join('\n'));
+    // Atomic (tmp+rename): never leave a half-written .gitignore
+    atomicWriteFileSync(gitignorePath, newLines.join('\n'));
     return { removed: true, lines: removedLines };
   }
   return { removed: false };
@@ -704,6 +719,11 @@ async function runUninstall(options = {}) {
   // Optionally remove .sinapse
   if (!keepData) {
     itemsToRemove.push({ path: '.sinapse', description: 'Project data and settings' });
+    // Story onda2-p9 — .synapse/ is the context-engine runtime (generated
+    // constitution + sessions/metrics). Grouped with project data for parity
+    // with .sinapse: removed by default, preserved under --keep-data.
+    // Regenerated automatically by any future `sinapse install`/`init`.
+    itemsToRemove.push({ path: '.synapse', description: 'Context engine runtime (constitution + sessions/metrics)' });
   }
 
   // Check what exists
@@ -836,6 +856,20 @@ async function runUninstall(options = {}) {
     logger.always(`  ✓ Cleaned ${gitignoreResult.lines} SINAPSE entries from .gitignore`);
   }
 
+  // UNINSTALL-GIT-HOOKS (audit AF-20260702 item 1.3) — reset git core.hooksPath
+  // so future commits don't point at the just-removed .sinapse-ai/git-hooks
+  // dir. Reuses the exact helper bin/commands/uninstall.js already ships
+  // (parity fix) instead of duplicating the logic here.
+  const { removeGitHooksConfig } = require('./commands/uninstall');
+  const hooksResult = await removeGitHooksConfig(cwd);
+  if (!quiet) {
+    if (hooksResult.unset) {
+      logger.always('  ✓ Reset git core.hooksPath (was SINAPSE-managed)');
+    } else if (hooksResult.value) {
+      logger.always('  - git core.hooksPath kept (custom, not SINAPSE-managed)');
+    }
+  }
+
   // Summary
   if (!quiet) {
     logger.always('\n✅ SINAPSE has been uninstalled.');
@@ -917,6 +951,26 @@ Examples:
 `);
 }
 
+/**
+ * Resolve whether `sinapse init` should run the wizard in quiet/default mode.
+ *
+ * Story onda2-p6 (bug found in S4): `install` already avoids crashing in a
+ * non-interactive shell because bin/commands/install.js passes `quiet: true`
+ * unconditionally to the wizard (language/LLM are resolved upstream via its
+ * own TTY-safe prompts). `init` had no such fallback — it called the wizard
+ * with no `quiet` flag at all, so a CI runner, piped stdin, or an AI agent
+ * invoking `npx sinapse-ai init` hit the wizard's language+LLM
+ * `inquirer.prompt()` and crashed with `ERR_USE_AFTER_CLOSE`. This mirrors
+ * install's fallback: no TTY -> quiet mode -> wizard uses its own defaults
+ * (pt + claude-code, see packages/installer/src/wizard/index.js).
+ *
+ * @param {boolean} [interactive] - Defaults to the real TTY/env/argv detection.
+ * @returns {boolean} true when the wizard should skip prompts and use defaults
+ */
+function shouldRunInitQuiet(interactive = detectInteractiveMode()) {
+  return !interactive;
+}
+
 async function initProject() {
   // 1. Parse ALL args after 'init'
   const initArgs = args.slice(1);
@@ -1009,6 +1063,9 @@ async function initProject() {
     template,
     skipInstall,
     force: isForce,
+    // Story onda2-p6 — fall back to quiet/default mode without a TTY (see
+    // shouldRunInitQuiet doc comment above for the crash this prevents).
+    quiet: shouldRunInitQuiet(),
   });
 }
 
@@ -1359,6 +1416,29 @@ async function main() {
       // Without this case the most powerful pipeline (executeFullPipeline) was
       // only reachable programmatically — violating Art. I (CLI First).
       try {
+        // Story onda2-p3 (AC2): `--help` answers with usage instead of failing
+        // on a missing story-id — also what `npx sinapse-ai orchestrate --help`
+        // reaches through the canonical binary's delegation.
+        if (args.includes('--help') || args.includes('-h')) {
+          logger.always(`Usage: sinapse orchestrate <story-id> [options]
+
+Runs the autonomous dev pipeline for ONE story: spec -> plan -> build -> QA.
+Scope: 1 story per run (multi-story chaining in the same directory is not
+supported — see docs/epics/epic-orchestration-consolidation/KNOWN-LIMITATIONS.md).
+
+Options:
+  --dry-run     Preview the pipeline (epics + detected tech stack), no execution
+  --epic <N>    Start from a specific epic (3=Spec, 4=Plan/Build, 6=QA)
+  --strict      Fail on any gate failure
+  --status      Show pipeline status for the story
+  --stop        Stop a running pipeline
+  --resume      Resume a stopped pipeline
+
+Related:
+  sinapse spec <story-id>   Real spec only (stops before plan/build/QA)
+  sinapse plan <story-id>   Real spec + plan (stops before build/QA)`);
+          process.exit(0);
+        }
         const orchestration = require('../.sinapse-ai/core/orchestration');
         const epicIdx = args.indexOf('--epic');
         // The story-id is the first positional arg after `orchestrate` — i.e.
@@ -1401,6 +1481,63 @@ async function main() {
       break; // unreachable (both branches process.exit) — satisfies no-fallthrough
     }
 
+    case 'spec':
+    case 'plan': {
+      // Story onda2-p3 (audit AF-20260702 item 2.3) — the hybrid's MEASURED
+      // value (real spec + real plan for ONE story) as first-class commands.
+      // Thin subcommands over the SAME orchestrate pipeline with a phase limit:
+      // `spec` stops after Epic 3; `plan` stops after Epic 4's plan phase —
+      // both stop BEFORE build/QA. No duplicated pipeline.
+      try {
+        if (args.includes('--help') || args.includes('-h')) {
+          logger.always(
+            command === 'spec'
+              ? `Usage: sinapse spec <story-id> [--dry-run]
+
+Generates the REAL specification (spec.md) for one story and stops there —
+no plan, no build, no QA. Same pipeline as \`sinapse orchestrate\`, limited to
+the spec phase. Artifact: docs/stories/<story-id>/spec.md
+
+Next step: sinapse plan <story-id>   (spec + implementation plan)`
+              : `Usage: sinapse plan <story-id> [--dry-run]
+
+Generates the REAL specification AND the implementation plan for one story,
+then stops — no build, no QA. Same pipeline as \`sinapse orchestrate\`, limited
+to the plan phase. Artifacts: docs/stories/<story-id>/spec.md and
+docs/stories/<story-id>/plan/implementation.yaml
+
+Next step: review the plan, then implement (natively or via sinapse orchestrate).`,
+          );
+          process.exit(0);
+        }
+
+        const orchestration = require('../.sinapse-ai/core/orchestration');
+        const storyId = args.slice(1).find((a) => !a.startsWith('--'));
+        const options = {
+          projectRoot: process.cwd(),
+          dryRun: args.includes('--dry-run'),
+          strict: args.includes('--strict'),
+        };
+
+        const result =
+          command === 'spec'
+            ? await orchestration.spec(storyId, options)
+            : await orchestration.plan(storyId, options);
+
+        const exitCode =
+          result && typeof result.exitCode === 'number'
+            ? result.exitCode
+            : result && result.success === false
+              ? 1
+              : 0;
+        process.exit(exitCode);
+      } catch (error) {
+        logger.error(`❌ ${command} command error: ${error.message}`);
+        process.exit(1);
+      }
+      break; // unreachable (both branches process.exit) — satisfies no-fallthrough
+    }
+
     case 'route': {
       // Doc-first routing observability (READ-ONLY) — Art. I (CLI First).
       // Usage: sinapse route "<brief>" [--type <project_type>]
@@ -1518,6 +1655,19 @@ async function main() {
       break; // unreachable (process.exit above) — satisfies no-fallthrough
     }
 
+    case 'agents':
+    case 'ideate': {
+      // `agents`/`ideate` are owned by bin/cli.js (SCHEMA-001 agent roster +
+      // IdeationEngine). Without this, an unknown command here fell through to
+      // launchSinapse and was silently passed as a raw prompt to Claude Code —
+      // same bug class the `ids:*` delegation below already fixes, so it's
+      // fixed the same way (spawnSync into the module that really owns it).
+      const cliBin = path.join(__dirname, 'cli.js');
+      const result = spawnSync(process.execPath, [cliBin, ...args], { stdio: 'inherit' });
+      process.exit(result.status === null ? 1 : result.status);
+      break; // unreachable (process.exit above) — satisfies no-fallthrough
+    }
+
     case undefined:
       // No arguments - launch Claude Code with SINAPSE branding
       launchSinapse([]);
@@ -1547,4 +1697,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { nodeSatisfies };
+module.exports = { nodeSatisfies, shouldRunInitQuiet };

package/bin/utils/staged-secret-scan.js

@@ -50,7 +50,9 @@ const SCANNER_SELF_FILES = new Set([
   'bin/utils/staged-secret-scan.js',
   '.claude/hooks/secret-scanning.cjs',
 ]);
-const TEST_FILE_PATTERN = /(^|\/)(tests?|__tests__)\/|\.(test|spec)\.[cm]?[jt]s$/i;
+// Each alternative carries its own anchors (grouped explicitly) so neither
+// branch can accidentally match a substring of the other's context.
+const TEST_FILE_PATTERN = /((^|\/)(tests?|__tests__)\/)|(\.(test|spec)\.[cm]?[jt]s$)/i;
 
 function isScanExemptPath(filePath) {
   const norm = String(filePath).replace(/\\/g, '/');

package/docs/framework/atlas/OPERATING-ATLAS.md

@@ -3,7 +3,7 @@
 > Single, generated map of how the SINAPSE framework works: routing, models,
 > constitution, workflows, agents, squads. Regenerate with `sinapse atlas`.
 > Counts are read from disk (Article VII — always exact).
-> Generated: 2026-06-26T05:56:32.158Z
+> Generated: 2026-07-03T03:44:39.813Z
 
 **At a glance:** 17 squads · 172 agents
 (12 framework + 160 squad) ·
@@ -488,13 +488,13 @@ squad workflows**. The 13 primary framework workflows have detailed docs in
 
 | Orchestrator | Persona | Squad | Role |
 |---|---|---|---|
-| `swarm-orqx` | Nexus | claude-code-mastery | Multi-Agent Systems Architect & Swarm Orchestration Specialist |
+| `swarm-orqx` | Relay | claude-code-mastery | Multi-Agent Systems Architect & Swarm Orchestration Specialist |
 | `snps-orqx` | Imperator | framework | Supreme Orchestrator of all 17 SINAPSE Squads (172 agents) |
 | `animations-orqx` | Kinetic | squad-animations | Animation Squad Orchestrator |
 | `squad-brand` | Meridian | squad-brand | Brand Squad Orchestrator — coordena os 14 agentes especialistas do squad |
 | `squad-cloning` | Helix | squad-cloning | Clone Pipeline Orchestrator — coordena o pipeline completo de clonagem cognitiva |
 | `commercial-orqx` | — | squad-commercial | Revenue Cycle Orchestrator |
-| `squad-content` | Nexus | squad-content | Content Pipeline Orchestrator — coordena todo o fluxo de deteccao, producao, publicacao e analise |
+| `squad-content` | Bulletin | squad-content | Content Pipeline Orchestrator — coordena todo o fluxo de deteccao, producao, publicacao e analise |
 | `squad-copy` | Quill Prime | squad-copy | Copy Squad Orchestrator — coordena os 12 agentes especialistas do squad |
 | `council-orqx` | Zenith | squad-council | Strategic Council Orchestrator & Wisdom Synthesizer |
 | `squad-courses` | Syllabus | squad-courses | Course Project Orchestrator — coordena o ciclo completo de criacao de cursos |