scene-capability-engine 3.6.64 → 3.6.67

package/docs/integration-philosophy.md

@@ -1,313 +1,106 @@
-# sce 集成哲学
+# Integration Philosophy
 
-> sce 如何与 AI 编码工具配合工作
+> SCE governs the project. The host AI runtime is important, but it is not the source of truth.
 
 ---
 
-## 核心定位
-
-**sce 不是替代 AI 工具，而是增强 AI 工具**
-
-```
-┌─────────────────────────────────────┐
-│         AI 编码工具                  │
-│    (Codex/Claude/Cursor/Windsurf)   │
-│                                      │
-│  用户主要工作界面 ← 这里写代码        │
-└──────────────┬──────────────────────┘
-               │
-               │ 读取上下文
-               ▼
-┌─────────────────────────────────────┐
-│            sce                       │
-│                                      │
-│  Spec 管理 + 上下文生成               │
-│  (后台运行，提供结构化信息)            │
-└─────────────────────────────────────┘
-```
+## 1. Replaceable Host, Stable Project Model
 
----
-
-## 三种集成模式
-
-### 模式 1：AI 主动调用 sce（最佳）⭐
-
-**适用工具**：Windsurf、Cline、Aider（可执行命令的 AI）
-
-**工作流**：
-```
-用户 → AI 工具 → AI 自动执行 sce 命令 → 获取上下文 → 生成代码
-```
-
-**示例对话**：
-```
-用户：我要实现用户登录功能
-
-AI：好的，让我先查看项目的 Spec
-    [自动执行] sce context export 01-00-user-login
-    [读取文件] .sce/specs/01-00-user-login/context-export.md
-    
-    我看到设计文档中定义了 AuthController...
-    [生成代码]
-    
-    [自动执行] sce task claim 01-00-user-login 1.1
-    任务已认领，开始实现...
-```
-
-**配置方法**：
-
-在 AI 工具的系统提示中添加：
-```markdown
-你可以使用以下 sce 命令来管理项目：
+Codex CLI, Claude Code, Cursor, Kiro, and similar tools may all host SCE-driven work.
 
-- `sce context export <spec-name>` - 导出 Spec 上下文
-- `sce prompt generate <spec-name> <task-id>` - 生成任务提示
-- `sce task claim <spec-name> <task-id>` - 认领任务
-- `sce status` - 查看项目状态
+What should stay stable across them is not the shell. It is the governed model:
 
-在实现功能前，先用 sce 命令查看相关 Spec。
-```
+- `project -> channel/session -> scene/spec -> task -> evidence`
+- `Four Teachings + Little Nine` before execution
+- Spec-scoped artifact management
+- SQLite-backed recoverable state
 
-**优势**：
-- ✅ 完全自动化
-- ✅ 用户无需手动操作
-- ✅ AI 自动管理 Spec 生命周期
+This prevents the system from collapsing back into "whatever the current chat remembered."
 
 ---
 
-### 模式 2：手动导出 + AI 使用（当前）
-
-**适用工具**：Claude Code、ChatGPT、GitHub Copilot
-
-**工作流**：
-```
-用户 → 手动执行 sce 命令 → 复制上下文 → 粘贴到 AI → AI 生成代码
-```
-
-**示例流程**：
-```bash
-# 1. 用户手动导出
-sce context export 01-00-user-login
-
-# 2. 复制内容
-cat .sce/specs/01-00-user-login/context-export.md | pbcopy
-
-# 3. 粘贴到 Claude/ChatGPT
-
-# 4. 对话
-用户：请实现任务 1.1
-AI：[生成代码]
-
-# 5. 手动更新任务状态
-# 编辑 tasks.md: - [x] 1.1 ...
-```
-
-**改进建议**：
-```bash
-# 添加快捷命令
-sce clip 01-00-user-login          # 自动复制到剪贴板
-sce clip 01-00-user-login 1.1      # 只复制任务 1.1 的上下文
-```
-
-**优势**：
-- ✅ 适用于所有 AI 工具
-- ✅ 用户完全控制
+## 2. Channel/Session Is the Collaboration Unit
 
-**劣势**：
-- ❌ 需要手动操作
-- ❌ 步骤较多
+Within one project, multiple collaboration channels may exist in parallel by default.
 
----
+- a channel/session is user-visible collaboration context
+- a scene is the semantic continuity boundary
+- a focused channel is only the current UI pointer
+- each `project + channel/session` must preserve its own local working state
 
-### 模式 3：Watch Mode 自动化（进阶）
-
-**适用场景**：频繁修改 Spec 的项目
-
-**工作流**：
-```
-用户修改 Spec → sce 自动检测 → 自动重新导出 → AI 工具自动刷新
-```
-
-**配置**：
-```bash
-# 启动 Watch Mode
-sce watch init
-sce watch install auto-export
-sce watch start
-
-# 现在修改任何 Spec 文件，都会自动重新导出
-```
-
-**Watch 配置示例**：
-```json
-{
-  "patterns": [
-    ".sce/specs/**/requirements.md",
-    ".sce/specs/**/design.md",
-    ".sce/specs/**/tasks.md"
-  ],
-  "actions": [
-    {
-      "name": "auto-export",
-      "command": "sce context export ${spec-name}"
-    }
-  ]
-}
-```
-
-**优势**：
-- ✅ 完全自动化
-- ✅ Spec 修改立即生效
+SCE should not silently fall back from explicit `project + channel` input to unrelated global guesses.
 
 ---
 
-## 推荐配置
-
-### 对于 Windsurf/Cline 用户（推荐）⭐
-
-**在 AI 系统提示中添加**：
-
-```markdown
-# Spec 管理规则
-
-项目使用 sce (Scene Capability Engine) 管理需求和设计。
-
-## 工作流程
-
-1. **查看 Spec**：实现功能前，先执行 `sce context export <spec-name>` 查看设计
-2. **认领任务**：开始工作前，执行 `sce task claim <spec-name> <task-id>`
-3. **实现代码**：严格按照 Spec 中的设计实现
-4. **更新状态**：完成后，在 tasks.md 中标记任务为完成 `[x]`
-
-## 可用命令
-
-- `sce status` - 查看项目状态
-- `sce context export <spec-name>` - 导出 Spec 上下文
-- `sce task claim <spec-name> <task-id>` - 认领任务
-- `sce prompt generate <spec-name> <task-id>` - 生成任务提示
+## 3. Specs Own the Work Artifacts
 
-## 示例
+Generated artifacts must live with the work they belong to.
 
-用户说："实现用户登录"
-你应该：
-1. 执行 `sce context export 01-00-user-login`
-2. 读取导出的上下文
-3. 根据设计文档实现代码
-4. 执行 `sce task claim 01-00-user-login 1.1`
-```
+- debug logs
+- reports
+- test scripts
+- temporary analysis
+- handoff bundles
 
-### 对于 Claude/ChatGPT 用户
+Default rule:
 
-**创建快捷脚本**：
+- if an active Spec exists, write under that Spec subtree
+- if no explicit Spec exists yet, use a governed general Spec
+- temporary documents are removed after the task is complete
 
-```bash
-# ~/.bashrc 或 ~/.zshrc
-alias sce-clip='sce context export $1 && cat .sce/specs/$1/context-export.md | pbcopy && echo "✅ 已复制到剪贴板"'
+This keeps evidence attached to execution instead of spreading across the repo.
 
-# 使用
-sce-clip 01-00-user-login
-# 然后直接粘贴到 Claude
-```
+---
 
-### 对于 Cursor 用户
+## 4. Compatibility Is Allowed, But It Is Not the Mainline
 
-**使用 Cursor Rules**：
+`context export` and `prompt generate` remain useful when a host tool cannot execute SCE directly.
 
-创建 `.cursorrules` 文件：
-```markdown
-# Spec 驱动开发
+But they are compatibility bridges.
 
-项目使用 sce 管理 Spec。实现功能前：
+They should not redefine the platform as:
 
-1. 查看 `.sce/specs/<spec-name>/design.md`
-2. 按照设计实现
-3. 更新 `.sce/specs/<spec-name>/tasks.md`
+- only an embedded helper
+- only a manual export utility
+- only a prompt-prep layer for other tools
 
-示例：
-- 设计文档：`.sce/specs/01-00-user-login/design.md`
-- 任务列表：`.sce/specs/01-00-user-login/tasks.md`
-```
+The long-term direction is SCE-native semantic/runtime capability with governed backflow and operator control.
 
 ---
 
-## 未来改进方向
-
-### 1. MCP (Model Context Protocol) 集成
-
-让 AI 工具通过 MCP 直接访问 sce：
-
-```javascript
-// AI 工具可以直接调用
-const context = await mcp.call('sce.getContext', '01-00-user-login');
-const tasks = await mcp.call('sce.getTasks', '01-00-user-login');
-```
-
-### 2. IDE 插件
+## 5. Debugging Must Converge
 
-为主流 IDE 提供插件：
-- VS Code Extension
-- Cursor Extension
-- JetBrains Plugin
+When localization keeps failing, SCE should not keep guessing.
 
-功能：
-- 右键菜单："导出到 AI 工具"
-- 状态栏显示当前 Spec
-- 快捷键快速导出
+Default rule:
 
-### 3. Web Dashboard
+- after more than two failed localization rounds, update the errorbook incident
+- add bisection-style debug evidence
+- keep halving the failing scope until the real blocker is isolated
 
-提供 Web 界面：
-```bash
-sce serve
-# 打开 http://localhost:3000
-# 可视化管理 Spec，一键复制上下文
-```
+This is part of the governance model, not a personal preference.
 
 ---
 
-## 常见问题
+## 6. Release Messaging Must Match the Real Mainline
 
-### Q: 为什么不把 sce 做成 AI 工具的插件？
+If top-level docs still tell users that the old embedded/manual-export model is primary, release messaging has already drifted from implementation reality.
 
-**A**: 
-- sce 是**通用工具**，支持所有 AI 工具
-- 做成插件会限制在特定工具
-- CLI 工具更灵活，可以被任何工具调用
+Therefore:
 
-### Q: 能否让 AI 工具自动读取 .sce/ 目录？
-
-**A**: 
-- 部分工具支持（Cursor、Copilot）
-- 但需要明确的上下文导出更可靠
-- sce 的价值在于**结构化和格式化**上下文
-
-### Q: 两套工具确实有点麻烦，有更简单的方案吗？
-
-**A**: 
-- **短期**：使用 Windsurf/Cline，让 AI 自动调用 sce
-- **中期**：使用快捷脚本（如 `sce-clip`）
-- **长期**：MCP 集成，完全无缝
+- top-level docs must describe the current mainline first
+- compatibility paths can stay, but only as compatibility paths
+- stable/preview/RC posture must be reported explicitly
 
 ---
 
-## 总结
-
-**sce 的定位**：
-- ❌ 不是独立的开发工具
-- ❌ 不是 AI 工具的竞争对手
-- ✅ 是 AI 工具的**上下文提供者**
-- ✅ 是项目的**Spec 管理系统**
+## Summary
 
-**最佳实践**：
-1. **用 sce 管理 Spec**（需求、设计、任务）
-2. **用 AI 工具写代码**（主要工作界面）
-3. **让 AI 工具调用 sce**（自动化集成）
+SCE is evolving toward an independent semantic and runtime control layer.
 
-**选择合适的模式**：
-- 能执行命令的 AI → 模式 1（AI 主动调用）⭐
-- 不能执行命令的 AI → 模式 2（手动导出）
-- 频繁修改 Spec → 模式 3（Watch Mode）
+Host AI tools remain valuable, but the governed project model, evidence model, and release model must belong to SCE itself.
 
 ---
 
-**记住**：sce 是幕后英雄，AI 工具是前台明星。两者配合，才能发挥最大价值！🚀
+**Version**: 3.6.67
+**Last Updated**: 2026-03-29

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

@@ -32,6 +32,7 @@ sce project supervision show --project workspace:customer-order-demo --json
 
 Expected use:
 - build project switcher from engine-owned roster
+- treat `project onboarding import` `publication.visibleInPortfolio=true` as the signal to refresh the roster immediately
 - preflight cross-project free-text routing before assistant/orchestration actions
 - render one project-scoped health summary without replaying raw event streams
 

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

@@ -50,6 +50,7 @@ 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
+sce project supervision show --project <project-id> --channel <channel-id> --json
 ```
 
 ## 1. Project Portfolio Projection
@@ -89,6 +90,23 @@ interface ProjectPortfolioRecord {
     sceneCount?: number
     specCount?: number
   }
+  projectChannelContext?: {
+    available: boolean
+    contextProjectId?: string | null
+    canonicalProjectIdMatched?: boolean
+    focusedChannelId?: string | null
+    channelCount?: number
+    storageMode?: 'split' | 'legacy' | 'none' | 'unknown'
+  }
+  supervisionSignals?: {
+    highestSeverity: 'none' | 'low' | 'medium' | 'high' | 'critical'
+    actionableCount: number
+    archiveMissingCount: number
+    backflowBlockedCount: number
+    governanceHotspotCount: number
+    pendingConnectCount: number
+    primaryRecommendedCommand?: string
+  }
   partial?: boolean
   partialReasons?: string[]
 }
@@ -100,6 +118,7 @@ interface ProjectPortfolioRecord {
 - 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.
+- If `supervisionSignals` is present, use it to rank which project should be entered first instead of inventing a frontend-only pressure model.
 - Do not rebuild roster truth from local UI cache when this payload is available.
 
 ### Important phase-1 semantics
@@ -140,12 +159,29 @@ interface ProjectOnboardingImportResult {
   generated_at: string
   success: boolean
   preview: LocalProjectCandidateInspection
+  publication: {
+    status: 'published' | 'pending' | 'not_published'
+    visibleInPortfolio: boolean
+    rootDir: string | null
+    projectId: string | null
+    workspaceId: string | null
+    publishedAt?: string
+  }
   steps: Array<{
-    key: 'register' | 'attach' | 'hydrate' | 'activate' | 'scaffold'
+    key: 'register' | 'attach' | 'hydrate' | 'publish' | 'activate' | 'scaffold'
     status: 'done' | 'skipped' | 'pending' | 'failed'
     reasonCode?: string
     detail?: string
   }>
+  projectChannelContext?: {
+    available: boolean
+    contextProjectId?: string | null
+    canonicalProjectIdMatched?: boolean
+    focusedChannelId?: string | null
+    channelCount?: number
+    storageMode?: 'split' | 'legacy' | 'none' | 'unknown'
+  }
+  projectChannel?: ProjectChannelBinding
 }
 ```
 
@@ -155,6 +191,8 @@ interface ProjectOnboardingImportResult {
 - Use `project onboarding import` when the user picks a local root directly; do not fake an app-library item just to enter onboarding.
 - If `kind=workspace-backed`, reuse returned `projectId/workspaceId` directly and avoid synthesizing a second registry identity.
 - If `kind=local-sce-candidate`, present it as a partial local project until onboarding import registers it.
+- Treat `publication.visibleInPortfolio=true` as the engine-owned signal that a follow-up `project portfolio show` refresh should already expose the imported project.
+- If onboarding returns `projectChannelContext`, preserve it as the imported project's initial collaboration snapshot instead of recomputing one in the frontend.
 - Render `reasonCodes` directly in CLI/IDE receipts; do not replace them with frontend-only heuristics.
 
 ## 2. Target Resolution
@@ -162,7 +200,7 @@ interface ProjectOnboardingImportResult {
 ### Command
 
 ```bash
-sce project target resolve --request "<text>" --current-project <project-id> --json
+sce project target resolve --request "<text>" --current-project <project-id> --channel <channel-id> --json
 ```
 
 ### Contract shape
@@ -172,10 +210,18 @@ interface ProjectTargetResolution {
   resolvedAt: string
   callerContext: {
     currentProjectId?: string
+    currentChannelId?: string
+    requestedChannelId?: string
+    currentChannelContextAvailable?: boolean
+    currentChannelStorageMode?: 'split' | 'legacy' | 'none' | 'unknown'
+    focusedChannelId?: string
+    activeScene?: string
+    activeSpecId?: string
     workspaceId?: string
     deviceId?: string
     toolInstanceId?: string
   }
+  callerProjectChannel?: ProjectChannelBinding
   status: 'current-project' | 'resolved-other-project' | 'ambiguous' | 'unresolved'
   currentProjectId?: string
   resolvedProjectId?: string
@@ -196,6 +242,7 @@ interface ProjectTargetResolution {
 
 - 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 the frontend is scoped to one collaboration channel, pass `--channel` and preserve returned `callerProjectChannel`.
 - 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.
@@ -214,24 +261,75 @@ sce project supervision show --project <project-id> --json
 interface ProjectSupervisionProjection {
   generatedAt: string
   projectId: string
+  requestedChannelId?: string
   cursor?: string
   summary: {
     blockedCount: number
     handoffCount: number
     riskCount: number
+    infoCount?: number
+    governanceHotspotCount?: number
+    archiveItemCount?: number
+    backflowItemCount?: number
     activeSceneCount?: number
     activeSpecCount?: number
     activeTaskCount?: number
+    projectChannelCount?: number
+    focusedChannelId?: string
+    highestSeverity?: 'none' | 'low' | 'medium' | 'high' | 'critical'
+    actionableCount?: number
+    criticalCount?: number
+    highCount?: number
+    mediumCount?: number
+    lowCount?: number
+    primaryRecommendedCommand?: string
     latestEventAt?: string
   }
+  projectChannelContext?: {
+    available?: boolean
+    contextProjectId?: string | null
+    canonicalProjectIdMatched?: boolean
+    focusedChannelId?: string | null
+    storageMode?: 'split' | 'legacy' | 'none' | 'unknown'
+    channels: ProjectChannelSummary[]
+  }
+  projectChannel?: ProjectChannelBinding
+  actionQueue?: ProjectSupervisionAction[]
   items: ProjectSupervisionItem[]
   partial?: boolean
   partialReasons?: string[]
 }
 
+interface ProjectChannelSummary {
+  channelId: string
+  focused: boolean
+  activeScene?: string | null
+  activeSpecId?: string | null
+  activeDoc?: string | null
+  activeSessionPath?: string | null
+  runState?: string | null
+  updatedAt?: string | null
+}
+
+interface ProjectChannelBinding {
+  project_id?: string | null
+  canonical_project_id?: string | null
+  context_available?: boolean
+  storage_mode?: 'split' | 'legacy' | 'none' | 'unknown'
+  requested_channel_id?: string | null
+  focused_channel_id?: string | null
+  channel_id?: string | null
+  active_scene?: string | null
+  active_spec_id?: string | null
+  active_doc?: string | null
+  active_session_path?: string | null
+  run_state?: string | null
+  updated_at?: string | null
+}
+
 interface ProjectSupervisionItem {
   id: string
-  kind: 'blocked' | 'handoff' | 'risk' | 'active'
+  kind: 'blocked' | 'handoff' | 'risk' | 'active' | 'info' | 'archive' | 'backflow' | 'governance'
   state: string
   reasonCode?: string
   sceneId?: string
@@ -241,12 +339,35 @@ interface ProjectSupervisionItem {
   eventId?: string
   updatedAt: string
   summary: string
+  severity?: 'none' | 'low' | 'medium' | 'high' | 'critical'
+  blocking_scope?: 'project' | 'channel' | 'scene' | 'spec'
+  recommended_action?: string | null
+  recommended_command?: string | null
+}
+
+interface ProjectSupervisionAction {
+  rank: number
+  id: string
+  kind: ProjectSupervisionItem['kind']
+  state: string
+  summary: string
+  updatedAt?: string
+  severity: 'low' | 'medium' | 'high' | 'critical'
+  blocking_scope: 'project' | 'channel' | 'scene' | 'spec'
+  recommended_action: string
+  recommended_command: string
+  channelId?: string
+  sceneId?: string
+  specId?: string
 }
 ```
 
 ### MagicBall rules
 
 - Render summary counters directly from `summary`.
+- If the frontend is currently scoped to one collaboration channel, pass `--channel <channel-id>` and consume `projectChannel` as the resolved focus.
+- Treat `focusedChannelId` as UI focus only; do not use it to erase sibling `channels[]`.
+- Treat `actionQueue` as the operator-facing priority list; do not recompute a separate severity ordering unless the backend payload is missing.
 - 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.
@@ -256,7 +377,7 @@ interface ProjectSupervisionItem {
 
 1. Load `sce project portfolio show --json` when entering the multi-project shell.
 2. When the user selects a local root manually, preflight it with `sce project candidate inspect --root <path> --json`.
-3. If the root is not yet portfolio-backed, import it through `sce project onboarding import --root <path> --json`.
+3. If the root is not yet portfolio-backed, import it through `sce project onboarding import --root <path> --json`, then trust `publication` plus a fresh portfolio refresh instead of keeping a shadow imported-project registry.
 4. Store `activeProjectId` and render a project switcher from `projects[]`.
 5. When the user enters a cross-project free-text request, preflight with `sce project target resolve --json`.
 6. After project selection or successful resolution, load `sce project supervision show --project <project-id> --json`.

package/docs/project-management/README.md

@@ -0,0 +1,14 @@
+# 项目管理目录
+
+这棵目录是 IDE 工程模式下的人类阅读与审查入口。
+
+- `delivery/`: 交付推进
+- `environment/`: 应用环境监管
+- `assurance/`: 运行保障
+
+约束：
+
+1. 结构化真相仍以 `.sce/pm/**` 和 SCE API 为准。
+2. `docs/project-management/**` 负责稳定目录结构、说明文档和人工审查入口。
+3. 新项目接入工程模式后，应自动补齐这棵目录。
+4. 模板统一放在 `.sce/templates/project-management/`。

package/docs/project-management/assurance/backup.md

@@ -0,0 +1,3 @@
+# 备份恢复
+
+用于说明备份基线、恢复点与恢复流程。

package/docs/project-management/assurance/config.md

@@ -0,0 +1,3 @@
+# 配置启停
+
+用于说明配置开关、启停约束与风险项。

package/docs/project-management/assurance/evidence/README.md

@@ -0,0 +1,3 @@
+# 保障证据
+
+用于归档保障相关日志、截图、备份和审查证据。

package/docs/project-management/assurance/incidents/README.md

@@ -0,0 +1,3 @@
+# 事件记录
+
+用于记录故障、异常和处置闭环。

package/docs/project-management/assurance/logs.md

@@ -0,0 +1,3 @@
+# 日志管理
+
+用于说明日志视图、读取入口与分析方式。

package/docs/project-management/assurance/overview.md

@@ -0,0 +1,3 @@
+# 保障总览
+
+用于总览运行保障覆盖、风险与恢复入口。

package/docs/project-management/assurance/recovery/README.md

@@ -0,0 +1,3 @@
+# 恢复记录
+
+用于记录恢复演练、回滚和恢复结果。

package/docs/project-management/assurance/resource.md

@@ -0,0 +1,3 @@
+# 资源状态
+
+用于汇总系统资源与关键运行状态。

package/docs/project-management/assurance/runbooks/README.md

@@ -0,0 +1,3 @@
+# Runbooks
+
+用于沉淀运行操作手册与标准处置流程。

package/docs/project-management/delivery/acceptance/README.md

@@ -0,0 +1,3 @@
+# 验收 / 审计
+
+用于组织验收报告、例外说明与审计证据。

package/docs/project-management/delivery/acceptance/evidence/README.md

@@ -0,0 +1,3 @@
+# 验收证据
+
+用于归档验收相关的截图、日志、附件与比对结果。