scene-capability-engine 3.6.32 → 3.6.36

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

@@ -0,0 +1,328 @@
+# MagicBall Write Auth Adaptation Guide
+
+## Goal
+
+Define how MagicBall should adapt to SCE write-authorization requirements.
+
+This guide focuses on:
+1. which actions require authorization
+2. how MagicBall should request or reuse a lease
+3. how to pass lease information to SCE
+4. how to handle denied / expired / invalid lease errors
+
+This guide is intentionally frontend-oriented.
+
+## Current SCE Authorization Model
+
+SCE uses a write-authorization layer centered on:
+- policy file: `.sce/config/authorization-policy.json`
+- lease storage: `.sce/state/sce-state.sqlite`
+- commands:
+  - `sce auth grant`
+  - `sce auth status`
+  - `sce auth revoke`
+
+The runtime enforcement entry is:
+- `ensureWriteAuthorization(...)`
+
+## What MagicBall Should Assume By Default
+
+MagicBall should assume:
+1. read operations do not require lease
+2. write operations may require lease
+3. the exact enforcement depends on SCE policy
+4. frontend must not guess policy internals from static assumptions
+
+Therefore, MagicBall should design write flows as:
+- optimistic if lease exists
+- blocked-with-guidance if lease is missing or invalid
+
+## SCE Commands Relevant To Auth
+
+### Grant lease
+```bash
+sce auth grant --scope <scope> --reason "<reason>" --json
+```
+
+### Inspect lease status
+```bash
+sce auth status --json
+sce auth status --lease <lease-id> --json
+```
+
+### Revoke lease
+```bash
+sce auth revoke --lease <lease-id> --json
+```
+
+## Scopes MagicBall Should Care About
+
+Current implemented write flows in SCE imply these practical action families:
+
+### App / mode related
+- `app:bundle:register`
+- `app:registry:configure`
+- `app:engineering:attach`
+- `app:engineering:hydrate`
+- `app:engineering:activate`
+- `app:runtime:install`
+- `app:runtime:activate`
+
+### Engineering mode PM data plane
+- `pm:requirement:upsert`
+- `pm:tracking:upsert`
+- `pm:planning:upsert`
+- `pm:change:upsert`
+- `pm:issue:upsert`
+
+### Ontology mode data plane
+- `ontology:er:upsert`
+- `ontology:br:upsert`
+- `ontology:dl:upsert`
+
+### Existing studio/task actions
+- `studio:apply`
+- `studio:release`
+- `studio:rollback`
+- `task:rerun`
+
+## Recommended MagicBall UI Rule
+
+### Rule 1
+Treat all mutating actions as lease-aware actions.
+
+### Rule 2
+Do not hide all write buttons permanently.
+Instead:
+- show action button
+- if no valid lease is present, show locked state or auth prompt before execution
+
+### Rule 3
+For dangerous write actions, require an explicit authorization step even if the button is visible.
+
+## Recommended Frontend State Model
+
+MagicBall should keep a lightweight authorization state model:
+
+```ts
+interface WriteLeaseState {
+  leaseId: string | null
+  subject: string | null
+  role: string | null
+  scope: string[]
+  expiresAt: string | null
+  revokedAt: string | null
+  active: boolean
+  stale: boolean
+}
+```
+
+Recommended derived flags:
+- `hasLease`
+- `leaseActive`
+- `leaseExpired`
+- `scopeSatisfied(action)`
+
+## Recommended Frontend Flow
+
+### 1. Startup / app switch
+When MagicBall starts or switches app/project context:
+1. call `sce auth status --json`
+2. cache active leases
+3. derive whether current user/session can write
+
+### 2. Before a write action
+When user clicks a write action:
+1. map UI action to SCE action scope
+2. check local cached lease state
+3. if lease exists and scope matches, execute command with `--auth-lease <lease-id>`
+4. if lease missing or insufficient, open auth prompt flow
+
+### 3. Auth prompt flow
+Recommended UI steps:
+1. show why authorization is required
+2. show requested action scope
+3. ask user to authorize
+4. execute `sce auth grant ... --json`
+5. cache returned `lease_id`
+6. retry original write action with `--auth-lease`
+
+## Suggested UI Copy Pattern
+
+### Locked action hint
+- `This action requires SCE write authorization.`
+- `Requested scope: pm:requirement:upsert`
+
+### Grant dialog content
+- `Action`: human-readable action name
+- `Requested scope`: exact SCE scope string
+- `Reason`: user-editable reason text
+- `Password`: if needed by policy
+
+### Success hint
+- `Write authorization granted for 15 minutes.`
+
+### Failure hint
+- `Authorization failed. Check password, lease policy, or requested scope.`
+
+## Recommended Scope Mapping Table
+
+| MagicBall UI action | SCE command | Required scope |
+| --- | --- | --- |
+| Save app bundle | `sce app bundle register` | `app:bundle:register` |
+| 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` |
+| 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` |
+| Save requirement | `sce pm requirement upsert` | `pm:requirement:upsert` |
+| Save tracking item | `sce pm tracking upsert` | `pm:tracking:upsert` |
+| Save plan | `sce pm planning upsert` | `pm:planning:upsert` |
+| Save change request | `sce pm change upsert` | `pm:change:upsert` |
+| Save issue item | `sce pm issue upsert` | `pm:issue:upsert` |
+| Save ER asset | `sce ontology er upsert` | `ontology:er:upsert` |
+| Save BR rule | `sce ontology br upsert` | `ontology:br:upsert` |
+| Save DL chain | `sce ontology dl upsert` | `ontology:dl:upsert` |
+| Apply studio change | `sce studio apply` | `studio:apply` |
+| Release studio result | `sce studio release` | `studio:release` |
+| Rollback studio result | `sce studio rollback` | `studio:rollback` |
+| Rerun task | `sce task rerun` | `task:rerun` |
+
+## Recommended Grant Command Patterns
+
+### Generic lease
+```bash
+sce auth grant --scope app:runtime:activate --reason "activate selected runtime release" --json
+```
+
+### 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
+```
+
+## How MagicBall Should Pass Lease To SCE
+
+For every write command, pass:
+- `--auth-lease <lease-id>`
+
+Example:
+```bash
+sce pm requirement upsert --input requirement.json --auth-lease <lease-id> --json
+```
+
+## Error Handling Rules
+
+MagicBall should not treat all write failures the same.
+
+### Case A: lease required
+Typical symptom:
+- error mentions `Write authorization required`
+- or says lease is required for action
+
+Frontend action:
+1. keep form state intact
+2. open authorization prompt
+3. let user retry after grant
+
+### Case B: lease not found
+Typical symptom:
+- error mentions `lease not found`
+
+Frontend action:
+1. clear cached lease id
+2. force refresh auth status
+3. reopen grant flow
+
+### Case C: lease expired / revoked
+Typical symptom:
+- error mentions expired / revoked / inactive lease
+
+Frontend action:
+1. mark local lease stale
+2. force refresh auth status
+3. ask user to grant again
+
+### Case D: scope mismatch
+Typical symptom:
+- authorization denied for action despite active lease
+
+Frontend action:
+1. show requested scope
+2. request a new lease with broader or correct scope
+
+### Case E: business validation error
+Typical symptom:
+- payload/field/schema validation failure
+- no auth wording in error message
+
+Frontend action:
+1. do not reopen auth flow
+2. keep current form state
+3. show validation feedback only
+
+## Recommended Frontend State Machine
+
+```text
+idle
+  -> checking_lease
+  -> lease_ready
+  -> lease_missing
+  -> requesting_lease
+  -> lease_granted
+  -> executing_write
+  -> write_succeeded
+  -> write_failed_auth
+  -> write_failed_validation
+```
+
+## Minimal Frontend Implementation Checklist
+
+### Required now
+1. local lease cache
+2. `auth status` fetch on startup / app switch
+3. action-to-scope mapping table
+4. shared auth prompt dialog
+5. automatic retry of blocked action after successful grant
+
+### Can wait
+1. lease auto-refresh before expiry
+2. batch lease orchestration for multi-step workflows
+3. lease history panel
+4. revoke button in UI
+
+## Recommended MagicBall Button Policy
+
+### Safe read-only buttons
+- always enabled
+
+### Write buttons with no lease
+- visible
+- disabled or soft-blocked
+- click opens auth dialog
+
+### Write buttons with valid lease
+- enabled
+- execute command with `--auth-lease`
+
+### High-risk buttons
+Examples:
+- runtime activate
+- engineering activate
+- studio release
+- backup restore
+
+Recommended behavior:
+- keep visible
+- require explicit confirmation even with valid lease
+
+## Practical Conclusion
+
+MagicBall should now implement write authorization as a shared UI capability, not as page-by-page special handling.
+
+The most important thing is:
+- centralize scope mapping
+- centralize lease state
+- centralize retry-after-grant flow
+
+That will keep all app/runtime/pm/ontology/studio write flows consistent.

package/docs/refactor-completion-roadmap.md

@@ -0,0 +1,116 @@
+# Refactor Completion And Next Roadmap
+
+## Scope
+
+This document records the completion state of the `3.6.33` refactor round and defines the next engineering direction.
+
+Current stable commits:
+
+- `0c9594d` `refactor(auto): finalize close-loop governance split and docs refresh`
+- `0fb49b7` `refactor(handoff): extract capability matrix service`
+- `8ebc5bc` `release: 3.6.33`
+
+## What Is Considered Done
+
+This refactor round is considered complete because the main autonomous delivery chain is no longer centered in `lib/commands/auto.js`.
+
+Completed extractions:
+
+- `lib/auto/close-loop-controller-service.js`
+- `lib/auto/close-loop-batch-service.js`
+- `lib/auto/close-loop-program-service.js`
+- `lib/auto/observability-service.js`
+- `lib/auto/program-summary.js`
+- `lib/auto/program-output.js`
+- `lib/auto/batch-output.js`
+- `lib/auto/program-governance-helpers.js`
+- `lib/auto/program-governance-loop-service.js`
+- `lib/auto/program-auto-remediation-service.js`
+- `lib/auto/output-writer.js`
+- `lib/auto/handoff-capability-matrix-service.js`
+
+Supporting cleanup completed in the same round:
+
+- README and docs hub restructuring
+- governance summary regression fix
+- governance weekly-ops session telemetry fix
+- session stats `criteria.days` fix
+
+## Resulting Architecture Shift
+
+Before this round:
+
+- `lib/commands/auto.js` contained both command registration and most major orchestration logic.
+- changes to program or governance behavior were high-risk because too many concerns were coupled.
+
+After this round:
+
+- `lib/commands/auto.js` is primarily a command-layer shell plus wrappers.
+- major delivery orchestration now lives under `lib/auto/`.
+- the first `auto-handoff` subdomain now has a dedicated service boundary.
+
+This is the practical reason the round is treated as complete even though `auto.js` is still large.
+
+## Why Some Work Was Explicitly Deferred
+
+Not every remaining function in `lib/commands/auto.js` should be extracted immediately.
+
+Deferred on purpose:
+
+- low-value helper moves with poor payoff
+- unstable `auto-handoff` micro-extractions that increased regression risk
+- cosmetic-only reductions that do not improve long-term maintainability
+
+The rule used during this round was:
+
+- keep extractions that create durable service boundaries
+- stop when the next move becomes lower value than the regression risk it introduces
+
+## Remaining High-Value Areas
+
+The next meaningful work is no longer the close-loop main path. It is concentrated in `auto-handoff` and a few release/governance support areas.
+
+Highest-value remaining themes:
+
+1. `auto-handoff` release evidence and history services
+2. `auto-handoff` release note / evidence review renderers
+3. `auto-handoff` baseline and coverage snapshot services
+4. final documentation and release process hardening
+
+## Recommended Next Round
+
+The next round should be treated as a focused `auto-handoff` refactor, not a continuation of generic `auto.js` cleanup.
+
+Recommended order:
+
+1. `release evidence` subdomain
+2. `release gate history` subdomain
+3. `release note / evidence review` rendering subdomain
+4. `baseline / coverage snapshot` subdomain
+
+Each subdomain should follow the same rule used in `3.6.33`:
+
+- extract one coherent service boundary
+- keep command behavior unchanged
+- require unit coverage for the new module
+- require guarded integration coverage before keeping the change
+
+## Validation Baseline
+
+The following checks were used to accept the current refactor round:
+
+- `npx jest tests/unit/auto --runInBand`
+- `npx jest tests/unit/commands/auto.test.js --runInBand`
+- `npx jest tests/integration/auto-close-loop-cli.integration.test.js tests/integration/version-cli.integration.test.js --runInBand`
+- `npm run test:release`
+
+Any next round should continue to use these as the minimum baseline.
+
+## Release Status
+
+Current stable release:
+
+- version: `3.6.33`
+- tag: `v3.6.33`
+
+This version is the baseline for future `auto-handoff` evolution.

package/docs/zh/README.md

@@ -1,31 +1,42 @@
 # SCE 文档总览
 
-本页仅保留高价值入口，帮助你快速完成从接入到规模化交付。
+本页只保留高价值入口，帮助你从接入、集成到规模化交付快速找到主路径。
 
 ---
 
 ## 优先入口
 
 - [快速开始](quick-start.md)
+- [AI 工具快速开始](../quick-start-with-ai-tools.md)
 - [命令参考](../command-reference.md)
 - [常见问题](../faq.md)
 - [故障排除](../troubleshooting.md)
 
 ---
 
-## 交付主路径
+## 核心交付路径
 
 - [Spec 工作流](../spec-workflow.md)
 - [自动闭环指南](../autonomous-control-guide.md)
 - [多 Agent 协同指南](../multi-agent-coordination-guide.md)
-- [Spec 协作指南](../spec-collaboration-guide.md)
-- [Spec 锁机制指南](../spec-locking-guide.md)
+- [场景运行时指南](../scene-runtime-guide.md)
+- [Value 可观测指南](../value-observability-guide.md)
+- [本轮重构完成总结与下一轮路线图](refactor-completion-roadmap.md)
+
+---
+
+## 治理与发布
+
+- [Errorbook 注册表指南](../errorbook-registry.md)
+- [安全治理默认基线](../security-governance-default-baseline.md)
+- [文档治理](../document-governance.md)
+- [发布检查清单](../release-checklist.md)
+- [发布归档](../releases/README.md)
 
 ---
 
 ## 场景化能力与 Moqui
 
-- [场景运行时指南](../scene-runtime-guide.md)
 - [Moqui 模板核心库 Playbook](../moqui-template-core-library-playbook.md)
 - [Moqui 能力矩阵](../moqui-capability-matrix.md)
 - [Moqui 标准重建指南](../moqui-standard-rebuild-guide.md)
@@ -33,27 +44,12 @@
 
 ---
 
-## 治理、质量与发布
-
-- [文档治理](../document-governance.md)
-- [安全治理默认基线](../security-governance-default-baseline.md)
-- [Errorbook 注册表指南](../errorbook-registry.md)
-- [发布检查清单](release-checklist.md)
-- [发布归档](releases/README.md)
-
----
-
-## 平台管理与运维
+## 平台与集成
 
 - [环境管理指南](../environment-management-guide.md)
 - [多仓库管理指南](../multi-repo-management-guide.md)
 - [团队协作指南](../team-collaboration-guide.md)
 - [手动工作流指南](../manual-workflows-guide.md)
-
----
-
-## AI 工具集成
-
 - [Cursor 集成](tools/cursor-guide.md)
 - [Claude Code 集成](tools/claude-guide.md)
 - [Windsurf 集成](tools/windsurf-guide.md)
@@ -62,20 +58,21 @@
 
 ---
 
-## 补充阅读
+## Language
 
-- [Value 可观测指南](value-observability-guide.md)
-- [架构说明](../architecture.md)
-- [开发者指南](../developer-guide.md)
-- [社区入口](../community.md)
+- [English Docs Hub](../README.md)
 
 ---
 
-## Language
+## 社区
 
-- [English Docs Hub](../README.md)
+- [社区入口](../community.md)
+- [GitHub Discussions](https://github.com/heguangyong/scene-capability-engine/discussions)
+- [GitHub Issues](https://github.com/heguangyong/scene-capability-engine/issues)
 
 ---
 
-**版本**：3.3.26  
-**最后更新**：2026-03-02
+**版本**：3.6.34
+**最后更新**：2026-03-08
+
+

package/docs/zh/refactor-completion-roadmap.md

@@ -0,0 +1,116 @@
+# 本轮重构完成总结与下一轮路线图
+
+## 范围
+
+本文件用于记录 `3.6.33` 这一轮重构的完成状态，并明确下一阶段的工程方向。
+
+当前稳定提交：
+
+- `0c9594d` `refactor(auto): finalize close-loop governance split and docs refresh`
+- `0fb49b7` `refactor(handoff): extract capability matrix service`
+- `8ebc5bc` `release: 3.6.33`
+
+## 什么算完成
+
+这一轮重构之所以可以判定为完成，不是因为 `lib/commands/auto.js` 里一个大函数都不剩，而是因为最核心的自动交付主链已经不再以它为中心。
+
+本轮已完成下沉：
+
+- `lib/auto/close-loop-controller-service.js`
+- `lib/auto/close-loop-batch-service.js`
+- `lib/auto/close-loop-program-service.js`
+- `lib/auto/observability-service.js`
+- `lib/auto/program-summary.js`
+- `lib/auto/program-output.js`
+- `lib/auto/batch-output.js`
+- `lib/auto/program-governance-helpers.js`
+- `lib/auto/program-governance-loop-service.js`
+- `lib/auto/program-auto-remediation-service.js`
+- `lib/auto/output-writer.js`
+- `lib/auto/handoff-capability-matrix-service.js`
+
+本轮同步完成的收口工作：
+
+- README 与 docs hub 重组
+- governance summary 真实回归修复
+- governance weekly-ops session telemetry 修复
+- session stats `criteria.days` 字段修复
+
+## 架构变化
+
+在本轮之前：
+
+- `lib/commands/auto.js` 同时承担命令注册和大量主执行逻辑。
+- program / governance 行为一旦调整，回归风险会很高，因为职责耦合过重。
+
+在本轮之后：
+
+- `lib/commands/auto.js` 更接近命令层壳子与 wrapper。
+- 主要交付链路已经迁移到 `lib/auto/`。
+- `auto-handoff` 也已经拥有了第一个完整专题边界。
+
+这就是为什么即使 `auto.js` 仍然很大，这一轮也可以被定义为完成。
+
+## 为什么有些工作被明确延后
+
+不是 `auto.js` 里剩下的每个函数，都值得马上继续拆。
+
+本轮明确延后的内容：
+
+- 收益很低的 helper 搬运
+- 一旦切出去就容易引入回归的 `auto-handoff` 零碎微边界
+- 对长期维护性帮助不大的纯 cosmetic 收缩
+
+本轮执行标准是：
+
+- 保留能形成长期 service 边界的拆分
+- 当下一刀的收益低于回归风险时，立即停止
+
+## 剩余高价值方向
+
+下一轮真正值得继续做的，不再是 close-loop 主链，而是 `auto-handoff` 及少量发布治理支持域。
+
+剩余高价值主题：
+
+1. `auto-handoff` release evidence 子域
+2. `auto-handoff` release gate history 子域
+3. `auto-handoff` release notes / evidence review 渲染子域
+4. `auto-handoff` baseline / coverage snapshot 子域
+
+## 建议的下一轮
+
+下一轮建议明确命名为 `auto-handoff` 专题重构，而不是继续做泛化的 `auto.js` 清理。
+
+建议顺序：
+
+1. `release evidence` 子域
+2. `release gate history` 子域
+3. `release notes / evidence review` 渲染子域
+4. `baseline / coverage snapshot` 子域
+
+每个子域都沿用本轮的标准：
+
+- 一次只切一个完整边界
+- 命令行为保持不变
+- 新模块必须有单测
+- 通过关键 integration 回归后才保留
+
+## 验证基线
+
+本轮用于验收的最低基线：
+
+- `npx jest tests/unit/auto --runInBand`
+- `npx jest tests/unit/commands/auto.test.js --runInBand`
+- `npx jest tests/integration/auto-close-loop-cli.integration.test.js tests/integration/version-cli.integration.test.js --runInBand`
+- `npm run test:release`
+
+下一轮建议继续沿用这套基线。
+
+## 发布状态
+
+当前稳定版本：
+
+- version: `3.6.33`
+- tag: `v3.6.33`
+
+后续 `auto-handoff` 的继续演进，应以这个版本作为新的稳定基线。