scene-capability-engine 3.6.57 → 3.6.59

package/docs/magicball-integration-doc-index.md

@@ -17,6 +17,8 @@ These are the current first-line integration documents:
 - `docs/magicball-app-collection-phase-1.md`
 - `docs/app-intent-apply-contract.md`
 - `docs/magicball-ui-surface-checklist.md`
+- `docs/magicball-engineering-projection-contract.md`
+- `docs/magicball-project-portfolio-contract.md`
 - `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
 - `docs/magicball-frontend-state-and-command-mapping.md`
 - `docs/magicball-cli-invocation-examples.md`
@@ -47,23 +49,31 @@ These are the current first-line integration documents:
    - serialized mode-home loading
    - ontology empty-state and starter-seed behavior
 
-6. `docs/magicball-frontend-state-and-command-mapping.md`
+6. `docs/magicball-engineering-projection-contract.md`
+   - stable engineering-facing payloads
+   - delivery / preview / ownership / open-import / scaffold contracts
+
+7. `docs/magicball-project-portfolio-contract.md`
+   - multi-project roster / target-resolution / supervision contracts
+   - phase-1 project switcher and cross-project preflight boundary
+
+8. `docs/magicball-frontend-state-and-command-mapping.md`
    - page state ownership
    - command-to-action mapping
    - error and retry boundaries
 
-7. `docs/magicball-write-auth-adaptation-guide.md`
+9. `docs/magicball-write-auth-adaptation-guide.md`
    - write authorization and lease handling
 
-8. `docs/magicball-task-feedback-timeline-guide.md`
+10. `docs/magicball-task-feedback-timeline-guide.md`
    - task feedback cards
    - timeline view integration
 
-9. `docs/magicball-cli-invocation-examples.md`
+11. `docs/magicball-cli-invocation-examples.md`
    - copy-ready CLI examples
    - wrapper and smoke verification patterns
 
-10. `docs/magicball-integration-issue-tracker.md`
+12. `docs/magicball-integration-issue-tracker.md`
    - current cross-project truth
    - only open issues, active decisions, and verified resolutions
 
@@ -75,6 +85,8 @@ Use:
 - `docs/magicball-app-collection-phase-1.md`
 - `docs/app-intent-apply-contract.md`
 - `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+- `docs/magicball-engineering-projection-contract.md`
+- `docs/magicball-project-portfolio-contract.md`
 - `docs/magicball-frontend-state-and-command-mapping.md`
 
 ### I need to implement ontology empty-state and starter seed
@@ -111,6 +123,8 @@ Use:
 | `app-intent-apply-contract.md` | apply JSON contract | medium |
 | `magicball-adaptation-task-checklist-v1.md` | execution checklist | medium |
 | `magicball-mode-home-and-ontology-empty-state-playbook.md` | frontend behavior policy | medium |
+| `magicball-engineering-projection-contract.md` | engineering payload contract | medium |
+| `magicball-project-portfolio-contract.md` | multi-project payload contract | medium |
 | `magicball-frontend-state-and-command-mapping.md` | frontend implementation mapping | medium |
 | `magicball-write-auth-adaptation-guide.md` | auth/write behavior | low |
 | `magicball-task-feedback-timeline-guide.md` | task/timeline integration | low |

package/docs/magicball-integration-issue-tracker.md

@@ -25,9 +25,11 @@ SCE changes completed and now available for MagicBall:
 - `mode application home --app ... --json`
 - `mode ontology home --app ... --json`
 - `mode engineering home --app ... --json`
+- `scene delivery show`
 - `app registry status/configure/sync*`
 - `app runtime show/releases/install/activate/uninstall`
-- `app engineering show/attach/hydrate/activate`
+- `app engineering preview/ownership/open/import/show/attach/hydrate/scaffold/activate`
+- `project portfolio show/target resolve/supervision show`
 - `pm requirement/tracking/planning/change/issue` data plane
 - `ontology er/br/dl` + `ontology triad summary`
 - `ontology seed list/show/apply`
@@ -38,14 +40,17 @@ SCE changes completed and now available for MagicBall:
 1. consume `mode * home` as the top-level source for the three modes
 2. consume `device current`, `app collection list/show/apply`, `scene workspace list/show/apply`, and `app install-state list` as the local device/install baseline
 3. consume `pm`, `ontology`, and `assurance` table payloads
-4. wire runtime install/activate/uninstall and engineering attach/hydrate/activate actions
-5. use demo app: `customer-order-demo`
+4. wire runtime install/activate/uninstall and engineering attach/hydrate/scaffold/activate actions
+5. treat `project portfolio / target resolve / supervision` as the default multi-project shell truth
+6. use demo app: `customer-order-demo`
 
 ### Related SCE docs
 - `docs/magicball-sce-adaptation-guide.md`
 - `docs/magicball-write-auth-adaptation-guide.md`
 - `docs/magicball-adaptation-task-checklist-v1.md`
 - `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+- `docs/magicball-engineering-projection-contract.md`
+- `docs/magicball-project-portfolio-contract.md`
 - `docs/magicball-frontend-state-and-command-mapping.md`
 - `docs/magicball-ui-surface-checklist.md`
 - `docs/magicball-integration-doc-index.md`
@@ -54,6 +59,7 @@ SCE changes completed and now available for MagicBall:
   - current entry docs vs secondary references vs historical drafts are now separated in `docs/magicball-integration-doc-index.md`
   - serialized `mode * home` loading as the safe default during `Issue 001` verification
   - `fallback + optional seed apply` as the recommended default for fresh-project ontology UX under `Issue 003`
+  - multi-project roster / routing / supervision contract is now captured in `docs/magicball-project-portfolio-contract.md`
 
 ### Next Needed From MagicBall
 1. treat the current doc set as stable and move into feedback-driven integration using the current entry docs
@@ -95,7 +101,9 @@ Related commands that were being loaded together:
 - `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`
 
 MagicBall action taken:
 - Changed mode-home loading from parallel to sequential in local store.
@@ -103,7 +111,9 @@ MagicBall action taken:
   1. application home
   2. ontology home
   3. engineering home
-  4. engineering show
+  4. scene delivery show
+  5. engineering preview
+  6. engineering ownership
 
 SCE action taken:
 - Added short read retry handling for retryable sqlite lock errors on app/mode/pm/ontology/assurance read paths.

package/docs/magicball-mode-home-and-ontology-empty-state-playbook.md

@@ -44,7 +44,9 @@ When opening an app page, MagicBall should call these commands in order:
 1. `sce mode application home --app <app-key> --json`
 2. `sce mode ontology home --app <app-key> --json`
 3. `sce mode engineering home --app <app-key> --json`
-4. `sce app engineering show --app <app-key> --json`
+4. `sce scene delivery show --scene <scene-id> --json`
+5. `sce app engineering preview --app <app-key> --json`
+6. `sce app engineering ownership --app <app-key> --json`
 
 ### Frontend State Rule
 
@@ -52,6 +54,8 @@ Treat each call as one step in a small boot pipeline.
 Do not issue step 2 before step 1 resolves.
 Do not issue step 3 before step 2 resolves.
 Do not issue step 4 before step 3 resolves.
+Do not issue step 5 before step 4 resolves.
+Do not issue step 6 before step 5 resolves.
 
 Recommended local state shape:
 
@@ -59,7 +63,7 @@ Recommended local state shape:
 interface ModeBootState {
   appKey: string
   bootStatus: 'idle' | 'loading' | 'partial' | 'ready' | 'failed'
-  activeStep: 'application-home' | 'ontology-home' | 'engineering-home' | 'engineering-show' | null
+  activeStep: 'application-home' | 'ontology-home' | 'engineering-home' | 'scene-delivery' | 'engineering-preview' | 'engineering-ownership' | null
   completedSteps: string[]
   lastError: string | null
 }
@@ -77,7 +81,9 @@ Recommended status copy:
 - step 1 loading: `Loading application view...`
 - step 2 loading: `Loading ontology view...`
 - step 3 loading: `Loading engineering view...`
-- step 4 loading: `Loading engineering workspace details...`
+- step 4 loading: `Loading delivery evidence...`
+- step 5 loading: `Loading engineering readiness...`
+- step 6 loading: `Loading ownership relation...`
 
 ### Failure Handling
 
@@ -85,7 +91,7 @@ If a step fails:
 - preserve all previously loaded payloads
 - store the exact failing command and stderr text
 - show a retry action for the failed step only
-- do not automatically restart the full four-step sequence unless the app context changed
+- do not automatically restart the full six-step sequence unless the app context changed
 
 Recommended retry behavior:
 - retry the failed step once on explicit user action
@@ -213,7 +219,9 @@ App Selected
   -> application home
   -> ontology home
   -> engineering home
-  -> engineering show
+  -> scene delivery
+  -> engineering preview
+  -> engineering ownership
 
 Ontology Tab Opened
   -> ontology home

package/docs/magicball-project-portfolio-contract.md

@@ -0,0 +1,216 @@
+# MagicBall Project Portfolio Contract
+
+## Goal
+
+Define the stable phase-1 SCE contract for MagicBall multi-project surfaces.
+
+This document covers:
+- project roster projection
+- target-project preflight resolution
+- project-scoped supervision snapshot
+
+This document does not define UI layout.
+It defines the backend payloads MagicBall should consume directly.
+
+Use together with:
+- `docs/magicball-sce-adaptation-guide.md`
+- `docs/magicball-frontend-state-and-command-mapping.md`
+- `docs/magicball-cli-invocation-examples.md`
+- `docs/magicball-integration-issue-tracker.md`
+
+## Phase-1 Position
+
+Phase-1 is read-first and engine-owned:
+- project visibility comes from registered workspaces plus the current unregistered `.sce` project when applicable
+- project identity is deterministic and stable for registered workspaces
+- target resolution is preflight-only and does not mutate active workspace selection
+- supervision is a project-scoped snapshot, not a raw cross-project event stream
+
+Phase-1 does not introduce:
+- a second persistent portfolio registry
+- frontend-owned project identity synthesis
+- implicit workspace switching during routing
+- fake streaming semantics for supervision refresh
+
+## Command Set
+
+```bash
+sce project portfolio show --json
+sce project target resolve --json
+sce project supervision show --project <project-id> --json
+```
+
+Optional caller-context inputs:
+
+```bash
+sce project portfolio show --workspace <workspace-name> --json
+sce project target resolve --request "<text>" --current-project <project-id> --workspace <workspace-name> --device <device-id> --tool-instance-id <tool-id> --json
+```
+
+## 1. Project Portfolio Projection
+
+### Command
+
+```bash
+sce project portfolio show --json
+```
+
+### Contract shape
+
+```ts
+interface ProjectPortfolioProjection {
+  generatedAt: string
+  callerContext?: {
+    workspaceId?: string
+    projectId?: string
+    deviceId?: string
+  }
+  activeProjectId?: string
+  projects: ProjectPortfolioRecord[]
+}
+
+interface ProjectPortfolioRecord {
+  projectId: string
+  workspaceId?: string
+  projectRoot: string
+  projectName?: string
+  provenance?: 'registered' | 'discovered'
+  readiness: 'ready' | 'partial' | 'pending' | 'blocked' | 'unknown'
+  status: 'active' | 'background' | 'idle' | 'inaccessible' | 'unknown'
+  availability: 'accessible' | 'inaccessible' | 'degraded'
+  activeSessionCount: number
+  lastActivityAt?: string
+  summary?: {
+    sceneCount?: number
+    specCount?: number
+  }
+  partial?: boolean
+  partialReasons?: string[]
+}
+```
+
+### MagicBall rules
+
+- Use `projectId` as the stable project route token for multi-project UI state.
+- Treat `workspaceId` as an optional display/debug field, not the only identity field.
+- Use `activeProjectId` as the current project marker.
+- Render `partial` and `availability` explicitly; do not silently drop degraded or inaccessible records.
+- Do not rebuild roster truth from local UI cache when this payload is available.
+
+### Important phase-1 semantics
+
+- Registered workspaces use stable `projectId` values derived from workspace identity, for example `workspace:<workspace-name>`.
+- An unregistered current `.sce` project may appear as one local `discovered` partial record.
+- `status=active` means the project matches caller context, not merely that it has background scene activity.
+
+## 2. Target Resolution
+
+### Command
+
+```bash
+sce project target resolve --request "<text>" --current-project <project-id> --json
+```
+
+### Contract shape
+
+```ts
+interface ProjectTargetResolution {
+  resolvedAt: string
+  callerContext: {
+    currentProjectId?: string
+    workspaceId?: string
+    deviceId?: string
+    toolInstanceId?: string
+  }
+  status: 'current-project' | 'resolved-other-project' | 'ambiguous' | 'unresolved'
+  currentProjectId?: string
+  resolvedProjectId?: string
+  confidence?: number
+  reasonCode?: string
+  candidates?: Array<{
+    projectId: string
+    workspaceId?: string
+    projectName?: string
+    appKey?: string
+    confidence?: number
+    reasonCode?: string
+  }>
+}
+```
+
+### MagicBall rules
+
+- Call `target resolve` before cross-project assistant or orchestration flows when the user request can target another project.
+- Keep caller-submitted `currentProjectId` and engine-resolved `resolvedProjectId` separately.
+- If `status=ambiguous`, show candidate selection UI instead of auto-picking.
+- If `status=unresolved`, preserve the exact request text and returned reason for user clarification.
+- Never treat `--workspace` as permission to switch the globally active workspace in frontend state.
+
+## 3. Project Supervision Snapshot
+
+### Command
+
+```bash
+sce project supervision show --project <project-id> --json
+```
+
+### Contract shape
+
+```ts
+interface ProjectSupervisionProjection {
+  generatedAt: string
+  projectId: string
+  cursor?: string
+  summary: {
+    blockedCount: number
+    handoffCount: number
+    riskCount: number
+    activeSceneCount?: number
+    activeSpecCount?: number
+    activeTaskCount?: number
+    latestEventAt?: string
+  }
+  items: ProjectSupervisionItem[]
+  partial?: boolean
+  partialReasons?: string[]
+}
+
+interface ProjectSupervisionItem {
+  id: string
+  kind: 'blocked' | 'handoff' | 'risk' | 'active'
+  state: string
+  reasonCode?: string
+  sceneId?: string
+  specId?: string
+  taskRef?: string
+  requestId?: string
+  eventId?: string
+  updatedAt: string
+  summary: string
+}
+```
+
+### MagicBall rules
+
+- Render summary counters directly from `summary`.
+- Use `items[]` for drillback cards or project health detail panels.
+- Preserve `sceneId/specId/requestId/eventId` for navigation and audit views.
+- Treat `cursor` as an opaque polling checkpoint only.
+- Do not present `cursor` as a replayable event stream offset.
+
+## 4. Recommended Multi-Project Frontend Flow
+
+1. Load `sce project portfolio show --json` when entering the multi-project shell.
+2. Store `activeProjectId` and render a project switcher from `projects[]`.
+3. When the user enters a cross-project free-text request, preflight with `sce project target resolve --json`.
+4. After project selection or successful resolution, load `sce project supervision show --project <project-id> --json`.
+5. Keep per-project tabs and page layout frontend-owned, but keep project truth engine-owned.
+
+## 5. Minimal Acceptance Criteria For MagicBall
+
+MagicBall can treat multi-project phase-1 as integrated when:
+- project switcher uses `project portfolio show`
+- cross-project preflight uses `project target resolve`
+- project health/drillback uses `project supervision show`
+- degraded and inaccessible projects are rendered explicitly
+- target resolution never mutates global active workspace state implicitly

package/docs/magicball-sce-adaptation-guide.md

@@ -15,6 +15,8 @@ Use these documents together:
 - `docs/magicball-app-collection-phase-1.md`
 - `docs/app-intent-apply-contract.md`
 - `docs/magicball-ui-surface-checklist.md`
+- `docs/magicball-engineering-projection-contract.md`
+- `docs/magicball-project-portfolio-contract.md`
 - `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
 - `docs/magicball-frontend-state-and-command-mapping.md`
 - `docs/magicball-cli-invocation-examples.md`
@@ -33,12 +35,13 @@ SCE currently provides MagicBall-facing support for:
 6. `app install-state` local device projection
 7. `application / ontology / engineering home projections`
 8. `app runtime install / activate / uninstall`
-9. `app engineering attach / hydrate / activate`
+9. `app engineering attach / hydrate / scaffold / activate`
 10. `pm` delivery data plane
 11. `ontology` triad data plane
 12. `assurance` data plane
 13. `write authorization`
 14. `task feedback + timeline`
+15. `project portfolio / target resolve / supervision`
 
 ## Planned Next Scope
 
@@ -89,7 +92,9 @@ Current default during `Issue 001` verification:
   1. `mode application home`
   2. `mode ontology home`
   3. `mode engineering home`
-  4. `app engineering show`
+  4. `scene delivery show`
+  5. `app engineering preview`
+  6. `app engineering ownership`
 
 ### 3. Fresh ontology behavior
 
@@ -125,14 +130,21 @@ Use `docs/magicball-cli-invocation-examples.md` for copy-ready commands.
 - `sce mode application home`
 - `sce mode ontology home`
 - `sce mode engineering home`
-- `sce app engineering show`
+- `sce scene delivery show`
+- `sce app engineering preview`
+- `sce app engineering ownership`
 
 ### Runtime and engineering control
 - `sce device override show/upsert`
 - `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 app registry status/configure/sync*`
 
+### Multi-project control
+- `sce project portfolio show`
+- `sce project target resolve`
+- `sce project supervision show`
+
 ### Engineering data plane
 - `sce pm requirement list/show/upsert`
 - `sce pm tracking board/show/upsert`
@@ -214,6 +226,7 @@ MagicBall should use `view_model.columns` as the preferred visible-column contra
 
 ### Specialized docs own
 - page-level done criteria: `docs/magicball-ui-surface-checklist.md`
+- multi-project contracts: `docs/magicball-project-portfolio-contract.md`
 - frontend state + command mapping: `docs/magicball-frontend-state-and-command-mapping.md`
 - mode-home + ontology empty-state behavior: `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
 - copy-ready commands: `docs/magicball-cli-invocation-examples.md`
@@ -230,3 +243,4 @@ MagicBall should now integrate SCE in this order:
 4. keep ontology empty-state explicit and seed apply optional
 5. keep write flows lease-aware
 6. use task/timeline view contracts instead of raw event-first rendering
+7. use `project portfolio / target resolve / supervision` for multi-project shells instead of frontend-rebuilt workspace truth

package/docs/magicball-ui-surface-checklist.md

@@ -10,6 +10,8 @@ Do not use it as the source of truth for state ownership, command mapping, or de
 
 Use together with:
 - `docs/magicball-frontend-state-and-command-mapping.md`
+- `docs/magicball-engineering-projection-contract.md`
+- `docs/magicball-project-portfolio-contract.md`
 - `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
 - `docs/magicball-cli-invocation-examples.md`
 - `docs/magicball-write-auth-adaptation-guide.md`
@@ -75,12 +77,16 @@ Use together with:
 
 ### Must render
 - delivery summary
+- delivery column from `scene delivery show`
+- engineering readiness state from `app engineering preview`
+- engineering ownership state from `app engineering ownership`
 - requirement / tracking / planning / change / issue tabs
 - assurance tabs
 - engineering workspace detail
 
 ### Done when
 - engineering tables use SCE table payloads directly
+- delivery / preview / ownership panels render backend contracts directly
 - empty engineering tables render as empty states, not legacy markdown fallbacks by default
 
 ## 6. Write Authorization
@@ -121,6 +127,25 @@ Detailed state ownership and error boundary rules live in:
 
 MagicBall can treat the current SCE integration as baseline-ready when:
 - workspace shell is serialized and stable
+- multi-project shell uses engine-owned project roster and supervision truth
 - ontology empty-state is explicit and usable
 - write authorization is shared capability, not page-by-page improvisation
 - task/timeline surfaces use SCE view contracts instead of raw event-first rendering
+
+## 10. Multi-project Shell
+
+### Must render
+- project switcher from `project portfolio show`
+- current project marker
+- project health summary from `project supervision show`
+- explicit degraded / inaccessible project states
+
+### Must behave correctly
+- cross-project free-text routing preflights through `project target resolve`
+- ambiguous resolution does not auto-select silently
+- target resolution does not implicitly switch active workspace selection
+
+### Done when
+- frontend no longer rebuilds project roster from local workspace cache alone
+- supervision panel uses backend snapshot items directly
+- unresolved or ambiguous routing is visible and auditable

package/docs/magicball-write-auth-adaptation-guide.md

@@ -64,6 +64,7 @@ Current implemented write flows in SCE imply these practical action families:
 - `app:registry:configure`
 - `app:engineering:attach`
 - `app:engineering:hydrate`
+- `app:engineering:scaffold`
 - `app:engineering:activate`
 - `app:runtime:install`
 - `app:runtime:activate`
@@ -174,6 +175,7 @@ Recommended UI steps:
 | Update registry config | `sce app registry configure` | `app:registry:configure` |
 | Attach engineering project | `sce app engineering attach` | `app:engineering:attach` |
 | Hydrate engineering workspace | `sce app engineering hydrate` | `app:engineering:hydrate` |
+| Scaffold engineering workspace baseline | `sce app engineering scaffold` | `app:engineering:scaffold` |
 | Activate engineering workspace | `sce app engineering activate` | `app:engineering:activate` |
 | Install runtime release | `sce app runtime install` | `app:runtime:install` |
 | Activate runtime release | `sce app runtime activate` | `app:runtime:activate` |
@@ -205,7 +207,7 @@ sce auth grant --scope app:runtime:uninstall --reason "remove non-active install
 
 ### Multiple scopes if one workflow batches mutations
 ```bash
-sce auth grant --scope app:engineering:attach,app:engineering:hydrate,app:engineering:activate --reason "initialize engineering workspace" --json
+sce auth grant --scope app:engineering:attach,app:engineering:hydrate,app:engineering:scaffold,app:engineering:activate --reason "initialize engineering workspace" --json
 ```
 
 ## How MagicBall Should Pass Lease To SCE

package/docs/release-checklist.md

@@ -82,12 +82,20 @@ Check that key docs are aligned with current version and capabilities:
 Optional sanity scan:
 
 ```bash
+npm run audit:magicball-engineering-contract
+npm run audit:magicball-project-contract
+
 rg -n "yourusername|support@example.com" README.md README.zh.md docs docs/zh -S
 
 # Canonical repository link check (should return no matches)
 rg -n "github.com/scene-capability-engine/sce" README.md README.zh.md docs START_HERE.txt INSTALL_OFFLINE.txt -S -g "!docs/release-checklist.md" -g "!docs/zh/release-checklist.md"
 ```
 
+Additional expectation:
+
+- `audit:magicball-engineering-contract` passes so active MagicBall entry docs stay aligned with `scene delivery`, `engineering preview/ownership`, and `open/import/scaffold` contracts.
+- `audit:magicball-project-contract` passes so active MagicBall entry docs stay aligned with `project portfolio`, `project target resolve`, and `project supervision show` contracts.
+
 ---
 
 ## 6. Git Readiness

package/docs/releases/README.md

@@ -9,6 +9,8 @@ This directory stores release-facing documents:
 ## Archived Versions
 
 - [Release checklist](../release-checklist.md)
+- [v3.6.59 release notes](./v3.6.59.md)
+- [v3.6.58 release notes](./v3.6.58.md)
 - [v3.6.57 release notes](./v3.6.57.md)
 - [v3.6.56 release notes](./v3.6.56.md)
 - [v3.6.55 release notes](./v3.6.55.md)

package/docs/releases/v3.6.58.md

@@ -0,0 +1,27 @@
+# v3.6.58 Release Notes
+
+Release date: 2026-03-19
+
+## Highlights
+
+- Added canonical delivery and engineering projection contracts for MagicBall, including `sce scene delivery show` and the `app engineering preview|ownership|open|import|scaffold` line.
+- Added phase-1 multi-project read contracts: `sce project portfolio show`, `sce project target resolve`, and `sce project supervision show`.
+- Synced MagicBall integration docs, CLI examples, frontend mapping, checklist, tracker, README, and release checklist so the new project/engineering surfaces are documented as stable integration inputs.
+- Added release-time MagicBall project-contract auditing so publish flow now checks both engineering and multi-project contract drift.
+
+## Validation
+
+- `npx jest tests/unit/commands/app-mode.test.js --runInBand`
+- `npx jest tests/unit/commands/scene-delivery.test.js --runInBand`
+- `npx jest tests/unit/commands/project.test.js --runInBand`
+- `npx jest tests/integration/project-cli.integration.test.js --runInBand`
+- `npx jest tests/unit/scripts/magicball-engineering-contract-audit.test.js --runInBand`
+- `npx jest tests/unit/scripts/magicball-project-contract-audit.test.js --runInBand`
+- `npm run audit:magicball-project-contract`
+- `npm run audit:magicball-engineering-contract`
+- `npm run test:release`
+- `node scripts/release-doc-version-audit.js --fail-on-error`
+
+## Release Notes
+
+- This patch turns the recent MagicBall/IDE projection work into a stable release line instead of a local patch stack. On the engineering side, SCE now exposes delivery projection plus conservative engineering readiness, ownership, open/import, and scaffold envelopes through one documented contract set. On the multi-project side, SCE now exposes an engine-owned project roster, target-project preflight resolution, and project-scoped supervision snapshot so adapters no longer need to synthesize portfolio truth from local workspace state. The accompanying MagicBall docs and publish audits were updated together, so future npm installs or local upgrades keep the same integration behavior instead of silently dropping these contracts.

package/docs/releases/v3.6.59.md

@@ -0,0 +1,18 @@
+# v3.6.59 Release Notes
+
+Release date: 2026-03-19
+
+## Highlights
+
+- Published an alignment-only follow-up patch so the npm package, repository tag, and release branch all reference the same final repository state.
+- Kept the MagicBall delivery, engineering, and multi-project contracts exactly the same as `v3.6.58`.
+
+## Validation
+
+- `npm run audit:release-docs`
+- `node scripts/git-managed-gate.js --fail-on-violation --json`
+- `npm publish --access public` via `prepublishOnly`
+
+## Release Notes
+
+- This patch does not introduce new runtime or adapter-facing behavior. It exists to remove release-state ambiguity after the post-release shared project problem projection snapshot was committed to the repository. Use `v3.6.59` as the canonical follow-up version when strict npm/tag/repository alignment matters.

package/docs/zh/release-checklist.md

@@ -67,12 +67,20 @@ npm pack --dry-run
 可选扫描：
 
 ```bash
+npm run audit:magicball-engineering-contract
+npm run audit:magicball-project-contract
+
 rg -n "yourusername|support@example.com" README.md README.zh.md docs docs/zh -S
 
 # canonical 仓库链接扫描（应返回空）
 rg -n "github.com/scene-capability-engine/sce" README.md README.zh.md docs START_HERE.txt INSTALL_OFFLINE.txt -S -g "!docs/release-checklist.md" -g "!docs/zh/release-checklist.md"
 ```
 
+额外预期：
+
+- `audit:magicball-engineering-contract` 通过，确保活跃的 MagicBall 入口文档与 `scene delivery`、`engineering preview/ownership`、`open/import/scaffold` 契约保持一致。
+- `audit:magicball-project-contract` 通过，确保活跃的 MagicBall 入口文档与 `project portfolio`、`project target resolve`、`project supervision show` 契约保持一致。
+
 ---
 
 ## 5. Git 准备状态

package/docs/zh/releases/README.md

@@ -9,6 +9,8 @@
 ## 历史版本归档
 
 - [发布检查清单](../release-checklist.md)
+- [v3.6.59 发布说明](./v3.6.59.md)
+- [v3.6.58 发布说明](./v3.6.58.md)
 - [v3.6.57 发布说明](./v3.6.57.md)
 - [v3.6.56 发布说明](./v3.6.56.md)
 - [v3.6.55 发布说明](./v3.6.55.md)