scene-capability-engine 3.3.17 → 3.3.21

package/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.21] - 2026-02-27
+
+### Fixed
+- `git-managed-gate` now supports CI tag/detached-HEAD release workflows by default:
+  - In CI context (`CI=1` or `GITHUB_ACTIONS=1`), branch/upstream sync checks are relaxed to avoid false blocking.
+  - Local release checks remain strict (clean worktree + branch/upstream sync).
+  - Added strict CI override: `SCE_GIT_MANAGEMENT_STRICT_CI=1` (or `--strict-ci`) for full enforcement in CI.
+
+### Changed
+- Added CI-aware flags for `git-managed-gate`:
+  - `--ci-context` / `--no-ci-context`
+  - `--strict-ci` / `--no-strict-ci`
+- Updated release and command documentation to clarify local-vs-CI gate behavior.
+
+## [3.3.19] - 2026-02-26
+
+### Added
+- Errorbook release gate command and script:
+  - `sce errorbook release-gate --min-risk <low|medium|high> [--include-verified] [--fail-on-block]`
+  - `node scripts/errorbook-release-gate.js --fail-on-block`
+- `package.json` script alias:
+  - `npm run gate:errorbook-release`
+- Git managed release gate script and alias:
+  - `node scripts/git-managed-gate.js --fail-on-violation`
+  - `npm run gate:git-managed`
+
+### Changed
+- `prepublishOnly` now enforces git-managed gate + errorbook release gate before interactive governance checks.
+- Studio gate failures are now auto-recorded into `.sce/errorbook` as `candidate` entries (tagged `release-blocker`) to avoid manual reminders.
+- Studio release preflight now includes `git-managed-gate` and `errorbook-release-gate` as required gate steps when scripts are available.
+
+## [3.3.18] - 2026-02-26
+
+### Added
+- Curated `errorbook` command set for high-signal failure remediation knowledge:
+  - `sce errorbook record`
+  - `sce errorbook list`
+  - `sce errorbook show <id>`
+  - `sce errorbook find --query <text>`
+  - `sce errorbook promote <id>`
+  - `sce errorbook deprecate <id> --reason <text>`
+  - `sce errorbook requalify <id> --status <candidate|verified>`
+
+### Changed
+- Added strict curation/promotion policy to command reference (`宁缺毋滥，优胜略汰`):
+  - fingerprint-based deduplication on record
+  - promotion gate requires validated root cause, fix actions, verification evidence, ontology tags, and minimum quality score
+
 ## [3.3.17] - 2026-02-26
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@
 > **⚠️ Important Clarification**: `scene-capability-engine` (`sce`) is an **npm package and CLI tool** for spec-driven development.  
 > Primary command is `sce`. Compatibility aliases are preserved for migration.
 
-**A context provider for AI coding tools** - Structure your project requirements, design, and tasks so AI assistants can help you build better software.
+**SCE (Scene Capability Engine) is an ontology-aware scene orchestration engine for AI agents** across plan, generate, patch, verify, and release workflows.
 
 **🚀 NEW: Autonomous Control** - Let AI independently manage entire development workflows from requirements to delivery.
 
@@ -16,7 +16,7 @@ English | [简体中文](README.zh.md)
 
 ## What is sce?
 
-**SCE (Scene Capability Engine) is a context management system for AI-assisted development.** It helps you organize project information into structured "Specs" (Requirements → Design → Tasks) that AI tools can understand and use effectively.
+**SCE (Scene Capability Engine) is an ontology-aware scene orchestration engine for AI-assisted development.** It organizes project information into structured "Specs" (Requirements → Design → Tasks) and routes execution through plan → generate → patch → verify → release workflows.
 
 Think of sce as a **librarian for your AI assistant** - it organizes and presents project context so your AI tool knows exactly what you're building, why, and how.
 
@@ -69,13 +69,16 @@ graph LR
 # 1) Adopt sce in current repo
 sce adopt
 
-# 2) Generate Spec workflow draft
-sce spec bootstrap --name 01-00-demo-feature --non-interactive
+# 2) Open primary scene session
+sce studio plan --scene scene.demo --from-chat session-demo --goal "demo workflow bootstrap" --json
 
-# 3) Generate KPI input sample
+# 3) Generate Spec workflow draft
+sce spec bootstrap --name 01-00-demo-feature --scene scene.demo --non-interactive
+
+# 4) Generate KPI input sample
 sce value metrics sample --out ./kpi-input.json --json
 
-# 4) Produce machine-readable KPI snapshot
+# 5) Produce machine-readable KPI snapshot
 sce value metrics snapshot --input ./kpi-input.json --json
 ```
 
@@ -559,13 +562,18 @@ sce auto schema check --json # Check autonomous archive schema compatibility
 sce auto schema migrate --apply --json # Backfill/migrate schema_version for autonomous archives
 
 # Spec workflow (recommended)
-sce spec bootstrap --name <spec> --non-interactive         # Generate requirements/design/tasks draft
-sce spec pipeline run --spec <spec>                         # Run staged workflow for one Spec
-sce spec gate run --spec <spec> --json                      # Run standardized Spec gate checks
+sce spec bootstrap --name <spec> --scene <scene-id> --non-interactive # Generate draft and bind as scene child session
+sce spec pipeline run --spec <spec> --scene <scene-id>                 # Run pipeline and auto-archive spec child session
+sce spec gate run --spec <spec> --scene <scene-id> --json  # Run gate and auto-archive spec child session
 sce spec bootstrap --specs "<spec-a,spec-b>" --max-parallel <N>  # Multi-Spec defaults to orchestrate
 sce spec pipeline run --specs "<spec-a,spec-b>" --max-parallel <N> # Multi-Spec defaults to orchestrate
 sce spec gate run --specs "<spec-a,spec-b>" --max-parallel <N>     # Multi-Spec defaults to orchestrate
 
+# Spec session governance default
+# - spec bootstrap|pipeline run|gate run must bind to an active scene primary session.
+# - Use --scene <scene-id> explicitly when multiple active scenes exist.
+# - Multi-Spec orchestrate fallback (--specs ...) keeps the same scene binding and archives per-spec child sessions.
+
 # Context management
 sce context export <spec-name>     # Export context for AI tools
 sce prompt generate <spec> <task>  # Generate task-specific prompt
@@ -739,7 +747,8 @@ MIT License - see [LICENSE](LICENSE) file for details.
 ```bash
 npm install -g scene-capability-engine
 sce adopt
-sce spec bootstrap --name 01-00-my-first-feature --non-interactive
+sce studio plan --scene scene.demo --from-chat session-demo --goal "bootstrap first feature" --json
+sce spec bootstrap --name 01-00-my-first-feature --scene scene.demo --non-interactive
 ```
 
 ---

package/README.zh.md

@@ -6,7 +6,7 @@
 > **⚠️ 重要说明**: `scene-capability-engine`（`sce`）是一个 **npm 包和 CLI 工具**，用于 Spec 驱动开发。  
 > 主命令为 `sce`，兼容别名保留用于迁移。
 
-**AI 编码工具的上下文提供者** - 结构化你的项目需求、设计和任务，让 AI 助手帮你构建更好的软件。
+**SCE（场景能力引擎）是一个面向 AI Agent 的本体感知场景编排引擎**，覆盖 plan、generate、patch、verify、release 全流程。
 
 [English](README.md) | 简体中文
 
@@ -14,7 +14,7 @@
 
 ## 什么是 sce？
 
-**SCE（场景能力引擎）是一个 AI 辅助开发的上下文管理系统。** 它帮助你将项目信息组织成结构化的 "Spec"（需求 → 设计 → 任务），让 AI 工具能够理解和有效使用。
+**SCE（场景能力引擎）是一个面向 AI 辅助开发的本体感知场景编排引擎。** 它将项目信息组织成结构化 Spec（需求 → 设计 → 任务），并通过 plan → generate → patch → verify → release 的流程路由执行。
 
 把 sce 想象成 **AI 助手的图书管理员** - 它组织和呈现项目上下文，让你的 AI 工具准确知道你在构建什么、为什么构建以及如何构建。
 
@@ -67,13 +67,16 @@ graph LR
 # 1) 在当前仓库启用 sce
 sce adopt
 
-# 2) 生成 Spec 工作流草稿
-sce spec bootstrap --name 01-00-demo-feature --non-interactive
+# 2) 打开主场景会话
+sce studio plan --scene scene.demo --from-chat session-demo --goal "demo workflow bootstrap" --json
 
-# 3) 生成 KPI 输入样例
+# 3) 生成 Spec 工作流草稿
+sce spec bootstrap --name 01-00-demo-feature --scene scene.demo --non-interactive
+
+# 4) 生成 KPI 输入样例
 sce value metrics sample --out ./kpi-input.json --json
 
-# 4) 产出机器可读 KPI 快照
+# 5) 产出机器可读 KPI 快照
 sce value metrics snapshot --input ./kpi-input.json --json
 ```
 
@@ -473,13 +476,18 @@ sce auto schema check --json # 检查自治归档 schema 兼容性
 sce auto schema migrate --apply --json # 回填/迁移自治归档 schema_version
 
 # Spec 工作流（推荐）
-sce spec bootstrap --name <spec> --non-interactive          # 生成 requirements/design/tasks 初稿
-sce spec pipeline run --spec <spec>                         # 对单个 Spec 执行分阶段流程
-sce spec gate run --spec <spec> --json                      # 执行标准化 Spec 闸口检查
+sce spec bootstrap --name <spec> --scene <scene-id> --non-interactive # 生成初稿并绑定 scene 子会话
+sce spec pipeline run --spec <spec> --scene <scene-id>                 # 执行分阶段流程并自动归档子会话
+sce spec gate run --spec <spec> --scene <scene-id> --json              # 执行闸口并自动归档子会话
 sce spec bootstrap --specs "<spec-a,spec-b>" --max-parallel <N>  # 多 Spec 默认转 orchestrate
 sce spec pipeline run --specs "<spec-a,spec-b>" --max-parallel <N> # 多 Spec 默认转 orchestrate
 sce spec gate run --specs "<spec-a,spec-b>" --max-parallel <N>     # 多 Spec 默认转 orchestrate
 
+# Spec 会话治理默认规则
+# - spec bootstrap|pipeline run|gate run 必须绑定活动中的 scene 主会话
+# - 当存在多个活动 scene 时，必须显式传入 --scene <scene-id>
+# - 多 Spec orchestrate 回退路径同样按 scene 绑定并写入每个 spec 的子会话归档
+
 # 上下文管理
 sce context export <spec-name>     # 为 AI 工具导出上下文
 sce prompt generate <spec> <task>  # 生成任务特定提示
@@ -546,7 +554,8 @@ sce orchestrate run --specs "<spec列表>" --max-parallel <N>  # 启动多 Agent
 sce orchestrate status                         # 查看编排进度
 sce orchestrate stop                           # 停止所有子 Agent
 
-# 说明：当使用 --specs 调用 sce spec bootstrap/pipeline run/gate run 时，会默认转到 orchestrate 模式
+# 说明：当使用 --specs 调用 sce spec bootstrap/pipeline run/gate run 时，会默认转到 orchestrate 模式，
+# 且仍要求绑定活动 scene 主会话（多活动 scene 时必须显式 --scene）
 
 # 发布基线（CI 默认）
 sce auto handoff preflight-check --require-pass --json  # 硬门禁：preflight 不通过则阻断发布
@@ -631,7 +640,8 @@ MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
 ```bash
 npm install -g scene-capability-engine
 sce adopt
-sce spec bootstrap --name 01-00-my-first-feature --non-interactive
+sce studio plan --scene scene.demo --from-chat session-demo --goal "bootstrap first feature" --json
+sce spec bootstrap --name 01-00-my-first-feature --scene scene.demo --non-interactive
 ```
 
 ---

package/bin/scene-capability-engine.js

@@ -817,6 +817,10 @@ registerLockCommands(program);
 const { registerKnowledgeCommands } = require('../lib/commands/knowledge');
 registerKnowledgeCommands(program);
 
+// Errorbook commands
+const { registerErrorbookCommands } = require('../lib/commands/errorbook');
+registerErrorbookCommands(program);
+
 // Studio orchestration commands
 const { registerStudioCommands } = require('../lib/commands/studio');
 registerStudioCommands(program);

package/docs/command-reference.md

@@ -49,17 +49,20 @@ sce doctor
 ### Spec Management
 
 ```bash
+# Ensure an active scene primary session exists first
+sce studio plan --scene scene.customer-order-inventory --from-chat session-20260226 --goal "spec delivery cycle" --json
+
 # Legacy low-level: create spec directory only
 sce create-spec 01-00-feature-name
 
 # Bootstrap full Spec draft (requirements/design/tasks)
-sce spec bootstrap --name 01-00-feature-name --non-interactive
+sce spec bootstrap --name 01-00-feature-name --scene scene.customer-order-inventory --non-interactive
 
 # Run pipeline for one Spec
-sce spec pipeline run --spec 01-00-feature-name
+sce spec pipeline run --spec 01-00-feature-name --scene scene.customer-order-inventory
 
 # Run gate for one Spec
-sce spec gate run --spec 01-00-feature-name --json
+sce spec gate run --spec 01-00-feature-name --scene scene.customer-order-inventory --json
 
 # Multi-Spec mode defaults to orchestrate routing
 sce spec bootstrap --specs "spec-a,spec-b" --max-parallel 3
@@ -70,6 +73,11 @@ sce spec gate run --specs "spec-a,spec-b" --max-parallel 3
 sce status --verbose
 ```
 
+Spec session governance:
+- `spec bootstrap|pipeline run|gate run` must bind to an active scene primary session (`--scene <scene-id>` or implicit binding from latest/unique active scene).
+- When multiple active scenes exist, you must pass `--scene` explicitly.
+- Multi-Spec orchestrate fallback (`--specs ...`) follows the same scene binding and writes per-spec child-session archive records.
+
 ### Value Metrics
 
 ```bash
@@ -152,6 +160,11 @@ sce session snapshot release-20260224 --summary "post-gate checkpoint" --payload
 sce session show release-20260224 --json
 ```
 
+Session governance defaults:
+- `1 scene = 1 primary session` (managed by `studio plan --scene ...`)
+- `spec` runs can bind as child sessions (`spec bootstrap|pipeline --scene <scene-id>`)
+- successful `studio release` auto-archives current scene session and opens next cycle session
+
 ### Watch Mode
 
 ```bash
@@ -318,13 +331,73 @@ Rate-limit profiles:
 - `balanced`: default profile for normal multi-agent runs
 - `aggressive`: higher throughput with lower protection margins
 
+### Errorbook (Curated Failure Knowledge)
+
+```bash
+# Record curated remediation entry
+sce errorbook record \
+  --title "Order approval queue saturation" \
+  --symptom "Approval queue backlog exceeded SLA" \
+  --root-cause "Worker pool under-provisioned and retries amplified load" \
+  --fix-action "Increase workers from 4 to 8" \
+  --fix-action "Reduce retry burst window" \
+  --verification "Load test confirms p95 < SLA threshold" \
+  --ontology "entity,relation,decision_policy" \
+  --tags "moqui,order,performance" \
+  --status verified \
+  --json
+
+# List/show/find entries
+sce errorbook list --status promoted --min-quality 75 --json
+sce errorbook show <entry-id> --json
+sce errorbook find --query "approve order timeout" --limit 10 --json
+
+# Promote only after strict gate checks pass
+sce errorbook promote <entry-id> --json
+
+# Eliminate obsolete/low-value entries (curation)
+sce errorbook deprecate <entry-id> --reason "superseded by v2 policy" --json
+
+# Requalify deprecated entry after remediation review
+sce errorbook requalify <entry-id> --status verified --json
+
+# Release hard gate (default in prepublish and studio release preflight)
+sce errorbook release-gate --min-risk high --fail-on-block --json
+
+# Git managed hard gate (default in prepublish and studio release preflight)
+node scripts/git-managed-gate.js --fail-on-violation --json
+```
+
+Curated quality policy (`宁缺毋滥，优胜略汰`) defaults:
+- `record` requires: `title`, `symptom`, `root_cause`, and at least one `fix_action`.
+- Fingerprint dedup is automatic; repeated records merge evidence and increment occurrence count.
+- `promote` enforces strict gate:
+  - `root_cause` present
+  - `fix_actions` non-empty
+  - `verification_evidence` non-empty
+  - `ontology_tags` non-empty
+  - `quality_score >= 75`
+- `deprecate` requires explicit `--reason` to preserve elimination traceability.
+- `requalify` only accepts `candidate|verified`; `promoted` must still go through `promote` gate.
+- `release-gate` blocks release when unresolved high-risk `candidate` entries remain.
+- `git-managed-gate` blocks release when:
+  - worktree has uncommitted changes
+  - branch has no upstream
+  - branch is ahead/behind upstream
+  - upstream is not a GitHub/GitLab remote (when such remotes exist)
+- If project has no GitHub/GitLab remote, gate passes by default (can hard-enforce with `--no-allow-no-remote` or `SCE_GIT_MANAGEMENT_ALLOW_NO_REMOTE=0`).
+- In CI/tag detached-HEAD context (`CI=1` or `GITHUB_ACTIONS=1`), branch/upstream sync checks are relaxed by default.
+  Use `SCE_GIT_MANAGEMENT_STRICT_CI=1` (or `--strict-ci`) to enforce full local-level branch checks in CI.
+
 ### Studio Workflow
 
 ```bash
-# Build a plan from chat/session context
-sce studio plan --from-chat session-20260226 --goal "customer+order+inventory demo" --json
+# Build a plan from chat/session context (scene is mandatory and becomes the primary session anchor)
+sce studio plan --scene scene.customer-order-inventory --from-chat session-20260226 --goal "customer+order+inventory demo" --json
 
-# Generate patch bundle metadata for a target scene
+# Generate patch bundle metadata (scene is inherited from plan)
+sce studio generate --target 331 --json
+# Optional explicit scene check (must match planned scene)
 sce studio generate --scene scene.customer-order-inventory --target 331 --json
 
 # Apply generated patch metadata
@@ -352,6 +425,8 @@ SCE_STUDIO_REQUIRE_AUTH=1 SCE_STUDIO_AUTH_PASSWORD=top-secret sce studio apply -
 ```
 
 Stage guardrails are enforced by default:
+- `plan` requires `--scene`; SCE binds one active primary session per scene
+- successful `release` auto-archives current scene session and auto-opens the next scene cycle session
 - `generate` requires `plan`
 - `apply` requires `generate`
 - `verify` requires `apply`
@@ -359,8 +434,9 @@ Stage guardrails are enforced by default:
 
 Studio gate execution defaults:
 - `verify --profile standard` runs executable gates (unit test script when available, interactive governance report when present, scene package publish-batch dry-run when handoff manifest exists)
-- `release --profile standard` runs executable release preflight (npm pack dry-run, weekly ops gate when summary exists, release asset integrity when evidence directory exists, scene package publish-batch ontology gate, handoff capability matrix gate)
+- `release --profile standard` runs executable release preflight (npm pack dry-run, git managed gate, errorbook release gate, weekly ops gate when summary exists, release asset integrity when evidence directory exists, scene package publish-batch ontology gate, handoff capability matrix gate)
 - `verify/release --profile strict` fails when any required gate step is skipped (for example missing manifest/evidence/scripts)
+- Required gate failures are auto-recorded into `.sce/errorbook` as `candidate` entries (tagged `release-blocker`) for follow-up triage.
 
 Authorization model (optional, policy-driven):
 - Enable policy: `SCE_STUDIO_REQUIRE_AUTH=1`
@@ -1619,18 +1695,24 @@ sce --version
 ### Starting a New Feature
 
 ```bash
+# 0. Open a scene primary session
+sce studio plan --scene scene.customer-order-inventory --from-chat session-20260226 --goal "new feature delivery" --json
+
 # 1. Bootstrap spec draft
-sce spec bootstrap --name 01-00-my-feature --non-interactive
+sce spec bootstrap --name 01-00-my-feature --scene scene.customer-order-inventory --non-interactive
 
 # 2. Run spec pipeline
-sce spec pipeline run --spec 01-00-my-feature
+sce spec pipeline run --spec 01-00-my-feature --scene scene.customer-order-inventory
+
+# 3. Run spec gate
+sce spec gate run --spec 01-00-my-feature --scene scene.customer-order-inventory --json
 
-# 3. Export context
+# 4. Export context
 sce context export 01-00-my-feature
 
-# 4. Work on tasks...
+# 5. Work on tasks...
 
-# 5. Sync progress
+# 6. Sync progress
 sce workspace sync
 ```
 

package/docs/release-checklist.md

@@ -95,12 +95,18 @@ rg -n "github.com/scene-capability-engine/sce" README.md README.zh.md docs START
 ```bash
 git status -sb
 git log --oneline -n 15
+
+# Mandatory managed-repo gate (default in prepublish/release preflight)
+node scripts/git-managed-gate.js --fail-on-violation --json
 ```
 
 Verify:
 
 - Working tree is clean.
 - Commits are logically grouped and messages are release-ready.
+- If GitHub/GitLab remote exists, current branch is upstream-tracked and fully synced (ahead=0, behind=0).
+- If customer has no GitHub/GitLab, gate can be bypassed by policy (`SCE_GIT_MANAGEMENT_ALLOW_NO_REMOTE=1`, default).
+- In CI/tag detached-HEAD contexts, branch/upstream sync checks are relaxed by default; enforce strict mode with `SCE_GIT_MANAGEMENT_STRICT_CI=1` when needed.
 
 ---
 

package/docs/zh/release-checklist.md

@@ -80,12 +80,18 @@ rg -n "github.com/scene-capability-engine/sce" README.md README.zh.md docs START
 ```bash
 git status -sb
 git log --oneline -n 15
+
+# 强制托管门禁（prepublish/release preflight 默认执行）
+node scripts/git-managed-gate.js --fail-on-violation --json
 ```
 
 确认：
 
 - 工作区干净；
 - 提交分组清晰、提交信息可直接用于发布记录。
+- 若配置了 GitHub/GitLab 远端：当前分支必须已设置 upstream 且与远端完全同步（ahead=0, behind=0）。
+- 若客户确实没有 GitHub/GitLab：可通过策略放行（`SCE_GIT_MANAGEMENT_ALLOW_NO_REMOTE=1`，默认开启）。
+- 在 CI/tag 的 detached HEAD 场景下，默认放宽分支/upstream 同步检查；如需强制严格校验，设置 `SCE_GIT_MANAGEMENT_STRICT_CI=1`。
 
 ---