scene-capability-engine 3.6.55 → 3.6.56

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.56] - 2026-03-17
+
+### Added
+- Added Spec `129-00-complex-problem-program-escalation` to formalize how SCE should decide between `single-spec`, `multi-spec-program`, and `research-program` for highly entangled problems.
+- Added read-only `sce spec strategy assess` so SCE can explicitly recommend `single-spec`, `multi-spec-program`, or `research-program` from either a broad goal or an existing Spec.
+- Added copy-ready phase-1 app intent examples under `docs/examples/app-intent-phase1/.sce/app/collections` and `docs/examples/app-intent-phase1/.sce/app/scene-profiles`, covering sales desktop, planning desktop, and warehouse tablet scenarios.
+- Added `docs/app-intent-apply-contract.md` to document the stable JSON contract for `sce app collection apply --json` and `sce scene workspace apply --json`.
+
+### Changed
+- MagicBall-facing docs and command reference now point directly to copy-ready sample assets, explicit apply JSON contract guidance, and the phase-2 direction of lightweight user-intent sync rather than device-state sync.
+- Spec workflow and autonomous-control guidance now explicitly describe when a problem should escalate from one Spec to a coordinated program-level path.
+
 ## [3.6.55] - 2026-03-16
 
 ### Added

package/README.md

@@ -183,6 +183,10 @@ Demo remote registries:
 - `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
@@ -223,5 +227,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.55
-**Last Updated**: 2026-03-16
+**Version**: 3.6.56
+**Last Updated**: 2026-03-17

package/README.zh.md

@@ -188,6 +188,10 @@ SCE 默认是强治理的。
 - `magicball-app-service-catalog`
 - 示例 app key：`customer-order-demo`
 
+面向场景的安装管理参考：
+- 示例：`docs/examples/app-intent-phase1/.sce/app/...`
+- apply JSON 契约：`docs/app-intent-apply-contract.md`
+
 ---
 
 ## 文档入口
@@ -228,5 +232,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.55
-**最后更新**：2026-03-16
+**版本**：3.6.56
+**最后更新**：2026-03-17

package/bin/scene-capability-engine.js

@@ -21,6 +21,7 @@ const { registerSpecPipelineCommand } = require('../lib/commands/spec-pipeline')
 const { registerSpecGateCommand } = require('../lib/commands/spec-gate');
 const { registerSpecDomainCommand } = require('../lib/commands/spec-domain');
 const { registerSpecRelatedCommand } = require('../lib/commands/spec-related');
+const { registerSpecStrategyCommand } = require('../lib/commands/spec-strategy');
 const { registerTimelineCommands } = require('../lib/commands/timeline');
 const { registerValueCommands } = require('../lib/commands/value');
 const { registerTaskCommands } = require('../lib/commands/task');
@@ -67,6 +68,7 @@ const program = new Command();
  * - `sce spec gate ...` -> `sce spec-gate ...`
  * - `sce spec domain ...` -> `sce spec-domain ...`
  * - `sce spec related ...` -> `sce spec-related ...`
+ * - `sce spec strategy ...` -> `sce spec-strategy ...`
  * - `sce spec create <name> ...` -> `sce create-spec <name> ...`
  * - `sce spec <name> ...` -> `sce create-spec <name> ...` (legacy)
  *
@@ -111,6 +113,11 @@ function normalizeSpecCommandArgs(argv) {
     return normalized;
   }
 
+  if (commandToken === 'strategy') {
+    normalized.splice(commandIndex, 2, 'spec-strategy');
+    return normalized;
+  }
+
   if (commandToken === 'create') {
     normalized.splice(commandIndex, 2, 'create-spec');
     return normalized;
@@ -414,6 +421,9 @@ registerSpecDomainCommand(program);
 // Spec related lookup command
 registerSpecRelatedCommand(program);
 
+// Spec strategy assessment command
+registerSpecStrategyCommand(program);
+
 // 系统诊断命令
 program
   .command('doctor')

package/docs/app-intent-apply-contract.md

@@ -0,0 +1,263 @@
+# App Intent Apply Contract
+
+## Scope
+
+This document defines the JSON response contract for:
+
+- `sce app collection apply --collection <id> --json`
+- `sce scene workspace apply --workspace <id> --json`
+
+Both commands share the same payload shape. The only stable differences are:
+
+- `mode`
+- `summary.source_type`
+- `summary.source_id`
+- `plan.source`
+
+## Top-Level Payload
+
+```json
+{
+  "mode": "app-collection-apply",
+  "generated_at": "2026-03-16T12:00:00.000Z",
+  "execute_supported": true,
+  "executed": false,
+  "execution_blocked_reason": null,
+  "execution": {
+    "results": [],
+    "preflight_failures": []
+  },
+  "current_device": {},
+  "device_override": {},
+  "summary": {},
+  "plan": {}
+}
+```
+
+### Field meanings
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `mode` | string | `app-collection-apply` or `scene-workspace-apply` |
+| `generated_at` | string | ISO timestamp |
+| `execute_supported` | boolean | Current implementation supports explicit execution |
+| `executed` | boolean | `true` only when `--execute` was requested and the plan really ran |
+| `execution_blocked_reason` | string or null | Blocking reason when execution did not run |
+| `execution.results` | array | Per-action execution result list |
+| `execution.preflight_failures` | array | Preflight failures when execution is blocked by runtime readiness |
+| `current_device` | object | Current device identity and capability projection |
+| `device_override` | object | Normalized local device override from `.sce/state/device/device-override.json` |
+| `summary` | object | Top-level counts for UI summary |
+| `plan` | object | Full desired-set and action diff contract |
+
+## Summary Contract
+
+```json
+{
+  "source_type": "app-collection",
+  "source_id": "sales-workbench",
+  "desired_app_count": 4,
+  "install_count": 2,
+  "activate_count": 1,
+  "uninstall_count": 1,
+  "keep_count": 0,
+  "skip_count": 1
+}
+```
+
+## Plan Contract
+
+```json
+{
+  "source": {
+    "type": "app-collection",
+    "id": "sales-workbench",
+    "name": "Sales Workbench"
+  },
+  "current_device": {
+    "device_id": "desktop-01",
+    "capability_tags": ["desktop", "win32", "x64"]
+  },
+  "device_override": {
+    "removed_apps": ["crm"],
+    "added_apps": [
+      {
+        "app_key": "notes",
+        "required": false
+      }
+    ]
+  },
+  "desired_apps": [],
+  "unresolved_collections": [],
+  "unresolved_apps": [],
+  "actions": [],
+  "counts": {
+    "install": 0,
+    "activate": 0,
+    "uninstall": 0,
+    "keep": 0,
+    "skip": 0
+  }
+}
+```
+
+### `desired_apps[]`
+
+Each item is the resolved desired app set after collection/workspace expansion and local device override merge.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `app_id` | string or null | Preferred explicit app identity when supplied |
+| `app_key` | string or null | Preferred route and registry key |
+| `required` | boolean | App is intended as required in the resolved desired set |
+| `allow_local_remove` | boolean | Whether local removal is allowed in intent metadata |
+| `priority` | number or null | Lower number means higher priority |
+| `default_entry` | string or null | Preferred initial route |
+| `capability_tags` | array | Capability filter merged from contributing items |
+| `metadata` | object | Free-form metadata |
+| `sources` | array | Provenance list such as `collection:<id>` or `workspace:<id>` |
+
+### `actions[]`
+
+Each item is the device-oriented diff result that the UI should render before execution.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `app_id` | string or null | Resolved app id |
+| `app_key` | string or null | Resolved app key |
+| `app_name` | string or null | Human-readable bundle name when known |
+| `decision` | string | `install`, `activate`, `uninstall`, `keep`, or `skip` |
+| `reason` | string | Why this decision was generated |
+| `install_status` | string | Current install status from bundle projection |
+| `installed_release_id` | string or null | Currently installed release on this device |
+| `active_release_id` | string or null | Currently active release |
+| `required` | boolean | Whether the resolved desired set marks this as required |
+| `sources` | array | Provenance list for desired entries; removals may be empty |
+
+### Stable `decision` values
+
+| Decision | Meaning |
+| --- | --- |
+| `install` | Desired app is not installed on this device |
+| `activate` | Installed release exists but is not the active release |
+| `uninstall` | App is installed but no longer desired on this device |
+| `keep` | App already matches desired state |
+| `skip` | Plan cannot safely execute this item automatically |
+
+### Stable `reason` values currently emitted
+
+| Reason | Meaning |
+| --- | --- |
+| `desired-app-not-installed` | Install candidate |
+| `installed-release-not-active` | Activate candidate |
+| `desired-app-already-installed` | Keep candidate |
+| `not-desired-on-current-device` | Uninstall candidate |
+| `device-capability-mismatch` | Desired app filtered out by capability tags |
+| `app-bundle-not-found` | Desired app does not resolve to a known bundle |
+| `active-release-protected` | Installed app is active and cannot be auto-uninstalled |
+
+## Execution Contract
+
+### `execution_blocked_reason`
+
+Current stable values:
+
+- `null`
+- `unresolved-collections`
+- `unresolved-app-bundles`
+- `active-release-protected`
+- comma-joined combinations such as `unresolved-collections,active-release-protected`
+- `install-preflight-failed`
+- `invalid-plan-action`
+
+### `execution.results[]`
+
+Returned only when execution actually runs.
+
+```json
+[
+  {
+    "app_ref": "crm",
+    "decision": "install",
+    "success": true,
+    "summary": {
+      "app_id": "app.crm",
+      "install_status": "installed",
+      "installed_release_id": "rel.crm.1",
+      "active_release_id": "rel.crm.1"
+    }
+  }
+]
+```
+
+### `execution.preflight_failures[]`
+
+Returned when execution is blocked because install/activate candidates are not runtime-ready.
+
+```json
+[
+  {
+    "app_ref": "crm",
+    "reason": "no-installable-runtime-release"
+  }
+]
+```
+
+Current stable preflight reasons:
+
+- `no-installable-runtime-release`
+- `no-activatable-installed-release`
+
+## Example: Plan Only
+
+```json
+{
+  "mode": "scene-workspace-apply",
+  "execute_supported": true,
+  "executed": false,
+  "execution_blocked_reason": null,
+  "summary": {
+    "source_type": "scene-workspace",
+    "source_id": "sales-desktop",
+    "desired_app_count": 4,
+    "install_count": 2,
+    "activate_count": 1,
+    "uninstall_count": 0,
+    "keep_count": 1,
+    "skip_count": 0
+  }
+}
+```
+
+## Example: Executed
+
+```json
+{
+  "mode": "app-collection-apply",
+  "execute_supported": true,
+  "executed": true,
+  "execution_blocked_reason": null,
+  "execution": {
+    "results": [
+      {
+        "app_ref": "crm",
+        "decision": "install",
+        "success": true
+      },
+      {
+        "app_ref": "todo",
+        "decision": "uninstall",
+        "success": true
+      }
+    ],
+    "preflight_failures": []
+  }
+}
+```
+
+## Frontend Guidance
+
+- Treat `plan.actions` as the primary render contract for the diff table.
+- Treat `summary` as the primary count badge contract.
+- Treat `execution.results` as post-run feedback only; do not infer the plan from it.
+- Use `execution_blocked_reason` and per-action `reason` together. One tells you why the full plan could not run; the other tells you why each row exists.

package/docs/autonomous-control-guide.md

@@ -87,6 +87,16 @@ sce auto close-loop-program \
   --program-audit-out .sce/reports/close-loop-program-audit.json \
   --json
 
+Use this path when the problem is broader than one Spec and already clearly points to multiple coordinated implementation tracks.
+
+If the problem is still too unclear for direct implementation splitting, treat it as a research-first program and clarify domains/contracts/rules before expecting stable executable tasks from child Specs.
+
+Suggested preflight:
+
+```bash
+sce spec strategy assess --goal "broad complex goal" --json
+```
+
 # 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

@@ -80,11 +80,18 @@ sce spec domain refresh --spec 01-00-feature-name --scene scene.customer-order-i
 sce spec related --query "customer order inventory reconciliation drift" --scene scene.customer-order-inventory --json
 sce spec related --spec 01-00-feature-name --limit 8 --json
 
+# Assess whether one Spec is enough before decomposition
+sce spec strategy assess --goal "broad complex goal" --json
+sce spec strategy assess --spec 01-00-feature-name --json
+
 # Multi-Spec mode defaults to orchestrate routing
 sce spec bootstrap --specs "spec-a,spec-b" --max-parallel 3
 sce spec pipeline run --specs "spec-a,spec-b" --max-parallel 3
 sce spec gate run --specs "spec-a,spec-b" --max-parallel 3
 
+# Very broad / entangled goals can use program mode first
+sce auto close-loop-program "broad complex goal" --program-goals 4 --json
+
 # Show Spec progress
 sce status --verbose
 ```
@@ -93,6 +100,7 @@ Spec session governance:
 - `spec bootstrap|pipeline run|gate run` must bind to an active scene primary session (`--scene <scene-id>` or implicit binding from latest/unique active scene).
 - 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.
 - `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`
@@ -104,6 +112,7 @@ Spec session governance:
   - `scene-spec.md` must include `Closed-Loop Research Contract`
   - `problem-domain-chain.json` must include `research_coverage` contract
 - `sce spec domain coverage` reports coverage dimensions (scene boundary, entity/relation/rules/policy/flow, failure signals, debug evidence plan, verification gate).
+- When one Spec cannot produce stable executable tasks, prefer escalating to a coordinated multi-Spec or program path instead of forcing more blind decomposition into the same Spec.
 
 ### Timeline Snapshots
 
@@ -429,6 +438,8 @@ sce mode engineering home --app customer-order-demo --json
 Device override notes:
 - `sce device override show` returns the normalized local per-device overlay from `.sce/state/device/device-override.json`.
 - `sce device override upsert --input <json>` merges only explicitly provided fields; omitted fields remain unchanged so local override policy is not blindly replaced.
+- Copy-ready collection/workspace examples live under `docs/examples/app-intent-phase1/.sce/app/...`.
+- Stable JSON contract for both apply commands is documented in `docs/app-intent-apply-contract.md`.
 
 ### PM Delivery Data Plane
 

package/docs/examples/app-intent-phase1/.sce/app/collections/planning-workbench.json

@@ -0,0 +1,34 @@
+{
+  "collection_id": "planning-workbench",
+  "name": "Planning Workbench",
+  "description": "MRP, scheduling, and inventory analysis bundle for planning teams.",
+  "status": "active",
+  "tags": ["planning", "mrp", "inventory"],
+  "items": [
+    {
+      "app_key": "mrp",
+      "required": true,
+      "allow_local_remove": false,
+      "priority": 10,
+      "default_entry": "mrp/workbench"
+    },
+    {
+      "app_key": "scheduling",
+      "required": true,
+      "allow_local_remove": false,
+      "priority": 20,
+      "default_entry": "schedule/board"
+    },
+    {
+      "app_key": "inventory-insight",
+      "required": false,
+      "allow_local_remove": true,
+      "priority": 30,
+      "default_entry": "inventory/analysis"
+    }
+  ],
+  "metadata": {
+    "owner_role": "planner",
+    "recommended_device_profile": "desktop-planning"
+  }
+}

package/docs/examples/app-intent-phase1/.sce/app/collections/sales-workbench.json

@@ -0,0 +1,40 @@
+{
+  "collection_id": "sales-workbench",
+  "name": "Sales Workbench",
+  "description": "Daily sales follow-up, quotation, and customer visit bundle for desktop users.",
+  "status": "active",
+  "tags": ["sales", "crm", "quotation"],
+  "items": [
+    {
+      "app_key": "crm",
+      "required": true,
+      "allow_local_remove": false,
+      "priority": 10,
+      "default_entry": "crm/home"
+    },
+    {
+      "app_key": "quotation",
+      "required": true,
+      "allow_local_remove": false,
+      "priority": 20,
+      "default_entry": "quotation/dashboard"
+    },
+    {
+      "app_key": "customer-visit",
+      "required": false,
+      "allow_local_remove": true,
+      "priority": 30,
+      "default_entry": "visit/agenda"
+    },
+    {
+      "app_key": "notes",
+      "required": false,
+      "allow_local_remove": true,
+      "priority": 40
+    }
+  ],
+  "metadata": {
+    "owner_role": "sales",
+    "recommended_device_profile": "desktop-sales"
+  }
+}

package/docs/examples/app-intent-phase1/.sce/app/collections/warehouse-kiosk.json

@@ -0,0 +1,35 @@
+{
+  "collection_id": "warehouse-kiosk",
+  "name": "Warehouse Kiosk",
+  "description": "Lightweight warehouse execution bundle for tablet or kiosk devices.",
+  "status": "active",
+  "tags": ["warehouse", "tablet", "barcode"],
+  "items": [
+    {
+      "app_key": "barcode-scan",
+      "required": true,
+      "allow_local_remove": false,
+      "priority": 10,
+      "capability_tags": ["tablet"],
+      "default_entry": "scan/inbound"
+    },
+    {
+      "app_key": "inbound-receipt",
+      "required": true,
+      "allow_local_remove": false,
+      "priority": 20,
+      "capability_tags": ["tablet"]
+    },
+    {
+      "app_key": "label-print",
+      "required": false,
+      "allow_local_remove": true,
+      "priority": 30,
+      "capability_tags": ["tablet"]
+    }
+  ],
+  "metadata": {
+    "owner_role": "warehouse",
+    "recommended_device_profile": "tablet-kiosk"
+  }
+}

package/docs/examples/app-intent-phase1/.sce/app/scene-profiles/planning-desktop.json

@@ -0,0 +1,23 @@
+{
+  "workspace_id": "planning-desktop",
+  "name": "Planning Desktop Workspace",
+  "description": "Desktop planning workspace that combines MRP, scheduling, and supply review.",
+  "status": "active",
+  "tags": ["planning", "desktop"],
+  "collection_refs": ["planning-workbench"],
+  "default_entry": "mrp/workbench",
+  "layout_hint": "wide-dashboard",
+  "items": [
+    {
+      "app_key": "supply-risk",
+      "required": false,
+      "allow_local_remove": true,
+      "priority": 40,
+      "capability_tags": ["desktop"]
+    }
+  ],
+  "metadata": {
+    "persona": "production-planner",
+    "device_type": "desktop"
+  }
+}

package/docs/examples/app-intent-phase1/.sce/app/scene-profiles/sales-desktop.json

@@ -0,0 +1,24 @@
+{
+  "workspace_id": "sales-desktop",
+  "name": "Sales Desktop Workspace",
+  "description": "Desktop-first workspace for sales follow-up, quotation, and optional analytics.",
+  "status": "active",
+  "tags": ["sales", "desktop"],
+  "collection_refs": ["sales-workbench"],
+  "default_entry": "crm/home",
+  "layout_hint": "two-column",
+  "items": [
+    {
+      "app_key": "analytics",
+      "required": false,
+      "allow_local_remove": true,
+      "priority": 50,
+      "capability_tags": ["desktop"],
+      "default_entry": "analytics/sales-pipeline"
+    }
+  ],
+  "metadata": {
+    "persona": "sales-representative",
+    "device_type": "desktop"
+  }
+}

package/docs/examples/app-intent-phase1/.sce/app/scene-profiles/warehouse-tablet.json

@@ -0,0 +1,23 @@
+{
+  "workspace_id": "warehouse-tablet",
+  "name": "Warehouse Tablet Workspace",
+  "description": "Tablet-first warehouse workspace with scanning and receiving actions.",
+  "status": "active",
+  "tags": ["warehouse", "tablet"],
+  "collection_refs": ["warehouse-kiosk"],
+  "default_entry": "scan/inbound",
+  "layout_hint": "single-focus",
+  "items": [
+    {
+      "app_key": "notes",
+      "required": false,
+      "allow_local_remove": true,
+      "priority": 40,
+      "capability_tags": ["tablet"]
+    }
+  ],
+  "metadata": {
+    "persona": "warehouse-operator",
+    "device_type": "tablet"
+  }
+}

package/docs/examples/app-intent-phase1/README.md

@@ -0,0 +1,29 @@
+# App Intent Phase-1 Examples
+
+This folder provides copy-ready sample assets for the shipped phase-1 app intent model.
+
+It mirrors the canonical workspace layout:
+
+- `.sce/app/collections/*.json`
+- `.sce/app/scene-profiles/*.json`
+
+## Suggested usage
+
+Copy the example files you actually need into your project workspace:
+
+```bash
+mkdir -p .sce/app/collections .sce/app/scene-profiles
+cp docs/examples/app-intent-phase1/.sce/app/collections/*.json .sce/app/collections/
+cp docs/examples/app-intent-phase1/.sce/app/scene-profiles/*.json .sce/app/scene-profiles/
+```
+
+Then adapt:
+
+- `app_key`
+- `required`
+- `allow_local_remove`
+- `priority`
+- `capability_tags`
+- `default_entry`
+
+These are examples, not mandatory defaults. Do not copy them blindly without aligning them to the target business scene.