scene-capability-engine 3.6.57 → 3.6.59

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.59] - 2026-03-19
+
+### Changed
+- Published a follow-up alignment patch so the npm package, Git tag, and repository release line all point at the final post-release state after shared project problem projection sync.
+- Kept runtime capability contracts unchanged from `3.6.58`; this patch is for release-state consistency rather than new engine behavior.
+
+## [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

package/README.md

@@ -169,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`
@@ -228,5 +230,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.57
-**Last Updated**: 2026-03-17
+**Version**: 3.6.59
+**Last Updated**: 2026-03-19

package/README.zh.md

@@ -174,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`
@@ -233,5 +235,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.57
-**最后更新**：2026-03-17
+**版本**：3.6.59
+**最后更新**：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/command-reference.md

@@ -411,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
@@ -428,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
@@ -2651,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.

package/docs/magicball-frontend-state-and-command-mapping.md

@@ -22,6 +22,7 @@ The current frontend-sensitive surfaces are:
 2. ontology empty-state and starter-seed initialization
 3. write-error presentation and retry boundaries
 4. timeline / task feedback handoff points
+5. multi-project portfolio / routing / supervision
 
 ## 2. Page State Ownership
 
@@ -38,7 +39,9 @@ interface AppWorkspaceState {
   applicationHome: Record<string, unknown> | null
   ontologyHome: Record<string, unknown> | null
   engineeringHome: Record<string, unknown> | null
-  engineeringDetail: Record<string, unknown> | null
+  sceneDelivery: Record<string, unknown> | null
+  engineeringPreview: Record<string, unknown> | null
+  engineeringOwnership: Record<string, unknown> | null
   boot: ModeBootState
 }
 ```
@@ -48,11 +51,35 @@ Owned commands:
 - `sce mode application home --app <app-key> --json`
 - `sce mode ontology home --app <app-key> --json`
 - `sce mode engineering home --app <app-key> --json`
-- `sce app engineering show --app <app-key> --json`
+- `sce scene delivery show --scene <scene-id> --json`
+- `sce app engineering preview --app <app-key> --json`
+- `sce app engineering ownership --app <app-key> --json`
 
 Rule:
 - this shell owns mode bootstrap and should not delegate command ordering to nested tabs
 
+### 2.1.1 Multi-project shell state
+
+Recommended shape:
+
+```ts
+interface ProjectWorkspaceShellState {
+  projectPortfolio: Record<string, unknown> | null
+  currentProjectId: string | null
+  projectTarget: Record<string, unknown> | null
+  projectSupervision: Record<string, unknown> | null
+}
+```
+
+Owned commands:
+- `sce project portfolio show --json`
+- `sce project target resolve --request <text> --current-project <project-id> --json`
+- `sce project supervision show --project <project-id> --json`
+
+Rule:
+- multi-project shell must consume engine-owned project truth directly
+- target resolution must be treated as preflight and must not mutate active workspace selection implicitly
+
 ### 2.2 Ontology Page State
 
 Recommended shape:
@@ -122,10 +149,12 @@ Rule:
 | Bootstrap step 1 | `sce mode application home --app <app-key> --json` | `applicationHome` | render app hero / release status | stop boot, allow step retry |
 | Bootstrap step 2 | `sce mode ontology home --app <app-key> --json` | `ontologyHome` | render ontology summary shell | keep app section visible, allow step retry |
 | Bootstrap step 3 | `sce mode engineering home --app <app-key> --json` | `engineeringHome` | render engineering summary shell | keep prior sections visible, allow step retry |
-| Bootstrap step 4 | `sce app engineering show --app <app-key> --json` | `engineeringDetail` | render repo/workspace detail | keep engineering summary visible, allow step retry |
+| Bootstrap step 4 | `sce scene delivery show --scene <scene-id> --json` | `sceneDelivery` | render delivery column with phase/status evidence | keep engineering summary visible, allow step retry |
+| Bootstrap step 5 | `sce app engineering preview --app <app-key> --json` | `engineeringPreview` | render readiness flags and next actions without client synthesis | keep engineering summary visible, allow step retry |
+| Bootstrap step 6 | `sce app engineering ownership --app <app-key> --json` | `engineeringOwnership` | render local/shared/unresolved ownership relation conservatively | keep engineering summary visible, allow step retry |
 
 Implementation rule:
-- all four steps execute sequentially
+- all six steps execute sequentially
 - each step updates `boot.activeStep`
 - each success appends to `boot.completedSteps`
 - each failure writes a `CommandFailureState`
@@ -168,7 +197,7 @@ Read errors should be rendered inline at the section that failed.
 Examples:
 - ontology summary failed -> show summary card error, not full page crash
 - ER list failed -> show ER table error, keep BR/DL areas usable
-- engineering detail failed -> keep engineering summary visible
+- engineering preview/ownership failed -> keep engineering summary visible
 
 ### 6.2 Write Errors
 
@@ -225,6 +254,14 @@ Use existing SCE view contracts for those surfaces:
 Recommended connection point:
 - when a write or seed command fails, store the exact command failure bundle so MagicBall can pass it into its AI assistant or timeline/task views later
 
+## 8.1 Multi-project supervision and routing
+
+| UI event | SCE command | State target | Success behavior | Failure behavior |
+| --- | --- | --- | --- | --- |
+| Open multi-project shell | `sce project portfolio show --json` | `projectPortfolio` | render project switcher and current active project marker | show shell-level error and preserve stale local shell state if available |
+| Enter cross-project request | `sce project target resolve --request <text> --current-project <project-id> --json` | `projectTarget` | route to current project, resolved project, or candidate chooser | preserve request text and show clarification UI |
+| Open project health panel | `sce project supervision show --project <project-id> --json` | `projectSupervision` | render blocked / handoff / risk / active summary and drillback items | keep project shell visible and show panel-level error |
+
 ## 9. Minimal Acceptance Checklist
 
 MagicBall can consider this mapping implemented when: