scene-capability-engine 3.6.56 → 3.6.58

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.58] - 2026-03-19
+
+### Added
+- Added `sce scene delivery show --scene <scene-id> --json` as the canonical delivery projection envelope for MagicBall/IDE engineering surfaces.
+- Added canonical `sce app engineering preview|ownership|open|import|scaffold` read/result contracts, plus corresponding MagicBall-facing contract docs and audits.
+- Added `sce project portfolio show --json`, `sce project target resolve --json`, and `sce project supervision show --project <project-id> --json` for phase-1 multi-project roster, routing preflight, and project-scoped supervision.
+- Added MagicBall multi-project contract documentation and `audit:magicball-project-contract` so release/publish flow now checks project portfolio/target/supervision doc drift.
+
+### Changed
+- MagicBall entry docs, CLI examples, frontend mapping, checklist, issue tracker, README, and release checklist now explicitly include multi-project shell integration through `project portfolio / target resolve / supervision`.
+- Prepublish release gating now also enforces MagicBall multi-project contract consistency alongside the existing engineering contract audit.
+
+## [3.6.57] - 2026-03-17
+
+### Added
+- Added a read-only `strategy_assessment` advisory to `sce spec gate run --spec <id>` and `sce spec pipeline run --spec <id>` single-Spec output so workflow consumers can see when the current Spec should escalate to `multi-spec-program` or `research-program`.
+
+### Changed
+- Human-readable `spec gate` and `spec pipeline` output now print an explicit strategy advisory for broad or clarification-heavy Specs, without auto-rerouting execution or changing the underlying execution decision itself.
+- Shared project problem projection sync is now idempotent when content does not change, so collaboration governance checks no longer dirty the worktree just by refreshing `generated_at`.
+
 ## [3.6.56] - 2026-03-17
 
 ### Added

package/README.md

@@ -140,6 +140,7 @@ SCE is opinionated by default.
 
 - `studio plan` runs intake and scene/spec governance unless policy explicitly allows bypass.
 - 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.
+- `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.
@@ -168,10 +169,12 @@ MagicBall-specific integration surfaces now also include:
 - `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 show|attach|hydrate|activate`
+- `sce app engineering preview|ownership|open|import|show|attach|hydrate|scaffold|activate`
+- `sce project portfolio show|target resolve|supervision show`
 - `sce mode application|ontology|engineering home`
 - `sce pm requirement|tracking|planning|change|issue ... --json`
 - `sce ontology er|br|dl ... --json`
@@ -227,5 +230,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.56
-**Last Updated**: 2026-03-17
+**Version**: 3.6.58
+**Last Updated**: 2026-03-19

package/README.zh.md

@@ -145,6 +145,7 @@ SCE 默认是强治理的。
 
 - `studio plan` 默认执行 intake 与 scene/spec 治理，除非策略显式允许绕过
 - 缺少业务场景/模块/页面/实体上下文时，SCE 必须先进入澄清，而不是把未知业务范围直接变成一刀切禁用
+- 单 spec 的 `spec pipeline` 和 `spec gate` 现在都会附带只读策略建议；当问题已经更适合 `multi-spec-program` / `research-program` 时，SCE 会显式提示，而不是继续把复杂问题盲目压进同一个 spec
 - 当 spec 绑定时，`verify` 和 `release` 默认执行 problem-closure 等相关门禁
 - `close-loop-program` 默认带 gate 评估、fallback-chain、governance replay、auto-remediation
 - co-work 基线默认开启：初始化或接管后的 SCE 项目会落地 `.sce/config/multi-agent.json` 且 `enabled=true`，但中央 coordinator 仍保持按需开启
@@ -173,10 +174,12 @@ SCE 默认是强治理的。
 - `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 show|attach|hydrate|activate`
+- `sce app engineering preview|ownership|open|import|show|attach|hydrate|scaffold|activate`
+- `sce project portfolio show|target resolve|supervision show`
 - `sce mode application|ontology|engineering home`
 - `sce pm requirement|tracking|planning|change|issue ... --json`
 - `sce ontology er|br|dl ... --json`
@@ -232,5 +235,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.56
-**最后更新**：2026-03-17
+**版本**：3.6.58
+**最后更新**：2026-03-19

package/bin/scene-capability-engine.js

@@ -1066,9 +1066,11 @@ registerCapabilityCommands(program);
 const { registerAppCommands } = require('../lib/commands/app');
 const { registerDeviceCommands } = require('../lib/commands/device');
 const { registerModeCommands } = require('../lib/commands/mode');
+const { registerProjectCommands } = require('../lib/commands/project');
 registerDeviceCommands(program);
 registerAppCommands(program);
 registerModeCommands(program);
+registerProjectCommands(program);
 const { registerPmCommands } = require('../lib/commands/pm');
 registerPmCommands(program);
 const { registerOntologyCommands } = require('../lib/commands/ontology');

package/docs/autonomous-control-guide.md

@@ -97,6 +97,8 @@ Suggested preflight:
 sce spec strategy assess --goal "broad complex goal" --json
 ```
 
+If you are already inside a single Spec flow, `sce spec gate run --spec <spec-id>` and `sce spec pipeline run --spec <spec-id>` now echo the same strategy concern as a non-blocking advisory when one Spec is no longer the right execution container.
+
 # Controller command: drain queue goals with autonomous close-loop-program runtime
 sce auto close-loop-controller .sce/auto/program-queue.lines \
   --dequeue-limit 2 \

package/docs/command-reference.md

@@ -101,6 +101,10 @@ Spec session governance:
 - 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.
 - `sce spec strategy assess` is read-only and should be used when you are not sure whether the current problem still fits one Spec.
+- `sce spec pipeline run --spec <id> --json` now includes the same read-only `strategy_assessment` block for single-Spec runs.
+- `sce spec gate run --spec <id> --json` now includes a read-only `strategy_assessment` block for single-Spec runs.
+- Human-readable `spec gate` output now prints a strategy advisory when the assessed decision is `multi-spec-program` or `research-program`, but it does not auto-reroute execution.
+- Human-readable `spec pipeline` output now prints the same advisory after stage results for single-Spec runs.
 - `spec bootstrap` always generates problem-domain, scene-spec, and `problem-contract` artifacts to force domain-first exploration.
 - `spec gate` now hard-fails when either of the following is missing or structurally incomplete:
   - `.sce/specs/<spec>/custom/problem-domain-map.md`
@@ -407,6 +411,10 @@ sce scene workspace list --json
 sce scene workspace show --workspace sales --json
 sce scene workspace apply --workspace sales --json
 
+# Scene delivery projection
+sce scene delivery show --scene scene.demo --json
+sce scene delivery show --scene scene.demo --spec 01-00-demo --json
+
 # Configure and sync remote registries
 sce app registry status --json
 sce app registry configure --bundle-index-url <path-or-url> --service-index-url <path-or-url> --json
@@ -424,9 +432,14 @@ sce app install-state list --json
 sce app install-state list --install-status installed --json
 
 # Engineering projection
+sce app engineering preview --app customer-order-demo --json
+sce app engineering ownership --app customer-order-demo --json
+sce app engineering open --app customer-order-demo --json
+sce app engineering import --app customer-order-demo --json
 sce app engineering show --app customer-order-demo --json
 sce app engineering attach --app customer-order-demo --repo <repo-url> --branch main --json
 sce app engineering hydrate --app customer-order-demo --json
+sce app engineering scaffold --app customer-order-demo --overwrite-policy missing-only --json
 sce app engineering activate --app customer-order-demo --json
 
 # Three-mode home projections
@@ -2647,6 +2660,69 @@ Overall Health: 2 healthy, 1 unhealthy
 
 ---
 
+## Project Portfolio And Supervision
+
+#### `sce project portfolio show`
+
+Inspect the canonical caller-visible project roster across registered workspaces and the current unregistered `.sce` project when applicable.
+
+**Usage:**
+```bash
+sce project portfolio show [options]
+```
+
+**Options:**
+- `--workspace <name>` - Resolve caller context against one registered workspace without switching the global active workspace
+- `--json` - Output the canonical `ProjectPortfolioProjection`
+
+**Behavior:**
+- Reuses registered workspace visibility from multi-workspace state
+- Marks inaccessible or partial projects explicitly instead of dropping them
+- Reuses project-local session governance signals to summarize active sessions and last activity
+
+#### `sce project target resolve`
+
+Resolve one target project for cross-project flows without mutating active workspace selection.
+
+**Usage:**
+```bash
+sce project target resolve [options]
+```
+
+**Options:**
+- `--request <text>` - Routing request text
+- `--current-project <id>` - Caller asserted current project id
+- `--workspace <name>` - Resolve caller context against one registered workspace
+- `--device <id>` - Opaque caller device id
+- `--tool-instance-id <id>` - Opaque caller tool instance id
+- `--json` - Output the canonical `ProjectTargetResolution`
+
+**Behavior:**
+- Returns `current-project`, `resolved-other-project`, `ambiguous`, or `unresolved`
+- Echoes caller context used during resolution
+- Returns alternative candidates for ambiguous matches
+
+#### `sce project supervision show`
+
+Inspect one project-scoped supervision snapshot with blocked, handoff, risk, and active items.
+
+**Usage:**
+```bash
+sce project supervision show --project <id> [options]
+```
+
+**Options:**
+- `--project <id>` - Visible project id from the portfolio projection
+- `--cursor <cursor>` - Best-effort checkpoint input; phase-1 still returns a full snapshot
+- `--json` - Output the canonical `ProjectSupervisionProjection`
+
+**Behavior:**
+- Reuses project-local session governance, spec governance, and report artifacts
+- Preserves scene/spec/event drillback fields when evidence is available
+- Returns an opaque snapshot cursor for polling without pretending to expose a raw event stream
+
+---
+
 ## See Also
 
 - [Multi-Repository Management Guide](./multi-repo-management-guide.md)

package/docs/magicball-adaptation-task-checklist-v1.md

@@ -12,12 +12,61 @@ This checklist is meant for:
 ## Scope
 
 Current checklist covers:
-1. app selection and mode switching
-2. application mode adaptation
-3. ontology mode adaptation
-4. engineering mode adaptation
-5. write authorization handling
-6. demo app verification
+1. multi-project workspace shell
+2. app selection and mode switching
+3. application mode adaptation
+4. ontology mode adaptation
+5. engineering mode adaptation
+6. write authorization handling
+7. demo app verification
+
+## Phase 0: Multi-project Workspace Shell
+
+### Task 0.1
+Load the engine-owned project roster before building a multi-project shell.
+
+Command:
+```bash
+sce project portfolio show --json
+```
+
+Done when:
+- project switcher is driven by `projects[]`
+- current project marker comes from `activeProjectId`
+- degraded or inaccessible projects are rendered explicitly
+
+### Task 0.2
+Use `projectId` as the frontend multi-project route token.
+
+Done when:
+- registered projects do not depend on path heuristics in the UI
+- frontend no longer rebuilds project identity from local workspace cache alone
+
+### Task 0.3
+Preflight free-text cross-project requests before opening a project-bound assistant or orchestration flow.
+
+Command:
+```bash
+sce project target resolve --request "<text>" --current-project <project-id> --json
+```
+
+Done when:
+- `current-project` and `resolved-other-project` are handled separately
+- `ambiguous` shows a candidate chooser instead of silent auto-selection
+- unresolved routing preserves request text and reason code for clarification
+
+### Task 0.4
+Render project health from the project-scoped supervision snapshot.
+
+Command:
+```bash
+sce project supervision show --project <project-id> --json
+```
+
+Done when:
+- blocked / handoff / risk / active counters come from backend summary directly
+- drillback panels use `items[]` directly
+- frontend does not present `cursor` as a raw event-stream offset
 
 ## Phase 1: App Entry And Mode Switching
 
@@ -55,7 +104,7 @@ sce mode engineering home --app customer-order-demo --json
 Done when:
 - all three mode entry pages are driven by these commands
 - frontend no longer reconstructs runtime/ontology/engineering binding itself
-- frontend loads them sequentially in this order: application -> ontology -> engineering -> engineering show
+- frontend loads them sequentially in this order: application -> ontology -> engineering -> scene delivery -> engineering preview -> engineering ownership
 - frontend does not switch these four reads back to parallel loading until `Issue 001` is explicitly closed in `docs/magicball-integration-issue-tracker.md`
 
 ## Phase 2: Application Mode
@@ -263,15 +312,20 @@ Wire engineering workspace flow.
 
 Commands:
 ```bash
-sce app engineering show --app customer-order-demo --json
+sce app engineering preview --app customer-order-demo --json
+sce app engineering ownership --app customer-order-demo --json
+sce app engineering open --app customer-order-demo --json
+sce app engineering import --app customer-order-demo --json
 sce app engineering attach --app customer-order-demo --repo <repo-url> --branch main --json
 sce app engineering hydrate --app customer-order-demo --json
+sce app engineering scaffold --app customer-order-demo --overwrite-policy missing-only --json
 sce app engineering activate --app customer-order-demo --json
 ```
 
 Done when:
-- MagicBall can detect attached/not-attached state
-- MagicBall can trigger attach/hydrate/activate
+- MagicBall can detect readiness via preview without client-side field synthesis
+- MagicBall can render conservative ownership relation without guessing missing links
+- MagicBall can trigger attach/hydrate/scaffold/activate
 - active engineering workspace path is shown in UI
 
 ## Phase 5: Write Authorization
@@ -301,6 +355,7 @@ Commands that matter now:
 - `sce app registry configure`
 - `sce app engineering attach`
 - `sce app engineering hydrate`
+- `sce app engineering scaffold`
 - `sce app engineering activate`
 - `sce app runtime install`
 - `sce app runtime activate`

package/docs/magicball-cli-invocation-examples.md

@@ -21,7 +21,19 @@ Assume:
 
 ## 1. Workspace Bootstrap
 
-### 1.0 Read current device baseline
+### 1.0 Read multi-project portfolio baseline
+```bash
+sce project portfolio show --json
+sce project target resolve --request "continue customer-order-demo" --json
+sce project supervision show --project workspace:customer-order-demo --json
+```
+
+Expected use:
+- build project switcher from engine-owned roster
+- preflight cross-project free-text routing before assistant/orchestration actions
+- render one project-scoped health summary without replaying raw event streams
+
+### 1.1 Read current device baseline
 ```bash
 sce device current --json
 sce device override show --json
@@ -62,7 +74,7 @@ Example local override patch:
 }
 ```
 
-### 1.1 App bundle identity
+### 1.2 App bundle identity
 ```bash
 sce app bundle show --app customer-order-demo --json
 ```
@@ -72,18 +84,20 @@ Expected use:
 - cache `app_key`
 - cache app-level bundle bindings
 
-### 1.2 Serialized mode-home bootstrap
+### 1.3 Serialized mode-home bootstrap
 Run in this order only:
 
 ```bash
 sce mode application home --app customer-order-demo --json
 sce mode ontology home --app customer-order-demo --json
 sce mode engineering home --app customer-order-demo --json
-sce app engineering show --app customer-order-demo --json
+sce scene delivery show --scene scene.customer-order-demo --json
+sce app engineering preview --app customer-order-demo --json
+sce app engineering ownership --app customer-order-demo --json
 ```
 
 Recommended frontend rule:
-- do not parallelize these four calls during current verification window
+- do not parallelize these six calls during current verification window
 
 ## 2. Application Mode Examples
 
@@ -185,9 +199,33 @@ sce assurance backup list --json
 sce assurance config switches --json
 ```
 
-### 4.4 Read engineering project detail
+### 4.4 Read engineering delivery projection
+```bash
+sce scene delivery show --scene scene.customer-order-demo --json
+```
+
+### 4.5 Read engineering project readiness preview
+```bash
+sce app engineering preview --app customer-order-demo --json
+```
+
+### 4.6 Read engineering ownership relation
+```bash
+sce app engineering ownership --app customer-order-demo --json
+```
+
+### 4.7 Read canonical open/import envelopes
+```bash
+sce app engineering open --app customer-order-demo --json
+sce app engineering import --app customer-order-demo --json
+```
+
+### 4.8 Mutate engineering workspace bindings
 ```bash
-sce app engineering show --app customer-order-demo --json
+sce app engineering attach --app customer-order-demo --repo <repo-url> --branch main --json
+sce app engineering hydrate --app customer-order-demo --json
+sce app engineering scaffold --app customer-order-demo --overwrite-policy missing-only --json
+sce app engineering activate --app customer-order-demo --json
 ```
 
 ## 5. Write Authorization Examples
@@ -316,6 +354,7 @@ async function runSceJson(args: string[]) {
 ### 8.2 Serialized workspace bootstrap wrapper
 ```ts
 async function loadWorkspace(appKey: string) {
+  const projectPortfolio = await runSceJson(['project', 'portfolio', 'show', '--json']);
   const appBundle = await runSceJson(['app', 'bundle', 'show', '--app', appKey, '--json']);
   const applicationHome = await runSceJson(['mode', 'application', 'home', '--app', appKey, '--json']);
   const ontologyHome = await runSceJson(['mode', 'ontology', 'home', '--app', appKey, '--json']);
@@ -323,6 +362,7 @@ async function loadWorkspace(appKey: string) {
   const engineeringDetail = await runSceJson(['app', 'engineering', 'show', '--app', appKey, '--json']);
 
   return {
+    projectPortfolio,
     appBundle,
     applicationHome,
     ontologyHome,
@@ -360,11 +400,16 @@ Suggested error bundle:
 Run this full sequence when verifying MagicBall local integration:
 
 ```bash
+sce project portfolio show --json
+sce project target resolve --request "continue customer-order-demo" --json
+sce project supervision show --project workspace:customer-order-demo --json
 sce app bundle show --app customer-order-demo --json
 sce mode application home --app customer-order-demo --json
 sce mode ontology home --app customer-order-demo --json
 sce mode engineering home --app customer-order-demo --json
-sce app engineering show --app customer-order-demo --json
+sce scene delivery show --scene scene.customer-order-demo --json
+sce app engineering preview --app customer-order-demo --json
+sce app engineering ownership --app customer-order-demo --json
 sce ontology triad summary --json
 sce pm requirement list --json
 sce assurance resource status --json

package/docs/magicball-engineering-projection-contract.md

@@ -0,0 +1,175 @@
+# MagicBall Engineering Projection Contract
+
+## Goal
+
+Provide one narrow contract document for the current engineering-facing SCE payloads that MagicBall should consume directly.
+
+This document is intentionally limited to:
+- delivery projection
+- engineering readiness preview
+- engineering ownership relation
+- canonical open/import result envelopes
+- scaffold result contract
+
+It does not redefine:
+- mode-home payloads
+- PM / ontology / assurance tables
+- write authorization flow
+
+## Current Read Models
+
+### 1. Delivery projection
+
+Command:
+
+```bash
+sce scene delivery show --scene <scene-id> --json
+```
+
+Frontend should rely on:
+- `summary`
+- `delivery`
+- `records`
+- `scene`
+- `spec`
+
+Use it for:
+- engineering delivery column
+- phase / status / evidence rendering
+- showing spec-bound delivery progress without frontend-side synthesis
+
+### 2. Engineering readiness preview
+
+Command:
+
+```bash
+sce app engineering preview --app <app-key> --json
+```
+
+Stable fields:
+- `summary.attached`
+- `summary.hydrated`
+- `summary.active`
+- `summary.sourceKnown`
+- `summary.projectionReady`
+- `summary.readinessReasonCodes[]`
+- `summary.nextActions[]`
+- `summary.workspacePath`
+- `summary.repoUrl`
+- `summary.branch`
+- `summary.codeVersion`
+
+Rule:
+- frontend should use `readinessReasonCodes` and `nextActions` directly
+- frontend should not infer readiness by reverse-engineering `repoUrl/workspacePath/metadata`
+
+### 3. Engineering ownership relation
+
+Command:
+
+```bash
+sce app engineering ownership --app <app-key> --json
+```
+
+Stable fields:
+- `summary.appKey`
+- `summary.workspaceId`
+- `summary.userId`
+- `summary.deviceId`
+- `summary.ownershipType`
+- `summary.sharedPolicy`
+
+Ownership type meanings:
+- `local`: SCE has evidence this engineering workspace is local to the current device context
+- `shared`: SCE has explicit shared ownership evidence or policy
+- `unresolved`: SCE does not have enough evidence and will not guess
+
+Rule:
+- treat `null` link fields as intentionally unknown
+- do not create a frontend-owned fallback ownership registry
+
+## Current Action Envelopes
+
+### 4. Canonical open/import result
+
+Commands:
+
+```bash
+sce app engineering open --app <app-key> --json
+sce app engineering import --app <app-key> --json
+```
+
+Stable fields:
+- `mode`
+- `success`
+- `summary`
+- `preview`
+- `steps[]`
+
+Stable step keys:
+- `register`
+- `attach`
+- `hydrate`
+- `activate`
+
+Stable step status values:
+- `done`
+- `pending`
+- `skipped`
+- `failed`
+
+Rule:
+- all four step keys remain ordered
+- non-applicable work reports `skipped`
+- frontend should render the step list directly instead of inferring flow order from command history
+
+### 5. Scaffold result
+
+Command:
+
+```bash
+sce app engineering scaffold --app <app-key> --overwrite-policy missing-only --json
+```
+
+Stable fields:
+- `summary.workspacePath`
+- `summary.createdDirectoryCount`
+- `summary.skippedDirectoryCount`
+- `summary.failedDirectoryCount`
+- `summary.createdFileCount`
+- `summary.skippedFileCount`
+- `summary.failedFileCount`
+- `summary.overwritePolicy`
+
+Overwrite policy values:
+- `never`
+- `missing-only`
+- `explicit`
+
+Rule:
+- scaffold only initializes the SCE baseline under the engineering workspace
+- scaffold does not authorize frontend to invent or rewrite business code layout
+- repeated runs should be rendered as explicit skipped work, not as silent success
+
+## Recommended Frontend Consumption Order
+
+For engineering-mode shell bootstrap, prefer:
+
+1. `sce mode engineering home --app <app-key> --json`
+2. `sce scene delivery show --scene <scene-id> --json`
+3. `sce app engineering preview --app <app-key> --json`
+4. `sce app engineering ownership --app <app-key> --json`
+
+For user-triggered engineering actions, prefer:
+
+1. preview first
+2. then `open` or `import` if the UI wants one canonical action-progress envelope
+3. then explicit write actions: `attach`, `hydrate`, `scaffold`, `activate`
+4. refresh `preview` and `ownership` after successful mutation
+
+## Guardrails
+
+- Do not treat `show` as the primary contract surface; it remains a compatibility alias.
+- Do not derive ownership from missing fields by guesswork.
+- Do not treat scaffold as permission to generate arbitrary business code.
+- Do not replace backend readiness/step semantics with frontend-invented labels.