scene-capability-engine 3.4.6 → 3.5.1

package/lib/commands/studio.js

@@ -11,6 +11,12 @@ const {
 const { findRelatedSpecs } = require('../spec/related-specs');
 const { captureTimelineCheckpoint } = require('../runtime/project-timeline');
 const { runProblemEvaluation } = require('../problem/problem-evaluator');
+const {
+  loadStudioIntakePolicy,
+  runStudioAutoIntake,
+  runStudioSpecGovernance,
+  runStudioSceneBackfill
+} = require('../studio/spec-intake-governor');
 
 const STUDIO_JOB_API_VERSION = 'sce.studio.job/v0.1';
 const STAGE_ORDER = ['plan', 'generate', 'apply', 'verify', 'release'];
@@ -1343,6 +1349,9 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   const fromChat = normalizeString(options.fromChat);
   const sceneId = normalizeString(options.scene);
   const specId = normalizeString(options.spec);
+  const goal = normalizeString(options.goal);
+  const manualSpecMode = options.manualSpec === true;
+  const skipSpecGovernance = options.specGovernance === false;
 
   if (!fromChat) {
     throw new Error('--from-chat is required');
@@ -1350,16 +1359,32 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   if (!sceneId) {
     throw new Error('--scene is required');
   }
-  const domainChainBinding = await resolveDomainChainBinding({
+
+  const intakePolicyBundle = await loadStudioIntakePolicy(projectPath, fileSystem);
+  const intakePolicy = intakePolicyBundle.policy || {};
+  const governancePolicy = intakePolicy.governance || {};
+  if (manualSpecMode && intakePolicy.allow_manual_spec_override !== true) {
+    throw new Error(
+      '--manual-spec is disabled by studio intake policy (allow_manual_spec_override=false)'
+    );
+  }
+  if (skipSpecGovernance && governancePolicy.require_auto_on_plan !== false) {
+    throw new Error(
+      '--no-spec-governance is disabled by studio intake policy (governance.require_auto_on_plan=true)'
+    );
+  }
+
+  let domainChainBinding = await resolveDomainChainBinding({
     sceneId,
     specId,
-    goal: normalizeString(options.goal)
+    goal
   }, {
     projectPath,
     fileSystem
   });
-  const relatedSpecLookup = await findRelatedSpecs({
-    query: normalizeString(options.goal),
+
+  let relatedSpecLookup = await findRelatedSpecs({
+    query: goal,
     sceneId,
     limit: 8,
     excludeSpecId: domainChainBinding.spec_id || specId || null
@@ -1367,6 +1392,45 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     projectPath,
     fileSystem
   });
+
+  const intake = await runStudioAutoIntake({
+    scene_id: sceneId,
+    from_chat: fromChat,
+    goal,
+    explicit_spec_id: specId,
+    domain_chain_binding: domainChainBinding,
+    related_specs: relatedSpecLookup,
+    apply: !manualSpecMode,
+    skip: manualSpecMode
+  }, {
+    projectPath,
+    fileSystem
+  });
+
+  const intakeSpecId = normalizeString(intake && intake.selected_spec_id);
+  const effectiveSpecId = intakeSpecId || normalizeString(domainChainBinding.spec_id) || specId || null;
+
+  if (effectiveSpecId && effectiveSpecId !== normalizeString(domainChainBinding.spec_id)) {
+    domainChainBinding = await resolveDomainChainBinding({
+      sceneId,
+      specId: effectiveSpecId,
+      goal
+    }, {
+      projectPath,
+      fileSystem
+    });
+  }
+
+  relatedSpecLookup = await findRelatedSpecs({
+    query: goal,
+    sceneId,
+    limit: 8,
+    excludeSpecId: effectiveSpecId || null
+  }, {
+    projectPath,
+    fileSystem
+  });
+
   const relatedSpecItems = Array.isArray(relatedSpecLookup.related_specs)
     ? relatedSpecLookup.related_specs.map((item) => ({
       spec_id: item.spec_id,
@@ -1387,7 +1451,7 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     domainChainBinding.problem_contract || {},
     {
       scene_id: sceneId,
-      goal: normalizeString(options.goal),
+      goal,
       problem_statement: normalizeString(domainChainBinding?.summary?.problem_statement),
       verification_plan: normalizeString(domainChainBinding?.summary?.verification_plan)
     }
@@ -1396,11 +1460,11 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     job_id: jobId,
     scene: {
       id: sceneId,
-      spec_id: domainChainBinding.spec_id || specId || null
+      spec_id: effectiveSpecId
     },
     source: {
-      goal: normalizeString(options.goal) || null,
-      spec_id: domainChainBinding.spec_id || specId || null,
+      goal: goal || null,
+      spec_id: effectiveSpecId,
       problem_contract: problemContract,
       problem_contract_path: domainChainBinding.problem_contract_path || null,
       domain_chain: {
@@ -1415,8 +1479,8 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   };
   const planProblemEvaluation = await enforceProblemEvaluationForStage(planShadowJob, 'plan', {
     scene_id: sceneId,
-    spec_id: domainChainBinding.spec_id || specId || null,
-    goal: normalizeString(options.goal) || null,
+    spec_id: effectiveSpecId,
+    goal: goal || null,
     problem_contract: problemContract,
     domain_chain: {
       resolved: domainChainBinding.resolved === true,
@@ -1444,16 +1508,35 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   const sessionStore = dependencies.sessionStore || new SessionStore(projectPath);
   const sceneSessionBinding = await sessionStore.beginSceneSession({
     sceneId,
-    objective: normalizeString(options.goal) || `Studio scene cycle for ${sceneId}`,
+    objective: goal || `Studio scene cycle for ${sceneId}`,
     tool: normalizeString(options.tool) || 'generic'
   });
+
+  let governanceSnapshot = null;
+  let governanceWarning = '';
+  const autoRunGovernance = !(skipSpecGovernance)
+    && (!intake || !intake.policy || !intake.policy.governance || intake.policy.governance.auto_run_on_plan !== false);
+  if (autoRunGovernance) {
+    try {
+      governanceSnapshot = await runStudioSpecGovernance({
+        apply: true,
+        scene: sceneId
+      }, {
+        projectPath,
+        fileSystem
+      });
+    } catch (error) {
+      governanceWarning = normalizeString(error && error.message);
+    }
+  }
+
   stages.plan = {
     status: 'completed',
     completed_at: now,
     metadata: {
       from_chat: fromChat,
       scene_id: sceneId,
-      spec_id: domainChainBinding.spec_id || specId || null,
+      spec_id: effectiveSpecId,
       scene_session_id: sceneSessionBinding.session.session_id,
       scene_cycle: sceneSessionBinding.scene_cycle,
       domain_chain_resolved: domainChainBinding.resolved === true,
@@ -1463,7 +1546,18 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
       domain_chain_summary: domainChainBinding.summary || null,
       domain_chain_reason: domainChainBinding.reason || null,
       problem_contract: problemContract,
+      intake: intake ? {
+        enabled: intake.enabled === true,
+        intent_type: intake.intent ? intake.intent.intent_type : null,
+        decision_action: intake.decision ? intake.decision.action : null,
+        decision_reason: intake.decision ? intake.decision.reason : null,
+        selected_spec_id: intake.selected_spec_id || effectiveSpecId || null,
+        created_spec_id: intake.created_spec && intake.created_spec.created ? intake.created_spec.spec_id : null,
+        policy_path: intake.policy_path || null
+      } : null,
       problem_evaluation: summarizeProblemEvaluation(planProblemEvaluation),
+      spec_governance: governanceSnapshot ? governanceSnapshot.summary : null,
+      spec_governance_warning: governanceWarning || null,
       related_specs_total: Number(relatedSpecLookup.total_candidates || 0),
       related_specs_top: relatedSpecItems
     }
@@ -1477,15 +1571,24 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     status: 'planned',
     source: {
       from_chat: fromChat,
-      goal: normalizeString(options.goal) || null,
-      spec_id: domainChainBinding.spec_id || specId || null,
+      goal: goal || null,
+      spec_id: effectiveSpecId,
       problem_contract: problemContract,
       problem_contract_path: domainChainBinding.problem_contract_path || null,
+      intake: intake ? {
+        enabled: intake.enabled === true,
+        policy_path: intake.policy_path || null,
+        policy_loaded_from: intake.policy_loaded_from || null,
+        intent: intake.intent || null,
+        decision: intake.decision || null,
+        selected_spec_id: intake.selected_spec_id || effectiveSpecId || null,
+        created_spec: intake.created_spec || null
+      } : null,
       domain_chain: {
         resolved: domainChainBinding.resolved === true,
         source: domainChainBinding.source || 'none',
         reason: domainChainBinding.reason || null,
-        spec_id: domainChainBinding.spec_id || null,
+        spec_id: effectiveSpecId || domainChainBinding.spec_id || null,
         chain_path: domainChainBinding.chain_path || null,
         candidate_count: Number.isFinite(Number(domainChainBinding.candidate_count))
           ? Number(domainChainBinding.candidate_count)
@@ -1500,11 +1603,20 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
         scene_id: relatedSpecLookup.scene_id || null,
         total_candidates: Number(relatedSpecLookup.total_candidates || 0),
         items: relatedSpecItems
-      }
+      },
+      spec_governance: governanceSnapshot
+        ? {
+          status: governanceSnapshot.summary ? governanceSnapshot.summary.status : null,
+          alert_count: governanceSnapshot.summary ? Number(governanceSnapshot.summary.alert_count || 0) : 0,
+          report_file: governanceSnapshot.report_file || null,
+          scene_index_file: governanceSnapshot.scene_index_file || null
+        }
+        : null,
+      spec_governance_warning: governanceWarning || null
     },
     scene: {
       id: sceneId,
-      spec_id: domainChainBinding.spec_id || specId || null,
+      spec_id: effectiveSpecId,
       related_spec_ids: relatedSpecItems.map((item) => item.spec_id)
     },
     session: {
@@ -1520,6 +1632,12 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
       patch_bundle_id: null,
       verify_report: null,
       release_ref: null,
+      spec_portfolio_report: governanceSnapshot && governanceSnapshot.report_file
+        ? governanceSnapshot.report_file
+        : null,
+      spec_scene_index: governanceSnapshot && governanceSnapshot.scene_index_file
+        ? governanceSnapshot.scene_index_file
+        : null,
       problem_eval_reports: {
         plan: normalizeString(planProblemEvaluation.report_file) || null
       }
@@ -1530,7 +1648,7 @@ 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,
+    spec_id: effectiveSpecId,
     scene_session_id: sceneSessionBinding.session.session_id,
     scene_cycle: sceneSessionBinding.scene_cycle,
     target: job.target,
@@ -1539,13 +1657,27 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     domain_chain_spec_id: domainChainBinding.spec_id || null,
     domain_chain_path: domainChainBinding.chain_path || null,
     problem_contract: problemContract,
+    intake_action: intake && intake.decision ? intake.decision.action : null,
+    intake_reason: intake && intake.decision ? intake.decision.reason : null,
+    intake_selected_spec_id: intake ? intake.selected_spec_id || effectiveSpecId || null : effectiveSpecId,
+    intake_created_spec_id: intake && intake.created_spec && intake.created_spec.created
+      ? intake.created_spec.spec_id
+      : null,
     problem_evaluation: summarizeProblemEvaluation(planProblemEvaluation),
+    spec_governance: governanceSnapshot ? governanceSnapshot.summary : null,
+    spec_governance_warning: governanceWarning || null,
     related_specs_total: Number(relatedSpecLookup.total_candidates || 0),
     related_spec_ids: relatedSpecItems.map((item) => item.spec_id)
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
   const payload = buildCommandPayload('studio-plan', job);
+  payload.scene = {
+    id: sceneId,
+    spec_id: effectiveSpecId
+  };
+  payload.intake = job.source && job.source.intake ? job.source.intake : null;
+  payload.spec_governance = governanceSnapshot ? governanceSnapshot.summary : null;
   printStudioPayload(payload, options);
   return payload;
 }
@@ -2178,6 +2310,152 @@ async function runStudioEventsCommand(options = {}, dependencies = {}) {
   return payload;
 }
 
+function printStudioIntakePayload(payload, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue('Studio intake'));
+  console.log(`  Scene: ${payload.scene_id || 'n/a'}`);
+  console.log(`  Goal: ${payload.goal || '(empty)'}`);
+  console.log(`  Intent: ${payload.intent && payload.intent.intent_type ? payload.intent.intent_type : 'unknown'}`);
+  console.log(`  Decision: ${payload.decision && payload.decision.action ? payload.decision.action : 'none'}`);
+  console.log(`  Spec: ${payload.selected_spec_id || 'n/a'}`);
+}
+
+async function runStudioIntakeCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const sceneId = normalizeString(options.scene);
+  const fromChat = normalizeString(options.fromChat);
+  const goal = normalizeString(options.goal);
+  const specId = normalizeString(options.spec);
+
+  if (!sceneId) {
+    throw new Error('--scene is required');
+  }
+  if (!fromChat) {
+    throw new Error('--from-chat is required');
+  }
+
+  const domainChainBinding = await resolveDomainChainBinding({
+    sceneId,
+    specId,
+    goal
+  }, {
+    projectPath,
+    fileSystem
+  });
+
+  const relatedSpecLookup = await findRelatedSpecs({
+    query: goal,
+    sceneId,
+    limit: 8,
+    excludeSpecId: domainChainBinding.spec_id || specId || null
+  }, {
+    projectPath,
+    fileSystem
+  });
+
+  const intake = await runStudioAutoIntake({
+    scene_id: sceneId,
+    from_chat: fromChat,
+    goal,
+    explicit_spec_id: specId,
+    domain_chain_binding: domainChainBinding,
+    related_specs: relatedSpecLookup,
+    apply: options.apply === true,
+    skip: options.manualSpec === true
+  }, {
+    projectPath,
+    fileSystem
+  });
+
+  const payload = {
+    ...intake,
+    domain_chain_source: domainChainBinding.source || 'none',
+    domain_chain_spec_id: domainChainBinding.spec_id || null,
+    related_specs_total: Number(relatedSpecLookup.total_candidates || 0)
+  };
+  printStudioIntakePayload(payload, options);
+  return payload;
+}
+
+function printStudioPortfolioPayload(payload, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  const summary = payload.summary || {};
+  console.log(chalk.blue('Studio portfolio governance'));
+  console.log(`  Status: ${summary.status || 'unknown'}`);
+  console.log(`  Scenes: ${summary.scene_count || 0}`);
+  console.log(`  Specs: ${summary.total_specs || 0}`);
+  console.log(`  Active: ${summary.active_specs || 0}`);
+  console.log(`  Completed: ${summary.completed_specs || 0}`);
+  console.log(`  Stale: ${summary.stale_specs || 0}`);
+  console.log(`  Duplicate pairs: ${summary.duplicate_pairs || 0}`);
+  console.log(`  Overflow scenes: ${summary.overflow_scenes || 0}`);
+}
+
+function printStudioBackfillPayload(payload, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(chalk.blue('Studio scene backfill'));
+  console.log(`  Source scene: ${payload.source_scene || 'scene.unassigned'}`);
+  console.log(`  Candidates: ${payload.summary ? payload.summary.candidate_count : 0}`);
+  console.log(`  Changed: ${payload.summary ? payload.summary.changed_count : 0}`);
+  console.log(`  Apply: ${payload.apply ? 'yes' : 'no'}`);
+  console.log(`  Override file: ${payload.override_file || 'n/a'}`);
+}
+
+async function runStudioPortfolioCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const payload = await runStudioSpecGovernance({
+    scene: normalizeString(options.scene),
+    apply: options.apply !== false
+  }, {
+    projectPath,
+    fileSystem
+  });
+
+  if (options.strict && payload.summary && Number(payload.summary.alert_count || 0) > 0) {
+    throw new Error(
+      `studio portfolio governance has alerts: ${payload.summary.alert_count} (duplicate/stale/overflow)`
+    );
+  }
+
+  printStudioPortfolioPayload(payload, options);
+  return payload;
+}
+
+async function runStudioBackfillSpecScenesCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const backfillOptions = {
+    scene: normalizeString(options.scene),
+    all: options.all === true,
+    limit: options.limit,
+    apply: options.apply === true,
+    refresh_governance: options.refreshGovernance !== false
+  };
+  if (options.activeOnly === true) {
+    backfillOptions.active_only = true;
+  }
+
+  const payload = await runStudioSceneBackfill(backfillOptions, {
+    projectPath,
+    fileSystem
+  });
+
+  printStudioBackfillPayload(payload, options);
+  return payload;
+}
+
 async function runStudioCommand(handler, options, stageName = '') {
   try {
     const stage = normalizeString(stageName) || 'unknown';
@@ -2221,11 +2499,46 @@ function registerStudioCommands(program) {
     .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('--manual-spec', 'Legacy bypass flag (disabled by default policy)')
     .option('--target <target>', 'Target integration profile', 'default')
+    .option('--no-spec-governance', 'Legacy bypass flag (disabled by default policy)')
     .option('--job <job-id>', 'Reuse an explicit studio job id')
     .option('--json', 'Print machine-readable JSON output')
     .action(async (options) => runStudioCommand(runStudioPlanCommand, options, 'plan'));
 
+  studio
+    .command('intake')
+    .description('Analyze chat goal and auto-resolve spec binding/create decision')
+    .requiredOption('--scene <scene-id>', 'Scene identifier')
+    .requiredOption('--from-chat <session>', 'Chat session identifier or transcript reference')
+    .option('--spec <spec-id>', 'Optional explicit spec id')
+    .option('--goal <goal>', 'Goal text used for intent classification')
+    .option('--apply', 'Create spec when decision is create_spec')
+    .option('--manual-spec', 'Legacy bypass flag (disabled by default policy)')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => runStudioCommand(runStudioIntakeCommand, options, 'intake'));
+
+  studio
+    .command('portfolio')
+    .description('Build scene-organized spec governance portfolio')
+    .option('--scene <scene-id>', 'Optional scene filter')
+    .option('--no-apply', 'Do not write portfolio/index artifacts to .sce/spec-governance/')
+    .option('--strict', 'Fail when governance alerts are detected')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => runStudioCommand(runStudioPortfolioCommand, options, 'portfolio'));
+
+  studio
+    .command('backfill-spec-scenes')
+    .description('Backfill scene bindings for historical specs (writes override mapping when --apply)')
+    .option('--scene <scene-id>', 'Source scene filter (default: scene.unassigned)')
+    .option('--all', 'Include completed/stale specs (default uses active-only policy)')
+    .option('--active-only', 'Force active-only filtering')
+    .option('--limit <n>', 'Maximum number of specs to process')
+    .option('--apply', 'Write mapping to .sce/spec-governance/spec-scene-overrides.json')
+    .option('--no-refresh-governance', 'Skip portfolio refresh after apply')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => runStudioCommand(runStudioBackfillSpecScenesCommand, options, 'backfill-spec-scenes'));
+
   studio
     .command('generate')
     .description('Generate patch bundle metadata for a planned studio job (scene inherited from plan)')
@@ -2310,12 +2623,15 @@ module.exports = {
   resolveNextAction,
   buildProgress,
   runStudioPlanCommand,
+  runStudioIntakeCommand,
   runStudioGenerateCommand,
   runStudioApplyCommand,
   runStudioVerifyCommand,
   runStudioReleaseCommand,
   runStudioRollbackCommand,
   runStudioEventsCommand,
+  runStudioPortfolioCommand,
+  runStudioBackfillSpecScenesCommand,
   runStudioResumeCommand,
   registerStudioCommands
 };

package/lib/spec/related-specs.js

@@ -1,6 +1,10 @@
 const path = require('path');
 const fs = require('fs-extra');
 const { DOMAIN_CHAIN_RELATIVE_PATH } = require('./domain-modeling');
+const {
+  loadSceneBindingOverrides,
+  resolveSceneIdFromOverrides
+} = require('./scene-binding-overrides');
 
 function normalizeText(value) {
   if (typeof value !== 'string') {
@@ -70,6 +74,8 @@ async function resolveSpecSearchEntries(projectPath, fileSystem = fs) {
     return [];
   }
 
+  const overrideContext = await loadSceneBindingOverrides(projectPath, {}, fileSystem);
+  const overrides = overrideContext.overrides;
   const names = await fileSystem.readdir(specsRoot);
   const entries = [];
 
@@ -106,7 +112,10 @@ async function resolveSpecSearchEntries(projectPath, fileSystem = fs) {
     ]);
 
     const sceneId = normalizeText(
-      (domainChain && domainChain.scene_id) || extractSceneIdFromSceneSpec(sceneSpecContent) || ''
+      (domainChain && domainChain.scene_id)
+      || extractSceneIdFromSceneSpec(sceneSpecContent)
+      || resolveSceneIdFromOverrides(specId, overrides)
+      || ''
     ) || null;
     const problemStatement = normalizeText(
       (domainChain && domainChain.problem && domainChain.problem.statement) || ''
@@ -257,4 +266,3 @@ module.exports = {
   calculateSpecRelevance,
   findRelatedSpecs
 };
-

package/lib/spec/scene-binding-overrides.js

@@ -0,0 +1,115 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+const DEFAULT_SPEC_SCENE_OVERRIDE_PATH = '.sce/spec-governance/spec-scene-overrides.json';
+
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeOverrideEntry(specId, payload = {}) {
+  const normalizedSpecId = normalizeText(specId);
+  if (!normalizedSpecId) {
+    return null;
+  }
+
+  if (typeof payload === 'string') {
+    const sceneId = normalizeText(payload);
+    if (!sceneId) {
+      return null;
+    }
+    return {
+      spec_id: normalizedSpecId,
+      scene_id: sceneId,
+      source: 'override',
+      rule_id: null,
+      updated_at: null
+    };
+  }
+
+  const sceneId = normalizeText(payload && payload.scene_id);
+  if (!sceneId) {
+    return null;
+  }
+  return {
+    spec_id: normalizedSpecId,
+    scene_id: sceneId,
+    source: normalizeText(payload.source) || 'override',
+    rule_id: normalizeText(payload.rule_id) || null,
+    updated_at: normalizeText(payload.updated_at) || null
+  };
+}
+
+function normalizeSceneBindingOverrides(raw = {}) {
+  const payload = raw && typeof raw === 'object' ? raw : {};
+  const mappingsRaw = payload.mappings && typeof payload.mappings === 'object'
+    ? payload.mappings
+    : {};
+  const mappings = {};
+  for (const [specId, entry] of Object.entries(mappingsRaw)) {
+    const normalized = normalizeOverrideEntry(specId, entry);
+    if (!normalized) {
+      continue;
+    }
+    mappings[normalized.spec_id] = {
+      scene_id: normalized.scene_id,
+      source: normalized.source,
+      rule_id: normalized.rule_id,
+      updated_at: normalized.updated_at
+    };
+  }
+  return {
+    schema_version: normalizeText(payload.schema_version) || '1.0',
+    generated_at: normalizeText(payload.generated_at) || null,
+    updated_at: normalizeText(payload.updated_at) || null,
+    mappings
+  };
+}
+
+async function loadSceneBindingOverrides(projectPath = process.cwd(), options = {}, fileSystem = fs) {
+  const overridePath = normalizeText(options.override_path || options.overridePath)
+    || DEFAULT_SPEC_SCENE_OVERRIDE_PATH;
+  const absolutePath = path.join(projectPath, overridePath);
+  let payload = {};
+  let loadedFrom = 'default';
+  if (await fileSystem.pathExists(absolutePath)) {
+    try {
+      payload = await fileSystem.readJson(absolutePath);
+      loadedFrom = 'file';
+    } catch (_error) {
+      payload = {};
+      loadedFrom = 'default';
+    }
+  }
+  return {
+    override_path: overridePath,
+    absolute_path: absolutePath,
+    loaded_from: loadedFrom,
+    overrides: normalizeSceneBindingOverrides(payload)
+  };
+}
+
+function resolveSceneIdFromOverrides(specId, overrides = {}) {
+  const normalizedSpecId = normalizeText(specId);
+  if (!normalizedSpecId) {
+    return null;
+  }
+  const mappings = overrides && typeof overrides === 'object' && overrides.mappings
+    ? overrides.mappings
+    : {};
+  const entry = mappings[normalizedSpecId];
+  if (!entry || typeof entry !== 'object') {
+    return null;
+  }
+  return normalizeText(entry.scene_id) || null;
+}
+
+module.exports = {
+  DEFAULT_SPEC_SCENE_OVERRIDE_PATH,
+  normalizeSceneBindingOverrides,
+  loadSceneBindingOverrides,
+  resolveSceneIdFromOverrides
+};