scene-capability-engine 3.5.1 → 3.6.0

package/CHANGELOG.md

@@ -7,6 +7,40 @@ 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
+- Studio task-stream contract in command JSON payloads:
+  - root IDs: `sessionId`, `sceneId`, `specId`, `taskId`, `eventId`
+  - normalized task payload: `task.goal`, `task.status`, `task.summary`, `task.handoff`, `task.next_action`
+  - UI-ready arrays: `task.file_changes[]`, `task.commands[]`, `task.errors[]`, `task.evidence[]`
+  - raw audit passthrough: `event[]` (with `studio events` keeping `events[]` compatibility)
+- OpenHands bridge for task stream:
+  - `sce studio events --openhands-events <path>`
+  - supports `.json`/`.jsonl` raw OpenHands events ingestion and maps to SCE task contract fields
+
+### Changed
+- `studio verify/release` now persist `gate_steps` in stage metadata so command execution details can be surfaced in `task.commands[]` and `task.errors[]`.
+
 ## [3.5.1] - 2026-03-03
 
 ### Added

package/README.md

@@ -128,10 +128,30 @@ SCE is tool-agnostic and works with Codex, Claude Code, Cursor, Windsurf, VS Cod
   - `sce workspace takeover-audit --json`
   - `sce workspace takeover-apply --json`
 
+Studio task-stream output contract (default):
+- 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`
+- Errors: `task.errors[]` with `message`, `error_bundle` (copy-ready)
+- 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.
 - `3.4.6`: Added default `problem-closure-gate` + `problem-contract` baseline and strengthened mandatory problem evaluation dimensions (`problem_contract`/`ontology_alignment`/`convergence`) for verify/release convergence control.
@@ -180,5 +200,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.5.1  
-**Last Updated**: 2026-03-03
+**Version**: 3.6.0  
+**Last Updated**: 2026-03-04

package/README.zh.md

@@ -128,10 +128,30 @@ SCE 对工具无锁定，可接入 Codex、Claude Code、Cursor、Windsurf、VS
   - `sce workspace takeover-audit --json`
   - `sce workspace takeover-apply --json`
 
+Studio 任务流输出契约（默认）：
+- 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`）
+- 错误复制：`task.errors[]`（`message`、`error_bundle`，可直接复制给 AI 修复）
+- 证据引用：`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 无序增长。
 - `3.4.6`：新增默认 `problem-closure-gate` + `problem-contract` 基线，并强化问题评估强制维度（`problem_contract`/`ontology_alignment`/`convergence`），提升 verify/release 收敛控制。
@@ -180,5 +200,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.5.1  
-**最后更新**：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

@@ -2,8 +2,8 @@
 
 > Quick reference for all `sce` commands
 
-**Version**: 3.5.0
-**Last Updated**: 2026-03-02
+**Version**: 3.5.2
+**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
@@ -550,6 +566,8 @@ sce studio resume --job <job-id> --json
 
 # Inspect recent stage events
 sce studio events --job <job-id> --limit 50 --json
+# Map OpenHands raw events into the same task-stream contract
+sce studio events --job <job-id> --openhands-events ./openhands-events.json --json
 
 # Rollback a job after apply/release
 sce studio rollback --job <job-id> --reason "manual-check-failed" --json
@@ -567,6 +585,19 @@ sce studio backfill-spec-scenes --scene scene.unassigned --limit 20 --apply --js
 SCE_STUDIO_REQUIRE_AUTH=1 SCE_STUDIO_AUTH_PASSWORD=top-secret sce studio apply --job <job-id> --auth-password top-secret --json
 ```
 
+Studio JSON output now includes a stable UI-oriented task stream contract (in addition to existing `job_*` fields):
+- 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`
+- `task.errors[]`: `message`, `error_bundle` (copy-ready diagnostic bundle)
+- `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
 - `plan` runs auto intake by default (`.sce/config/studio-intake-policy.json`):