scene-capability-engine 3.6.32 → 3.6.37

package/CHANGELOG.md

@@ -7,6 +7,104 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.37] - 2026-03-12
+
+### Added
+- Added explicit release-environment guidance that clarifies this project publishes only from `v*` tag pushes, requires GitHub Actions secret `NPM_TOKEN`, and must bump `package.json.version` before tagging.
+- Added release notes for `v3.6.37` under `docs/releases/` and `docs/zh/releases/`.
+
+### Changed
+- Removed legacy `kse` command/content references across active code paths, templates, fixtures, watch configuration, version metadata, steering, and release documentation without preserving compatibility aliases.
+- Renamed the multi-workspace directory validation API from `isValidKseDirectory` to `isValidSceDirectory` and updated the related tests.
+- Renamed historical spec/template fixture paths from `kse` identifiers to `sce` identifiers, including scene package template IDs and spec-scene override references.
+- Updated the branding consistency gate to fail on legacy `kse` aliases and stale social handles instead of allowing them to linger in tracked content.
+- Fixed `scripts/git-managed-gate.js` on Windows by falling back to `git.cmd` / `git.exe` resolution, so `prepublishOnly` and release preflight no longer misreport a valid repository as missing git metadata.
+
+### Added
+- Added `lib/auto/handoff-release-gate-history-loaders-service.js` for release-gate history entry normalization, report discovery, seed loading, and merge selection.
+- Added `lib/auto/handoff-run-service.js` for full auto-handoff orchestration outside the command layer.
+- Added `lib/auto/recovery-memory-service.js` for recovery-memory persistence, scope resolution, pruning, and remediation-action selection.
+- Added `lib/auto/batch-goal-input-service.js` for batch goal file loading, semantic decomposition, and summary-resume restoration.
+- Added `lib/auto/handoff-reporting-service.js` for handoff regression/evidence reporting and markdown rendering.
+- Added dedicated unit coverage in `tests/unit/auto/handoff-release-gate-history-loaders-service.test.js`, `tests/unit/auto/handoff-run-service.test.js`, `tests/unit/auto/recovery-memory-service.test.js`, `tests/unit/auto/batch-goal-input-service.test.js`, and `tests/unit/auto/handoff-reporting-service.test.js`.
+
+### Changed
+- Moved `runAutoHandoff` out of `lib/commands/auto.js`, leaving the command layer as a thin dependency-injected wrapper.
+- Moved recovery-memory persistence and remediation-selection flow out of `lib/commands/auto.js`, leaving close-loop recover commands on service-backed wrappers.
+- Moved batch goal input/resume flow out of `lib/commands/auto.js`, including goal-file parsing, semantic decomposition, and summary-based resume assembly.
+- Moved handoff regression/evidence rendering flow out of `lib/commands/auto.js`, leaving report commands on service-backed wrappers.
+- Completed the high-value `auto-handoff` extraction round by splitting snapshot, release-gate loader, and run orchestration boundaries into dedicated services.
+
+## [3.6.34] - 2026-03-08
+
+### Added
+- Added 'docs/refactor-completion-roadmap.md' and 'docs/zh/refactor-completion-roadmap.md' to capture the completed refactor scope and next roadmap.
+- Added 'lib/auto/handoff-capability-matrix-service.js' for handoff capability matrix policy/recommendation/build orchestration.
+- Added 'lib/auto/handoff-release-evidence-service.js' for handoff release-evidence load/merge/report persistence.
+- Added 'lib/auto/handoff-evidence-review-service.js' for evidence snapshots, review-report assembly, and release-draft context resolution.
+- Added 'lib/auto/handoff-release-gate-history-service.js' for release gate history index assembly and markdown rendering.
+
+### Changed
+- Completed a coherent 'auto-handoff' refactor round across capability matrix, release evidence, evidence review, and release gate history subdomains.
+- Updated README/docs hub version markers to '3.6.34'.
+
+## [3.6.33] - 2026-03-08
+
+### Added
+- Added 'docs/auto-refactor-index.md' to track safe 'auto.js' extraction boundaries, cutover status, and validation gates.
+
+### Changed
+- Cut over mainline 'runCloseLoopController' to 'lib/auto/close-loop-controller-service.js' through dependency injection from 'lib/commands/auto.js'.
+- Cut over mainline 'executeCloseLoopBatch' to 'lib/auto/close-loop-batch-service.js' through dependency injection from 'lib/commands/auto.js'.
+- Cut over mainline 'buildAutoObservabilitySnapshot' to 'lib/auto/observability-service.js' through dependency injection from 'lib/commands/auto.js'.
+- Cut over mainline 'executeCloseLoopProgramGoal' to 'lib/auto/close-loop-program-service.js' through dependency injection from 'lib/commands/auto.js'.
+- Cut over program summary helpers (`KPI`, coordination, recovery merge, failure-source indexing) to 'lib/auto/program-summary.js'.
+- Cut over program KPI/audit writers to 'lib/auto/program-output.js'.
+- Cut over batch/program/recover summary console presenter to 'lib/auto/batch-output.js'.
+- Cut over program gate policy/fallback evaluation, anomaly patching, and failure-signature normalization to 'lib/auto/program-governance-helpers.js'.
+- Cut over program governance replay/recover orchestration to 'lib/auto/program-governance-loop-service.js'.
+- Cut over program gate auto-remediation and spec-prune side effects to 'lib/auto/program-auto-remediation-service.js'.
+- Cut over shared JSON/text output writers to 'lib/auto/output-writer.js'.
+- Removed dead duplicate controller queue helper definitions from 'lib/commands/auto.js' after the controller cutover stabilized.
+- Wired controller queue/lock/output helpers into stable command and service boundaries with dedicated controller unit coverage and guarded integration validation.
+- Added dedicated batch-service unit coverage for summary assembly, program-mode diagnostics, and spec-session budget hard-fail handling.
+- Added dedicated observability-service unit coverage and kept command-layer observability snapshot behavior under existing auto command tests.
+- Added dedicated close-loop-program-service unit coverage for recovery, gate, output, and governance-disabled flow behavior.
+- Added dedicated program-summary unit coverage for KPI snapshots, coordination summaries, recovery merge behavior, and failure-source indexing.
+- Added dedicated program-output unit coverage for KPI/audit payload persistence while keeping command-level file output tests green.
+- Added dedicated batch-output unit coverage and kept command-level close-loop presentation flows green.
+- Added dedicated program-governance-helper unit coverage and kept command/integration gate-fallback behavior green.
+- Added dedicated program-governance-loop unit coverage and kept command/integration governance replay behavior green.
+- Added dedicated program-auto-remediation unit coverage and kept command/integration remediation behavior green.
+- Added dedicated output-writer unit coverage and kept command/integration output-file behavior green.
+- Cut over handoff capability matrix policy/recommendation/build flow to 'lib/auto/handoff-capability-matrix-service.js'.
+- Added dedicated handoff-capability-matrix-service unit coverage and kept command/integration handoff matrix flows green.
+- Cut over handoff release-evidence load/merge/report flow to 'lib/auto/handoff-release-evidence-service.js'.
+- Added dedicated handoff-release-evidence-service unit coverage and kept command/integration evidence flows green.
+- Cut over handoff evidence snapshot/review-report/draft-context flow to 'lib/auto/handoff-evidence-review-service.js'.
+- Added dedicated handoff-evidence-review-service unit coverage and kept command/integration review flows green.
+- Cut over handoff release gate history index/markdown flow to 'lib/auto/handoff-release-gate-history-service.js'.
+- Added dedicated handoff-release-gate-history-service unit coverage and kept command/integration gate-index flows green.
+- Cut over handoff baseline / scene-batch / capability-coverage snapshots to 'lib/auto/handoff-snapshots-service.js'.
+- Added dedicated handoff-snapshots-service unit coverage and kept command/integration handoff run and matrix flows green.
+- Continued service-layer extraction by moving recovery-cycle orchestration into 'lib/auto/close-loop-recovery-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving latest recoverable summary/controller selection into 'lib/auto/recovery-selection-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving archive schema check/migrate logic into 'lib/auto/archive-schema-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving close-loop session read logic into 'lib/auto/close-loop-session-storage-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving batch summary read/load logic into 'lib/auto/batch-summary-storage-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving controller session read/load logic into 'lib/auto/controller-session-storage-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving governance session read/load/persist logic into 'lib/auto/governance-session-storage-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving batch/controller session persistence into 'lib/auto/session-persistence-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving close-loop/batch/controller prune orchestration into 'lib/auto/session-prune-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving close-loop/controller/governance session query orchestration into 'lib/auto/session-query-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving governance advisory recovery/controller execution into 'lib/auto/governance-advisory-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving 'buildAutoGovernanceStats' into 'lib/auto/governance-stats-service.js' with dedicated unit coverage.
+- Continued service-layer extraction by moving 'runAutoGovernanceCloseLoop' into 'lib/auto/governance-close-loop-service.js' with dedicated unit coverage.
+- Started service-layer extraction by moving 'runAutoGovernanceMaintenance' into 'lib/auto/governance-maintenance-service.js' with dedicated unit coverage.
+- Completed the planned 'auto.js' governance cutover set: 'governance-signals', governance session/stats presenters, 'governance-maintenance-presenter', 'program-diagnostics', and extracted 'governance-summary' from command mainline.
+- Cut over shared 'retention-policy', 'spec-protection', and 'session-presenter' helpers into 'lib/commands/auto.js' mainline after passing unit and guarded integration validation.
+- Cut over shared 'archive-summary' helpers into 'lib/commands/auto.js' mainline after passing unit and guarded integration validation.
+
 ## [3.6.32] - 2026-03-07
 
 ### Fixed
@@ -193,7 +291,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `state-reconcile-<tag>.json`
 
 ### Changed
-- Release workflow state reconciliation gate is now enforce-by-default (`KSE_RELEASE_STATE_MIGRATION_ENFORCE` defaults to `true`).
+- Release workflow state reconciliation gate is now enforce-by-default (`SCE_RELEASE_STATE_MIGRATION_ENFORCE` defaults to `true`).
 - Release workflow Node runtime updated to `22.x` so sqlite-backed reconciliation can run in release pipeline.
 
 ## [3.6.7] - 2026-03-05
@@ -771,7 +869,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Interactive runtime policy + work-order default pipeline**: Added `interactive-runtime-policy-evaluate` and `interactive-work-order-build`, integrated both into `interactive-customization-loop` and `interactive-flow` (including `sce scene interactive-loop/interactive-flow` passthrough), with default `runtime_mode=ops-fix`, `runtime_environment=staging`, runtime non-allow fail gate option, and auditable work-order artifacts.
 - **Release weekly ops closed-loop summary**: Added `node scripts/release-ops-weekly-summary.js` (npm alias `npm run report:release-ops-weekly`) to aggregate handoff evidence, release-gate history, interactive governance, and matrix signals into one weekly risk/recommendation card (`weekly-ops-summary.json|.md`).
 - **Release workflow weekly ops asset publication**: `release.yml` now exports and publishes `weekly-ops-summary-<tag>.json|.md` alongside governance snapshot and Moqui release evidence assets.
-- **Release weekly ops hard gate**: Added `node scripts/release-weekly-ops-gate.js` (npm alias `npm run gate:release-ops-weekly`) and wired release workflow defaults to block publish when weekly ops summary risk exceeds `medium` (configurable via `KSE_RELEASE_WEEKLY_OPS_*` variables).
+- **Release weekly ops hard gate**: Added `node scripts/release-weekly-ops-gate.js` (npm alias `npm run gate:release-ops-weekly`) and wired release workflow defaults to block publish when weekly ops summary risk exceeds `medium` (configurable via `SCE_RELEASE_WEEKLY_OPS_*` variables).
 - **Unified weekly+drift remediation bundle**: Added `node scripts/release-risk-remediation-bundle.js` (npm alias `npm run report:release-risk-remediation`) and wired release workflow to publish `release-risk-remediation-<tag>.json|.md|.lines` assets derived from merged gate signals.
 - **Release asset integrity hard gate**: Added `node scripts/release-asset-integrity-check.js` (npm alias `npm run gate:release-asset-integrity`) and wired `release.yml` to block publish on missing/empty core release-evidence assets, while exporting `release-asset-integrity-<tag>.json|.md`.
 - **Interactive dialogue governance baseline**: Added `node scripts/interactive-dialogue-governance.js`, baseline policy `docs/interactive-customization/dialogue-governance-policy-baseline.json`, and loop/flow integration so embedded assistants emit `allow|clarify|deny` dialogue decisions with clarification prompts before planning.
@@ -793,7 +891,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Interactive matrix signal closed-loop defaultization**: `interactive-flow` now runs a default matrix snapshot stage (`moqui-template-baseline-report`) after loop execution, persists session matrix artifacts, appends `.sce/reports/interactive-matrix-signals.jsonl`, and exposes matrix controls (`--no-matrix`, thresholds, compare baseline, signal path, fail-on-portfolio/regression/error) in both script and `sce scene interactive-flow`.
 - **Interactive approval workflow state machine**: Added `node scripts/interactive-approval-workflow.js` (status alias `npm run report:interactive-approval-status`) covering `draft/submitted/approved/rejected/executed/verified/archived` transitions, with high-risk execute blocking and append-only approval event audit JSONL.
 - **Interactive Moqui adapter stage-C baseline**: Added `lib/interactive-customization/moqui-interactive-adapter.js` plus `node scripts/interactive-moqui-adapter.js` (alias `npm run report:interactive-adapter-capabilities`) to implement unified adapter contract `capabilities/plan/validate/apply/rollback`, low-risk one-click apply (`low-risk-apply`), policy-aware controlled execution, and append-only execution records with validation snapshot + rollback reference.
-- **Interactive template matrix stage-D baseline**: Added `kse.scene--moqui-interactive-customization-loop--0.1.0` scene package assets (scene-package/scene manifest/template manifest), plus template sedimentation playbook, adapter extension contract schema/sample, and Domain_Pack extension flow docs for cross-stack replication.
+- **Interactive template matrix stage-D baseline**: Added `sce.scene--moqui-interactive-customization-loop--0.1.0` scene package assets (scene-package/scene manifest/template manifest), plus template sedimentation playbook, adapter extension contract schema/sample, and Domain_Pack extension flow docs for cross-stack replication.
 - **Interactive governance observability + alerting**: Added `node scripts/interactive-governance-report.js` (alias `npm run report:interactive-governance`) to compute adoption/success/rollback/security-intercept/satisfaction KPIs, apply threshold alerts, and emit JSON/Markdown governance reports with `--fail-on-alert` gate behavior.
 - **Interactive governance matrix telemetry integration**: `interactive-governance-report` now consumes matrix signals by default, computes matrix pass/regression/stage-error metrics, and enforces threshold alerts for matrix trend degradation.
 - **Matrix regression gate + remediation queue automation**: Added `scripts/matrix-regression-gate.js` and `scripts/moqui-matrix-remediation-queue.js` with npm aliases (`gate:matrix-regression`, `report:matrix-remediation-queue`) so CI/release can enforce configurable regression limits and export close-loop remediation lines from matrix regressions.
@@ -816,8 +914,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Capability matrix recommendations upgrade**: `sce auto handoff capability-matrix` now also recommends baseline-driven phased one-shot remediation commands when Moqui matrix regressions appear in baseline trend comparison.
 - **Handoff profile policy abstraction (`default|moqui|enterprise`)**: `sce auto handoff run` and `sce auto handoff capability-matrix` now support `--profile` preset policies with explicit option override precedence, plus external integration contract guidance in `docs/handoff-profile-integration-guide.md`.
 - **Regression/governance recommendation unification**: `sce auto handoff regression`, `sce auto governance stats`, and governance close-loop release-gate blockers now include baseline-driven phased one-shot remediation guidance for Moqui matrix regressions.
-- **Release workflow matrix evidence hardening**: `test.yml` and `release.yml` now archive matrix/governance artifacts by default and support configurable matrix regression hard-gate controls via `KSE_MATRIX_REGRESSION_GATE_ENFORCE` + `KSE_MATRIX_REGRESSION_GATE_MAX`.
-- **Release workflow Moqui summary alignment**: `release.yml` now explicitly generates and publishes `moqui-release-summary.{json,md}` from baseline + interactive governance + evidence inputs, with optional hard-gate flag `KSE_MOQUI_RELEASE_SUMMARY_ENFORCE`.
+- **Release workflow matrix evidence hardening**: `test.yml` and `release.yml` now archive matrix/governance artifacts by default and support configurable matrix regression hard-gate controls via `SCE_MATRIX_REGRESSION_GATE_ENFORCE` + `SCE_MATRIX_REGRESSION_GATE_MAX`.
+- **Release workflow Moqui summary alignment**: `release.yml` now explicitly generates and publishes `moqui-release-summary.{json,md}` from baseline + interactive governance + evidence inputs, with optional hard-gate flag `SCE_MOQUI_RELEASE_SUMMARY_ENFORCE`.
 - **Release governance snapshot standalone assets**: Added `scripts/release-governance-snapshot-export.js` and wired `release.yml` to publish `governance-snapshot-<tag>.json|.md` as independent governance audit artifacts (with unavailable placeholders when evidence summary is missing).
 - **331-poc integration checklist baseline**: Added `docs/interactive-customization/331-poc-sce-integration-checklist.md` to define minimal runtime contract, default commands, gate defaults, and pass criteria for Moqui + SCE deployment.
 - **Interactive feedback ingestion helper**: Added `node scripts/interactive-feedback-log.js` (alias `npm run log:interactive-feedback`) to append structured business-user feedback events into `.sce/reports/interactive-user-feedback.jsonl` for governance sample coverage and trend stability.
@@ -1200,7 +1298,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.39.0] - 2026-02-10
 
 ### Added
-- **Moqui ERP Adapter**: Integrate Moqui ERP instance into KSE scene runtime
+- **Moqui ERP Adapter**: Integrate Moqui ERP instance into SCE scene runtime
   - `MoquiClient` — HTTP client with JWT auth lifecycle (login, refresh, re-login, logout), retry logic using Node.js built-in `http`/`https`
   - `MoquiAdapter` — Binding handler for `spec.erp.*` and `moqui.*` refs, entity CRUD, service invocation, screen discovery
   - `sce scene connect` — Test connectivity and authentication to Moqui ERP instance
@@ -2004,7 +2102,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Template management: `sce templates update`, `sce templates cache`, `sce templates guide`
   - Custom sources: `sce templates add-source <name> <url>`, `sce templates remove-source <name>`, `sce templates sources`
   - Create Spec from template: `sce spec create <name> --template <template-id>`
-  - Local caching for offline use (~/.kse/templates/)
+  - Local caching for offline use (~/.sce/templates/)
   - Multi-source support with conflict resolution (source:template-id format)
   - Automatic variable substitution ({{SPEC_NAME}}, {{DATE}}, {{AUTHOR}}, etc.)
   - YAML frontmatter removal in applied templates
@@ -2101,10 +2199,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Multi-user support**: Detects and respects `contexts/` multi-user collaboration setup
   - Differential backup: Only backs up violating files/directories (not entire .sce/)
   - Backup location: `.sce/backups/steering-cleanup-{timestamp}/`
-  - Version-based caching (~/.kse/steering-check-cache.json) to avoid repeated checks
+  - Version-based caching (~/.sce/steering-check-cache.json) to avoid repeated checks
   - Performance target: <50ms per check
   - Clear progress messages during auto-fix
-  - Bypass options: `--skip-steering-check` flag and `KSE_SKIP_STEERING_CHECK` environment variable
+  - Bypass options: `--skip-steering-check` flag and `SCE_SKIP_STEERING_CHECK` environment variable
   - Force check option: `--force-steering-check` flag
   - Comprehensive documentation in `.sce/README.md`
 
@@ -2142,7 +2240,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Critical Principle**: Added "测试失败零容忍原则" (Zero Tolerance for Test Failures) to CORE_PRINCIPLES.md
   - Emphasizes "千里之堤溃于蚁穴" - never ignore any test failure
   - Provides clear execution standards and rationale
-  - Aligns with Ultrawork spirit and KSE core values
+  - Aligns with Ultrawork spirit and SCE core values
 
 ### Changed
 - **Documentation Optimization**: Refactored CORE_PRINCIPLES.md for clarity and value density
@@ -2329,7 +2427,7 @@ rm -rf .sce/steering/workspaces
   - `sce workspace remove <name>` - Remove workspace from registry
   - `sce workspace info [name]` - Display workspace details
 - **Data Atomicity Architecture**
-  - Single source of truth: `~/.kse/workspace-state.json`
+  - Single source of truth: `~/.sce/workspace-state.json`
   - Atomic operations for all workspace state changes
   - Automatic migration from legacy format
   - Cross-platform path handling with PathUtils

package/README.md

@@ -1,203 +1,200 @@
-# SCE - Scene Capability Engine
+# SCE - Scene Capability Engine
 
 [![npm version](https://badge.fury.io/js/scene-capability-engine.svg)](https://badge.fury.io/js/scene-capability-engine)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**SCE is a scene capability orchestration engine for AI-native software delivery.**  
-It provides a deterministic path from `goal -> scene -> spec -> patch -> verify -> release`.
+**SCE is a scene-governed execution and governance engine for AI-native software delivery.**
+It turns open-ended agent work into a controlled path from `goal -> scene -> spec -> task -> patch -> verify -> release`.
 
 English | [简体中文](README.zh.md)
 
 ---
 
-## Why SCE
+## What SCE Solves
 
-SCE is designed for teams that want AI agents to deliver software end-to-end without losing control.
+AI agents can generate code quickly, but they also drift, over-create context, lose execution history, and hide risky decisions inside long sessions.
 
-- Keep delivery aligned to requirements through Spec-first workflows.
-- Scale from single-task execution to multi-agent program orchestration.
-- Prevent silent drift with mandatory gates, ontology checks, and release evidence.
-- Preserve local work history with timeline snapshots, not just Git pushes.
+SCE provides the missing control layer:
+
+- `Scene-governed context`: one primary session per scene, many specs per scene, many tasks per spec.
+- `Spec-first execution`: requirements, design, tasks, and gates stay attached to the work, not buried in chat history.
+- `Bounded autonomous delivery`: agents can run `close-loop`, `close-loop-program`, and `close-loop-controller` with retry, fallback, and governance policies.
+- `Recoverable local history`: timeline snapshots, task refs, and SQLite-backed state keep work recoverable even before Git push.
+- `Release-grade governance`: validation gates, handoff evidence, git management checks, and errorbook-driven learning prevent silent regressions.
 
 ---
 
-## Core Capabilities
-
-| Capability | What SCE Provides | Outcome |
-| --- | --- | --- |
-| Scene + Spec model | Scene-governed sessions and Spec lifecycle (`requirements/design/tasks`) | Stable context across long AI runs |
-| Auto intake + Spec governance | Goal intent detection, auto spec bind/create, scene portfolio governance | Automatic scene-to-spec tracking with bounded spec growth |
-| Studio workflow | `studio plan -> generate -> apply -> verify -> release` | Structured chat-to-release execution |
-| Autonomous delivery | `auto close-loop`, `close-loop-program`, `close-loop-controller` | Unattended bounded convergence |
-| Multi-agent orchestration | DAG scheduling, retries, 429 adaptive parallel control | Reliable parallel execution at scale |
-| Domain/ontology governance | problem-domain chain + scene template + gate validation | Fewer semantic regressions |
-| Problem closure loop | problem-domain map + chain + `problem-contract` + closure gate | Root-cause-first fixes with bounded convergence |
-| Problem evaluation routing | Stage-level risk/evidence/readiness scoring with mandatory policy | Adaptive execution strategy with guarded apply/release |
-| Local timeline safety | `timeline save/auto/list/show/restore/push` + key-event auto checkpoints | Recoverable local history |
-| Errorbook-driven repair | Local + registry-backed error patterns and release gates | Faster diagnosis and safer fixes |
-| Release governance | Git-managed gate, errorbook gate, handoff preflight, tag pipeline | Auditable, reproducible releases |
+## Core Model
+
+SCE organizes agent work using one stable hierarchy:
+
+- `session -> scene -> spec -> task -> event`
+- `scene` is the continuity boundary
+- `spec` is the governed work package
+- `task` is the smallest user-facing execution unit
+- `event` remains the raw audit stream behind the task view
+
+This gives you a predictable way to manage long-running agent work without relying on fragile chat context alone.
 
 ---
 
-## 3-Minute Quick Start
+## Major Capabilities
+
+### 1. Scene + Spec Governance
+- Automatic goal intake and spec binding/creation during `studio plan`
+- Scene portfolio governance for existing and new specs
+- Scene/spec/task contracts stored under `.sce/`
+- Historical spec-scene backfill for older projects
+
+### 2. Studio Execution Flow
+- `studio plan -> generate -> apply -> verify -> release`
+- Structured task stream for frontend or IDE integration
+- Task refs (`SS.PP.TT`) for lookup and rerun
+- Auth lease model for protected write operations
+
+### 3. Autonomous Delivery
+- `sce auto close-loop`
+- `sce auto close-loop-batch`
+- `sce auto close-loop-program`
+- `sce auto close-loop-controller`
+- Built-in retry, fallback-chain, governance replay, and anomaly-aware adaptation
+
+### 4. Problem Closure and Errorbook
+- Problem-domain map, chain, contract, and closure gate
+- Incident staging before promotion to the long-term errorbook
+- Local + registry-backed errorbook workflow
+- Default rule: after repeated failed attempts, debug evidence is required
+
+### 5. Local Timeline and SQLite State
+- Timeline save/list/show/restore/push commands
+- SQLite-backed task/event/session state
+- Deterministic task references and rerun support
+- File-to-SQLite migration and reconciliation tooling
+
+### 6. Capability and Scene Assetization
+- Scene/capability inventory and governance views
+- Capability extraction, evaluation, and publication workflow
+- Scene runtime and ontology-oriented execution support
+- Moqui-oriented capability validation and handoff baselines
 
+---
+
+## Quick Start
+
+### Install
 ```bash
-# 1) Install
 npm install -g scene-capability-engine
+```
 
-# 2) Adopt in your project
+### Adopt into a project
+```bash
 sce adopt
+```
 
-# 3) Open a primary scene session
+### Start a scene-governed workflow
+```bash
 sce studio plan --scene scene.demo --from-chat session-demo --goal "bootstrap first feature" --json
-
-# 4) Bootstrap and run one Spec
 sce spec bootstrap --name 01-00-first-feature --scene scene.demo --non-interactive
 sce spec pipeline run --spec 01-00-first-feature --scene scene.demo
 ```
 
-For autonomous execution:
-
+### Run autonomous delivery
 ```bash
 sce auto close-loop "deliver customer + order + inventory baseline"
 ```
 
 ---
 
-## Recommended Workflows
+## Recommended Usage Paths
 
-### 1) Feature Delivery (default)
+### Feature Delivery
 ```bash
-sce studio plan --scene scene.customer-order --from-chat session-20260302 --goal "optimize checkout"
+sce studio plan --scene scene.customer-order --from-chat session-20260308 --goal "optimize checkout" --json
 sce spec bootstrap --name 02-00-checkout-optimization --scene scene.customer-order --non-interactive
-sce spec domain coverage --spec 02-00-checkout-optimization --json
 sce spec gate run --spec 02-00-checkout-optimization --scene scene.customer-order --json
 ```
 
-### 2) Program-Scale Autonomous Delivery
+### Program-Scale Autonomous Delivery
 ```bash
 sce auto close-loop-program "stabilize order lifecycle and release governance" --program-govern-until-stable --json
 ```
 
-### 3) Local History Safety (timeline)
+### Timeline Safety
 ```bash
 sce timeline save --summary "before risky refactor"
 sce timeline list --limit 20
 sce timeline restore <snapshot-id>
-sce timeline push origin main
 ```
 
-### 4) Release Baseline
+### Protected Write Flow
 ```bash
-sce auto handoff preflight-check --require-pass --json
-git tag -a vX.Y.Z -m "vX.Y.Z"
-git push origin vX.Y.Z
+sce auth grant --scope studio:* --reason "apply approved patch" --auth-password <password> --json
+sce auth status --json
 ```
 
 ---
 
-## Default Problem-Solving Loop
+## Default Governance Behavior
 
-SCE now enforces a domain-closed diagnosis and repair route by default:
+SCE is opinionated by default.
 
-1. Scope the problem first with scene artifacts (`problem-domain-map.md`, `scene-spec.md`, `problem-domain-chain.json`, `problem-contract.json`).
-2. Keep trial-and-error history in incident staging (`.sce/errorbook/staging/incidents/`) to avoid repeating failed attempts.
-3. Use problem evaluation to prioritize likely impact areas before applying/releasing changes.
-
-Hard rule defaults:
-- After two failed rounds on the same problem fingerprint, debug evidence is required in subsequent attempts.
-- `studio verify/release` run `problem-closure-gate` by default when a spec is bound.
-- `studio plan` auto-runs goal intake (`bind existing spec` or `create spec`) and writes scene portfolio governance snapshots by default.
-- `studio plan --manual-spec` and `--no-spec-governance` are blocked by default policy; use policy overrides only when absolutely necessary.
-- Historical specs can be scene-governed incrementally via `sce studio backfill-spec-scenes --apply` (writes `.sce/spec-governance/spec-scene-overrides.json`).
+- `studio plan` runs intake and scene/spec governance unless policy explicitly allows bypass.
+- `verify` and `release` enforce problem-closure and related gates when a spec is bound.
+- Autonomous program execution applies gate evaluation, fallback-chain logic, governance replay, and auto-remediation.
+- State persistence prefers SQLite, not ad hoc local caches.
+- Release validation defaults to integration test coverage via `npm run test:release` for faster publish feedback.
 
 ---
 
-## AI Agent Compatibility
-
-SCE is tool-agnostic and works with Codex, Claude Code, Cursor, Windsurf, VS Code Copilot, and other CLI-capable agents.
-
-- Runtime context is managed by `.sce/` (not IDE-specific hidden folders).
-- Session governance is scene-first: `1 scene = 1 primary session`.
-- Spec work is attached as child sessions and auto-archived.
-- Startup now auto-detects adopted projects and aligns takeover baseline defaults automatically.
-- Multi-agent anti-429 runtime now supports deterministic retry spread and machine-readable `rate-limit:decision` telemetry (`rateLimitRetrySpreadMs`, `rateLimitLaunchHoldPollMs`, `rateLimitDecisionEventThrottleMs`).
-- Problem evaluation policy is enabled by default (`.sce/config/problem-eval-policy.json`) and evaluates every Studio stage.
-- Problem closure policy is enabled by default (`.sce/config/problem-closure-policy.json`) and blocks verify/release bypass when required domain/problem evidence is missing.
-- Error handling now follows a full incident loop by default: every record attempt is staged first and auto-closed on verified/promoted outcomes.
-- You can inspect or force-align baseline explicitly:
-  - `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.task_ref`, `task.title_norm`, `task.raw_request`, `task.goal`, `task.sub_goals`, `task.acceptance_criteria`, `task.needs_split`, `task.confidence`, `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
-- Gradual file-to-sqlite migration tooling:
-  - `sce state plan --json`
-  - `sce state doctor --json`
-  - `sce state migrate --all --apply --json`
-  - `sce state reconcile --all --apply --json` (doctor -> migrate -> doctor one-shot)
-  - `sce state export --out .sce/reports/state-migration/state-export.latest.json --json`
-  - reconciliation gate: `npm run gate:state-migration-reconciliation`
-  - release workflow defaults to enforce mode for state reconciliation gate and runs reconcile before publish
-  - runtime reads now prefer sqlite indexes for timeline/scene-session views when indexed data exists
-  - `state doctor` now emits `summary` and runtime diagnostics (`runtime.timeline`, `runtime.scene_session`) with read-source and consistency status
-  - migratable components now include runtime + errorbook + spec-governance + release evidence indexes (`errorbook.entry-index`, `errorbook.incident-index`, `governance.spec-scene-overrides`, `governance.scene-index`, `release.evidence-runs-index`, `release.gate-history-index`)
-- Write authorization lease model (SQLite-backed):
-  - policy file: `.sce/config/authorization-policy.json`
-  - grant lease: `sce auth grant --scope studio:* --reason "<reason>" --auth-password <password> --json`
-  - inspect/revoke: `sce auth status --json` / `sce auth revoke --lease <lease-id> --json`
-  - protected writes accept `--auth-lease <lease-id>` on `studio apply/release/rollback` and `task rerun`
+## Key Integration Points
 
----
+For IDEs, AI shells, or custom frontends, the most important SCE surfaces are:
+
+- `sce studio plan|generate|apply|verify|release`
+- `sce studio events --openhands-events <path>`
+- `sce task ref|show|rerun`
+- `sce timeline save|list|show|restore`
+- `sce capability inventory`
+- `sce auth grant|status|revoke`
+- SQLite state at `.sce/state/sce-state.sqlite`
+
+MagicBall-specific integration surfaces now also include:
 
-## Important Version Changes
+- `sce app bundle list|show|register`
+- `sce app registry status|configure|sync*`
+- `sce app runtime show|releases|install|activate`
+- `sce app engineering show|attach|hydrate|activate`
+- `sce mode application|ontology|engineering home`
+- `sce pm requirement|tracking|planning|change|issue ... --json`
+- `sce ontology er|br|dl ... --json`
+- `sce ontology triad summary --json`
+- `sce assurance resource|logs|backup|config ... --json`
 
-- `3.6.2`: Added release-level version integration tests (`tests/integration/version-cli.integration.test.js`) and switched release default verification to integration-only gate (`npm run test:release`) for faster publish feedback.
-- `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.
-- `3.4.5`: `git-managed-gate` now treats worktree checks as advisory in default relaxed CI mode (`CI/GITHUB_ACTIONS`, non-strict), preventing false release blocking.
-- `3.4.4`: Added `SCE_GIT_MANAGEMENT_ALLOW_UNTRACKED=1` / `--allow-untracked`; release workflow uses it for npm publish after generating release evidence artifacts.
-- `3.4.3`: Introduced mandatory problem evaluation across Studio stages (`plan/generate/apply/verify/release`) with policy file `.sce/config/problem-eval-policy.json` and stage report artifacts.
-- `3.4.2`: Errorbook incident flow moved to full staging closed-loop (attempt history, incident inspection, resolved archive).
-- `3.4.1`: Added workspace takeover baseline automation (`takeover-audit` / `takeover-apply`) and startup alignment defaults.
+Demo remote registries:
+- `magicball-app-bundle-registry`
+- `magicball-app-service-catalog`
+- demo app key: `customer-order-demo`
 
 ---
 
-## Documentation Map
+## Documentation
 
 Start here:
 
 - [Quick Start](docs/quick-start.md)
+- [Quick Start with AI Tools](docs/quick-start-with-ai-tools.md)
 - [Command Reference](docs/command-reference.md)
 - [Autonomous Control Guide](docs/autonomous-control-guide.md)
 - [Scene Runtime Guide](docs/scene-runtime-guide.md)
-- [Value Observability Guide](docs/value-observability-guide.md)
 - [Multi-Agent Coordination Guide](docs/multi-agent-coordination-guide.md)
 - [Errorbook Registry Guide](docs/errorbook-registry.md)
 - [Documentation Hub](docs/README.md)
 
-Moqui-focused:
+Moqui and capability-focused docs:
 
 - [Moqui Template Core Library Playbook](docs/moqui-template-core-library-playbook.md)
 - [Moqui Standard Rebuild Guide](docs/moqui-standard-rebuild-guide.md)
+- [SCE Capability Matrix Roadmap](docs/sce-capability-matrix-roadmap.md)
 
 ---
 
@@ -218,5 +215,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.32  
-**Last Updated**: 2026-03-05
+**Version**: 3.6.34
+**Last Updated**: 2026-03-08