Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (scene-capability-engine) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

SCE - Scene Capability Engine

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 | 简体中文

What SCE Solves

AI agents can generate code quickly, but they also drift, over-create context, lose execution history, and hide risky decisions inside long sessions.

SCE provides the missing control layer:

Scene-governed context: scene stays the semantic boundary, while one project can host many channels/sessions in parallel and each channel keeps its own scene + spec focus.
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 Model

SCE organizes agent work using one stable semantic/collaboration model:

project -> scene -> spec
project -> channel/session -> (scene + spec focus) -> task -> event
scene is the continuity boundary
channel/session is the collaboration thread, not the semantic domain
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.

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
Hierarchical task refs (scene.spec.task / SS.PP.TT) for lookup, controlled rerun, and rerun hints aligned to the original project + channel focus
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
Semantic observation, replay evaluation, local promotion, governed delta export, and native backflow rerank
Shared-library mirror publication that advances qualified lessons from publish_pending to published-shared
semantic promote now auto-publishes qualified lessons by default under the adopt-implied model
Shared-sync handoff bundle export that packages the local semantic mirror into spec-scoped bundle/index/shards/receipt artifacts
Shared-sync intake that lets another terminal sync governed bundle output back into its local semantic mirror
Scene runtime and ontology-oriented execution support
Moqui-oriented capability validation and handoff baselines

Quick Start

Install

npm install -g scene-capability-engine

Adopt into a project

sce adopt

Start a scene-governed workflow

sce studio plan --scene scene.demo --from-chat session-demo --goal "bootstrap first feature" --json
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

Run autonomous delivery

sce auto close-loop "deliver customer + order + inventory baseline"

Recommended Usage Paths

Feature Delivery

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 gate run --spec 02-00-checkout-optimization --scene scene.customer-order --json

Program-Scale Autonomous Delivery

sce auto close-loop-program "stabilize order lifecycle and release governance" --program-govern-until-stable --json

Timeline Safety

sce timeline save --summary "before risky refactor"
sce timeline list --limit 20
sce timeline restore <snapshot-id>

Protected Write Flow

sce auth grant --scope studio:* --reason "apply approved patch" --auth-password <password> --json
sce auth status --json

Default Governance Behavior

SCE is opinionated by default.

studio plan runs intake and scene/spec governance unless policy explicitly allows bypass.
studio plan, studio intake, and native ask pass through the Four Teachings supreme-intent gate first; off-track requests are clarified, rewritten, narrowed, or refused before execution, and existing bound Specs receive governed evidence.
When business scene/module/page/entity context is missing, SCE must route to clarification first; unknown business scope must not be turned into blanket disable.
CORE_PRINCIPLES.md keeps only Four Teachings + Little Nine in the supreme-principle layer; execution baselines belong in RULES_GUIDE.md, and reusable tactics belong in governance docs or lessons.
After two failed localization rounds, record/update an errorbook incident and use bisection-style debug logs to keep halving the failing scope instead of continuing blind patch attempts.
Agent-generated scripts, reports, debug logs, test scripts, and temporary analysis default to the active Spec subdirectories; if no explicit Spec exists yet, use a governed general Spec instead of scattering files.
spec pipeline and spec gate now carry a read-only strategy advisory for single-Spec runs, so broad or clarification-heavy work is surfaced as multi-spec-program / research-program instead of being blindly forced deeper into one Spec.
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.
Co-work baseline is enabled by default: initialized/adopted SCE projects provision .sce/config/multi-agent.json with enabled=true, while the central coordinator stays opt-in.
State persistence prefers SQLite, not ad hoc local caches.
Oversized source files must trigger periodic refactor assessment; SCE recommends project-specific thresholds, with 2000 / 4000 / 10000 as the default source-file fallback.
Release validation defaults to integration test coverage via npm run test:release for faster publish feedback.

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
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:

sce device current
sce device override show|upsert
sce app bundle list|show|register
sce app collection list|show|apply
sce app install-state list
sce scene delivery show
sce scene workspace list|show|apply
sce app registry status|configure|sync*
sce app runtime show|releases|install|activate|uninstall
sce app engineering preview|ownership|open|import|show|attach|hydrate|scaffold|activate
sce project portfolio show|candidate inspect|onboarding import|target resolve|supervision show
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

Demo remote registries:

magicball-app-bundle-registry
magicball-app-service-catalog
demo app key: customer-order-demo

Scene-oriented install-management references:

examples: docs/examples/app-intent-phase1/.sce/app/...
apply JSON contract: docs/app-intent-apply-contract.md

Documentation

Start here:

Moqui and capability-focused docs:

Community

Scan the QR code and note sce to join the WeChat group.

License

MIT. See LICENSE.

Version: 3.6.67 Last Updated: 2026-03-29