scene-capability-engine 3.3.23 → 3.3.25

package/lib/commands/studio.js

@@ -4,6 +4,11 @@ const { spawnSync } = require('child_process');
 const fs = require('fs-extra');
 const chalk = require('chalk');
 const { SessionStore } = require('../runtime/session-store');
+const {
+  DOMAIN_CHAIN_RELATIVE_PATH,
+  ensureSpecDomainArtifacts
+} = require('../spec/domain-modeling');
+const { findRelatedSpecs } = require('../spec/related-specs');
 
 const STUDIO_JOB_API_VERSION = 'sce.studio.job/v0.1';
 const STAGE_ORDER = ['plan', 'generate', 'apply', 'verify', 'release'];
@@ -151,7 +156,7 @@ async function autoRecordGateFailure(failure = {}, context = {}, dependencies =
     const title = `[studio:${stage}] gate failure: ${stepId}`;
     const tags = ['studio', 'gate-failure', 'release-blocker', `stage-${stage}`];
     const fingerprint = createGateFailureFingerprint(failure, context);
-    const specRef = normalizeString(context.scene_id) || jobId;
+    const specRef = normalizeString(context.spec_id) || normalizeString(context.scene_id) || jobId;
 
     const result = await runErrorbookRecordCommand({
       title,
@@ -678,6 +683,211 @@ function resolveNextAction(job) {
   return 'complete';
 }
 
+function toRelativePosix(projectPath, absolutePath) {
+  return path.relative(projectPath, absolutePath).replace(/\\/g, '/');
+}
+
+async function readSpecDomainChain(projectPath, specId, fileSystem = fs) {
+  const specRoot = path.join(projectPath, '.sce', 'specs', specId);
+  const chainPath = path.join(specRoot, DOMAIN_CHAIN_RELATIVE_PATH);
+  if (!await fileSystem.pathExists(chainPath)) {
+    return null;
+  }
+  try {
+    const payload = await fileSystem.readJson(chainPath);
+    const stat = await fileSystem.stat(chainPath);
+    return {
+      spec_id: specId,
+      chain_path: toRelativePosix(projectPath, chainPath),
+      payload,
+      updated_at: stat && stat.mtime ? stat.mtime.toISOString() : null,
+      mtime_ms: Number(stat && stat.mtimeMs) || 0
+    };
+  } catch (_error) {
+    return null;
+  }
+}
+
+function normalizeChainList(value, limit = 5) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .filter((item) => item && (typeof item === 'string' || typeof item === 'object'))
+    .slice(0, limit)
+    .map((item) => {
+      if (typeof item === 'string') {
+        return normalizeString(item);
+      }
+      return item;
+    });
+}
+
+function summarizeDomainChain(payload = {}) {
+  const ontology = payload && typeof payload.ontology === 'object' ? payload.ontology : {};
+  const decisionPath = Array.isArray(payload.decision_execution_path) ? payload.decision_execution_path : [];
+  const correctionLoop = payload && typeof payload.correction_loop === 'object' ? payload.correction_loop : {};
+  const verification = payload && typeof payload.verification === 'object' ? payload.verification : {};
+  const hypotheses = Array.isArray(payload.hypotheses) ? payload.hypotheses : [];
+  const risks = Array.isArray(payload.risks) ? payload.risks : [];
+
+  return {
+    scene_id: normalizeString(payload.scene_id) || null,
+    spec_id: normalizeString(payload.spec_id) || null,
+    problem_statement: normalizeString(payload?.problem?.statement) || null,
+    ontology_counts: {
+      entity: Array.isArray(ontology.entity) ? ontology.entity.length : 0,
+      relation: Array.isArray(ontology.relation) ? ontology.relation.length : 0,
+      business_rule: Array.isArray(ontology.business_rule) ? ontology.business_rule.length : 0,
+      decision_policy: Array.isArray(ontology.decision_policy) ? ontology.decision_policy.length : 0,
+      execution_flow: Array.isArray(ontology.execution_flow) ? ontology.execution_flow.length : 0
+    },
+    hypothesis_count: hypotheses.length,
+    risk_count: risks.length,
+    decision_path_steps: decisionPath.length,
+    correction_loop: {
+      triggers: normalizeChainList(correctionLoop.triggers, 5),
+      actions: normalizeChainList(correctionLoop.actions, 5)
+    },
+    verification_gates: normalizeChainList(verification.gates, 6)
+  };
+}
+
+function buildDomainChainRuntimeContext(payload = {}) {
+  return {
+    scene_id: normalizeString(payload.scene_id) || null,
+    spec_id: normalizeString(payload.spec_id) || null,
+    problem: {
+      statement: normalizeString(payload?.problem?.statement) || null,
+      scope: normalizeString(payload?.problem?.scope) || null,
+      symptom: normalizeString(payload?.problem?.symptom) || null
+    },
+    ontology: {
+      entity: normalizeChainList(payload?.ontology?.entity, 20),
+      relation: normalizeChainList(payload?.ontology?.relation, 20),
+      business_rule: normalizeChainList(payload?.ontology?.business_rule, 20),
+      decision_policy: normalizeChainList(payload?.ontology?.decision_policy, 20),
+      execution_flow: normalizeChainList(payload?.ontology?.execution_flow, 20)
+    },
+    hypotheses: normalizeChainList(payload.hypotheses, 10),
+    risks: normalizeChainList(payload.risks, 10),
+    decision_execution_path: normalizeChainList(payload.decision_execution_path, 12),
+    correction_loop: {
+      triggers: normalizeChainList(payload?.correction_loop?.triggers, 10),
+      actions: normalizeChainList(payload?.correction_loop?.actions, 10)
+    },
+    verification: {
+      plan: normalizeString(payload?.verification?.plan) || null,
+      gates: normalizeChainList(payload?.verification?.gates, 10)
+    }
+  };
+}
+
+async function resolveSceneDomainChainCandidates(projectPath, sceneId, fileSystem = fs) {
+  const specsRoot = path.join(projectPath, '.sce', 'specs');
+  if (!await fileSystem.pathExists(specsRoot)) {
+    return [];
+  }
+  const entries = await fileSystem.readdir(specsRoot);
+  const candidates = [];
+  for (const entry of entries) {
+    const specRoot = path.join(specsRoot, entry);
+    let stat = null;
+    try {
+      stat = await fileSystem.stat(specRoot);
+    } catch (_error) {
+      continue;
+    }
+    if (!stat || !stat.isDirectory()) {
+      continue;
+    }
+    const chain = await readSpecDomainChain(projectPath, entry, fileSystem);
+    if (!chain) {
+      continue;
+    }
+    if (normalizeString(chain?.payload?.scene_id) !== sceneId) {
+      continue;
+    }
+    candidates.push(chain);
+  }
+  candidates.sort((left, right) => (right.mtime_ms || 0) - (left.mtime_ms || 0));
+  return candidates;
+}
+
+async function resolveDomainChainBinding(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const sceneId = normalizeString(options.sceneId);
+  const explicitSpec = normalizeString(options.specId);
+  const goal = normalizeString(options.goal);
+
+  if (explicitSpec) {
+    const specRoot = path.join(projectPath, '.sce', 'specs', explicitSpec);
+    if (!await fileSystem.pathExists(specRoot)) {
+      throw new Error(`--spec not found under .sce/specs: ${explicitSpec}`);
+    }
+    await ensureSpecDomainArtifacts(projectPath, explicitSpec, {
+      fileSystem,
+      sceneId,
+      problemStatement: goal || `Studio scene cycle for ${sceneId}`
+    });
+    const chain = await readSpecDomainChain(projectPath, explicitSpec, fileSystem);
+    if (!chain) {
+      return {
+        resolved: false,
+        source: 'explicit-spec',
+        spec_id: explicitSpec,
+        reason: 'domain_chain_missing'
+      };
+    }
+    return {
+      resolved: true,
+      source: 'explicit-spec',
+      spec_id: explicitSpec,
+      chain_path: chain.chain_path,
+      updated_at: chain.updated_at,
+      summary: summarizeDomainChain(chain.payload),
+      context: buildDomainChainRuntimeContext(chain.payload)
+    };
+  }
+
+  if (!sceneId) {
+    return {
+      resolved: false,
+      source: 'none',
+      spec_id: null,
+      reason: 'scene_id_missing'
+    };
+  }
+
+  const candidates = await resolveSceneDomainChainCandidates(projectPath, sceneId, fileSystem);
+  if (candidates.length === 0) {
+    return {
+      resolved: false,
+      source: 'none',
+      spec_id: null,
+      reason: 'no_scene_bound_domain_chain'
+    };
+  }
+
+  const selected = candidates[0];
+  return {
+    resolved: true,
+    source: candidates.length === 1 ? 'scene-auto-single' : 'scene-auto-latest',
+    spec_id: selected.spec_id,
+    chain_path: selected.chain_path,
+    updated_at: selected.updated_at,
+    candidate_count: candidates.length,
+    candidates: candidates.slice(0, 5).map((item) => ({
+      spec_id: item.spec_id,
+      chain_path: item.chain_path,
+      updated_at: item.updated_at
+    })),
+    summary: summarizeDomainChain(selected.payload),
+    context: buildDomainChainRuntimeContext(selected.payload)
+  };
+}
+
 function printStudioPayload(payload, options = {}) {
   if (options.json) {
     console.log(JSON.stringify(payload, null, 2));
@@ -731,11 +941,37 @@ function buildCommandPayload(mode, job) {
   };
 }
 
+function buildJobDomainChainMetadata(job = {}) {
+  const domainChain = job && job.source && job.source.domain_chain
+    ? job.source.domain_chain
+    : null;
+  const summary = domainChain && domainChain.summary ? domainChain.summary : null;
+  const context = domainChain && domainChain.context ? domainChain.context : null;
+  return {
+    resolved: domainChain && domainChain.resolved === true,
+    source: domainChain && domainChain.source ? domainChain.source : 'none',
+    spec_id: normalizeString(job?.source?.spec_id) || normalizeString(job?.scene?.spec_id) || null,
+    chain_path: domainChain && domainChain.chain_path ? domainChain.chain_path : null,
+    reason: domainChain && domainChain.reason ? domainChain.reason : null,
+    decision_path_steps: summary ? Number(summary.decision_path_steps || 0) : 0,
+    risk_count: summary ? Number(summary.risk_count || 0) : 0,
+    correction_triggers: summary && summary.correction_loop
+      ? normalizeChainList(summary.correction_loop.triggers, 10)
+      : [],
+    verification_gates: summary
+      ? normalizeChainList(summary.verification_gates, 10)
+      : [],
+    summary: summary || null,
+    context: context || null
+  };
+}
+
 async function runStudioPlanCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
   const fromChat = normalizeString(options.fromChat);
   const sceneId = normalizeString(options.scene);
+  const specId = normalizeString(options.spec);
 
   if (!fromChat) {
     throw new Error('--from-chat is required');
@@ -743,6 +979,33 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   if (!sceneId) {
     throw new Error('--scene is required');
   }
+  const domainChainBinding = await resolveDomainChainBinding({
+    sceneId,
+    specId,
+    goal: normalizeString(options.goal)
+  }, {
+    projectPath,
+    fileSystem
+  });
+  const relatedSpecLookup = await findRelatedSpecs({
+    query: normalizeString(options.goal),
+    sceneId,
+    limit: 8,
+    excludeSpecId: domainChainBinding.spec_id || specId || null
+  }, {
+    projectPath,
+    fileSystem
+  });
+  const relatedSpecItems = Array.isArray(relatedSpecLookup.related_specs)
+    ? relatedSpecLookup.related_specs.map((item) => ({
+      spec_id: item.spec_id,
+      scene_id: item.scene_id || null,
+      score: Number(item.score || 0),
+      reasons: Array.isArray(item.reasons) ? item.reasons : [],
+      matched_tokens: Array.isArray(item.matched_tokens) ? item.matched_tokens : [],
+      updated_at: item.updated_at || null
+    }))
+    : [];
 
   const paths = resolveStudioPaths(projectPath);
   await ensureStudioDirectories(paths, fileSystem);
@@ -762,8 +1025,17 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     metadata: {
       from_chat: fromChat,
       scene_id: sceneId,
+      spec_id: domainChainBinding.spec_id || specId || null,
       scene_session_id: sceneSessionBinding.session.session_id,
-      scene_cycle: sceneSessionBinding.scene_cycle
+      scene_cycle: sceneSessionBinding.scene_cycle,
+      domain_chain_resolved: domainChainBinding.resolved === true,
+      domain_chain_source: domainChainBinding.source || 'none',
+      domain_chain_spec_id: domainChainBinding.spec_id || null,
+      domain_chain_path: domainChainBinding.chain_path || null,
+      domain_chain_summary: domainChainBinding.summary || null,
+      domain_chain_reason: domainChainBinding.reason || null,
+      related_specs_total: Number(relatedSpecLookup.total_candidates || 0),
+      related_specs_top: relatedSpecItems
     }
   };
 
@@ -775,10 +1047,33 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     status: 'planned',
     source: {
       from_chat: fromChat,
-      goal: normalizeString(options.goal) || null
+      goal: normalizeString(options.goal) || null,
+      spec_id: domainChainBinding.spec_id || specId || null,
+      domain_chain: {
+        resolved: domainChainBinding.resolved === true,
+        source: domainChainBinding.source || 'none',
+        reason: domainChainBinding.reason || null,
+        spec_id: domainChainBinding.spec_id || null,
+        chain_path: domainChainBinding.chain_path || null,
+        candidate_count: Number.isFinite(Number(domainChainBinding.candidate_count))
+          ? Number(domainChainBinding.candidate_count)
+          : 0,
+        candidates: Array.isArray(domainChainBinding.candidates) ? domainChainBinding.candidates : [],
+        summary: domainChainBinding.summary || null,
+        context: domainChainBinding.context || null,
+        updated_at: domainChainBinding.updated_at || null
+      },
+      related_specs: {
+        query: relatedSpecLookup.query || '',
+        scene_id: relatedSpecLookup.scene_id || null,
+        total_candidates: Number(relatedSpecLookup.total_candidates || 0),
+        items: relatedSpecItems
+      }
     },
     scene: {
-      id: sceneId
+      id: sceneId,
+      spec_id: domainChainBinding.spec_id || specId || null,
+      related_spec_ids: relatedSpecItems.map((item) => item.spec_id)
     },
     session: {
       policy: 'mandatory.scene-primary',
@@ -800,9 +1095,16 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   await appendStudioEvent(paths, job, 'stage.plan.completed', {
     from_chat: fromChat,
     scene_id: sceneId,
+    spec_id: domainChainBinding.spec_id || specId || null,
     scene_session_id: sceneSessionBinding.session.session_id,
     scene_cycle: sceneSessionBinding.scene_cycle,
-    target: job.target
+    target: job.target,
+    domain_chain_resolved: domainChainBinding.resolved === true,
+    domain_chain_source: domainChainBinding.source || 'none',
+    domain_chain_spec_id: domainChainBinding.spec_id || null,
+    domain_chain_path: domainChainBinding.chain_path || null,
+    related_specs_total: Number(relatedSpecLookup.total_candidates || 0),
+    related_spec_ids: relatedSpecItems.map((item) => item.spec_id)
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
@@ -836,26 +1138,45 @@ async function runStudioGenerateCommand(options = {}, dependencies = {}) {
   }
   const sceneId = sceneArg || jobSceneId;
   const patchBundleId = normalizeString(options.patchBundle) || `patch-${sceneId}-${Date.now()}`;
+  const domainChainMetadata = buildJobDomainChainMetadata(job);
+  const generateReportPath = `${STUDIO_REPORTS_DIR}/generate-${job.job_id}.json`;
+  const generateReport = {
+    mode: 'studio-generate',
+    api_version: STUDIO_JOB_API_VERSION,
+    job_id: job.job_id,
+    scene_id: sceneId,
+    target: normalizeString(options.target) || job.target || 'default',
+    patch_bundle_id: patchBundleId,
+    generated_at: nowIso(),
+    domain_chain: domainChainMetadata
+  };
+  await writeStudioReport(projectPath, generateReportPath, generateReport, fileSystem);
 
   job.scene = job.scene || {};
   job.scene.id = sceneId;
+  job.scene.spec_id = normalizeString(job?.source?.spec_id) || normalizeString(job?.scene?.spec_id) || null;
   job.target = normalizeString(options.target) || job.target || 'default';
   job.status = 'generated';
   job.artifacts = job.artifacts || {};
   job.artifacts.patch_bundle_id = patchBundleId;
+  job.artifacts.generate_report = generateReportPath;
   job.updated_at = nowIso();
 
   ensureStageCompleted(job, 'generate', {
     scene_id: sceneId,
     target: job.target,
-    patch_bundle_id: patchBundleId
+    patch_bundle_id: patchBundleId,
+    domain_chain: domainChainMetadata,
+    report: generateReportPath
   });
 
   await saveJob(paths, job, fileSystem);
   await appendStudioEvent(paths, job, 'stage.generate.completed', {
     scene_id: sceneId,
     target: job.target,
-    patch_bundle_id: patchBundleId
+    patch_bundle_id: patchBundleId,
+    domain_chain: domainChainMetadata,
+    report: generateReportPath
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
@@ -931,6 +1252,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
 
   const verifyReportPath = `${STUDIO_REPORTS_DIR}/verify-${job.job_id}.json`;
   const verifyStartedAt = nowIso();
+  const domainChainMetadata = buildJobDomainChainMetadata(job);
   const autoErrorbookRecords = [];
   const gateSteps = await buildVerifyGateSteps({ profile }, {
     projectPath,
@@ -946,7 +1268,8 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
         stage: 'verify',
         profile,
         job_id: job.job_id,
-        scene_id: job?.scene?.id
+        scene_id: job?.scene?.id,
+        spec_id: domainChainMetadata.spec_id
       }, {
         projectPath,
         fileSystem,
@@ -971,6 +1294,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     completed_at: verifyCompletedAt,
     passed: gateResult.passed,
     steps: gateResult.steps,
+    domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   };
 
@@ -989,6 +1313,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
         profile,
         passed: false,
         report: verifyReportPath,
+        domain_chain: domainChainMetadata,
         auto_errorbook_records: autoErrorbookRecords
       }
     };
@@ -996,6 +1321,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     await appendStudioEvent(paths, job, 'stage.verify.failed', {
       profile,
       report: verifyReportPath,
+      domain_chain: domainChainMetadata,
       auto_errorbook_records: autoErrorbookRecords
     }, fileSystem);
     await writeLatestJob(paths, jobId, fileSystem);
@@ -1007,6 +1333,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     profile,
     passed: true,
     report: verifyReportPath,
+    domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   });
 
@@ -1015,6 +1342,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     profile,
     passed: true,
     report: verifyReportPath,
+    domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
@@ -1055,6 +1383,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
   const profile = normalizeString(options.profile) || 'standard';
   const releaseReportPath = `${STUDIO_REPORTS_DIR}/release-${job.job_id}.json`;
   const releaseStartedAt = nowIso();
+  const domainChainMetadata = buildJobDomainChainMetadata(job);
   const autoErrorbookRecords = [];
   const gateSteps = await buildReleaseGateSteps({ profile }, {
     projectPath,
@@ -1070,7 +1399,8 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
         stage: 'release',
         profile,
         job_id: job.job_id,
-        scene_id: job?.scene?.id
+        scene_id: job?.scene?.id,
+        spec_id: domainChainMetadata.spec_id
       }, {
         projectPath,
         fileSystem,
@@ -1097,6 +1427,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     completed_at: releaseCompletedAt,
     passed: gateResult.passed,
     steps: gateResult.steps,
+    domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   };
 
@@ -1118,6 +1449,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
         passed: false,
         report: releaseReportPath,
         auth_required: authResult.required,
+        domain_chain: domainChainMetadata,
         auto_errorbook_records: autoErrorbookRecords
       }
     };
@@ -1127,6 +1459,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
       release_ref: releaseRef,
       report: releaseReportPath,
       auth_required: authResult.required,
+      domain_chain: domainChainMetadata,
       auto_errorbook_records: autoErrorbookRecords
     }, fileSystem);
     await writeLatestJob(paths, jobId, fileSystem);
@@ -1139,6 +1472,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     release_ref: releaseRef,
     report: releaseReportPath,
     auth_required: authResult.required,
+    domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   });
 
@@ -1169,6 +1503,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     release_ref: releaseRef,
     report: releaseReportPath,
     auth_required: authResult.required,
+    domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
@@ -1320,6 +1655,7 @@ function registerStudioCommands(program) {
     .description('Create/refresh a studio plan job from chat context')
     .requiredOption('--scene <scene-id>', 'Scene identifier (mandatory primary session anchor)')
     .requiredOption('--from-chat <session>', 'Chat session identifier or transcript reference')
+    .option('--spec <spec-id>', 'Optional spec binding for domain-chain context ingestion')
     .option('--goal <goal>', 'Optional goal summary')
     .option('--target <target>', 'Target integration profile', 'default')
     .option('--job <job-id>', 'Reuse an explicit studio job id')