sinapse-ai 1.16.0 → 1.19.0

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/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

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

@@ -0,0 +1,136 @@
+/**
+ * Build Command — executable sibling of `sinapse route`.
+ *
+ * `route()` SHOWS the deterministic doc-first decision for a briefing (type →
+ * workflow → required docs → gate). `build()` RUNS it: it drives the
+ * BobOrchestrator decision-tree engine (Projeto Bob) from a briefing in GUIDED
+ * mode — it detects project state, routes to the greenfield / brownfield /
+ * existing-project handler, and surfaces the next action/checkpoint instead of
+ * spawning agents headlessly.
+ *
+ * Congruence guarantee: both `route()` and `build()` start from
+ * `resolveDocFirstState`, so the conversation, the doc-first gate hook, `route`
+ * and `build` can never disagree about type/workflow/gate.
+ *
+ * The heavy orchestration index (locks, observability panel, status writer) is
+ * required LAZILY — `--dry-run` never constructs it, so it stays side-effect-free.
+ *
+ * @module core/orchestration/build-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: Object.assign(id, { bold: id }),
+    cyan: Object.assign(id, { bold: id }), gray: id, bold: id, dim: id,
+  };
+}
+
+/**
+ * Render the compact doc-first routing header (the "plan"), shared with `route`
+ * so `build` is visibly congruent with it.
+ * @param {string} brief
+ * @param {object} state - resolveDocFirstState() result
+ */
+function printPlanHeader(brief, state) {
+  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 Build — guided orchestration'));
+  console.log(chalk.cyan('═══════════════════════════════════════════════════════════\n'));
+
+  console.log(`Brief:        ${chalk.gray(briefLabel)}`);
+  console.log(`Project type: ${chalk.bold(state.projectType)}`);
+  console.log(`Workflow:     ${chalk.bold(state.workflow || 'SDC (no upstream re-doc)')}`);
+  console.log(
+    `Doc-first:    ${state.gate.satisfied
+      ? chalk.green('✅ gate satisfied')
+      : chalk.red('🚫 gate blocked — missing: ' + state.gate.missing.join(', '))}\n`,
+  );
+  void ok;
+}
+
+/**
+ * Render the BobOrchestrator result in a guided, scannable way.
+ * @param {object} result - OrchestrationResult from BobOrchestrator.orchestrate
+ */
+function printEngineResult(result) {
+  const r = result || {};
+  console.log(chalk.bold('Engine decision:'));
+  console.log(`  Project state: ${chalk.bold(r.projectState || 'unknown')}`);
+  console.log(`  Action:        ${chalk.bold(r.action || 'n/a')}`);
+
+  const data = r.data || {};
+  const nextStep = r.nextStep || data.nextStep;
+  const message = data.formattedMessage || data.message || data.summary;
+  if (message) {
+    console.log('\n' + chalk.gray(String(message).trim()));
+  }
+  if (nextStep) {
+    console.log(`\n${chalk.cyan('▶ Next step:')} ${chalk.bold(nextStep)}`);
+  }
+
+  console.log('');
+  if (r.success) {
+    console.log(chalk.green.bold('  ✅ Orchestration step completed.\n'));
+  } else {
+    console.log(chalk.red.bold(`  🚫 Orchestration did not complete: ${r.error || r.action || 'unknown'}\n`));
+  }
+}
+
+/**
+ * Execute the `build` 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
+ * @param {boolean} [options.dryRun] - Show the plan + engine entry without running it
+ * @returns {Promise<{success:boolean, exitCode:number, state:object, result?:object}>}
+ */
+async function build(brief, options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const state = resolveDocFirstState({ projectRoot, brief, projectType: options.type });
+
+  printPlanHeader(brief, state);
+
+  if (options.dryRun) {
+    console.log(chalk.yellow.bold('  (dry-run) '), 'would run BobOrchestrator.orchestrate({ userGoal })');
+    console.log(
+      chalk.gray('  No engine constructed — no locks, no panel, no side effects.\n'),
+    );
+    return { success: true, exitCode: 0, state };
+  }
+
+  // Lazily require the heavy orchestration index ONLY for the real run.
+  let BobOrchestrator;
+  try {
+    ({ BobOrchestrator } = require('./index'));
+  } catch (error) {
+    console.log(chalk.red(`  ✗ Could not load orchestration engine: ${error.message}\n`));
+    return { success: false, exitCode: 1, state };
+  }
+
+  const bob = new BobOrchestrator(projectRoot, { userGoal: brief });
+  const result = await bob.orchestrate({ userGoal: brief, storyPath: options.storyPath });
+
+  printEngineResult(result);
+
+  return {
+    success: !!(result && result.success),
+    exitCode: result && result.success === false ? 1 : 0,
+    state,
+    result,
+  };
+}
+
+module.exports = { build };

package/.sinapse-ai/core/orchestration/doc-first-resolver.js

@@ -0,0 +1,322 @@
+/**
+ * Doc-First Resolver — deterministic "what does this project need before code?"
+ *
+ * Single source of truth for the Documentation-First contract (Constitution
+ * Article III). Given a project root (and optionally a user brief), it answers,
+ * with NO LLM reasoning and NO side effects:
+ *
+ *   - projectType : site | lp | app | platform | saas | api | service | feature | fix
+ *   - workflow    : which greenfield workflow applies (reuses greenfield-handler map)
+ *   - artifacts   : the upstream docs required before stories (brief/prd/spec/arch)
+ *   - gate        : is the minimal doc-first gate satisfied? (PRD + epic + a Ready story)
+ *
+ * Two consumers share this module so they never drift:
+ *   1. `sinapse route "<brief>"` — read-only observability of the routing decision.
+ *   2. The doc-first PreToolUse gate hook — blocks code writes when `gate.satisfied`
+ *      is false. The module is intentionally dependency-light (fs/path + the
+ *      greenfield-handler constants only) so it is safe and fast to require inside
+ *      a hook. It NEVER constructs the heavy BobOrchestrator (locks, panels, etc.).
+ *
+ * @module core/orchestration/doc-first-resolver
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  GREENFIELD_WORKFLOW_BY_TYPE,
+  resolveGreenfieldWorkflow,
+} = require('./greenfield-handler');
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              PROJECT TYPE CLASSIFICATION
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Keyword → project_type map. Mirrors the classification matrix in
+ * `.claude/rules/documentation-first.md` and `project-intelligence.md`.
+ * Order matters: more specific buckets are tested before broader ones.
+ * @constant
+ */
+const TYPE_KEYWORDS = Object.freeze([
+  { type: 'fix', words: ['bug', 'conserta', 'corrige', 'corrigir', 'ajusta', 'ajustar', 'tweak', 'hotfix'] },
+  { type: 'refactor', words: ['refatora', 'refatorar', 'refactor', 'renomeia', 'renomear', 'limpa', 'cleanup'] },
+  { type: 'lp', words: ['landing page', 'landing', 'lp', 'sales page', 'captura', 'squeeze'] },
+  { type: 'saas', words: ['saas', 'software as a service', 'multi-tenant', 'multitenant'] },
+  { type: 'platform', words: ['plataforma', 'platform', 'dashboard', 'admin', 'portal', 'painel'] },
+  { type: 'app', words: ['app mobile', 'mobile', 'ios', 'android', 'react native', 'flutter', 'aplicativo'] },
+  { type: 'api', words: ['api', 'backend', 'microservice', 'microsserviço', 'rest', 'graphql'] },
+  { type: 'service', words: ['worker', 'cron', 'etl', 'integration', 'integração', 'automation', 'automação'] },
+  { type: 'site', words: ['site', 'website', 'web site', 'institucional', 'página', 'pagina'] },
+  { type: 'feature', words: ['feature', 'funcionalidade', 'implementa', 'implementar', 'adiciona'] },
+]);
+
+/** Escape a string for safe use inside a RegExp. */
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Classify a brief string into a project_type. Returns `null` when the brief is
+ * empty or no keyword matches (caller decides the fallback). Matching is by whole
+ * word/phrase boundary (so "Asaas" does NOT match the keyword "saas").
+ * @param {string} [brief]
+ * @returns {string|null}
+ */
+function classifyProjectType(brief) {
+  if (!brief || typeof brief !== 'string') return null;
+  const haystack = brief.toLowerCase();
+  for (const { type, words } of TYPE_KEYWORDS) {
+    if (words.some((w) => new RegExp(`\\b${escapeRegExp(w)}\\b`, 'i').test(haystack))) {
+      return type;
+    }
+  }
+  return null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              REQUIRED ARTIFACTS PER PROJECT TYPE
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Upstream artifacts required BEFORE the first story, keyed by greenfield
+ * workflow. Mirrors the "Required upstream artifacts per project type" table in
+ * `documentation-first.md`. `feature` / `fix` / `refactor` do not require the
+ * upstream re-doc chain (they ride on an existing project).
+ * @constant
+ */
+const REQUIRED_ARTIFACTS_BY_WORKFLOW = Object.freeze({
+  'greenfield-ui': [
+    { id: 'brief', path: 'docs/project-brief.md' },
+    { id: 'prd', path: 'docs/prd.md' },
+    { id: 'front-end-spec', path: 'docs/front-end-spec.md' },
+    { id: 'architecture', path: 'docs/front-end-architecture.md' },
+  ],
+  'greenfield-fullstack': [
+    { id: 'brief', path: 'docs/project-brief.md' },
+    { id: 'prd', path: 'docs/prd.md' },
+    { id: 'front-end-spec', path: 'docs/front-end-spec.md' },
+    { id: 'architecture', path: 'docs/fullstack-architecture.md' },
+  ],
+  'greenfield-service': [
+    { id: 'brief', path: 'docs/project-brief.md' },
+    { id: 'prd', path: 'docs/prd.md' },
+    { id: 'architecture', path: 'docs/service-architecture.md' },
+  ],
+});
+
+/** Project types that bypass the upstream greenfield doc-chain. */
+const LIGHT_TYPES = Object.freeze(['feature', 'fix', 'refactor']);
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              PROJECT MATURITY
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+/** Directories whose presence (with real files) signals existing application code. */
+const CODE_DIRS = Object.freeze(['src', 'app', 'packages', 'components', 'pages', 'lib']);
+
+/**
+ * Assess project maturity for gate scoping. Two signals matter:
+ *
+ *   - isFrameworkRepo : this IS the SINAPSE framework's own repo (package.json
+ *                       name === 'sinapse-ai'). Framework development operates
+ *                       above the story layer (Constitution Art. III exception),
+ *                       so the doc-first gate must never block it.
+ *   - isGreenfield    : the project has no substantial application code yet — a
+ *                       brand-new project. The hard doc-first gate applies HERE
+ *                       (this is the "criar um site → straight to code" case).
+ *                       Existing projects defer to the lighter story-gate.
+ *
+ * @param {string} projectRoot
+ * @returns {{ isFrameworkRepo: boolean, isGreenfield: boolean }}
+ */
+function assessProjectMaturity(projectRoot) {
+  let isFrameworkRepo = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+    if (pkg && pkg.name === 'sinapse-ai') isFrameworkRepo = true;
+  } catch {
+    // no package.json — fine
+  }
+
+  // Greenfield = no substantial application code yet. A lone package.json does
+  // NOT flip this off — otherwise scaffolding package.json first (an exempt
+  // file) would bypass the gate. Only populated code dirs count as "existing".
+  const hasCode = CODE_DIRS.some((d) => dirHasAnyFile(path.join(projectRoot, d)));
+  const isGreenfield = !hasCode;
+
+  return { isFrameworkRepo, isGreenfield };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              MINIMAL DOC-FIRST GATE
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+const VALID_STORY_STATUSES = Object.freeze(['ready', 'inprogress', 'inreview', 'done']);
+
+/** True if a `docs/prd.md` (or sharded `docs/prd/`) exists and is non-trivial. */
+function hasPrd(projectRoot) {
+  const file = path.join(projectRoot, 'docs', 'prd.md');
+  if (fileHasContent(file)) return true;
+  return dirHasMarkdown(path.join(projectRoot, 'docs', 'prd'));
+}
+
+/** True if at least one epic exists under `docs/epics/` or `docs/stories/epics/`. */
+function hasEpic(projectRoot) {
+  return (
+    dirHasMarkdown(path.join(projectRoot, 'docs', 'epics')) ||
+    dirHasMarkdown(path.join(projectRoot, 'docs', 'stories', 'epics'))
+  );
+}
+
+/** True if at least one story under `docs/stories/` is at a >= Ready status. */
+function hasReadyStory(projectRoot) {
+  const dir = path.join(projectRoot, 'docs', 'stories');
+  return walkMarkdown(dir).some((f) => storyStatusIsReady(f));
+}
+
+/**
+ * Parse a story file's frontmatter `status:` and decide whether it is >= Ready.
+ * Uses a bounded, non-greedy regex (the greedy `[\w\s]*` form historically
+ * captured the next line — see the story-gate memory).
+ * @param {string} file
+ * @returns {boolean}
+ */
+function storyStatusIsReady(file) {
+  let content;
+  try {
+    content = fs.readFileSync(file, 'utf8');
+  } catch {
+    return false;
+  }
+  const m = content.match(/status:\s*["']?([a-z][a-z ]*?)["']?\s*(?:\r?\n|$)/i);
+  if (!m) return false;
+  const status = m[1].toLowerCase().replace(/\s+/g, '');
+  return VALID_STORY_STATUSES.includes(status);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              MAIN RESOLVER
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Resolve the full doc-first picture for a project.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.projectRoot=process.cwd()] - Project root.
+ * @param {string} [opts.brief] - User briefing (used to classify project type).
+ * @param {string} [opts.projectType] - Explicit type override (skips classification).
+ * @returns {{
+ *   brief: string|null,
+ *   projectType: string,
+ *   classified: boolean,
+ *   isLightType: boolean,
+ *   workflow: string|null,
+ *   artifacts: Array<{id:string, path:string, exists:boolean}>,
+ *   gate: { prd:boolean, epic:boolean, readyStory:boolean, satisfied:boolean, missing:string[] }
+ * }}
+ */
+function resolveDocFirstState(opts = {}) {
+  const projectRoot = opts.projectRoot || process.cwd();
+  const brief = opts.brief || null;
+  const classifiedType = opts.projectType || classifyProjectType(brief);
+  const projectType = classifiedType || 'site'; // safe default: assume a full project needs docs
+  const isLightType = LIGHT_TYPES.includes(projectType);
+
+  const workflow = isLightType ? null : resolveGreenfieldWorkflow(projectType);
+
+  const artifacts = (REQUIRED_ARTIFACTS_BY_WORKFLOW[workflow] || []).map((a) => ({
+    id: a.id,
+    path: a.path,
+    exists: fileHasContent(path.join(projectRoot, a.path)),
+  }));
+
+  const prd = hasPrd(projectRoot);
+  const epic = hasEpic(projectRoot);
+  const readyStory = hasReadyStory(projectRoot);
+
+  // Light types ride on an existing project: the minimal gate is "a Ready story"
+  // (the existing story-gate). Full projects additionally need PRD + epic.
+  const missing = [];
+  if (!readyStory) missing.push('story (status >= Ready)');
+  if (!isLightType) {
+    if (!prd) missing.push('PRD (docs/prd.md)');
+    if (!epic) missing.push('epic (docs/epics/)');
+  }
+  const satisfied = missing.length === 0;
+
+  return {
+    brief,
+    projectType,
+    classified: Boolean(classifiedType),
+    isLightType,
+    workflow,
+    artifacts,
+    gate: { prd, epic, readyStory, satisfied, missing },
+    maturity: assessProjectMaturity(projectRoot),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              FS HELPERS (lean, no deps)
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+function fileHasContent(file) {
+  try {
+    const stat = fs.statSync(file);
+    return stat.isFile() && stat.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+function dirHasMarkdown(dir) {
+  try {
+    return fs.readdirSync(dir).some((f) => f.toLowerCase().endsWith('.md'));
+  } catch {
+    return false;
+  }
+}
+
+/** True if `dir` exists and contains at least one regular file (any depth-1 entry). */
+function dirHasAnyFile(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true }).some((e) => e.isFile() || e.isDirectory());
+  } catch {
+    return false;
+  }
+}
+
+/** Recursively collect `.md` files under a dir (bounded depth, fail-safe). */
+function walkMarkdown(dir, depth = 0) {
+  if (depth > 4) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...walkMarkdown(full, depth + 1));
+    } else if (e.name.toLowerCase().endsWith('.md')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  classifyProjectType,
+  resolveDocFirstState,
+  assessProjectMaturity,
+  REQUIRED_ARTIFACTS_BY_WORKFLOW,
+  TYPE_KEYWORDS,
+  // re-exported for callers that want the raw map
+  GREENFIELD_WORKFLOW_BY_TYPE,
+};

package/.sinapse-ai/core/orchestration/executors/epic-4-executor.js

@@ -115,6 +115,9 @@ class Epic4Executor extends EpicExecutor {
           return this._completeExecution({
             implementationPath: planPath,
             planPath,
+            // F5 (epic: orchestration-consolidation): propagate the real plan object
+            // so the downstream epic4_to_epic6 gate can verify it is not degraded/stub.
+            plan: buildResult.plan,
             build: buildResult,
             reportPath: buildResult.reportPath,
             phases: buildResult.phases,

package/.sinapse-ai/core/orchestration/gate-evaluator.js

@@ -54,7 +54,9 @@ const DEFAULT_GATE_CONFIG = {
     blocking: true,
     requireTests: true,
     minTestCoverage: 0,
-    checks: ['plan_complete', 'implementation_exists', 'no_critical_errors'],
+    // F5 (epic: orchestration-consolidation): `plan_is_real` gives this gate teeth —
+    // a degraded/stub/absent/subtask-less plan is BLOCKED, not waved through.
+    checks: ['plan_complete', 'plan_is_real', 'implementation_exists', 'no_critical_errors'],
   },
 };
 
@@ -148,11 +150,7 @@ class GateEvaluator {
       const checks = await this._runGateChecks(fromEpic, toEpic, epicResult, gateConfig);
       result.checks = checks;
 
-      // Calculate score
-      const passedChecks = checks.filter((c) => c.passed).length;
-      result.score = checks.length > 0 ? (passedChecks / checks.length) * 5 : 5;
-
-      // Collect issues
+      // Collect issues from failed checks
       result.issues = checks
         .filter((c) => !c.passed)
         .map((c) => ({
@@ -161,6 +159,22 @@ class GateEvaluator {
           severity: c.severity || 'medium',
         }));
 
+      // Calculate score — honesty invariant (F5, epic: orchestration-consolidation):
+      // a gate that evaluated ZERO checks verified NOTHING. It must NOT receive the
+      // max score (the old `: 5` was theater — an unconfigured gate always passed).
+      // Score 0 + an explicit issue so the verdict reflects "no real verification".
+      if (checks.length === 0) {
+        result.score = 0;
+        result.issues.push({
+          check: 'no_checks_evaluated',
+          message: 'Gate evaluated zero checks — nothing was actually verified',
+          severity: this.strictMode ? 'critical' : 'high',
+        });
+      } else {
+        const passedChecks = checks.filter((c) => c.passed).length;
+        result.score = (passedChecks / checks.length) * 5;
+      }
+
       // Determine verdict (AC2)
       result.verdict = this._determineVerdict(result, gateConfig);
 
@@ -279,11 +293,46 @@ class GateEvaluator {
         break;
 
       // Epic 4 checks
-      case 'plan_complete':
-        result.passed = !!epicResult.planPath || epicResult.planComplete === true;
+      case 'plan_complete': {
+        // F5: hardened but backward-compatible. When a real plan OBJECT is present
+        // (wired in via epic-4-executor), require real phases. When only a path/flag
+        // is present (legacy callers), keep the old signal so existing behavior holds.
+        const plan = epicResult.plan;
+        if (plan && typeof plan === 'object') {
+          result.passed = Array.isArray(plan.phases) && plan.phases.length > 0;
+        } else {
+          result.passed = !!epicResult.planPath || epicResult.planComplete === true;
+        }
         result.message = result.passed ? 'Implementation plan complete' : 'Plan not complete';
         result.severity = 'high';
         break;
+      }
+
+      case 'plan_is_real': {
+        // F5 (epic: orchestration-consolidation) — the gate's teeth. Honesty
+        // invariant: a degraded/stub/absent/subtask-less plan is NOT a real artifact
+        // and MUST block, not slip through. Critical severity → verdict BLOCKED.
+        const plan = epicResult.plan;
+        if (!plan || typeof plan !== 'object') {
+          result.passed = false;
+          result.message = 'No real plan object to inspect (plan absent)';
+        } else if (plan.degraded === true || plan.stub === true) {
+          result.passed = false;
+          result.message = `Plan is degraded/stub${plan.reason ? ` (${plan.reason})` : ''}`;
+        } else {
+          const phases = Array.isArray(plan.phases) ? plan.phases : [];
+          const subtaskCount = phases.reduce(
+            (n, p) => n + (Array.isArray(p.subtasks) ? p.subtasks.length : 0),
+            0,
+          );
+          result.passed = phases.length > 0 && subtaskCount > 0;
+          result.message = result.passed
+            ? `Plan is real (${phases.length} phase(s), ${subtaskCount} subtask(s))`
+            : 'Plan has no subtasks';
+        }
+        result.severity = 'critical';
+        break;
+      }
 
       case 'implementation_exists':
         result.passed = !!epicResult.implementationPath || epicResult.codeChanges?.length > 0;
@@ -342,7 +391,7 @@ class GateEvaluator {
       case 3:
         return ['spec_exists', 'complexity_assessed'];
       case 4:
-        return ['plan_complete', 'no_critical_errors'];
+        return ['plan_complete', 'plan_is_real', 'no_critical_errors'];
       case 6:
         return ['qa_report_exists', 'verdict_generated'];
       default: