sinapse-ai 1.17.0 → 1.19.1

package/.claude/rules/documentation-first.md

@@ -44,6 +44,12 @@ No implementation proceeds without ALL of these:
 
 **Attempting to write code without a valid story → BLOCKED.**
 
+## Enforcement model — floor-reactive by design (honest)
+
+Doc-first is enforced by a **deterministic reactive floor**, not by proactive prose: on a build request, `sinapse route` classifies the project type and **blocks** when the required artifacts are missing (story `Ready`; epic/PRD/architecture for large projects). This floor holds even if the agent forgets the rule, and it is covered by passing tests.
+
+Audit AF-20260629 **refuted** the earlier "prose without enforcement" hypothesis — the floor genuinely classifies and blocks. What is *not* wired into the prompt is the proactive **layer-2 conduction** (auto-walking the user through PRD → epic → story turn by turn). That layer is intentional **roadmap**, not a missing guardrail: no new always-on hook is added here by design (a reactive floor is lower-risk than a proactive prompt injector).
+
 ## Project Type Gate (NON-NEGOTIABLE)
 
 > **Why this exists:** A bare `epic + story` pipeline is necessary but not sufficient for **large projects**. A site, landing page, SaaS platform, mobile app, or backend service needs *upstream* artifacts (project brief, PRD, architecture, design spec) **before** stories can be written meaningfully. Without this gate, the framework writes stories from a vague verbal description and produces generic / off-brand output.

package/.sinapse-ai/constitution.md

@@ -115,7 +115,7 @@ Qualidade não é negociável. Todo código passa por múltiplos gates antes de
 - MUST: Story status é "Done" ou "Ready for Review"
 - SHOULD: Cobertura de testes não diminui
 
-**Gate:** `pre-push.md` - BLOCK se qualquer check falhar
+**Gate:** `.sinapse-ai/git-hooks/pre-push` - BLOCK se qualquer check falhar (executa `npm run validate:all`, fail-closed)
 
 ---
 
@@ -389,5 +389,5 @@ Resultado: nada foi fundido. Dual register preservado. Article XI formalizado pr
 
 ---
 
-*SINAPSE Constitution v1.0.0*
+*SINAPSE Constitution v2.2.0*
 *CLI First | Agent-Driven | Quality First*

package/.sinapse-ai/core/code-intel/registry-syncer.js

@@ -6,6 +6,7 @@ const crypto = require('crypto');
 const yaml = require('js-yaml');
 const { getClient, isCodeIntelAvailable } = require('../code-intel');
 const { RegistryLoader, DEFAULT_REGISTRY_PATH } = require('../ids/registry-loader');
+const { atomicWriteSync } = require('../synapse/utils/atomic-write');
 
 // Role inference from entity path (order matters: more specific patterns first)
 const ROLE_MAP = [
@@ -366,10 +367,11 @@ class RegistrySyncer {
    * @private
    */
   _atomicWrite(registryPath, registry) {
-    const tmpPath = registryPath + '.tmp';
     const content = yaml.dump(registry, { lineWidth: 120, noRefs: true });
-    fs.writeFileSync(tmpPath, content, 'utf8');
-    fs.renameSync(tmpPath, registryPath);
+    // Delegate to the canonical helper: it does unlink-first on Windows and
+    // retries the rename on transient EPERM/EBUSY locks (AV / Search indexer /
+    // concurrent readers) that POSIX never hits.
+    atomicWriteSync(registryPath, content, 'utf8');
   }
 
   /**

package/.sinapse-ai/core/doctor/checks/agent-memory.js

@@ -12,13 +12,15 @@ const fs = require('fs');
 
 const name = 'agent-memory';
 
+// Canonical SINAPSE agent ids (current naming, since v6.0.0).
+// These match the directory names under .sinapse-ai/development/agents/.
 const EXPECTED_AGENTS = [
-  'dev',
-  'qa',
+  'developer',
+  'quality-gate',
   'architect',
-  'pm',
-  'po',
-  'sm',
+  'project-lead',
+  'product-lead',
+  'sprint-lead',
   'analyst',
   'data-engineer',
   'ux',

package/.sinapse-ai/core/doctor/checks/claude-md.js

@@ -45,6 +45,19 @@ async function run(context) {
     };
   }
 
+  // In the framework's own source repo, .claude/CLAUDE.md is the contributor
+  // variant (headings like "Framework Boundary", "Agents") rather than the
+  // install template (PT section titles). The content exists under different
+  // headings, so this is expected — surface as INFO, not WARN.
+  if (context.isFrameworkRepo) {
+    return {
+      check: name,
+      status: 'INFO',
+      message: `Dev CLAUDE.md variant — install-template sections not required in the source repo (${missingSections.join(', ')})`,
+      fixCommand: null,
+    };
+  }
+
   return {
     check: name,
     status: 'WARN',

package/.sinapse-ai/core/doctor/checks/constitution-consistency.js

@@ -30,6 +30,7 @@ const KEY_ARTICLES = [
   'Mandatory Delegation',
   'Safe Collaboration',
   'Security & Data Protection',
+  'Conservative Default',
 ];
 
 /**

package/.sinapse-ai/core/doctor/checks/hooks-claude-count.js

@@ -99,6 +99,17 @@ async function run(context) {
   }
 
   if (hookCount >= 2 && !registered) {
+    // In the framework's own source repo, settings.local.json is gitignored
+    // (per-machine) and hook registration is an install-time step. Hook files
+    // shipping unregistered is expected here — surface as INFO, not WARN.
+    if (context.isFrameworkRepo) {
+      return {
+        check: name,
+        status: 'INFO',
+        message: `${hookCount} hook files present — registration is install-time (settings.local.json is gitignored in the source repo)`,
+        fixCommand: null,
+      };
+    }
     return {
       check: name,
       status: 'WARN',

package/.sinapse-ai/core/doctor/checks/settings-json.js

@@ -28,8 +28,11 @@ function checkBoundaryAlignment(context, denyRules) {
     return [];
   }
 
-  // Extract boundary.protected paths from YAML (simple line parsing)
-  const lines = content.split('\n');
+  // Extract boundary.protected paths from YAML (simple line parsing).
+  // Split on /\r?\n/ so a CRLF-saved core-config.yaml (Windows editors,
+  // core.autocrlf) does not leave a trailing \r that breaks the path regex
+  // below and silently empties protectedPaths (false-negative boundary check).
+  const lines = content.split(/\r?\n/);
   const protectedPaths = [];
   let inProtected = false;
 
@@ -91,6 +94,17 @@ async function run(context) {
   const allowCount = allowRules.length;
 
   if (denyCount < 40) {
+    // In the framework's own source repo, boundary protection is OFF by design
+    // (core-config boundary.frameworkProtection:false) so contributors can edit
+    // core files — 0 deny rules is the expected, correct state here.
+    if (context.isFrameworkRepo) {
+      return {
+        check: name,
+        status: 'INFO',
+        message: `Deny rules off (${denyCount}) — expected in the framework source repo (frameworkProtection:false)`,
+        fixCommand: null,
+      };
+    }
     return {
       check: name,
       status: 'WARN',

package/.sinapse-ai/core/doctor/index.js

@@ -69,6 +69,27 @@ function detectInstallState(context) {
   return { installed: false };
 }
 
+/**
+ * Detect whether doctor is running inside the framework's OWN source repo,
+ * as opposed to a user project that installed SINAPSE. In the source repo the
+ * root package.json name is exactly 'sinapse-ai'. User projects have their own
+ * name (with sinapse-ai under node_modules), so this never false-positives for
+ * them.
+ *
+ * @param {string} projectRoot
+ * @returns {boolean}
+ */
+function detectFrameworkRepo(projectRoot) {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'),
+    );
+    return Boolean(pkg) && pkg.name === 'sinapse-ai';
+  } catch {
+    return false;
+  }
+}
+
 const VALID_ON_ERROR = new Set(['fail', 'warn', 'skip']);
 
 /**
@@ -134,6 +155,12 @@ async function runDoctorChecks(options = {}) {
     const context = {
       projectRoot,
       frameworkRoot: path.resolve(__dirname, '..', '..', '..'),
+      // True when doctor runs inside the framework's OWN source repo (vs a user
+      // install). In the source repo some install-time artifacts are absent BY
+      // DESIGN — deny rules are off for contributors (frameworkProtection:false),
+      // hooks live in gitignored settings.local.json, and CLAUDE.md is the dev
+      // variant. Context checks degrade WARN→INFO here to avoid false alarms.
+      isFrameworkRepo: detectFrameworkRepo(projectRoot),
       options: { fix, json, dryRun, quiet, deep, homeDir },
     };
 

package/.sinapse-ai/core/execution/build-orchestrator.js

@@ -227,6 +227,10 @@ class BuildOrchestrator extends EventEmitter {
         duration,
         phases: ctx.phases,
         reportPath: ctx.reportPath,
+        // F5 (epic: orchestration-consolidation): surface the real plan object so the
+        // quality gate can inspect its honesty (degraded/stub/subtasks). Without this
+        // the epic4_to_epic6 gate has nothing real to bite on.
+        plan: ctx.plan,
       };
     } catch (error) {
       ctx.errors.push(error);
@@ -850,18 +854,120 @@ The subtask is complete only when verification passes.
   }
 
   /**
-   * Generate implementation plan using Claude
+   * Whether real planning-via-agent (spawning `claude`) is allowed.
+   *
+   * Mirrors {@link EpicExecutor#_realExecutionAllowed}: returns false inside the
+   * jest runner unless `SINAPSE_REAL_DISPATCH=1`. This guard is CRITICAL — the
+   * `claude` CLI IS on the PATH in this repo, so without it a `generatePlan()`
+   * call under unit tests would spawn the real CLI, burn the user's tokens and be
+   * non-deterministic.
+   *
+   * Honesty invariant (epic: orchestration-consolidation, F4): no path returns a
+   * "real" plan without doing real work. When this returns false, the caller
+   * falls back to a deterministic plan explicitly marked degraded/stub — never a
+   * fabricated plan passed off as agent-generated.
+   *
+   * @returns {boolean}
+   * @private
    */
-  async generatePlan(ctx) {
-    // For now, return a basic plan structure
-    // In a full implementation, this would use Claude to analyze the story
-    // and generate a detailed implementation plan
+  _planningViaAgentAllowed() {
+    return (
+      process.env.JEST_WORKER_ID === undefined || process.env.SINAPSE_REAL_DISPATCH === '1'
+    );
+  }
 
-    const storyContent = fs.readFileSync(ctx.storyPath, 'utf-8');
+  /**
+   * Build the planning prompt sent to the `claude` CLI.
+   * Feeds the FULL story (prose + ACs) and asks for a structured JSON plan.
+   *
+   * @param {string} storyId
+   * @param {string} storyContent - Full raw story file content
+   * @returns {string}
+   */
+  buildPlanPrompt(storyId, storyContent) {
+    return `You are a senior engineer producing an implementation plan for a development story.
 
-    // Extract acceptance criteria
-    const acMatches = storyContent.match(/- \[ \] AC\d+:.*$/gm) || [];
+## Story (${storyId})
+${storyContent}
+
+## Task
+Analyze the FULL story above (prose AND acceptance criteria) and produce a structured implementation plan.
+
+Respond with ONLY a JSON object (optionally inside a \`\`\`json fenced block), no prose before or after, in EXACTLY this shape:
+
+{
+  "phases": [
+    {
+      "id": "phase-id",
+      "name": "Human-readable phase name",
+      "subtasks": [
+        {
+          "id": "1.1",
+          "description": "What to implement",
+          "files": ["path/to/file.js"],
+          "verification": "command or check that confirms this subtask is done"
+        }
+      ]
+    }
+  ]
+}
+
+Rules:
+- Break the work into logical phases, each with concrete subtasks.
+- Every subtask MUST have a stable id ("phase.subtask", e.g. "1.1"), a clear description, the files it will touch, and a verification step.
+- Ground every subtask in the story's acceptance criteria — do not invent scope.`;
+  }
+
+  /**
+   * Robustly parse a plan JSON object out of a raw `claude` response.
+   * Tolerates ```json fenced blocks and surrounding prose; returns null when no
+   * valid plan object can be extracted (caller then degrades honestly).
+   *
+   * @param {string} raw - Raw CLI stdout
+   * @returns {{phases: Array}|null}
+   */
+  parsePlanResponse(raw) {
+    if (!raw || typeof raw !== 'string') {
+      return null;
+    }
+    let text = raw.trim();
+
+    // Prefer a fenced ```json ... ``` block when present.
+    const fenceMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fenceMatch) {
+      text = fenceMatch[1].trim();
+    } else {
+      // Otherwise slice from the first `{` to the last `}` (drops surrounding prose).
+      const first = text.indexOf('{');
+      const last = text.lastIndexOf('}');
+      if (first !== -1 && last > first) {
+        text = text.slice(first, last + 1);
+      }
+    }
 
+    try {
+      const obj = JSON.parse(text);
+      if (!obj || typeof obj !== 'object' || !Array.isArray(obj.phases)) {
+        return null;
+      }
+      return obj;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Build a deterministic, HONESTLY-DEGRADED plan from the story's ACs via regex.
+   * Always marked `degraded: true` / `stub: true` with a `reason` so the engine
+   * never passes a fallback off as a real agent-generated plan (F4 invariant).
+   *
+   * @param {Object} ctx
+   * @param {string[]} acMatches - Pre-extracted `- [ ] ACn:` lines
+   * @param {string} reason - Why we degraded (for honest reporting)
+   * @returns {Object}
+   * @private
+   */
+  _degradedPlan(ctx, acMatches, reason) {
     const subtasks = acMatches.map((ac, i) => ({
       id: `1.${i + 1}`, // Format: phase.subtask (e.g., "1.1", "1.2")
       description: ac.replace(/- \[ \] AC\d+:\s*/, ''),
@@ -872,6 +978,9 @@ The subtask is complete only when verification passes.
     return {
       storyId: ctx.storyId,
       generatedAt: new Date().toISOString(),
+      degraded: true,
+      stub: true,
+      reason,
       phases: [
         {
           id: 'implementation',
@@ -882,6 +991,81 @@ The subtask is complete only when verification passes.
     };
   }
 
+  /**
+   * Generate an implementation plan from a story.
+   *
+   * Honesty invariant (epic: orchestration-consolidation, F4):
+   * - AC1: when real execution is allowed → invoke `claude` over the FULL story
+   *   and return a rich plan WITHOUT any stub/degraded mark.
+   * - AC2: when real execution is NOT allowed (jest w/o SINAPSE_REAL_DISPATCH),
+   *   claude is unavailable/fails, or the response can't be parsed → fall back to
+   *   the deterministic regex plan, marked `degraded:true`/`stub:true` + `reason`.
+   *   Never throws here; the pipeline proceeds with a degraded plan.
+   * - AC3: missing / empty / non-actionable story → throw explicitly.
+   *
+   * @param {Object} ctx - { storyId, storyPath, config, worktree? }
+   * @returns {Promise<Object>} Plan ({ phases, ... }); degraded plans are marked.
+   */
+  async generatePlan(ctx) {
+    // AC3: explicit failure when there is no usable story file.
+    if (!ctx || !ctx.storyPath || !fs.existsSync(ctx.storyPath)) {
+      throw new Error(
+        `generatePlan: story file not found (storyId=${ctx && ctx.storyId}, path=${ctx && ctx.storyPath})`,
+      );
+    }
+
+    const storyContent = fs.readFileSync(ctx.storyPath, 'utf-8');
+    const trimmed = storyContent.trim();
+
+    // Deterministic AC extraction — shared by both the real and fallback paths.
+    const acMatches = storyContent.match(/- \[ \] AC\d+:.*$/gm) || [];
+
+    // "Actionable" = has ACs OR meaningful prose (more than a bare heading).
+    const proseWithoutHeadings = trimmed
+      .split('\n')
+      .filter((line) => !line.trim().startsWith('#'))
+      .join('\n')
+      .trim();
+    const hasActionableContent = acMatches.length > 0 || proseWithoutHeadings.length >= 20;
+
+    // AC3: empty or non-actionable story → explicit error, never a silent empty plan.
+    if (trimmed.length === 0 || !hasActionableContent) {
+      throw new Error(
+        `generatePlan: story has no actionable content (storyId=${ctx.storyId}, path=${ctx.storyPath})`,
+      );
+    }
+
+    // AC1: real planning path — guarded against burning tokens under jest.
+    if (this._planningViaAgentAllowed()) {
+      try {
+        const prompt = this.buildPlanPrompt(ctx.storyId, storyContent);
+        const workDir = (ctx.worktree && ctx.worktree.path) || this.rootPath;
+        const cliResult = await this.runClaudeCLI(prompt, workDir, ctx.config || this.config);
+        const stdout =
+          typeof cliResult === 'string' ? cliResult : (cliResult && cliResult.stdout) || '';
+        const parsed = this.parsePlanResponse(stdout);
+
+        if (parsed && Array.isArray(parsed.phases) && parsed.phases.length > 0) {
+          // AC1: real plan — no stub/degraded mark.
+          return {
+            storyId: ctx.storyId,
+            generatedAt: new Date().toISOString(),
+            phases: parsed.phases,
+          };
+        }
+
+        // AC2: unparseable / empty agent response → honest degraded fallback.
+        return this._degradedPlan(ctx, acMatches, 'agent-response-unparseable');
+      } catch (err) {
+        // AC2: claude unavailable / spawn error / timeout → honest degraded fallback (no throw).
+        return this._degradedPlan(ctx, acMatches, `agent-invocation-failed: ${err.message}`);
+      }
+    }
+
+    // AC2: real planning disabled (jest without SINAPSE_REAL_DISPATCH) → honest degraded fallback.
+    return this._degradedPlan(ctx, acMatches, 'real-planning-disabled');
+  }
+
   /**
    * Format duration
    */

package/.sinapse-ai/core/external-executors/delegate-cli.js

@@ -1,6 +1,10 @@
 const fs = require('fs');
 const path = require('path');
-const { spawn, spawnSync } = require('child_process');
+const { spawnSync } = require('child_process');
+// cross-spawn resolves Windows .cmd/.bat/.ps1 shims (e.g. an npm-global `codex.cmd`)
+// that native child_process.spawn cannot launch without a shell — it throws ENOENT.
+// It preserves detached + stdio + env semantics, so background spawning is unchanged.
+const crossSpawn = require('cross-spawn');
 
 const DEFAULT_RUN_DIR = '.sinapse/external-runs';
 const SUPPORTED_SANDBOXES = new Set([
@@ -449,7 +453,7 @@ async function spawnExecutor(plan) {
   };
 
   try {
-    child = spawn(plan.command, plan.args, {
+    child = crossSpawn(plan.command, plan.args, {
       cwd: plan.options.workdir,
       detached: !plan.options.foreground,
       stdio: ['pipe', logFd, logFd],

package/.sinapse-ai/core/health-check/checks/project/constitution-consistency.js

@@ -15,7 +15,7 @@ const path = require('path');
 const { BaseCheck, CheckSeverity, CheckDomain } = require('../../base-check');
 
 /**
- * Expected articles in Constitution v2.0.0
+ * Expected articles in Constitution v2.2.0
  * Source of truth: .sinapse-ai/constitution.md
  */
 const EXPECTED_ARTICLES = [
@@ -29,6 +29,7 @@ const EXPECTED_ARTICLES = [
   { number: 'VIII', title: 'Mandatory Delegation', severity: 'NON-NEGOTIABLE' },
   { number: 'IX', title: 'Safe Collaboration', severity: 'NON-NEGOTIABLE' },
   { number: 'X', title: 'Security & Data Protection', severity: 'NON-NEGOTIABLE' },
+  { number: 'XI', title: 'Conservative Default', severity: 'MUST' },
 ];
 
 /**

package/.sinapse-ai/core/ideation/ideation-engine.js

@@ -8,7 +8,10 @@
 
 const fs = require('fs');
 const path = require('path');
-const { spawnSync } = require('child_process');
+// cross-spawn.sync resolves npm/npx to their Windows .cmd shims WITHOUT a shell.
+// Native spawnSync('npm.cmd', ...) without shell:true returns EINVAL on modern Node
+// (post CVE-2024-27980), silently no-op'ing the audit/madge checks on Windows.
+const crossSpawn = require('cross-spawn');
 
 // Import dependencies with fallbacks
 const GOTCHAS_MEMORY_MODULE = '../memory/gotchas-memory';
@@ -622,10 +625,9 @@ class SecurityAnalyzer {
     const findings = [];
 
     try {
-      // spawnSync (no shell) — cross-platform; npm exits non-zero when vulns
-      // exist but still prints the JSON report to stdout, which is what we parse.
-      const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-      const audit = spawnSync(npmCmd, ['audit', '--json'], {
+      // cross-spawn.sync resolves npm's Windows shim without a shell; npm exits
+      // non-zero when vulns exist but still prints the JSON report to stdout.
+      const audit = crossSpawn.sync('npm', ['audit', '--json'], {
         cwd: this.rootPath,
         encoding: 'utf8',
         maxBuffer: 10 * 1024 * 1024,
@@ -866,9 +868,9 @@ class ArchitectureAnalyzer {
     const findings = [];
 
     try {
-      // Use madge if available (spawnSync, no shell — cross-platform).
-      const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-      const proc = spawnSync(npxCmd, ['madge', '--circular', '--warning', path.join(this.rootPath, 'src')], {
+      // cross-spawn.sync resolves npx's Windows shim without a shell (native
+      // spawnSync of npx.cmd without shell:true returns EINVAL on modern Node).
+      const proc = crossSpawn.sync('npx', ['madge', '--circular', '--warning', path.join(this.rootPath, 'src')], {
         encoding: 'utf8',
         timeout: 30000,
         windowsHide: true,

package/.sinapse-ai/core/mcp/config-migrator.js

@@ -19,6 +19,7 @@ const {
   createGlobalConfig,
 } = require('./global-config-manager');
 const { getProjectMcpPath, checkLinkStatus, LINK_STATUS, createLink } = require('./symlink-manager');
+const { retrySync } = require('../synapse/utils/atomic-write');
 
 /**
  * Migration options
@@ -267,7 +268,8 @@ function executeMigration(projectRoot = process.cwd(), option = MIGRATION_OPTION
       const backupPath = projectMcpPath + '.backup.' + Date.now();
 
       try {
-        fs.renameSync(projectMcpPath, backupPath);
+        // retrySync: transient EPERM/EBUSY from AV / Search indexer on Windows.
+        retrySync(() => fs.renameSync(projectMcpPath, backupPath));
         results.backupPath = backupPath;
       } catch (error) {
         results.errors.push(`Backup failed: ${error.message}`);
@@ -315,14 +317,15 @@ function restoreFromBackup(backupPath, projectRoot = process.cwd()) {
     if (fs.existsSync(projectMcpPath)) {
       const stats = fs.lstatSync(projectMcpPath);
       if (stats.isSymbolicLink()) {
-        fs.unlinkSync(projectMcpPath);
+        retrySync(() => fs.unlinkSync(projectMcpPath));
       } else {
-        fs.rmSync(projectMcpPath, { recursive: true });
+        retrySync(() => fs.rmSync(projectMcpPath, { recursive: true }));
       }
     }
 
-    // Restore backup
-    fs.renameSync(backupPath, projectMcpPath);
+    // Restore backup — retry transient Windows locks so a legit rollback
+    // isn't lost to a momentary AV/indexer handle on the config dir.
+    retrySync(() => fs.renameSync(backupPath, projectMcpPath));
 
     return { success: true, restored: projectMcpPath };
   } catch (error) {

package/.sinapse-ai/core/mcp/global-config-manager.js

@@ -181,7 +181,10 @@ function readGlobalConfig() {
   }
 
   try {
-    const content = fs.readFileSync(configPath, 'utf8');
+    // Strip a leading BOM: a global-config.json saved by a Windows editor
+    // (Notepad) starts with U+FEFF and would make JSON.parse throw, silently
+    // dropping the user's MCP global config via the catch below.
+    const content = fs.readFileSync(configPath, 'utf8').replace(/^\uFEFF/, '');
     return JSON.parse(content);
   } catch (error) {
     console.error(`Error reading global config: ${error.message}`);

package/.sinapse-ai/core/mcp/symlink-manager.js

@@ -13,6 +13,7 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 const { isWindows, getGlobalMcpDir, getLinkType } = require('./os-detector');
+const { retrySync } = require('../synapse/utils/atomic-write');
 
 /**
  * Link status types
@@ -284,7 +285,9 @@ function createLink(projectRoot = process.cwd(), options = {}) {
         const configFile = path.join(linkPath, 'global-config.json');
         if (fs.existsSync(configFile)) {
           const backupPath = linkPath + '.backup.' + Date.now();
-          fs.renameSync(linkPath, backupPath);
+          // retrySync: on Windows the rename of a dir held by AV / Search
+          // indexer / a concurrent reader throws transient EPERM/EBUSY.
+          retrySync(() => fs.renameSync(linkPath, backupPath));
           return {
             success: false,
             error: `Existing config backed up to ${backupPath}. Run with --migrate to merge configs.`,
@@ -293,10 +296,10 @@ function createLink(projectRoot = process.cwd(), options = {}) {
             backup: backupPath,
           };
         }
-        fs.rmSync(linkPath, { recursive: true });
+        retrySync(() => fs.rmSync(linkPath, { recursive: true }));
       } else {
         // Remove symlink/junction
-        fs.unlinkSync(linkPath);
+        retrySync(() => fs.unlinkSync(linkPath));
       }
     } catch (error) {
       return {

package/.sinapse-ai/core/orchestration/bob-orchestrator.js

@@ -10,8 +10,7 @@
  *
  * Integrates all Epic 11 modules:
  * - ExecutorAssignment (11.1) — agent selection
- * - TerminalSpawner (11.2) — agent spawning
- * - WorkflowExecutor (11.3) — development cycle
+ * - WorkflowExecutor (11.3) — development cycle (honest manual hand-off)
  * - SurfaceChecker (11.4) — human decision criteria
  * - SessionState (11.5) — session persistence
  *
@@ -1252,8 +1251,7 @@ class BobOrchestrator {
    *
    * Delegates to Epic 11 modules:
    * - ExecutorAssignment for agent selection (AC8)
-   * - TerminalSpawner for agent spawning (AC9)
-   * - WorkflowExecutor for development cycle (AC10)
+   * - WorkflowExecutor for development cycle, with honest manual hand-off (AC10)
    *
    * Story 12.5 AC5: Updates session state at each phase transition.
    *

package/.sinapse-ai/core/orchestration/brownfield-handler.js

@@ -352,13 +352,14 @@ Quer que eu comece?`;
       // Record phase in session state
       await this._recordPhase(BrownfieldPhase.SYSTEM_DOCUMENTATION, context);
 
-      // Execute workflow
+      // Hand the discovery workflow to the executor. executeWorkflow() loads and
+      // validates the workflow definition and returns a structured handoff; the
+      // per-phase documentation is produced by the agents the workflow assigns.
+      // Progress for those agent steps is tracked via _onPhaseStart/_onPhaseComplete/
+      // _onPhaseError + handlePhaseFailureAction as the agents report in.
       const result = await workflowExecutor.executeWorkflow(this.workflowPath, {
         projectRoot: this.projectRoot,
         techStack: context.techStack || {},
-        onPhaseStart: (phase) => this._onPhaseStart(phase, context),
-        onPhaseComplete: (phase, output) => this._onPhaseComplete(phase, output, context),
-        onPhaseError: (phase, error) => this._onPhaseError(phase, error, context),
       });
 
       // Check if workflow completed successfully