scene-capability-engine 3.5.2 → 3.6.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.0] - 2026-03-04
+
+### Added
+- SQLite-backed SCE state store (`.sce/state/sce-state.sqlite`) for scene/spec/task-ref/event runtime governance.
+- Hierarchical task reference registry (`SS.PP.TT`) persisted in SQLite (`task_ref_registry` table).
+- New task reference commands:
+  - `sce task ref --scene <scene-id> --spec <spec-id> --task <task-id> --json`
+  - `sce task show --ref <SS.PP.TT> --json`
+  - `sce task rerun --ref <SS.PP.TT> [--dry-run] --json`
+- New module: `lib/task/task-ref-registry.js`.
+- New state-store unit tests for sqlite-only backend enforcement and fallback gating.
+
+### Changed
+- Studio task-stream payload now includes `taskRef` at root level and `task.ref` in `task` object.
+- Studio `task.summary` now carries task reference context for UI traceability.
+- Studio event stream persistence switched to SQLite (`studio_event_stream`) as the single source of truth.
+- CLI now registers a dedicated `task` command group (`claim/unclaim/list/status/ref/show/rerun`).
+- State backend selection now enforces sqlite-only runtime policy (no legacy file backend branch).
+
 ## [3.5.2] - 2026-03-03
 
 ### Added

package/README.md

@@ -129,7 +129,7 @@ SCE is tool-agnostic and works with Codex, Claude Code, Cursor, Windsurf, VS Cod
   - `sce workspace takeover-apply --json`
 
 Studio task-stream output contract (default):
-- IDs: `sessionId`, `sceneId`, `specId`, `taskId`, `eventId`
+- IDs: `sessionId`, `sceneId`, `specId`, `taskId`, `taskRef`, `eventId`
 - Task: `task.goal`, `task.status`, `task.summary` (3-line), `task.handoff`, `task.next_action`
 - File refs: `task.file_changes[]` with `path`, `line`, `diffRef`
 - Command logs: `task.commands[]` with `cmd`, `exit_code`, `stdout`, `stderr`, `log_path`
@@ -137,11 +137,20 @@ Studio task-stream output contract (default):
 - Evidence: `task.evidence[]`
 - Raw audit stream: `event[]` (and `studio events` keeps `events[]` compatibility field)
 - OpenHands bridge: `sce studio events --openhands-events <path>` maps OpenHands raw events into the same task contract (`source_stream=openhands`)
+- Hierarchical task reference operations:
+  - `sce task ref --scene <scene-id> --spec <spec-id> --task <task-id> --json`
+  - `sce task show --ref <SS.PP.TT> --json`
+  - `sce task rerun --ref <SS.PP.TT> [--dry-run] --json`
+- Runtime governance state store policy:
+  - SQLite-only backend (`.sce/state/sce-state.sqlite`)
+  - In-memory fallback only in `NODE_ENV=test` or when `SCE_STATE_ALLOW_MEMORY_FALLBACK=1`
+  - Outside those conditions, unavailable SQLite support fails fast for task-ref/event persistence
 
 ---
 
 ## Important Version Changes
 
+- `3.6.0`: Added hierarchical task references (`taskRef`, format `SS.PP.TT`) backed by SQLite state store `.sce/state/sce-state.sqlite`, plus new task commands (`sce task ref/show/rerun`) for reference lookup and deterministic rerun.
 - `3.5.2`: Introduced task-stream output contract for Studio commands (`sessionId/sceneId/specId/taskId/eventId`, structured `task.*` fields, `event[]` audit stream) and added OpenHands raw-event bridge via `sce studio events --openhands-events <path>`.
 - `3.5.1`: Enforced stricter Studio intake defaults (`--manual-spec` and `--no-spec-governance` blocked unless policy override), added historical spec scene backfill command (`sce studio backfill-spec-scenes`) and persisted override mapping (`.sce/spec-governance/spec-scene-overrides.json`) for portfolio/related-spec alignment.
 - `3.5.0`: Added Studio automatic goal intake + scene spec portfolio governance (`sce studio intake`, `sce studio portfolio`), including default intake policy baseline and governance artifacts for bounded scene spec growth.
@@ -191,5 +200,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.5.2  
-**Last Updated**: 2026-03-03
+**Version**: 3.6.0  
+**Last Updated**: 2026-03-04

package/README.zh.md

@@ -129,7 +129,7 @@ SCE 对工具无锁定，可接入 Codex、Claude Code、Cursor、Windsurf、VS
   - `sce workspace takeover-apply --json`
 
 Studio 任务流输出契约（默认）：
-- ID 字段：`sessionId`、`sceneId`、`specId`、`taskId`、`eventId`
+- ID 字段：`sessionId`、`sceneId`、`specId`、`taskId`、`taskRef`、`eventId`
 - 任务主体：`task.goal`、`task.status`、`task.summary`（固定三行）、`task.handoff`、`task.next_action`
 - 文件引用：`task.file_changes[]`（`path`、`line`、`diffRef`）
 - 命令执行：`task.commands[]`（`cmd`、`exit_code`、`stdout`、`stderr`、`log_path`）
@@ -137,11 +137,20 @@ Studio 任务流输出契约（默认）：
 - 证据引用：`task.evidence[]`
 - 原始审计流：`event[]`（`studio events` 同时保留 `events[]` 兼容字段）
 - OpenHands 桥接：`sce studio events --openhands-events <path>` 可将 OpenHands 原始事件映射为同一 task 契约（`source_stream=openhands`）
+- 分层任务引用操作：
+  - `sce task ref --scene <scene-id> --spec <spec-id> --task <task-id> --json`
+  - `sce task show --ref <SS.PP.TT> --json`
+  - `sce task rerun --ref <SS.PP.TT> [--dry-run] --json`
+- 运行时治理状态库策略：
+  - 仅支持 SQLite 后端（`.sce/state/sce-state.sqlite`）
+  - 仅在 `NODE_ENV=test` 或 `SCE_STATE_ALLOW_MEMORY_FALLBACK=1` 时允许内存回退
+  - 在上述条件之外若 SQLite 不可用，任务引用/事件持久化会快速失败
 
 ---
 
 ## 重要版本变更
 
+- `3.6.0`：新增分层任务引用（`taskRef`，格式 `SS.PP.TT`），持久化到 SQLite 状态库 `.sce/state/sce-state.sqlite`；新增 `sce task ref/show/rerun` 用于引用查询与可重放执行。
 - `3.5.2`：新增 Studio 任务流输出契约（`sessionId/sceneId/specId/taskId/eventId`、结构化 `task.*` 字段、`event[]` 审计流），并新增 OpenHands 原始事件桥接能力：`sce studio events --openhands-events <path>`。
 - `3.5.1`：默认强化 Studio intake 治理（`--manual-spec`、`--no-spec-governance` 在未显式放开策略时会被阻断），新增历史 spec 场景回填命令 `sce studio backfill-spec-scenes`，并写入 `.sce/spec-governance/spec-scene-overrides.json` 以统一 portfolio 与 related-spec 的场景映射。
 - `3.5.0`：新增 Studio 目标自动 intake + 场景 spec 组合治理（`sce studio intake`、`sce studio portfolio`），并默认启用 intake 策略基线与治理快照产物，控制场景内 spec 无序增长。
@@ -191,5 +200,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.5.2  
-**最后更新**：2026-03-03
+**版本**：3.6.0  
+**最后更新**：2026-03-04

package/bin/scene-capability-engine.js

@@ -23,6 +23,7 @@ const { registerSpecDomainCommand } = require('../lib/commands/spec-domain');
 const { registerSpecRelatedCommand } = require('../lib/commands/spec-related');
 const { registerTimelineCommands } = require('../lib/commands/timeline');
 const { registerValueCommands } = require('../lib/commands/value');
+const { registerTaskCommands } = require('../lib/commands/task');
 const VersionChecker = require('../lib/version/version-checker');
 const {
   findLegacyKiroDirectories,
@@ -943,6 +944,7 @@ registerOrchestrateCommands(program);
 
 // Value realization and observability commands
 registerValueCommands(program);
+registerTaskCommands(program);
 
 // Template management commands
 const templatesCommand = require('../lib/commands/templates');

package/docs/command-reference.md

@@ -3,7 +3,7 @@
 > Quick reference for all `sce` commands
 
 **Version**: 3.5.2
-**Last Updated**: 2026-03-03
+**Last Updated**: 2026-03-04
 
 ---
 
@@ -181,10 +181,26 @@ sce task claim <spec-name> <task-id>
 # Unclaim a task
 sce task unclaim <spec-name> <task-id>
 
-# Show task status
+# List claimed tasks
+sce task list <spec-name>
 sce task status <spec-name>
+
+# Resolve or create hierarchical task reference (scene.spec.task)
+sce task ref --scene <scene-id> --spec <spec-id> --task <task-id> --json
+
+# Show task mapping from hierarchical ref
+sce task show --ref <SS.PP.TT> --json
+
+# Rerun by hierarchical ref (dry-run preview)
+sce task rerun --ref <SS.PP.TT> --dry-run --json
 ```
 
+Task references and studio runtime events are persisted in SQLite state store:
+- `.sce/state/sce-state.sqlite`
+- Backend policy: SQLite only (no file-backend mode).
+- In-memory fallback is restricted to `NODE_ENV=test` or `SCE_STATE_ALLOW_MEMORY_FALLBACK=1`.
+- If SQLite runtime support is unavailable outside fallback conditions, `task ref/show/rerun` and `studio events` persistence operations fail fast.
+
 ### Context & Prompts
 
 ```bash
@@ -570,7 +586,7 @@ SCE_STUDIO_REQUIRE_AUTH=1 SCE_STUDIO_AUTH_PASSWORD=top-secret sce studio apply -
 ```
 
 Studio JSON output now includes a stable UI-oriented task stream contract (in addition to existing `job_*` fields):
-- root IDs: `sessionId`, `sceneId`, `specId`, `taskId`, `eventId`
+- root IDs: `sessionId`, `sceneId`, `specId`, `taskId`, `taskRef`, `eventId`
 - `task.goal`, `task.status`, `task.summary` (fixed 3-line summary), `task.handoff`, `task.next_action`
 - `task.file_changes[]`: `path`, `line`, `diffRef`
 - `task.commands[]`: `cmd`, `exit_code`, `stdout`, `stderr`, `log_path`
@@ -578,6 +594,9 @@ Studio JSON output now includes a stable UI-oriented task stream contract (in ad
 - `task.evidence[]`: structured evidence references
 - `event[]`: raw audit event stream (`studio events` also keeps legacy `events[]` for compatibility)
 - `studio events --openhands-events <path>` switches `source_stream=openhands` and maps OpenHands raw events to the same task contract fields.
+- hierarchical task reference lookup/rerun:
+  - `sce task show --ref <SS.PP.TT> --json`
+  - `sce task rerun --ref <SS.PP.TT> [--dry-run] --json`
 
 Stage guardrails are enforced by default:
 - `plan` requires `--scene`; SCE binds one active primary session per scene

package/lib/commands/studio.js

@@ -11,6 +11,8 @@ const {
 const { findRelatedSpecs } = require('../spec/related-specs');
 const { captureTimelineCheckpoint } = require('../runtime/project-timeline');
 const { runProblemEvaluation } = require('../problem/problem-evaluator');
+const { TaskRefRegistry } = require('../task/task-ref-registry');
+const { getSceStateStore } = require('../state/sce-state-store');
 const {
   loadStudioIntakePolicy,
   runStudioAutoIntake,
@@ -40,8 +42,7 @@ function resolveStudioPaths(projectPath = process.cwd()) {
     projectPath,
     studioDir,
     jobsDir: path.join(studioDir, 'jobs'),
-    latestFile: path.join(studioDir, 'latest-job.json'),
-    eventsDir: path.join(studioDir, 'events')
+    latestFile: path.join(studioDir, 'latest-job.json')
   };
 }
 
@@ -597,7 +598,6 @@ async function writeStudioReport(projectPath, relativePath, payload, fileSystem
 
 async function ensureStudioDirectories(paths, fileSystem = fs) {
   await fileSystem.ensureDir(paths.jobsDir);
-  await fileSystem.ensureDir(paths.eventsDir);
 }
 
 async function writeLatestJob(paths, jobId, fileSystem = fs) {
@@ -622,10 +622,6 @@ function getJobFilePath(paths, jobId) {
   return path.join(paths.jobsDir, `${jobId}.json`);
 }
 
-function getEventLogFilePath(paths, jobId) {
-  return path.join(paths.eventsDir, `${jobId}.jsonl`);
-}
-
 async function saveJob(paths, job, fileSystem = fs) {
   const jobFile = getJobFilePath(paths, job.job_id);
   await fileSystem.writeJson(jobFile, job, { spaces: 2 });
@@ -640,40 +636,28 @@ async function appendStudioEvent(paths, job, eventType, metadata = {}, fileSyste
     timestamp: nowIso(),
     metadata
   };
-  const eventLine = `${JSON.stringify(event)}\n`;
-  const eventFile = getEventLogFilePath(paths, job.job_id);
-  await fileSystem.appendFile(eventFile, eventLine, 'utf8');
+  const sceneId = normalizeString(job?.scene?.id) || null;
+  const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id) || null;
+  const stateStore = getSceStateStore(paths.projectPath, { fileSystem });
+  const persisted = await stateStore.appendStudioEvent({
+    ...event,
+    scene_id: sceneId,
+    spec_id: specId
+  });
+  if (!persisted) {
+    throw new Error('Failed to persist studio event into sqlite state store');
+  }
   return event;
 }
 
 async function readStudioEvents(paths, jobId, options = {}, fileSystem = fs) {
   const { limit = 50 } = options;
-  const eventFile = getEventLogFilePath(paths, jobId);
-  const exists = await fileSystem.pathExists(eventFile);
-  if (!exists) {
-    return [];
-  }
-
-  const content = await fileSystem.readFile(eventFile, 'utf8');
-  const lines = content
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean);
-
-  const parsed = [];
-  for (const line of lines) {
-    try {
-      const payload = JSON.parse(line);
-      parsed.push(payload);
-    } catch (_error) {
-      // Ignore malformed lines to keep event stream robust.
-    }
-  }
-
-  if (limit <= 0) {
-    return parsed;
+  const stateStore = getSceStateStore(paths.projectPath, { fileSystem });
+  const events = await stateStore.listStudioEvents(jobId, { limit });
+  if (events === null) {
+    throw new Error('SQLite state backend unavailable while reading studio events');
   }
-  return parsed.slice(-limit);
+  return events;
 }
 
 async function loadJob(paths, jobId, fileSystem = fs) {
@@ -1333,20 +1317,20 @@ function collectTaskEvidence(job = {}, stageName = '', stageMetadata = {}) {
   if (normalizeString(job && job.job_id)) {
     evidence.push({
       type: 'event-log',
-      ref: `.sce/studio/events/${job.job_id}.jsonl`,
-      detail: 'raw-audit-stream'
+      ref: '.sce/state/sce-state.sqlite',
+      detail: `studio_event_stream:job_id=${job.job_id}`
     });
   }
 
   return normalizeTaskEvidence(evidence);
 }
 
-function buildTaskSummaryLines(job = {}, stageName = '', taskStatus = '', nextAction = '') {
+function buildTaskSummaryLines(job = {}, stageName = '', taskStatus = '', nextAction = '', taskRef = '') {
   const sceneId = normalizeString(job?.scene?.id) || 'scene.n/a';
   const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id) || 'spec.n/a';
   const progress = buildProgress(job);
   return [
-    `Stage: ${stageName || 'plan'} | Status: ${taskStatus || 'unknown'}`,
+    `Stage: ${stageName || 'plan'} | Status: ${taskStatus || 'unknown'}${taskRef ? ` | Ref: ${taskRef}` : ''}`,
     `Scene: ${sceneId} | Spec: ${specId} | Progress: ${progress.completed}/${progress.total}`,
     `Next: ${nextAction || 'n/a'}`
   ];
@@ -1380,6 +1364,7 @@ function buildTaskEnvelope(mode, job, options = {}) {
   const sessionId = normalizeString(job?.session?.scene_session_id) || null;
   const sceneId = normalizeString(job?.scene?.id) || null;
   const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id) || null;
+  const taskRef = normalizeString(options.taskRef) || null;
 
   const commands = normalizeTaskCommands([
     ...(Array.isArray(stageMetadata.commands) ? stageMetadata.commands : []),
@@ -1401,17 +1386,24 @@ function buildTaskEnvelope(mode, job, options = {}) {
       release_ref: normalizeString(stageMetadata.release_ref) || normalizeString(job?.artifacts?.release_ref) || null
     };
 
+  const normalizedHandoff = {
+    ...handoff,
+    task_ref: taskRef
+  };
+
   return {
     sessionId,
     sceneId,
     specId,
     taskId,
+    taskRef,
     eventId: normalizeString(latestEvent && latestEvent.event_id) || null,
     task: {
+      ref: taskRef,
       goal,
       status: taskStatus,
-      summary: buildTaskSummaryLines(job, stageName, taskStatus, nextAction),
-      handoff,
+      summary: buildTaskSummaryLines(job, stageName, taskStatus, nextAction, taskRef),
+      handoff: normalizedHandoff,
       next_action: nextAction,
       file_changes: fileChanges,
       commands,
@@ -1862,7 +1854,49 @@ function ensureNotRolledBack(job, stageName) {
   }
 }
 
-function buildCommandPayload(mode, job, options = {}) {
+function buildStudioTaskKey(stageName = '') {
+  const normalizedStage = normalizeString(stageName) || 'task';
+  return `studio:${normalizedStage}`;
+}
+
+async function resolveTaskReference(mode, job, options = {}) {
+  const explicitTaskRef = normalizeString(options.taskRef);
+  if (explicitTaskRef) {
+    return explicitTaskRef;
+  }
+
+  const sceneId = normalizeString(job?.scene?.id);
+  const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id);
+  if (!sceneId || !specId) {
+    return null;
+  }
+
+  const stageName = resolveTaskStage(mode, job, options.stageName);
+  const taskKey = normalizeString(options.taskKey) || buildStudioTaskKey(stageName);
+  const projectPath = normalizeString(options.projectPath) || process.cwd();
+  const fileSystem = options.fileSystem || fs;
+  const taskRefRegistry = options.taskRefRegistry || new TaskRefRegistry(projectPath, { fileSystem });
+
+  try {
+    const taskRef = await taskRefRegistry.resolveOrCreateRef({
+      sceneId,
+      specId,
+      taskKey,
+      source: 'studio-stage',
+      metadata: {
+        mode: normalizeString(mode) || null,
+        stage: stageName || null,
+        job_id: normalizeString(job?.job_id) || null
+      }
+    });
+    return taskRef.task_ref;
+  } catch (_error) {
+    return null;
+  }
+}
+
+async function buildCommandPayload(mode, job, options = {}) {
+  const taskRef = await resolveTaskReference(mode, job, options);
   const base = {
     mode,
     success: true,
@@ -1874,7 +1908,10 @@ function buildCommandPayload(mode, job, options = {}) {
   };
   return {
     ...base,
-    ...buildTaskEnvelope(mode, job, options)
+    ...buildTaskEnvelope(mode, job, {
+      ...options,
+      taskRef
+    })
   };
 }
 
@@ -2367,9 +2404,11 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-plan', job, {
+  const payload = await buildCommandPayload('studio-plan', job, {
     stageName: 'plan',
-    event: planEvent
+    event: planEvent,
+    projectPath,
+    fileSystem
   });
   payload.scene = {
     id: sceneId,
@@ -2465,9 +2504,11 @@ async function runStudioGenerateCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-generate', job, {
+  const payload = await buildCommandPayload('studio-generate', job, {
     stageName: 'generate',
-    event: generateEvent
+    event: generateEvent,
+    projectPath,
+    fileSystem
   });
   printStudioPayload(payload, options);
   return payload;
@@ -2535,9 +2576,11 @@ async function runStudioApplyCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-apply', job, {
+  const payload = await buildCommandPayload('studio-apply', job, {
     stageName: 'apply',
-    event: applyEvent
+    event: applyEvent,
+    projectPath,
+    fileSystem
   });
   printStudioPayload(payload, options);
   return payload;
@@ -2685,9 +2728,11 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-verify', job, {
+  const payload = await buildCommandPayload('studio-verify', job, {
     stageName: 'verify',
-    event: verifyEvent
+    event: verifyEvent,
+    projectPath,
+    fileSystem
   });
   printStudioPayload(payload, options);
   return payload;
@@ -2894,9 +2939,11 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-release', job, {
+  const payload = await buildCommandPayload('studio-release', job, {
     stageName: 'release',
-    event: releaseEvent
+    event: releaseEvent,
+    projectPath,
+    fileSystem
   });
   printStudioPayload(payload, options);
   return payload;
@@ -2916,8 +2963,10 @@ async function runStudioResumeCommand(options = {}, dependencies = {}) {
 
   const job = await loadJob(paths, jobId, fileSystem);
   const events = await readStudioEvents(paths, jobId, { limit: 20 }, fileSystem);
-  const payload = buildCommandPayload('studio-resume', job, {
-    events
+  const payload = await buildCommandPayload('studio-resume', job, {
+    events,
+    projectPath,
+    fileSystem
   });
   payload.success = true;
   printStudioPayload(payload, options);
@@ -2975,9 +3024,11 @@ async function runStudioRollbackCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-rollback', job, {
+  const payload = await buildCommandPayload('studio-rollback', job, {
     stageName: 'rollback',
-    event: rollbackEvent
+    event: rollbackEvent,
+    projectPath,
+    fileSystem
   });
   payload.rollback = { ...job.rollback };
   printStudioPayload(payload, options);
@@ -3035,7 +3086,11 @@ async function runStudioEventsCommand(options = {}, dependencies = {}) {
     sourceStream = 'openhands';
   }
 
-  const payload = buildCommandPayload('studio-events', job, { events });
+  const payload = await buildCommandPayload('studio-events', job, {
+    events,
+    projectPath,
+    fileSystem
+  });
   payload.limit = limit;
   payload.source_stream = sourceStream;
   if (sourceStream === 'openhands') {