scene-capability-engine 3.3.17 → 3.3.21

package/lib/commands/spec-bootstrap.js

@@ -11,9 +11,13 @@ const { ContextCollector } = require('../spec/bootstrap/context-collector');
 const { QuestionnaireEngine } = require('../spec/bootstrap/questionnaire-engine');
 const { DraftGenerator } = require('../spec/bootstrap/draft-generator');
 const { TraceEmitter } = require('../spec/bootstrap/trace-emitter');
+const { SessionStore } = require('../runtime/session-store');
+const { resolveSpecSceneBinding } = require('../runtime/scene-session-binding');
+const { bindMultiSpecSceneSession } = require('../runtime/multi-spec-scene-session');
 
 async function runSpecBootstrap(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
+  const sessionStore = dependencies.sessionStore || new SessionStore(projectPath);
 
   const specTargets = parseSpecTargets({
     spec: options.spec || options.name,
@@ -22,13 +26,24 @@ async function runSpecBootstrap(options = {}, dependencies = {}) {
 
   if (specTargets.length > 1) {
     const executeOrchestration = dependencies.runOrchestration || runOrchestration;
-    return runMultiSpecViaOrchestrate({
+    return bindMultiSpecSceneSession({
       specTargets,
-      projectPath,
-      commandOptions: options,
-      runOrchestration: executeOrchestration,
+      sceneId: options.scene,
+      commandName: 'spec-bootstrap',
       commandLabel: 'Multi-spec bootstrap',
-      nextActionLabel: 'Multi-spec bootstrap defaulted to orchestrate mode.'
+      commandOptions: options,
+      runViaOrchestrate: () => runMultiSpecViaOrchestrate({
+        specTargets,
+        projectPath,
+        commandOptions: options,
+        runOrchestration: executeOrchestration,
+        commandLabel: 'Multi-spec bootstrap',
+        nextActionLabel: 'Multi-spec bootstrap defaulted to orchestrate mode.'
+      })
+    }, {
+      projectPath,
+      fileSystem: dependencies.fileSystem || fs,
+      sessionStore
     });
   }
 
@@ -57,61 +72,120 @@ async function runSpecBootstrap(options = {}, dependencies = {}) {
     throw new Error('Spec name is required');
   }
 
-  const draft = draftGenerator.generate({
-    specName,
-    profile: options.profile || 'general',
-    template: options.template || 'default',
-    context,
-    answers
+  const sceneBinding = await resolveSpecSceneBinding({
+    sceneId: options.scene,
+    allowNoScene: false
+  }, {
+    projectPath,
+    fileSystem: dependencies.fileSystem || fs,
+    sessionStore
   });
 
-  const specPath = path.join(projectPath, '.sce', 'specs', specName);
-  const files = {
-    requirements: path.join(specPath, 'requirements.md'),
-    design: path.join(specPath, 'design.md'),
-    tasks: path.join(specPath, 'tasks.md')
-  };
-
-  if (!options.dryRun) {
-    await fs.ensureDir(specPath);
-    await fs.writeFile(files.requirements, draft.requirements, 'utf8');
-    await fs.writeFile(files.design, draft.design, 'utf8');
-    await fs.writeFile(files.tasks, draft.tasks, 'utf8');
+  let specSession = null;
+  if (sceneBinding && !options.dryRun) {
+    const linked = await sessionStore.startSpecSession({
+      sceneId: sceneBinding.scene_id,
+      specId: specName,
+      objective: `Spec bootstrap: ${specName}`
+    });
+    specSession = linked.spec_session;
   }
 
-  const result = {
-    success: true,
-    specName,
-    specPath: path.relative(projectPath, specPath),
-    dryRun: !!options.dryRun,
-    files: {
-      requirements: path.relative(projectPath, files.requirements),
-      design: path.relative(projectPath, files.design),
-      tasks: path.relative(projectPath, files.tasks)
-    },
-    trace: {
-      template: options.template || 'default',
+  try {
+    const draft = draftGenerator.generate({
+      specName,
       profile: options.profile || 'general',
-      parameters: {
-        nonInteractive: !!options.nonInteractive,
-        dryRun: !!options.dryRun,
-        json: !!options.json
+      template: options.template || 'default',
+      context,
+      answers
+    });
+
+    const specPath = path.join(projectPath, '.sce', 'specs', specName);
+    const files = {
+      requirements: path.join(specPath, 'requirements.md'),
+      design: path.join(specPath, 'design.md'),
+      tasks: path.join(specPath, 'tasks.md')
+    };
+
+    if (!options.dryRun) {
+      await fs.ensureDir(specPath);
+      await fs.writeFile(files.requirements, draft.requirements, 'utf8');
+      await fs.writeFile(files.design, draft.design, 'utf8');
+      await fs.writeFile(files.tasks, draft.tasks, 'utf8');
+    }
+
+    const result = {
+      success: true,
+      specName,
+      specPath: path.relative(projectPath, specPath),
+      dryRun: !!options.dryRun,
+      files: {
+        requirements: path.relative(projectPath, files.requirements),
+        design: path.relative(projectPath, files.design),
+        tasks: path.relative(projectPath, files.tasks)
+      },
+      trace: {
+        template: options.template || 'default',
+        profile: options.profile || 'general',
+        parameters: {
+          nonInteractive: !!options.nonInteractive,
+          dryRun: !!options.dryRun,
+          json: !!options.json
+        },
+        context: {
+          totalSpecs: context.totalSpecs,
+          preferredLanguage: context.preferredLanguage
+        },
+        mapping: draft.metadata.mapping
       },
-      context: {
-        totalSpecs: context.totalSpecs,
-        preferredLanguage: context.preferredLanguage
+      preview: {
+        requirements: draft.requirements,
+        design: draft.design,
+        tasks: draft.tasks
       },
-      mapping: draft.metadata.mapping
-    },
-    preview: {
-      requirements: draft.requirements,
-      design: draft.design,
-      tasks: draft.tasks
+      scene_session: sceneBinding
+        ? {
+          bound: true,
+          scene_id: sceneBinding.scene_id,
+          scene_cycle: sceneBinding.scene_cycle,
+          scene_session_id: sceneBinding.scene_session_id,
+          spec_session_id: specSession ? specSession.session_id : null,
+          binding_source: sceneBinding.source
+        }
+        : {
+          bound: false
+        }
+    };
+
+    if (specSession) {
+      await sessionStore.completeSpecSession({
+        specSessionRef: specSession.session_id,
+        status: 'completed',
+        summary: `Spec bootstrap completed: ${specName}`,
+        payload: {
+          command: 'spec-bootstrap',
+          spec: specName
+        }
+      });
     }
-  };
 
-  traceEmitter.emit(result, { json: options.json });
-  return result;
+    traceEmitter.emit(result, { json: options.json });
+    return result;
+  } catch (error) {
+    if (specSession) {
+      await sessionStore.completeSpecSession({
+        specSessionRef: specSession.session_id,
+        status: 'failed',
+        summary: `Spec bootstrap failed: ${specName}`,
+        payload: {
+          command: 'spec-bootstrap',
+          spec: specName,
+          error: error.message
+        }
+      });
+    }
+    throw error;
+  }
 }
 
 function registerSpecBootstrapCommand(program) {
@@ -123,6 +197,7 @@ function registerSpecBootstrapCommand(program) {
     .option('--specs <names>', 'Comma-separated Spec identifiers (multi-spec defaults to orchestrate mode)')
     .option('--template <template-id>', 'Template hint for draft generation')
     .option('--profile <profile-id>', 'Profile for default generation strategy')
+    .option('--scene <scene-id>', 'Bind this spec bootstrap as a child session of an active scene')
     .option('--non-interactive', 'Disable prompts and use arguments/defaults only')
     .option('--dry-run', 'Preview generation result without writing files')
     .option('--json', 'Output machine-readable JSON')

package/lib/commands/spec-gate.js

@@ -12,9 +12,13 @@ const { RuleRegistry } = require('../spec-gate/rules/rule-registry');
 const { createDefaultRules } = require('../spec-gate/rules/default-rules');
 const { GateEngine } = require('../spec-gate/engine/gate-engine');
 const { ResultEmitter } = require('../spec-gate/result-emitter');
+const { SessionStore } = require('../runtime/session-store');
+const { resolveSpecSceneBinding } = require('../runtime/scene-session-binding');
+const { bindMultiSpecSceneSession } = require('../runtime/multi-spec-scene-session');
 
 async function runSpecGate(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
+  const sessionStore = dependencies.sessionStore || new SessionStore(projectPath);
   const specTargets = parseSpecTargets(options);
 
   if (specTargets.length === 0) {
@@ -23,13 +27,24 @@ async function runSpecGate(options = {}, dependencies = {}) {
 
   if (specTargets.length > 1) {
     const executeOrchestration = dependencies.runOrchestration || runOrchestration;
-    return runMultiSpecViaOrchestrate({
+    return bindMultiSpecSceneSession({
       specTargets,
-      projectPath,
-      commandOptions: options,
-      runOrchestration: executeOrchestration,
+      sceneId: options.scene,
+      commandName: 'spec-gate',
       commandLabel: 'Multi-spec gate',
-      nextActionLabel: 'Multi-spec gate execution defaulted to orchestrate mode.'
+      commandOptions: options,
+      runViaOrchestrate: () => runMultiSpecViaOrchestrate({
+        specTargets,
+        projectPath,
+        commandOptions: options,
+        runOrchestration: executeOrchestration,
+        commandLabel: 'Multi-spec gate',
+        nextActionLabel: 'Multi-spec gate execution defaulted to orchestrate mode.'
+      })
+    }, {
+      projectPath,
+      fileSystem: dependencies.fileSystem || fs,
+      sessionStore
     });
   }
 
@@ -40,30 +55,81 @@ async function runSpecGate(options = {}, dependencies = {}) {
     throw new Error(`Spec not found: ${specId}`);
   }
 
-  const policyLoader = dependencies.policyLoader || new PolicyLoader(projectPath);
-  const policy = dependencies.policy || await policyLoader.load({
-    policy: options.policy,
-    strict: options.strict
+  const sceneBinding = await resolveSpecSceneBinding({
+    sceneId: options.scene,
+    allowNoScene: false
+  }, {
+    projectPath,
+    fileSystem: dependencies.fileSystem || fs,
+    sessionStore
   });
-
-  const registry = dependencies.registry || new RuleRegistry(createDefaultRules(projectPath));
-  const engine = dependencies.engine || new GateEngine({
-    registry,
-    policy
+  const linked = await sessionStore.startSpecSession({
+    sceneId: sceneBinding.scene_id,
+    specId,
+    objective: `Spec gate: ${specId}`
   });
+  const specSession = linked.spec_session;
 
-  const result = await engine.evaluate({ specId });
-  const emitter = dependencies.emitter || new ResultEmitter(projectPath);
-  const emitted = await emitter.emit(result, {
-    json: options.json,
-    out: options.out,
-    silent: options.silent
-  });
+  const policyLoader = dependencies.policyLoader || new PolicyLoader(projectPath);
+  try {
+    const policy = dependencies.policy || await policyLoader.load({
+      policy: options.policy,
+      strict: options.strict
+    });
 
-  return {
-    ...result,
-    report_path: emitted.outputPath
-  };
+    const registry = dependencies.registry || new RuleRegistry(createDefaultRules(projectPath));
+    const engine = dependencies.engine || new GateEngine({
+      registry,
+      policy
+    });
+
+    const result = await engine.evaluate({ specId });
+    const emitter = dependencies.emitter || new ResultEmitter(projectPath);
+    const emitted = await emitter.emit(result, {
+      json: options.json,
+      out: options.out,
+      silent: options.silent
+    });
+
+    const decisionStatus = result.decision === 'no-go' ? 'failed' : 'completed';
+    await sessionStore.completeSpecSession({
+      specSessionRef: specSession.session_id,
+      status: decisionStatus,
+      summary: `Spec gate ${result.decision}: ${specId}`,
+      payload: {
+        command: 'spec-gate',
+        spec: specId,
+        decision: result.decision,
+        score: result.score,
+        report_path: emitted.outputPath || null
+      }
+    });
+
+    return {
+      ...result,
+      report_path: emitted.outputPath,
+      scene_session: {
+        bound: true,
+        scene_id: sceneBinding.scene_id,
+        scene_cycle: sceneBinding.scene_cycle,
+        scene_session_id: sceneBinding.scene_session_id,
+        spec_session_id: specSession.session_id,
+        binding_source: sceneBinding.source
+      }
+    };
+  } catch (error) {
+    await sessionStore.completeSpecSession({
+      specSessionRef: specSession.session_id,
+      status: 'failed',
+      summary: `Spec gate failed: ${specId}`,
+      payload: {
+        command: 'spec-gate',
+        spec: specId,
+        error: error.message
+      }
+    });
+    throw error;
+  }
 }
 
 async function generateSpecGatePolicyTemplate(options = {}, dependencies = {}) {
@@ -99,6 +165,7 @@ function registerSpecGateCommand(program) {
     .description('Execute gate checks for one or more Specs')
     .option('--spec <name>', 'Single Spec identifier')
     .option('--specs <names>', 'Comma-separated Spec identifiers (multi-spec defaults to orchestrate mode)')
+    .option('--scene <scene-id>', 'Bind this spec gate run as a child session of an active scene')
     .option('--policy <path>', 'Policy JSON path')
     .option('--strict', 'Enable strict mode override')
     .option('--json', 'Output machine-readable JSON')

package/lib/commands/spec-pipeline.js

@@ -10,9 +10,13 @@ const {
 const { PipelineStateStore } = require('../spec/pipeline/state-store');
 const { StageRunner } = require('../spec/pipeline/stage-runner');
 const { createDefaultStageAdapters } = require('../spec/pipeline/stage-adapters');
+const { SessionStore } = require('../runtime/session-store');
+const { resolveSpecSceneBinding } = require('../runtime/scene-session-binding');
+const { bindMultiSpecSceneSession } = require('../runtime/multi-spec-scene-session');
 
 async function runSpecPipeline(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
+  const sessionStore = dependencies.sessionStore || new SessionStore(projectPath);
   const specTargets = parseSpecTargets(options);
   if (specTargets.length === 0) {
     throw new Error('Either --spec or --specs is required');
@@ -20,13 +24,24 @@ async function runSpecPipeline(options = {}, dependencies = {}) {
 
   if (specTargets.length > 1) {
     const executeOrchestration = dependencies.runOrchestration || runOrchestration;
-    return runMultiSpecViaOrchestrate({
+    return bindMultiSpecSceneSession({
       specTargets,
-      projectPath,
-      commandOptions: options,
-      runOrchestration: executeOrchestration,
+      sceneId: options.scene,
+      commandName: 'spec-pipeline',
       commandLabel: 'Multi-spec pipeline',
-      nextActionLabel: 'Multi-spec execution defaulted to orchestrate mode.'
+      commandOptions: options,
+      runViaOrchestrate: () => runMultiSpecViaOrchestrate({
+        specTargets,
+        projectPath,
+        commandOptions: options,
+        runOrchestration: executeOrchestration,
+        commandLabel: 'Multi-spec pipeline',
+        nextActionLabel: 'Multi-spec execution defaulted to orchestrate mode.'
+      })
+    }, {
+      projectPath,
+      fileSystem: dependencies.fileSystem || fs,
+      sessionStore
     });
   }
 
@@ -37,6 +52,25 @@ async function runSpecPipeline(options = {}, dependencies = {}) {
     throw new Error(`Spec not found: ${specId}`);
   }
 
+  const sceneBinding = await resolveSpecSceneBinding({
+    sceneId: options.scene,
+    allowNoScene: false
+  }, {
+    projectPath,
+    fileSystem: dependencies.fileSystem || fs,
+    sessionStore
+  });
+
+  let specSession = null;
+  if (sceneBinding && !options.dryRun) {
+    const linked = await sessionStore.startSpecSession({
+      sceneId: sceneBinding.scene_id,
+      specId,
+      objective: `Spec pipeline: ${specId}`
+    });
+    specSession = linked.spec_session;
+  }
+
   const stateStore = dependencies.stateStore || new PipelineStateStore(projectPath);
   const adapters = dependencies.adapters || createDefaultStageAdapters(projectPath);
   const stageRunner = dependencies.stageRunner || new StageRunner({
@@ -70,7 +104,24 @@ async function runSpecPipeline(options = {}, dependencies = {}) {
     state
   };
 
-  const execution = await stageRunner.run(runContext);
+  let execution;
+  try {
+    execution = await stageRunner.run(runContext);
+  } catch (error) {
+    if (specSession) {
+      await sessionStore.completeSpecSession({
+        specSessionRef: specSession.session_id,
+        status: 'failed',
+        summary: `Spec pipeline failed: ${specId}`,
+        payload: {
+          command: 'spec-pipeline',
+          spec: specId,
+          error: error.message
+        }
+      });
+    }
+    throw error;
+  }
   await stateStore.markFinished(state, execution.status);
 
   const result = {
@@ -80,9 +131,36 @@ async function runSpecPipeline(options = {}, dependencies = {}) {
     stage_results: execution.stageResults,
     failure: execution.failure,
     next_actions: buildNextActions(execution),
-    state_file: path.relative(projectPath, stateStore.getRunPath(specId, state.run_id))
+    state_file: path.relative(projectPath, stateStore.getRunPath(specId, state.run_id)),
+    scene_session: sceneBinding
+      ? {
+        bound: true,
+        scene_id: sceneBinding.scene_id,
+        scene_cycle: sceneBinding.scene_cycle,
+        scene_session_id: sceneBinding.scene_session_id,
+        spec_session_id: specSession ? specSession.session_id : null,
+        binding_source: sceneBinding.source
+      }
+      : {
+        bound: false
+      }
   };
 
+  if (specSession) {
+    await sessionStore.completeSpecSession({
+      specSessionRef: specSession.session_id,
+      status: execution.status === 'completed' ? 'completed' : 'failed',
+      summary: `Spec pipeline ${execution.status}: ${specId}`,
+      payload: {
+        command: 'spec-pipeline',
+        spec: specId,
+        run_id: state.run_id,
+        pipeline_status: execution.status,
+        failure: execution.failure || null
+      }
+    });
+  }
+
   if (options.out) {
     const outPath = path.isAbsolute(options.out)
       ? options.out
@@ -111,6 +189,7 @@ function registerSpecPipelineCommand(program) {
     .description('Execute pipeline stages for one or more Specs')
     .option('--spec <name>', 'Single Spec identifier')
     .option('--specs <names>', 'Comma-separated Spec identifiers (multi-spec defaults to orchestrate mode)')
+    .option('--scene <scene-id>', 'Bind this spec pipeline run as a child session of an active scene')
     .option('--from-stage <stage>', 'Start stage (requirements/design/tasks/gate)')
     .option('--to-stage <stage>', 'End stage (requirements/design/tasks/gate)')
     .option('--resume', 'Resume from latest unfinished stage state')