scene-capability-engine 3.3.18 → 3.3.22

package/lib/runtime/scene-session-binding.js

@@ -0,0 +1,109 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { SessionStore } = require('./session-store');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+async function loadLatestStudioJob(projectPath, fileSystem = fs) {
+  const latestPath = path.join(projectPath, '.sce', 'studio', 'latest-job.json');
+  if (!await fileSystem.pathExists(latestPath)) {
+    return null;
+  }
+
+  let latestPayload;
+  try {
+    latestPayload = await fileSystem.readJson(latestPath);
+  } catch (_error) {
+    return null;
+  }
+
+  const jobId = normalizeString(latestPayload && latestPayload.job_id);
+  if (!jobId) {
+    return null;
+  }
+
+  const jobPath = path.join(projectPath, '.sce', 'studio', 'jobs', `${jobId}.json`);
+  if (!await fileSystem.pathExists(jobPath)) {
+    return null;
+  }
+
+  try {
+    return await fileSystem.readJson(jobPath);
+  } catch (_error) {
+    return null;
+  }
+}
+
+async function resolveSpecSceneBinding(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const sessionStore = dependencies.sessionStore || new SessionStore(projectPath);
+  const explicitSceneId = normalizeString(options.sceneId || options.scene);
+  const allowNoScene = options.allowNoScene !== false;
+
+  if (explicitSceneId) {
+    const active = await sessionStore.getActiveSceneSession(explicitSceneId);
+    if (!active) {
+      throw new Error(`No active scene session for scene "${explicitSceneId}". Run "sce studio plan --scene ${explicitSceneId} --from-chat <session>" first.`);
+    }
+    return {
+      source: 'explicit',
+      scene_id: explicitSceneId,
+      scene_cycle: active.scene_cycle,
+      scene_session_id: active.session.session_id,
+      scene_session: active.session
+    };
+  }
+
+  const studioJob = await loadLatestStudioJob(projectPath, fileSystem);
+  const studioSceneId = normalizeString(studioJob && studioJob.scene && studioJob.scene.id);
+  const studioSceneSessionId = normalizeString(studioJob && studioJob.session && studioJob.session.scene_session_id);
+  if (studioSceneId && studioSceneSessionId) {
+    try {
+      const studioSession = await sessionStore.getSession(studioSceneSessionId);
+      if (studioSession && studioSession.status === 'active') {
+        return {
+          source: 'studio-latest',
+          scene_id: studioSceneId,
+          scene_cycle: studioSession.scene && studioSession.scene.cycle ? studioSession.scene.cycle : null,
+          scene_session_id: studioSession.session_id,
+          scene_session: studioSession
+        };
+      }
+    } catch (_error) {
+      // fall through to active scene scan
+    }
+  }
+
+  const activeScenes = await sessionStore.listActiveSceneSessions();
+  if (activeScenes.length === 1) {
+    return {
+      source: 'active-scene-auto',
+      scene_id: activeScenes[0].scene_id,
+      scene_cycle: activeScenes[0].scene_cycle,
+      scene_session_id: activeScenes[0].session.session_id,
+      scene_session: activeScenes[0].session
+    };
+  }
+
+  if (activeScenes.length > 1) {
+    const sceneIds = activeScenes.map((item) => item.scene_id).join(', ');
+    throw new Error(`Multiple active scene sessions detected (${sceneIds}). Use --scene <scene-id> to bind spec session explicitly.`);
+  }
+
+  if (allowNoScene) {
+    return null;
+  }
+
+  throw new Error('No active scene session found. Run "sce studio plan --scene <scene-id> --from-chat <session>" first.');
+}
+
+module.exports = {
+  resolveSpecSceneBinding,
+  loadLatestStudioJob
+};

package/lib/runtime/session-store.js

@@ -4,6 +4,9 @@ const { SteeringContract, normalizeToolName } = require('./steering-contract');
 
 const SESSION_SCHEMA_VERSION = '1.0';
 const SESSION_DIR = path.join('.sce', 'sessions');
+const SESSION_GOVERNANCE_SCHEMA_VERSION = '1.0';
+const SESSION_GOVERNANCE_DIR = path.join('.sce', 'session-governance');
+const SESSION_SCENE_INDEX_FILE = 'scene-index.json';
 
 function toRelativePosix(workspaceRoot, absolutePath) {
   return path.relative(workspaceRoot, absolutePath).replace(/\\/g, '/');
@@ -25,10 +28,26 @@ function generateSessionId() {
   return `sess-${yyyy}${mm}${dd}-${hh}${mi}${ss}-${rand}`;
 }
 
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function safeSceneId(value) {
+  const normalized = `${value || ''}`.trim().replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return normalized || 'scene';
+}
+
+function nextSnapshotId(session) {
+  const snapshots = Array.isArray(session && session.snapshots) ? session.snapshots : [];
+  return `snap-${snapshots.length + 1}`;
+}
+
 class SessionStore {
   constructor(workspaceRoot, steeringContract = null) {
     this._workspaceRoot = workspaceRoot;
     this._sessionsDir = path.join(workspaceRoot, SESSION_DIR);
+    this._sessionGovernanceDir = path.join(workspaceRoot, SESSION_GOVERNANCE_DIR);
+    this._sceneIndexPath = path.join(this._sessionGovernanceDir, SESSION_SCENE_INDEX_FILE);
     this._steeringContract = steeringContract || new SteeringContract(workspaceRoot);
   }
 
@@ -38,7 +57,7 @@ class SessionStore {
     const objective = `${options.objective || ''}`.trim();
     const requestedId = safeSessionId(options.sessionId);
     const sessionId = requestedId || generateSessionId();
-    const now = new Date().toISOString();
+    const now = nowIso();
 
     await this._steeringContract.ensureContract();
     const steeringPayload = await this._steeringContract.buildCompilePayload(tool, agentVersion);
@@ -86,7 +105,7 @@ class SessionStore {
 
   async resumeSession(sessionRef = 'latest', options = {}) {
     const { sessionId, session } = await this._resolveSession(sessionRef);
-    const now = new Date().toISOString();
+    const now = nowIso();
     const status = `${options.status || 'active'}`.trim() || 'active';
 
     session.status = status;
@@ -104,7 +123,7 @@ class SessionStore {
 
   async snapshotSession(sessionRef = 'latest', options = {}) {
     const { sessionId, session } = await this._resolveSession(sessionRef);
-    const now = new Date().toISOString();
+    const now = nowIso();
     const summary = `${options.summary || ''}`.trim();
     const status = options.status ? `${options.status}`.trim() : session.status;
     const payload = options.payload == null ? null : options.payload;
@@ -167,6 +186,414 @@ class SessionStore {
     return records;
   }
 
+  async beginSceneSession(options = {}) {
+    const sceneId = `${options.sceneId || ''}`.trim();
+    if (!sceneId) {
+      throw new Error('sceneId is required for beginSceneSession');
+    }
+
+    const forceNew = options.forceNew === true;
+    const sceneIndex = await this._readSceneIndex();
+    const sceneRecord = sceneIndex.scenes[sceneId] || {
+      scene_id: sceneId,
+      active_session_id: null,
+      active_cycle: null,
+      latest_completed_session_id: null,
+      last_cycle: 0,
+      cycles: []
+    };
+
+    if (!forceNew && sceneRecord.active_session_id) {
+      try {
+        const activeSession = await this.getSession(sceneRecord.active_session_id);
+        if (
+          activeSession &&
+          activeSession.status === 'active' &&
+          activeSession.scene &&
+          activeSession.scene.id === sceneId
+        ) {
+          return {
+            created_new: false,
+            scene_cycle: Number(sceneRecord.active_cycle || 1),
+            session: activeSession,
+            scene_record: sceneRecord
+          };
+        }
+      } catch (_error) {
+        // stale active pointer; continue and create a new one
+      }
+    }
+
+    const cycle = Number(sceneRecord.last_cycle || 0) + 1;
+    const requestedSessionId = safeSessionId(options.sessionId);
+    const generatedScenePrefix = `scene-${safeSceneId(sceneId)}-c${cycle}`;
+    const candidateSessionId = requestedSessionId || `${generatedScenePrefix}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const session = await this.startSession({
+      tool: options.tool || 'generic',
+      agentVersion: options.agentVersion || null,
+      objective: options.objective || `Scene ${sceneId} cycle ${cycle}`,
+      sessionId: candidateSessionId
+    });
+
+    const now = nowIso();
+    session.scene = {
+      id: sceneId,
+      role: 'primary',
+      cycle,
+      state: 'active'
+    };
+    session.children = session.children || {};
+    session.children.spec_sessions = Array.isArray(session.children.spec_sessions)
+      ? session.children.spec_sessions
+      : [];
+    session.updated_at = now;
+    session.timeline = Array.isArray(session.timeline) ? session.timeline : [];
+    session.timeline.push({
+      at: now,
+      event: 'scene_session_started',
+      detail: {
+        scene_id: sceneId,
+        cycle
+      }
+    });
+    await this._writeSession(session.session_id, session);
+
+    sceneRecord.active_session_id = session.session_id;
+    sceneRecord.active_cycle = cycle;
+    sceneRecord.last_cycle = cycle;
+    sceneRecord.updated_at = now;
+    sceneRecord.cycles = Array.isArray(sceneRecord.cycles) ? sceneRecord.cycles : [];
+    sceneRecord.cycles.push({
+      cycle,
+      session_id: session.session_id,
+      status: 'active',
+      started_at: session.started_at,
+      completed_at: null
+    });
+    sceneIndex.scenes[sceneId] = sceneRecord;
+    await this._writeSceneIndex(sceneIndex);
+
+    return {
+      created_new: true,
+      scene_cycle: cycle,
+      session,
+      scene_record: sceneRecord
+    };
+  }
+
+  async completeSceneSession(sceneId, sessionRef = null, options = {}) {
+    const normalizedSceneId = `${sceneId || ''}`.trim();
+    if (!normalizedSceneId) {
+      throw new Error('sceneId is required for completeSceneSession');
+    }
+
+    const sceneIndex = await this._readSceneIndex();
+    const sceneRecord = sceneIndex.scenes[normalizedSceneId];
+    if (!sceneRecord) {
+      throw new Error(`Scene is not tracked in session governance: ${normalizedSceneId}`);
+    }
+
+    const resolvedSessionRef = `${sessionRef || sceneRecord.active_session_id || ''}`.trim();
+    if (!resolvedSessionRef) {
+      throw new Error(`No active scene session to complete: ${normalizedSceneId}`);
+    }
+
+    const { sessionId, session } = await this._resolveSession(resolvedSessionRef);
+    if (!session.scene || session.scene.id !== normalizedSceneId) {
+      throw new Error(`Session ${sessionId} is not bound to scene ${normalizedSceneId}`);
+    }
+
+    const now = nowIso();
+    const completionStatus = `${options.status || 'completed'}`.trim() || 'completed';
+    const summary = `${options.summary || ''}`.trim();
+    const payload = {
+      job_id: options.jobId || null,
+      release_ref: options.releaseRef || null,
+      channel: options.channel || null
+    };
+
+    session.snapshots = Array.isArray(session.snapshots) ? session.snapshots : [];
+    session.snapshots.push({
+      snapshot_id: nextSnapshotId(session),
+      captured_at: now,
+      status: completionStatus,
+      summary,
+      payload
+    });
+    session.status = completionStatus;
+    session.updated_at = now;
+    session.scene.state = 'completed';
+    session.scene.completed_at = now;
+    session.timeline = Array.isArray(session.timeline) ? session.timeline : [];
+    session.timeline.push({
+      at: now,
+      event: 'scene_session_completed',
+      detail: {
+        scene_id: normalizedSceneId,
+        release_ref: payload.release_ref,
+        channel: payload.channel
+      }
+    });
+    await this._writeSession(sessionId, session);
+
+    sceneRecord.cycles = Array.isArray(sceneRecord.cycles) ? sceneRecord.cycles : [];
+    for (const cycle of sceneRecord.cycles) {
+      if (cycle && cycle.session_id === sessionId) {
+        cycle.status = completionStatus;
+        cycle.completed_at = now;
+        cycle.release_ref = payload.release_ref;
+      }
+    }
+    sceneRecord.active_session_id = null;
+    sceneRecord.active_cycle = null;
+    sceneRecord.latest_completed_session_id = sessionId;
+    sceneRecord.updated_at = now;
+    sceneIndex.scenes[normalizedSceneId] = sceneRecord;
+    await this._writeSceneIndex(sceneIndex);
+
+    if (options.autoStartNext === false) {
+      return {
+        completed_session: session,
+        next_session: null,
+        next_scene_cycle: null
+      };
+    }
+
+    const next = await this.beginSceneSession({
+      sceneId: normalizedSceneId,
+      tool: session.tool,
+      agentVersion: session.agent_version || null,
+      objective: options.nextObjective || `Scene ${normalizedSceneId} follow-up cycle`
+    });
+    next.session.timeline = Array.isArray(next.session.timeline) ? next.session.timeline : [];
+    next.session.timeline.push({
+      at: nowIso(),
+      event: 'scene_session_rollover',
+      detail: {
+        from_session_id: sessionId,
+        scene_id: normalizedSceneId
+      }
+    });
+    await this._writeSession(next.session.session_id, next.session);
+
+    return {
+      completed_session: session,
+      next_session: next.session,
+      next_scene_cycle: next.scene_cycle
+    };
+  }
+
+  async startSpecSession(options = {}) {
+    const sceneId = `${options.sceneId || ''}`.trim();
+    const specId = `${options.specId || ''}`.trim();
+    if (!sceneId) {
+      throw new Error('sceneId is required for startSpecSession');
+    }
+    if (!specId) {
+      throw new Error('specId is required for startSpecSession');
+    }
+
+    const sceneIndex = await this._readSceneIndex();
+    const sceneRecord = sceneIndex.scenes[sceneId];
+    if (!sceneRecord || !sceneRecord.active_session_id) {
+      throw new Error(`No active scene session for scene: ${sceneId}`);
+    }
+
+    const parentSession = await this.getSession(sceneRecord.active_session_id);
+    const cycle = parentSession && parentSession.scene && parentSession.scene.cycle
+      ? Number(parentSession.scene.cycle)
+      : Number(sceneRecord.active_cycle || 1);
+    const specSessionId = safeSessionId(options.sessionId)
+      || `spec-${safeSceneId(specId)}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const specSession = await this.startSession({
+      tool: parentSession.tool || options.tool || 'generic',
+      agentVersion: parentSession.agent_version || options.agentVersion || null,
+      objective: options.objective || `Spec ${specId} for scene ${sceneId}`,
+      sessionId: specSessionId
+    });
+
+    const now = nowIso();
+    specSession.scene = {
+      id: sceneId,
+      role: 'spec',
+      cycle,
+      parent_session_id: parentSession.session_id,
+      spec_id: specId,
+      state: 'active'
+    };
+    specSession.updated_at = now;
+    specSession.timeline = Array.isArray(specSession.timeline) ? specSession.timeline : [];
+    specSession.timeline.push({
+      at: now,
+      event: 'spec_session_started',
+      detail: {
+        scene_id: sceneId,
+        spec_id: specId,
+        parent_session_id: parentSession.session_id
+      }
+    });
+    await this._writeSession(specSession.session_id, specSession);
+
+    parentSession.children = parentSession.children || {};
+    parentSession.children.spec_sessions = Array.isArray(parentSession.children.spec_sessions)
+      ? parentSession.children.spec_sessions
+      : [];
+    parentSession.children.spec_sessions.push({
+      spec_id: specId,
+      spec_session_id: specSession.session_id,
+      status: 'active',
+      started_at: now
+    });
+    parentSession.updated_at = now;
+    parentSession.timeline = Array.isArray(parentSession.timeline) ? parentSession.timeline : [];
+    parentSession.timeline.push({
+      at: now,
+      event: 'spec_session_attached',
+      detail: {
+        scene_id: sceneId,
+        spec_id: specId,
+        spec_session_id: specSession.session_id
+      }
+    });
+    await this._writeSession(parentSession.session_id, parentSession);
+
+    return {
+      scene_session: parentSession,
+      spec_session: specSession
+    };
+  }
+
+  async completeSpecSession(options = {}) {
+    const specSessionRef = `${options.specSessionRef || ''}`.trim();
+    if (!specSessionRef) {
+      throw new Error('specSessionRef is required for completeSpecSession');
+    }
+
+    const now = nowIso();
+    const summary = `${options.summary || ''}`.trim();
+    const status = `${options.status || 'completed'}`.trim() || 'completed';
+    const payload = options.payload == null ? null : options.payload;
+
+    const { sessionId, session } = await this._resolveSession(specSessionRef);
+    if (!session.scene || session.scene.role !== 'spec') {
+      throw new Error(`Session ${sessionId} is not a spec child session`);
+    }
+
+    session.snapshots = Array.isArray(session.snapshots) ? session.snapshots : [];
+    session.snapshots.push({
+      snapshot_id: nextSnapshotId(session),
+      captured_at: now,
+      status,
+      summary,
+      payload
+    });
+    session.status = status;
+    session.scene.state = 'completed';
+    session.scene.completed_at = now;
+    session.updated_at = now;
+    session.timeline = Array.isArray(session.timeline) ? session.timeline : [];
+    session.timeline.push({
+      at: now,
+      event: 'spec_session_completed',
+      detail: {
+        scene_id: session.scene.id,
+        spec_id: session.scene.spec_id
+      }
+    });
+    await this._writeSession(sessionId, session);
+
+    if (session.scene.parent_session_id) {
+      try {
+        const parent = await this.getSession(session.scene.parent_session_id);
+        parent.children = parent.children || {};
+        parent.children.spec_sessions = Array.isArray(parent.children.spec_sessions)
+          ? parent.children.spec_sessions
+          : [];
+        parent.children.spec_sessions = parent.children.spec_sessions.map((entry) => {
+          if (entry && entry.spec_session_id === sessionId) {
+            return {
+              ...entry,
+              status,
+              completed_at: now
+            };
+          }
+          return entry;
+        });
+        parent.updated_at = now;
+        parent.timeline = Array.isArray(parent.timeline) ? parent.timeline : [];
+        parent.timeline.push({
+          at: now,
+          event: 'spec_session_archived',
+          detail: {
+            scene_id: session.scene.id,
+            spec_id: session.scene.spec_id,
+            spec_session_id: sessionId
+          }
+        });
+        await this._writeSession(parent.session_id, parent);
+      } catch (_error) {
+        // parent may have been removed manually; spec session has already been archived
+      }
+    }
+
+    return session;
+  }
+
+  async listSceneRecords() {
+    const sceneIndex = await this._readSceneIndex();
+    return Object.values(sceneIndex.scenes || {});
+  }
+
+  async listActiveSceneSessions() {
+    const records = await this.listSceneRecords();
+    const active = [];
+    for (const record of records) {
+      if (!record || !record.active_session_id) {
+        continue;
+      }
+      try {
+        const session = await this.getSession(record.active_session_id);
+        if (session && session.status === 'active') {
+          active.push({
+            scene_id: record.scene_id,
+            scene_cycle: record.active_cycle,
+            session
+          });
+        }
+      } catch (_error) {
+        // skip stale references
+      }
+    }
+    return active;
+  }
+
+  async getActiveSceneSession(sceneId) {
+    const normalizedSceneId = `${sceneId || ''}`.trim();
+    if (!normalizedSceneId) {
+      throw new Error('sceneId is required for getActiveSceneSession');
+    }
+    const sceneIndex = await this._readSceneIndex();
+    const record = sceneIndex.scenes[normalizedSceneId];
+    if (!record || !record.active_session_id) {
+      return null;
+    }
+    try {
+      const session = await this.getSession(record.active_session_id);
+      if (!session || session.status !== 'active') {
+        return null;
+      }
+      return {
+        scene_id: normalizedSceneId,
+        scene_cycle: record.active_cycle,
+        session
+      };
+    } catch (_error) {
+      return null;
+    }
+  }
+
   async _resolveSession(sessionRef) {
     const ref = `${sessionRef || 'latest'}`.trim();
     if (ref === 'latest') {
@@ -195,6 +622,48 @@ class SessionStore {
     await fs.writeJson(this._sessionPath(sessionId), session, { spaces: 2 });
   }
 
+  async _readSceneIndex() {
+    if (!await fs.pathExists(this._sceneIndexPath)) {
+      return {
+        schema_version: SESSION_GOVERNANCE_SCHEMA_VERSION,
+        updated_at: nowIso(),
+        scenes: {}
+      };
+    }
+
+    try {
+      const payload = await fs.readJson(this._sceneIndexPath);
+      return {
+        schema_version: payload && payload.schema_version
+          ? payload.schema_version
+          : SESSION_GOVERNANCE_SCHEMA_VERSION,
+        updated_at: payload && payload.updated_at ? payload.updated_at : nowIso(),
+        scenes: payload && typeof payload.scenes === 'object' && payload.scenes
+          ? payload.scenes
+          : {}
+      };
+    } catch (_error) {
+      return {
+        schema_version: SESSION_GOVERNANCE_SCHEMA_VERSION,
+        updated_at: nowIso(),
+        scenes: {}
+      };
+    }
+  }
+
+  async _writeSceneIndex(indexPayload) {
+    const payload = {
+      schema_version: SESSION_GOVERNANCE_SCHEMA_VERSION,
+      updated_at: nowIso(),
+      scenes: indexPayload && typeof indexPayload.scenes === 'object' && indexPayload.scenes
+        ? indexPayload.scenes
+        : {}
+    };
+    await fs.ensureDir(this._sessionGovernanceDir);
+    await fs.writeJson(this._sceneIndexPath, payload, { spaces: 2 });
+    return payload;
+  }
+
   _sessionPath(sessionId) {
     return path.join(this._sessionsDir, `${sessionId}.json`);
   }
@@ -204,4 +673,7 @@ module.exports = {
   SessionStore,
   SESSION_SCHEMA_VERSION,
   SESSION_DIR,
+  SESSION_GOVERNANCE_SCHEMA_VERSION,
+  SESSION_GOVERNANCE_DIR,
+  SESSION_SCENE_INDEX_FILE,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.3.18",
+  "version": "3.3.22",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {
@@ -68,10 +68,12 @@
     "report:interactive-governance": "node scripts/interactive-governance-report.js --period weekly --json",
     "report:release-ops-weekly": "node scripts/release-ops-weekly-summary.js --json",
     "gate:release-ops-weekly": "node scripts/release-weekly-ops-gate.js",
+    "gate:errorbook-release": "node scripts/errorbook-release-gate.js --fail-on-block",
+    "gate:git-managed": "node scripts/git-managed-gate.js --fail-on-violation",
     "gate:release-asset-integrity": "node scripts/release-asset-integrity-check.js",
     "report:release-risk-remediation": "node scripts/release-risk-remediation-bundle.js --json",
     "report:moqui-core-regression": "node scripts/moqui-core-regression-suite.js --json",
-    "prepublishOnly": "npm run test:full && npm run test:skip-audit && npm run test:sce-tracking && npm run test:brand-consistency && npm run report:interactive-governance -- --fail-on-alert",
+    "prepublishOnly": "npm run test:full && npm run test:skip-audit && npm run test:sce-tracking && npm run test:brand-consistency && npm run gate:git-managed && npm run gate:errorbook-release && npm run report:interactive-governance -- --fail-on-alert",
     "publish:manual": "npm publish --access public",
     "install-global": "npm install -g .",
     "uninstall-global": "npm uninstall -g scene-capability-engine"