scene-capability-engine 3.6.55 → 3.6.56

package/docs/magicball-app-collection-phase-1.md

@@ -84,6 +84,22 @@ Recommended split:
 
 This boundary matters because SQLite is suitable for local query-heavy facts, but it should not become the only source of truth for portable shared intent.
 
+## Copy-ready examples
+
+Sample assets are available here:
+
+- `docs/examples/app-intent-phase1/.sce/app/collections/*.json`
+- `docs/examples/app-intent-phase1/.sce/app/scene-profiles/*.json`
+- `docs/examples/app-intent-phase1/README.md`
+
+These examples are intentionally realistic but still generic:
+
+- sales desktop workspace
+- planning desktop workspace
+- warehouse tablet workspace
+
+Use them as a starting point, then replace app keys and business metadata with project-specific values.
+
 ## Recommended phase-1 command shape
 
 Phase-1 overall command surface:
@@ -108,6 +124,10 @@ Execution rule:
 - local override updates now also have an explicit CLI governance surface instead of requiring manual file edits
 - execution should reuse the existing app runtime path
 
+JSON response contract:
+
+- `docs/app-intent-apply-contract.md`
+
 ## Frontend implication for MagicBall
 
 MagicBall should keep using current per-app runtime controls until this phase ships.
@@ -128,6 +148,23 @@ Once phase-1 lands, the preferred top-level interaction should become:
 3. explicitly apply the plan
 4. continue using per-app runtime controls for detail views
 
+## Phase 2 direction
+
+Phase-2 should be planned as lightweight user-intent sync, not as device-state sync.
+
+Recommended boundary:
+
+- sync shared `app_collection` / `scene_profile` selections or bindings
+- do not sync `device_installation` facts as the cross-device source of truth
+- keep `device_override` local unless a project explicitly introduces a higher-level policy mechanism
+
+Recommended deliverables for phase-2 planning:
+
+1. user binding model for scene/profile selection
+2. device-aware resolution order for `user intent + local override + capability tags`
+3. pull/push sync semantics with conflict visibility rather than silent overwrite
+4. explicit non-goal: do not force all devices into the same installed app set
+
 ## Practical conclusion
 
 SCE should support this direction, but it should do so by extending the current app/runtime model rather than replacing it.

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

@@ -44,6 +44,7 @@ Optional local override input:
 - `.sce/state/device/device-override.json`
 - use this for per-device add/remove exceptions instead of mutating shared collection/workspace definitions
 - update it explicitly via `sce device override upsert --input <json> --json`
+- copy-ready collection/workspace examples live under `docs/examples/app-intent-phase1/.sce/app/...`
 
 Example local override patch:
 ```json

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

@@ -15,6 +15,7 @@ It is a navigation layer, not a new source of truth.
 These are the current first-line integration documents:
 - `docs/magicball-sce-adaptation-guide.md`
 - `docs/magicball-app-collection-phase-1.md`
+- `docs/app-intent-apply-contract.md`
 - `docs/magicball-ui-surface-checklist.md`
 - `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
 - `docs/magicball-frontend-state-and-command-mapping.md`
@@ -37,28 +38,32 @@ These are the current first-line integration documents:
    - current device / collection / workspace / override baseline
    - shipped phase-1 install orchestration contract
 
-4. `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+4. `docs/app-intent-apply-contract.md`
+   - stable JSON response contract for `collection apply` and `scene workspace apply`
+   - execution/blocking/preflight semantics
+
+5. `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
    - two active frontend-sensitive defaults
    - serialized mode-home loading
    - ontology empty-state and starter-seed behavior
 
-5. `docs/magicball-frontend-state-and-command-mapping.md`
+6. `docs/magicball-frontend-state-and-command-mapping.md`
    - page state ownership
    - command-to-action mapping
    - error and retry boundaries
 
-6. `docs/magicball-write-auth-adaptation-guide.md`
+7. `docs/magicball-write-auth-adaptation-guide.md`
    - write authorization and lease handling
 
-7. `docs/magicball-task-feedback-timeline-guide.md`
+8. `docs/magicball-task-feedback-timeline-guide.md`
    - task feedback cards
    - timeline view integration
 
-8. `docs/magicball-cli-invocation-examples.md`
+9. `docs/magicball-cli-invocation-examples.md`
    - copy-ready CLI examples
    - wrapper and smoke verification patterns
 
-9. `docs/magicball-integration-issue-tracker.md`
+10. `docs/magicball-integration-issue-tracker.md`
    - current cross-project truth
    - only open issues, active decisions, and verified resolutions
 
@@ -68,6 +73,7 @@ These are the current first-line integration documents:
 Use:
 - `docs/magicball-sce-adaptation-guide.md`
 - `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-frontend-state-and-command-mapping.md`
 
@@ -102,6 +108,7 @@ Use:
 | --- | --- | --- |
 | `magicball-sce-adaptation-guide.md` | main overview | low |
 | `magicball-app-collection-phase-1.md` | next-phase install model | medium |
+| `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-frontend-state-and-command-mapping.md` | frontend implementation mapping | medium |

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

@@ -13,6 +13,7 @@ Implementation detail should live in the specialized documents listed below.
 Use these documents together:
 - `docs/magicball-integration-doc-index.md`
 - `docs/magicball-app-collection-phase-1.md`
+- `docs/app-intent-apply-contract.md`
 - `docs/magicball-ui-surface-checklist.md`
 - `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
 - `docs/magicball-frontend-state-and-command-mapping.md`
@@ -58,6 +59,7 @@ Planned phase-1 position:
 
 Reference:
 - `docs/magicball-app-collection-phase-1.md`
+- `docs/app-intent-apply-contract.md`
 
 ## Core Integration Positioning
 

package/docs/releases/README.md

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

package/docs/releases/v3.6.56.md

@@ -0,0 +1,19 @@
+# v3.6.56 Release Notes
+
+Release date: 2026-03-17
+
+## Highlights
+
+- Added read-only `sce spec strategy assess` to decide whether a problem should stay `single-spec` or escalate to `multi-spec-program` / `research-program`.
+- Added a formal strategy Spec for complex-problem program escalation so SCE can stop forcing highly entangled work through one oversized Spec.
+- Added copy-ready phase-1 app intent examples plus a stable `apply` JSON contract document so scene-oriented install management can be adopted directly instead of inferred from source code.
+
+## Validation
+
+- `npx jest tests/unit/commands/spec-strategy.test.js --runInBand`
+- `node bin/sce.js --skip-steering-check --no-version-check spec strategy assess --goal "fix login button alignment in application home page" --json`
+- `node scripts/release-doc-version-audit.js --fail-on-error`
+
+## Release Notes
+
+- This patch turns SCE's existing multi-Spec and close-loop-program runtime into a better governed path for complex work. The key addition is not another executor, but an explicit strategy assessment layer that can say when one Spec is still enough and when the problem should first be treated as a coordinated program or a research-first clarification portfolio.

package/docs/spec-workflow.md

@@ -115,6 +115,46 @@ sce spec domain validate --spec <spec-id> --fail-on-gap --json
 
 This is the default way to avoid wrong-direction implementation and to force evidence-based correction loops.
 
+## When One Spec Is Not Enough
+
+Not every problem should be forced into a single Spec.
+
+Use this rule of thumb:
+
+- simple problem: stay with one Spec
+- medium complexity: split into a few implementation Specs and use orchestrate mode
+- very complex problem: first treat it as a program, not as a single implementation Spec
+
+Typical escalation signals:
+
+- one Spec keeps expanding but still cannot produce stable executable tasks
+- the problem spans multiple scenes, roles, or bounded contexts
+- API/data contracts are still unclear enough that task breakdown would be guesswork
+- business rules and policy boundaries are not yet settled
+- a single problem-domain chain already shows multiple semi-independent clusters
+
+Current SCE execution paths you can already use:
+
+```bash
+# read-only strategy assessment
+sce spec strategy assess --goal "broad complex goal" --json
+
+# multi-spec implementation program
+sce spec bootstrap --specs "spec-a,spec-b" --max-parallel 3
+
+# broad goal -> autonomous master/sub program decomposition
+sce auto close-loop-program "broad complex goal" --program-goals 4 --json
+```
+
+The strategic gap currently being formalized is:
+
+- how SCE should assess this threshold explicitly
+- when it should recommend `single-spec` vs `multi-spec-program` vs `research-program`
+
+Reference Spec:
+
+- `.sce/specs/129-00-complex-problem-program-escalation/`
+
 ---
 
 ## Stage 1: Requirements

package/docs/zh/releases/README.md

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

package/docs/zh/releases/v3.6.56.md

@@ -0,0 +1,19 @@
+# v3.6.56 发布说明
+
+发布日期：2026-03-17
+
+## 重点变化
+
+- 新增只读命令 `sce spec strategy assess`，用于判断问题应继续使用 `single-spec`，还是升级为 `multi-spec-program` / `research-program`。
+- 新增复杂问题升级策略 Spec，使 SCE 不再默认把高度纠缠的问题硬塞进一个超大 Spec。
+- 补充 phase-1 应用意图样例与稳定的 `apply` JSON 契约文档，让面向场景的安装管理能力可以直接落地，而不是只能靠读源码理解。
+
+## 验证
+
+- `npx jest tests/unit/commands/spec-strategy.test.js --runInBand`
+- `node bin/sce.js --skip-steering-check --no-version-check spec strategy assess --goal "fix login button alignment in application home page" --json`
+- `node scripts/release-doc-version-audit.js --fail-on-error`
+
+## 发布说明
+
+- 这个补丁版的重点不是再造一个执行器，而是给 SCE 已有的多 Spec / close-loop-program 执行能力补上策略层。现在 SCE 可以更明确地判断：一个问题是否还适合留在单 Spec，还是应该先升级为协调型 program，或者先进入 research-first 的澄清拆分路径。

package/lib/commands/spec-strategy.js

@@ -0,0 +1,73 @@
+const chalk = require('chalk');
+const fs = require('fs-extra');
+const { assessComplexityStrategy } = require('../spec/complexity-strategy');
+
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function printPayload(payload, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue('Spec Strategy Assess'));
+  console.log(`  Source: ${payload.source.type}${payload.source.id ? ` (${payload.source.id})` : ''}`);
+  console.log(`  Decision: ${payload.decision}`);
+  console.log(`  Reason: ${payload.decision_reason}`);
+  console.log(`  Recommended Program Specs: ${payload.summary.recommended_program_specs}`);
+  if (Array.isArray(payload.signals) && payload.signals.length > 0) {
+    console.log(chalk.gray('  Signals:'));
+    payload.signals.forEach((signal) => {
+      console.log(chalk.gray(`    - ${signal}`));
+    });
+  }
+}
+
+async function runSpecStrategyAssessCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const payload = await assessComplexityStrategy({
+    goal: normalizeText(options.goal),
+    spec: normalizeText(options.spec)
+  }, {
+    projectPath,
+    fileSystem
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+function registerSpecStrategyCommand(program) {
+  const strategy = program
+    .command('spec-strategy')
+    .description('Assess whether a problem should stay single-spec or escalate to a coordinated program');
+
+  strategy
+    .command('assess')
+    .description('Assess complexity and recommend single-spec vs multi-spec-program vs research-program')
+    .option('--goal <text>', 'Broad goal or problem statement to assess')
+    .option('--spec <spec-id>', 'Existing spec to assess from current artifacts')
+    .option('--json', 'Output machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runSpecStrategyAssessCommand(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ spec-strategy assess failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  runSpecStrategyAssessCommand,
+  registerSpecStrategyCommand
+};