scene-capability-engine 3.3.25 → 3.4.5

package/lib/commands/studio.js

@@ -9,6 +9,8 @@ const {
   ensureSpecDomainArtifacts
 } = require('../spec/domain-modeling');
 const { findRelatedSpecs } = require('../spec/related-specs');
+const { captureTimelineCheckpoint } = require('../runtime/project-timeline');
+const { runProblemEvaluation } = require('../problem/problem-evaluator');
 
 const STUDIO_JOB_API_VERSION = 'sce.studio.job/v0.1';
 const STAGE_ORDER = ['plan', 'generate', 'apply', 'verify', 'release'];
@@ -966,6 +968,119 @@ function buildJobDomainChainMetadata(job = {}) {
   };
 }
 
+function summarizeProblemEvaluation(evaluation = {}) {
+  return {
+    passed: evaluation.passed === true,
+    blocked: evaluation.blocked === true,
+    confidence_score: Number(evaluation.confidence_score || 0),
+    risk_level: normalizeString(evaluation?.dimensions?.risk?.level) || 'low',
+    strategy: normalizeString(evaluation?.dimensions?.strategy?.strategy) || 'direct-execution',
+    blockers: Array.isArray(evaluation.blockers) ? evaluation.blockers : [],
+    warnings: Array.isArray(evaluation.warnings) ? evaluation.warnings : [],
+    recommendations: Array.isArray(evaluation.recommendations) ? evaluation.recommendations : [],
+    report_file: normalizeString(evaluation.report_file) || null
+  };
+}
+
+function deriveGateSignals(steps = []) {
+  const normalized = Array.isArray(steps) ? steps : [];
+  const requiredTotal = normalized.filter((step) => step && step.required !== false).length;
+  const requiredEnabled = normalized.filter((step) => step && step.required !== false && step.enabled !== false).length;
+  return {
+    required_total: requiredTotal,
+    required_enabled: requiredEnabled,
+    required_missing: Math.max(0, requiredTotal - requiredEnabled)
+  };
+}
+
+function buildStageReadiness(job = {}, stage = '', overrides = {}) {
+  const normalizedStage = normalizeString(stage).toLowerCase();
+  const patchBundleReady = normalizeString(job?.artifacts?.patch_bundle_id).length > 0;
+  const verifyReportReady = normalizeString(job?.artifacts?.verify_report).length > 0;
+  const readiness = {
+    prerequisites_ready: true,
+    rollback_ready: isStageCompleted(job, 'apply'),
+    patch_bundle_ready: patchBundleReady,
+    verify_report_ready: verifyReportReady
+  };
+
+  if (normalizedStage === 'generate') {
+    readiness.prerequisites_ready = isStageCompleted(job, 'plan');
+  } else if (normalizedStage === 'apply') {
+    readiness.prerequisites_ready = isStageCompleted(job, 'generate');
+  } else if (normalizedStage === 'verify') {
+    readiness.prerequisites_ready = isStageCompleted(job, 'apply');
+  } else if (normalizedStage === 'release') {
+    readiness.prerequisites_ready = isStageCompleted(job, 'verify');
+  }
+
+  return {
+    ...readiness,
+    ...overrides
+  };
+}
+
+function assignProblemEvalArtifact(job = {}, stage = '', evaluation = {}) {
+  const normalizedStage = normalizeString(stage).toLowerCase();
+  if (!normalizedStage) {
+    return;
+  }
+  job.artifacts = job.artifacts || {};
+  const reports = job.artifacts.problem_eval_reports && typeof job.artifacts.problem_eval_reports === 'object'
+    ? job.artifacts.problem_eval_reports
+    : {};
+  reports[normalizedStage] = normalizeString(evaluation.report_file) || null;
+  job.artifacts.problem_eval_reports = reports;
+}
+
+async function enforceProblemEvaluationForStage(job = {}, stage = '', context = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const evaluation = await runProblemEvaluation({
+    stage,
+    job_id: normalizeString(job.job_id),
+    scene_id: normalizeString(context.scene_id || job?.scene?.id),
+    spec_id: normalizeString(context.spec_id || job?.source?.spec_id || job?.scene?.spec_id),
+    goal: normalizeString(context.goal || job?.source?.goal),
+    release_channel: normalizeString(context.release_channel || ''),
+    domain_chain: context.domain_chain || (job?.source?.domain_chain || {}),
+    related_specs_count: Number(context.related_specs_count || job?.source?.related_specs?.total_candidates || 0),
+    stage_readiness: context.stage_readiness || buildStageReadiness(job, stage),
+    gate_signals: context.gate_signals || {}
+  }, {
+    projectPath,
+    fileSystem,
+    env: dependencies.env,
+    writeReport: true
+  });
+  assignProblemEvalArtifact(job, stage, evaluation);
+  return evaluation;
+}
+
+async function markStudioStageBlockedByProblemEval(paths, job, stageName, evaluation, fileSystem = fs) {
+  const summary = summarizeProblemEvaluation(evaluation);
+  job.status = `${stageName}_blocked`;
+  job.updated_at = nowIso();
+  job.stages = job.stages || createStageState();
+  job.stages[stageName] = {
+    status: 'blocked',
+    completed_at: null,
+    metadata: {
+      problem_evaluation: summary
+    }
+  };
+  await saveJob(paths, job, fileSystem);
+  await appendStudioEvent(paths, job, `stage.${stageName}.blocked`, {
+    problem_evaluation: summary
+  }, fileSystem);
+  await writeLatestJob(paths, job.job_id, fileSystem);
+
+  const reason = summary.blockers.length > 0
+    ? summary.blockers.join(', ')
+    : 'problem-evaluation-policy';
+  throw new Error(`studio ${stageName} blocked by problem evaluation: ${reason}`);
+}
+
 async function runStudioPlanCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
@@ -1012,6 +1127,51 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
 
   const jobId = normalizeString(options.job) || createJobId();
   const now = nowIso();
+  const planShadowJob = {
+    job_id: jobId,
+    scene: {
+      id: sceneId,
+      spec_id: domainChainBinding.spec_id || specId || null
+    },
+    source: {
+      goal: normalizeString(options.goal) || null,
+      spec_id: domainChainBinding.spec_id || specId || null,
+      domain_chain: {
+        resolved: domainChainBinding.resolved === true,
+        summary: domainChainBinding.summary || null
+      },
+      related_specs: {
+        total_candidates: Number(relatedSpecLookup.total_candidates || 0)
+      }
+    },
+    artifacts: {}
+  };
+  const planProblemEvaluation = await enforceProblemEvaluationForStage(planShadowJob, 'plan', {
+    scene_id: sceneId,
+    spec_id: domainChainBinding.spec_id || specId || null,
+    goal: normalizeString(options.goal) || null,
+    domain_chain: {
+      resolved: domainChainBinding.resolved === true,
+      summary: domainChainBinding.summary || null
+    },
+    related_specs_count: Number(relatedSpecLookup.total_candidates || 0),
+    stage_readiness: {
+      prerequisites_ready: true,
+      rollback_ready: false,
+      patch_bundle_ready: false,
+      verify_report_ready: false
+    }
+  }, {
+    projectPath,
+    fileSystem,
+    env: dependencies.env
+  });
+  if (!planProblemEvaluation.passed) {
+    const blockers = Array.isArray(planProblemEvaluation.blockers) && planProblemEvaluation.blockers.length > 0
+      ? planProblemEvaluation.blockers.join(', ')
+      : 'problem-evaluation-policy';
+    throw new Error(`studio plan blocked by problem evaluation: ${blockers}`);
+  }
   const stages = createStageState();
   const sessionStore = dependencies.sessionStore || new SessionStore(projectPath);
   const sceneSessionBinding = await sessionStore.beginSceneSession({
@@ -1034,6 +1194,7 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
       domain_chain_path: domainChainBinding.chain_path || null,
       domain_chain_summary: domainChainBinding.summary || null,
       domain_chain_reason: domainChainBinding.reason || null,
+      problem_evaluation: summarizeProblemEvaluation(planProblemEvaluation),
       related_specs_total: Number(relatedSpecLookup.total_candidates || 0),
       related_specs_top: relatedSpecItems
     }
@@ -1087,7 +1248,10 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     artifacts: {
       patch_bundle_id: null,
       verify_report: null,
-      release_ref: null
+      release_ref: null,
+      problem_eval_reports: {
+        plan: normalizeString(planProblemEvaluation.report_file) || null
+      }
     }
   };
 
@@ -1103,6 +1267,7 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     domain_chain_source: domainChainBinding.source || 'none',
     domain_chain_spec_id: domainChainBinding.spec_id || null,
     domain_chain_path: domainChainBinding.chain_path || null,
+    problem_evaluation: summarizeProblemEvaluation(planProblemEvaluation),
     related_specs_total: Number(relatedSpecLookup.total_candidates || 0),
     related_spec_ids: relatedSpecItems.map((item) => item.spec_id)
   }, fileSystem);
@@ -1137,6 +1302,21 @@ async function runStudioGenerateCommand(options = {}, dependencies = {}) {
     throw new Error(`Scene mismatch: planned scene is "${jobSceneId}" but --scene provided "${sceneArg}"`);
   }
   const sceneId = sceneArg || jobSceneId;
+  const generateProblemEvaluation = await enforceProblemEvaluationForStage(job, 'generate', {
+    scene_id: sceneId,
+    spec_id: normalizeString(job?.source?.spec_id) || normalizeString(job?.scene?.spec_id) || null,
+    goal: normalizeString(job?.source?.goal),
+    domain_chain: job?.source?.domain_chain || {},
+    related_specs_count: Number(job?.source?.related_specs?.total_candidates || 0),
+    stage_readiness: buildStageReadiness(job, 'generate')
+  }, {
+    projectPath,
+    fileSystem,
+    env: dependencies.env
+  });
+  if (!generateProblemEvaluation.passed) {
+    await markStudioStageBlockedByProblemEval(paths, job, 'generate', generateProblemEvaluation, fileSystem);
+  }
   const patchBundleId = normalizeString(options.patchBundle) || `patch-${sceneId}-${Date.now()}`;
   const domainChainMetadata = buildJobDomainChainMetadata(job);
   const generateReportPath = `${STUDIO_REPORTS_DIR}/generate-${job.job_id}.json`;
@@ -1166,6 +1346,7 @@ async function runStudioGenerateCommand(options = {}, dependencies = {}) {
     scene_id: sceneId,
     target: job.target,
     patch_bundle_id: patchBundleId,
+    problem_evaluation: summarizeProblemEvaluation(generateProblemEvaluation),
     domain_chain: domainChainMetadata,
     report: generateReportPath
   });
@@ -1175,6 +1356,7 @@ async function runStudioGenerateCommand(options = {}, dependencies = {}) {
     scene_id: sceneId,
     target: job.target,
     patch_bundle_id: patchBundleId,
+    problem_evaluation: summarizeProblemEvaluation(generateProblemEvaluation),
     domain_chain: domainChainMetadata,
     report: generateReportPath
   }, fileSystem);
@@ -1210,6 +1392,23 @@ async function runStudioApplyCommand(options = {}, dependencies = {}) {
   if (!patchBundleId) {
     throw new Error('--patch-bundle is required (or generate stage must provide one)');
   }
+  const applyProblemEvaluation = await enforceProblemEvaluationForStage(job, 'apply', {
+    scene_id: normalizeString(job?.scene?.id),
+    spec_id: normalizeString(job?.source?.spec_id) || normalizeString(job?.scene?.spec_id) || null,
+    goal: normalizeString(job?.source?.goal),
+    domain_chain: job?.source?.domain_chain || {},
+    related_specs_count: Number(job?.source?.related_specs?.total_candidates || 0),
+    stage_readiness: buildStageReadiness(job, 'apply', {
+      patch_bundle_ready: normalizeString(patchBundleId).length > 0
+    })
+  }, {
+    projectPath,
+    fileSystem,
+    env: dependencies.env
+  });
+  if (!applyProblemEvaluation.passed) {
+    await markStudioStageBlockedByProblemEval(paths, job, 'apply', applyProblemEvaluation, fileSystem);
+  }
 
   job.status = 'applied';
   job.artifacts = job.artifacts || {};
@@ -1218,13 +1417,15 @@ async function runStudioApplyCommand(options = {}, dependencies = {}) {
 
   ensureStageCompleted(job, 'apply', {
     patch_bundle_id: patchBundleId,
-    auth_required: authResult.required
+    auth_required: authResult.required,
+    problem_evaluation: summarizeProblemEvaluation(applyProblemEvaluation)
   });
 
   await saveJob(paths, job, fileSystem);
   await appendStudioEvent(paths, job, 'stage.apply.completed', {
     patch_bundle_id: patchBundleId,
-    auth_required: authResult.required
+    auth_required: authResult.required,
+    problem_evaluation: summarizeProblemEvaluation(applyProblemEvaluation)
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
@@ -1258,6 +1459,24 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     projectPath,
     fileSystem
   });
+  const verifyProblemEvaluation = await enforceProblemEvaluationForStage(job, 'verify', {
+    scene_id: normalizeString(job?.scene?.id),
+    spec_id: normalizeString(domainChainMetadata.spec_id) || normalizeString(job?.source?.spec_id),
+    goal: normalizeString(job?.source?.goal),
+    domain_chain: job?.source?.domain_chain || {},
+    related_specs_count: Number(job?.source?.related_specs?.total_candidates || 0),
+    stage_readiness: buildStageReadiness(job, 'verify', {
+      gate_required_ready: deriveGateSignals(gateSteps).required_missing === 0
+    }),
+    gate_signals: deriveGateSignals(gateSteps)
+  }, {
+    projectPath,
+    fileSystem,
+    env: dependencies.env
+  });
+  if (!verifyProblemEvaluation.passed) {
+    await markStudioStageBlockedByProblemEval(paths, job, 'verify', verifyProblemEvaluation, fileSystem);
+  }
   const gateResult = await executeGateSteps(gateSteps, {
     projectPath,
     commandRunner: dependencies.commandRunner,
@@ -1295,6 +1514,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     passed: gateResult.passed,
     steps: gateResult.steps,
     domain_chain: domainChainMetadata,
+    problem_evaluation: summarizeProblemEvaluation(verifyProblemEvaluation),
     auto_errorbook_records: autoErrorbookRecords
   };
 
@@ -1313,6 +1533,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
         profile,
         passed: false,
         report: verifyReportPath,
+        problem_evaluation: summarizeProblemEvaluation(verifyProblemEvaluation),
         domain_chain: domainChainMetadata,
         auto_errorbook_records: autoErrorbookRecords
       }
@@ -1321,6 +1542,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     await appendStudioEvent(paths, job, 'stage.verify.failed', {
       profile,
       report: verifyReportPath,
+      problem_evaluation: summarizeProblemEvaluation(verifyProblemEvaluation),
       domain_chain: domainChainMetadata,
       auto_errorbook_records: autoErrorbookRecords
     }, fileSystem);
@@ -1333,6 +1555,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     profile,
     passed: true,
     report: verifyReportPath,
+    problem_evaluation: summarizeProblemEvaluation(verifyProblemEvaluation),
     domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   });
@@ -1342,6 +1565,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     profile,
     passed: true,
     report: verifyReportPath,
+    problem_evaluation: summarizeProblemEvaluation(verifyProblemEvaluation),
     domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   }, fileSystem);
@@ -1389,6 +1613,26 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     projectPath,
     fileSystem
   });
+  const releaseGateSignals = deriveGateSignals(gateSteps);
+  const releaseProblemEvaluation = await enforceProblemEvaluationForStage(job, 'release', {
+    scene_id: normalizeString(job?.scene?.id),
+    spec_id: normalizeString(domainChainMetadata.spec_id) || normalizeString(job?.source?.spec_id),
+    goal: normalizeString(job?.source?.goal),
+    release_channel: channel,
+    domain_chain: job?.source?.domain_chain || {},
+    related_specs_count: Number(job?.source?.related_specs?.total_candidates || 0),
+    stage_readiness: buildStageReadiness(job, 'release', {
+      gate_required_ready: releaseGateSignals.required_missing === 0
+    }),
+    gate_signals: releaseGateSignals
+  }, {
+    projectPath,
+    fileSystem,
+    env: dependencies.env
+  });
+  if (!releaseProblemEvaluation.passed) {
+    await markStudioStageBlockedByProblemEval(paths, job, 'release', releaseProblemEvaluation, fileSystem);
+  }
   const gateResult = await executeGateSteps(gateSteps, {
     projectPath,
     commandRunner: dependencies.commandRunner,
@@ -1428,6 +1672,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     passed: gateResult.passed,
     steps: gateResult.steps,
     domain_chain: domainChainMetadata,
+    problem_evaluation: summarizeProblemEvaluation(releaseProblemEvaluation),
     auto_errorbook_records: autoErrorbookRecords
   };
 
@@ -1449,6 +1694,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
         passed: false,
         report: releaseReportPath,
         auth_required: authResult.required,
+        problem_evaluation: summarizeProblemEvaluation(releaseProblemEvaluation),
         domain_chain: domainChainMetadata,
         auto_errorbook_records: autoErrorbookRecords
       }
@@ -1459,6 +1705,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
       release_ref: releaseRef,
       report: releaseReportPath,
       auth_required: authResult.required,
+      problem_evaluation: summarizeProblemEvaluation(releaseProblemEvaluation),
       domain_chain: domainChainMetadata,
       auto_errorbook_records: autoErrorbookRecords
     }, fileSystem);
@@ -1472,6 +1719,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     release_ref: releaseRef,
     report: releaseReportPath,
     auth_required: authResult.required,
+    problem_evaluation: summarizeProblemEvaluation(releaseProblemEvaluation),
     domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   });
@@ -1503,6 +1751,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     release_ref: releaseRef,
     report: releaseReportPath,
     auth_required: authResult.required,
+    problem_evaluation: summarizeProblemEvaluation(releaseProblemEvaluation),
     domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   }, fileSystem);
@@ -1636,8 +1885,30 @@ async function runStudioEventsCommand(options = {}, dependencies = {}) {
   return payload;
 }
 
-async function runStudioCommand(handler, options) {
+async function runStudioCommand(handler, options, stageName = '') {
   try {
+    const stage = normalizeString(stageName) || 'unknown';
+    const sceneId = normalizeString(options && options.scene);
+    const summaryGoal = normalizeString(options && options.goal);
+    const fromChat = normalizeString(options && options.fromChat);
+    const summaryParts = [
+      'studio',
+      stage,
+      sceneId ? `scene=${sceneId}` : '',
+      summaryGoal ? `goal=${summaryGoal}` : '',
+      fromChat ? `chat=${fromChat}` : ''
+    ].filter(Boolean);
+
+    await captureTimelineCheckpoint({
+      trigger: 'key-event',
+      event: `studio.${stage}`,
+      summary: summaryParts.join(' | '),
+      command: `sce studio ${stage}`.trim(),
+      sceneId
+    }, {
+      projectPath: process.cwd()
+    });
+
     await handler(options);
   } catch (error) {
     console.error(chalk.red(`Studio command failed: ${error.message}`));
@@ -1660,7 +1931,7 @@ function registerStudioCommands(program) {
     .option('--target <target>', 'Target integration profile', 'default')
     .option('--job <job-id>', 'Reuse an explicit studio job id')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioPlanCommand, options));
+    .action(async (options) => runStudioCommand(runStudioPlanCommand, options, 'plan'));
 
   studio
     .command('generate')
@@ -1670,7 +1941,7 @@ function registerStudioCommands(program) {
     .option('--patch-bundle <id>', 'Explicit patch bundle id')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioGenerateCommand, options));
+    .action(async (options) => runStudioCommand(runStudioGenerateCommand, options, 'generate'));
 
   studio
     .command('apply')
@@ -1680,7 +1951,7 @@ function registerStudioCommands(program) {
     .option('--require-auth', 'Require authorization even when policy is advisory')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioApplyCommand, options));
+    .action(async (options) => runStudioCommand(runStudioApplyCommand, options, 'apply'));
 
   studio
     .command('verify')
@@ -1688,7 +1959,7 @@ function registerStudioCommands(program) {
     .option('--profile <profile>', 'Verification profile', 'standard')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioVerifyCommand, options));
+    .action(async (options) => runStudioCommand(runStudioVerifyCommand, options, 'verify'));
 
   studio
     .command('release')
@@ -1700,14 +1971,14 @@ function registerStudioCommands(program) {
     .option('--release-ref <ref>', 'Explicit release reference/tag')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioReleaseCommand, options));
+    .action(async (options) => runStudioCommand(runStudioReleaseCommand, options, 'release'));
 
   studio
     .command('resume')
     .description('Inspect current studio job and next action')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioResumeCommand, options));
+    .action(async (options) => runStudioCommand(runStudioResumeCommand, options, 'resume'));
 
   studio
     .command('events')
@@ -1715,7 +1986,7 @@ function registerStudioCommands(program) {
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--limit <number>', 'Maximum number of recent events to return', '50')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioEventsCommand, options));
+    .action(async (options) => runStudioCommand(runStudioEventsCommand, options, 'events'));
 
   studio
     .command('rollback')
@@ -1725,7 +1996,7 @@ function registerStudioCommands(program) {
     .option('--auth-password <password>', 'Authorization password for protected rollback action')
     .option('--require-auth', 'Require authorization even when policy is advisory')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioRollbackCommand, options));
+    .action(async (options) => runStudioCommand(runStudioRollbackCommand, options, 'rollback'));
 }
 
 module.exports = {