@hongmaple0820/scale-engine 0.24.0 → 0.26.0

package/docs/guides/DEVELOPMENT_WORKFLOW.md

@@ -0,0 +1,80 @@
+# SCALE Engine 开发工作流
+
+这份文档说明日常如何在 `scale-engine` 仓库里按最新工程化工作流工作。
+
+## 标准闭环
+
+```text
+探索 -> 规划 -> 执行 -> 验证 -> 沉淀
+```
+
+## 1. 探索
+
+目标：先弄清真实仓库状态，再动手。
+
+```bash
+make new-task NAME=task-slug LEVEL=M
+make plan NAME=task-slug LEVEL=M
+make explore FILES='AGENTS.md CLAUDE.md README.md package.json src/api/cli.ts' MSG='main contradiction'
+make gate-workflow
+```
+
+最低要求：
+
+- 至少读 3 个相关文件。
+- 写清主矛盾，而不是只列文件名。
+- 对不确定项明确标出，不靠猜。
+
+## 2. 规划
+
+在 `.planning/tasks/<task>/plan.md` 里至少补齐这些信息：
+
+- scope / boundary
+- acceptance criteria
+- exception / failure path
+- rollback / fallback
+- verification commands
+
+如果任务改动发布、权限、安全、凭据、npm 发版或破坏性行为，按 `CRITICAL` 处理。
+
+## 3. 执行
+
+原则：
+
+- 最小必要修改。
+- 优先复用现有脚本和 `npm` 命令，不再发明第二套命令。
+- 改 `src/` 行为时，原则上同步改 `tests/`，否则会被 G3 拦下。
+
+## 4. 验证
+
+推荐顺序：
+
+```bash
+make gate-quality
+make verify PROFILE=default
+git diff --check
+```
+
+其中：
+
+- `G4` 验证 workflow 脚本本身可解析。
+- `G5` 运行 `lint + typecheck + test + build`。
+- `G6` 检查任务证据和 diff hygiene。
+- `G7` 是安全面，默认走 `npm audit --audit-level=high`。
+- `G8` 检查 Markdown 与工作流文档的基础卫生。
+
+## 5. 沉淀
+
+应该留下：
+
+- `verification.md`
+- `review.md`
+- `summary.md`
+- 必要的长期规则文档更新
+
+不应该留下：
+
+- 临时日志
+- worktree 状态
+- 截图、trace、缓存
+- 只对一次任务有意义的中间文件

package/docs/guides/GETTING_STARTED.md

@@ -0,0 +1,50 @@
+# SCALE Engine 仓库上手
+
+这份文档面向要开发 `scale-engine` 仓库本身的人，不是面向安装 CLI 的最终用户。
+
+## 15 分钟路径
+
+1. 先读根目录 [README.md](../../README.md)。
+2. 跑本仓库 workflow 预检：
+
+```bash
+make preflight
+```
+
+3. 看当前可用验证面：
+
+```bash
+make verify-list
+```
+
+4. 建一个任务骨架并记录探索：
+
+```bash
+make new-task NAME=example LEVEL=M
+make plan NAME=example LEVEL=M
+make explore FILES='AGENTS.md CLAUDE.md README.md package.json' MSG='main contradiction'
+make gate-workflow
+```
+
+5. 做完改动后跑质量面：
+
+```bash
+make gate-quality
+make verify PROFILE=default
+git diff --check
+```
+
+## 你应该看到什么
+
+- `.scale/workspace.json` 明确了 `dev -> master` 的仓库分支策略。
+- `.agent/project.json` 定义了本仓库的 Node/TypeScript 验证命令。
+- `scripts/gates/*` 和 `scripts/workflow/*` 不是说明文档，而是可执行入口。
+- `.planning/tasks/<date>-<task>/` 用于任务级证据，不再把临时过程写进 `docs/`。
+
+## 常见误区
+
+- `make gate-workflow` 通过，不代表代码质量通过。
+- `make gate-quality` 通过，也不代表你已经记录了风险、回滚和未验证项。
+- `G8` 会检查改动过的 Markdown 和工作流文档卫生，不替代业务验证。
+- `--dry-run` 只能证明入口存在，不能写成“测试通过”。
+- 不要把 `.claude/worktrees/`、`.agent/state/`、日志或截图提交进仓库。

package/docs/start/README.md

@@ -1,72 +1,78 @@
-# SCALE Engine 入门路径
-
-这个目录面向新用户。目标是先跑通一条最小路径，再理解完整体系，不要求一开始掌握所有命令。
-
-## 推荐阅读顺序
-
-1. [3 分钟快速开始](quickstart.md)
-   从空目录初始化治理工作流，看到 `.scale`、模板、验证 profile 和状态输出。
-
-2. [Artifact 生命周期](artifact-lifecycle.md)
-   完整走一遍 Need → Spec → Plan → Task → Change → Evidence → Release，理解 FSM 和 Guard 如何用物理约束替代提示词建议。
-
-3. [官方 Demo Walkthrough](agent-governance-demo.md)
-   用一个 OAuth state 加固任务演示：上下文对齐、诊断计划、TDD 切片、HTML artifact、资源治理和工程规范扫描。
-
-4. 回到根目录 [README](../../README.md)
-   理解 SCALE Engine 的核心能力和 governance pack 选择。
-
-4. [升级管理](../UPGRADE_MANAGEMENT.md)
-   理解工作流更新、第三方 skills/MCP/CLI 更新时如何先检查、生成计划、避免覆盖本地改动。
-
-5. 查看 [文档地图](../README.md)
-   区分哪些文档是用户指南、哪些是参考资料、哪些是历史规划和过程记录。
-
-## 15 分钟学习路径
-
-```bash
-npm install -g @hongmaple0820/scale-engine
-scale --version
-mkdir scale-demo && cd scale-demo
-scale init --governance-pack standard
-scale preflight --preflight-profile quick
-scale status
-```
-
-跑完后先回答三个问题：
-
-- `.scale/verification.json` 里定义了哪些验证 profile？
-- `docs/workflow/templates/` 里有哪些任务产物模板？
-- `scale status` 建议下一步做什么？
-
-如果这三个问题答不上来，先不要继续看高级命令。
-
-## 你应该先看到什么
-
-跑完 quickstart 后，至少应该能看到：
-
-- `scale preflight --preflight-profile quick` 可以执行。
-- `scale status` 能告诉你当前项目下一步该做什么。
-- `.scale/verification.json` 存在，并描述本地验证 profile。
-- `docs/workflow/templates/` 存在，并包含 Mini-PRD、plan、verification、review、summary 等模板。
-- `scale artifact render` 可以把任务 Markdown 证据渲染成 HTML。
-
-如果其中任何一步失败，先看命令输出，不要假设是环境问题。SCALE 的原则是：没有真实命令结果，就不声称通过。
-
-## 场景选择
-
-| 场景 | 推荐入口 |
-| --- | --- |
-| 第一次试用 | [3 分钟快速开始](quickstart.md) |
-| 想看 Agent 治理闭环 | [官方 Demo Walkthrough](agent-governance-demo.md) |
-| 前端项目 | `scale init --governance-pack frontend-app` |
-| Node/TypeScript 包 | `scale init --governance-pack node-library` |
-| Go 多服务后端 | `scale init --governance-pack go-service-matrix` |
-| 多仓库/MOE 工作区 | `scale init --governance-pack moe-workspace` |
-| 文档、报告、截图、脚本混乱 | `scale init --governance-pack resource-governance` |
-| 工作流或第三方能力要升级 | `scale upgrade check && scale upgrade plan --html` |
-
-
-## 工作流升级短路径
-
-已有项目先看 [SCALE workflow upgrade guide](workflow-upgrade.md)。它说明 `scale init --interactive`、`scale upgrade check/plan/apply/rollback`、仓库本地 `make workflow-upgrade-*` 入口，以及生成文件更新和项目级验证之间的边界。
+# SCALE Engine 入门路径
+
+这个目录面向新用户。目标是先跑通一条最小路径，再理解完整体系，不要求一开始掌握所有命令。
+
+## 推荐阅读顺序
+
+1. [3 分钟快速开始](quickstart.md)
+   从空目录初始化治理工作流，看到 `.scale`、模板、验证 profile 和状态输出。
+
+2. [Artifact 生命周期](artifact-lifecycle.md)
+   完整走一遍 Need → Spec → Plan → Task → Change → Evidence → Release，理解 FSM 和 Guard 如何用物理约束替代提示词建议。
+
+3. [官方 Demo Walkthrough](agent-governance-demo.md)
+   用一个 OAuth state 加固任务演示：上下文对齐、诊断计划、TDD 切片、HTML artifact、资源治理和工程规范扫描。
+
+4. 回到根目录 [README](../../README.md)
+   理解 SCALE Engine 的核心能力和 governance pack 选择。
+
+4. [工作流升级指南](workflow-upgrade.md)
+   理解工作流更新、第三方 skills/MCP/CLI 更新时如何先检查、生成计划、自动刷新干净受管文件，并避免覆盖本地改动。
+
+5. 查看 [文档地图](../README.md)
+   区分哪些文档是用户指南、哪些是参考资料、哪些是历史规划和过程记录。
+
+如果你要开发的是 `scale-engine` 仓库本身，而不是把 SCALE 接入别的项目，改看：
+
+- [../guides/GETTING_STARTED.md](../guides/GETTING_STARTED.md)
+- [../guides/DEVELOPMENT_WORKFLOW.md](../guides/DEVELOPMENT_WORKFLOW.md)
+- [../workflow/README.md](../workflow/README.md)
+
+## 15 分钟学习路径
+
+```bash
+npm install -g @hongmaple0820/scale-engine
+scale --version
+mkdir scale-demo && cd scale-demo
+scale init --governance-pack standard
+scale preflight --preflight-profile quick
+scale status
+```
+
+跑完后先回答三个问题：
+
+- `.scale/verification.json` 里定义了哪些验证 profile？
+- `docs/workflow/templates/` 里有哪些任务产物模板？
+- `scale status` 建议下一步做什么？
+
+如果这三个问题答不上来，先不要继续看高级命令。
+
+## 你应该先看到什么
+
+跑完 quickstart 后，至少应该能看到：
+
+- `scale preflight --preflight-profile quick` 可以执行。
+- `scale status` 能告诉你当前项目下一步该做什么。
+- `.scale/verification.json` 存在，并描述本地验证 profile。
+- `docs/workflow/templates/` 存在，并包含 Mini-PRD、plan、verification、review、summary 等模板。
+- `scale artifact render` 可以把任务 Markdown 证据渲染成 HTML。
+
+如果其中任何一步失败，先看命令输出，不要假设是环境问题。SCALE 的原则是：没有真实命令结果，就不声称通过。
+
+## 场景选择
+
+| 场景 | 推荐入口 |
+| --- | --- |
+| 第一次试用 | [3 分钟快速开始](quickstart.md) |
+| 想看 Agent 治理闭环 | [官方 Demo Walkthrough](agent-governance-demo.md) |
+| 前端项目 | `scale init --governance-pack frontend-app` |
+| Node/TypeScript 包 | `scale init --governance-pack node-library` |
+| Go 多服务后端 | `scale init --governance-pack go-service-matrix` |
+| 多仓库/MOE 工作区 | `scale init --governance-pack moe-workspace` |
+| 文档、报告、截图、脚本混乱 | `scale init --governance-pack resource-governance` |
+| 工作流或第三方能力要升级 | `scale upgrade check --lang zh && scale upgrade plan --html --lang zh` |
+
+
+## 工作流升级短路径
+
+已有项目先看 [SCALE 工作流升级指南](workflow-upgrade.md)。它说明 `scale init --interactive`、`scale upgrade check/plan/apply/rollback`、`--lang zh/en` 双语输出、仓库本地 `make workflow-upgrade-*` 入口，以及生成文件更新和项目级验证之间的边界。

package/docs/start/agent-governance-demo.md

@@ -1,107 +1,107 @@
-# 官方 Demo Walkthrough：让 Agent 不再跳过工程纪律
-
-这个 demo 用一个很小的 OAuth state 校验任务，演示 SCALE 如何把“应该做”的工程动作变成可检查证据。
-
-## Demo 目标
-
-我们要实现并验证一个安全敏感行为：
-
-> 当 OAuth callback 的 state 过期、被消费或不匹配时，系统必须拒绝请求，而不是返回模糊 500。
-
-SCALE 关注的不是这段业务逻辑有多复杂，而是 Agent 是否：
-
-- 先澄清上下文和验收标准。
-- 先诊断失败模式，不盲修。
-- 写出可检查的 TDD 切片。
-- 运行验证命令并留下证据。
-- 生成可评审的 Markdown 和 HTML artifact。
-- 不把临时报告、截图、脚本、敏感信息乱提交。
-
-## 1. 准备 demo 项目
-
-从仓库复制官方 demo：
-
-```powershell
-Copy-Item -Recurse E:\project\scale-engine\examples\demo-projects\agent-governance-demo .\scale-agent-demo
-Set-Location .\scale-agent-demo
-npm install
-npm test
-```
-
-macOS/Linux 可以用：
-
-```bash
-cp -R /path/to/scale-engine/examples/demo-projects/agent-governance-demo ./scale-agent-demo
-cd scale-agent-demo
-npm install
-npm test
-```
-
-## 2. 安装治理工作流
-
-```bash
-scale init --governance-pack node-library
-scale preflight --preflight-profile quick
-scale status
-```
-
-你应该看到 SCALE 生成 `.scale`、`docs/workflow/templates` 和项目治理规则。
-
-## 3. 建立任务证据
-
-```bash
-scale context init --name "Agent Governance Demo"
-scale runtime start --session-id 2026-05-18-oauth-state --task-id 2026-05-18-oauth-state --level M --agent codex
-scale context grill --task-id 2026-05-18-oauth-state --task "加固 OAuth state 校验"
-scale diagnose plan --task-id 2026-05-18-oauth-state --symptom "OAuth callback 在 state 过期或不匹配时行为不明确"
-scale tdd slice --task-id 2026-05-18-oauth-state --behavior "拒绝过期、已消费或不匹配的 OAuth state" --public-interface "verifyOAuthState(record, providedState, now)" --failing-test "expired, consumed, mismatched state should return ok=false" --test-file tests/oauth-state.test.ts --impl-files src/oauth-state.ts
-```
-
-这一步会在任务目录中沉淀探索、诊断和 TDD 证据。
-
-## 4. 运行真实验证
-
-```bash
-npm test
-scale standards scan --dir .
-scale assets scan --dir .
-scale runtime record --title "demo business tests" --kind command --status passed --command "npm test" --exit-code 0 --summary "official demo OAuth state tests passed"
-scale runtime final-check --task-id 2026-05-18-oauth-state --session-id 2026-05-18-oauth-state --level M
-```
-
-验收标准：
-
-- `npm test` 必须真实通过。
-- `standards scan` 不能发现阻断级别问题。
-- `assets scan` 应能识别长期维护文档、任务证据和生成产物分类。
-- `runtime final-check` 必须确认当前任务范围内有通过证据，且没有失败证据。
-
-## 5. 生成记忆候选和 HTML artifact
-
-```bash
-scale memory pack --task-id 2026-05-18-oauth-state --session-id 2026-05-18-oauth-state --task "加固 OAuth state 校验" --level M --budget 4000
-scale memory settle --task-id 2026-05-18-oauth-state --session-id 2026-05-18-oauth-state --task "加固 OAuth state 校验" --level M
-```
-
-`memory pack` 用于恢复上下文，`memory settle` 用于把本次真实验证沉淀成可审查学习候选。候选仍需要人审后才能进入长期知识库或工程规范。
-
-```bash
-scale artifact render --task-id 2026-05-18-oauth-state --artifact-dir docs/worklog/tasks/2026-05-18-oauth-state
-scale artifact doctor --artifact-dir docs/worklog/tasks/2026-05-18-oauth-state
-scale artifact open --task-id 2026-05-18-oauth-state --artifact-dir docs/worklog/tasks/2026-05-18-oauth-state
-```
-
-HTML artifact 的价值是让人类更快评审 Agent 的思考、证据和风险。Markdown 仍然是源文件，HTML 是交付视图。
-
-## 6. 对比没有 SCALE 的情况
-
-没有 SCALE 时，Agent 很容易出现这些行为：
-
-- 直接改实现，不先说明验收标准。
-- 修了 happy path，却漏掉过期、已消费、不匹配等异常路径。
-- 说“测试通过”，但没有命令输出。
-- 写了临时脚本、截图、报告，却不知道哪些应该提交。
-- 发版前没有 review evidence 和风险记录。
-
-有 SCALE 后，这些行为会被命令、模板、门禁和证据文件显式化。它不能替代人类判断，但能让 Agent 的工作不再靠口头保证。
-
+# 官方 Demo Walkthrough：让 Agent 不再跳过工程纪律
+
+这个 demo 用一个很小的 OAuth state 校验任务，演示 SCALE 如何把“应该做”的工程动作变成可检查证据。
+
+## Demo 目标
+
+我们要实现并验证一个安全敏感行为：
+
+> 当 OAuth callback 的 state 过期、被消费或不匹配时，系统必须拒绝请求，而不是返回模糊 500。
+
+SCALE 关注的不是这段业务逻辑有多复杂，而是 Agent 是否：
+
+- 先澄清上下文和验收标准。
+- 先诊断失败模式，不盲修。
+- 写出可检查的 TDD 切片。
+- 运行验证命令并留下证据。
+- 生成可评审的 Markdown 和 HTML artifact。
+- 不把临时报告、截图、脚本、敏感信息乱提交。
+
+## 1. 准备 demo 项目
+
+从仓库复制官方 demo：
+
+```powershell
+Copy-Item -Recurse E:\project\scale-engine\examples\demo-projects\agent-governance-demo .\scale-agent-demo
+Set-Location .\scale-agent-demo
+npm install
+npm test
+```
+
+macOS/Linux 可以用：
+
+```bash
+cp -R /path/to/scale-engine/examples/demo-projects/agent-governance-demo ./scale-agent-demo
+cd scale-agent-demo
+npm install
+npm test
+```
+
+## 2. 安装治理工作流
+
+```bash
+scale init --governance-pack node-library
+scale preflight --preflight-profile quick
+scale status
+```
+
+你应该看到 SCALE 生成 `.scale`、`docs/workflow/templates` 和项目治理规则。
+
+## 3. 建立任务证据
+
+```bash
+scale context init --name "Agent Governance Demo"
+scale runtime start --session-id 2026-05-18-oauth-state --task-id 2026-05-18-oauth-state --level M --agent codex
+scale context grill --task-id 2026-05-18-oauth-state --task "加固 OAuth state 校验"
+scale diagnose plan --task-id 2026-05-18-oauth-state --symptom "OAuth callback 在 state 过期或不匹配时行为不明确"
+scale tdd slice --task-id 2026-05-18-oauth-state --behavior "拒绝过期、已消费或不匹配的 OAuth state" --public-interface "verifyOAuthState(record, providedState, now)" --failing-test "expired, consumed, mismatched state should return ok=false" --test-file tests/oauth-state.test.ts --impl-files src/oauth-state.ts
+```
+
+这一步会在任务目录中沉淀探索、诊断和 TDD 证据。
+
+## 4. 运行真实验证
+
+```bash
+npm test
+scale standards scan --dir .
+scale assets scan --dir .
+scale runtime record --title "demo business tests" --kind command --status passed --command "npm test" --exit-code 0 --summary "official demo OAuth state tests passed"
+scale runtime final-check --task-id 2026-05-18-oauth-state --session-id 2026-05-18-oauth-state --level M
+```
+
+验收标准：
+
+- `npm test` 必须真实通过。
+- `standards scan` 不能发现阻断级别问题。
+- `assets scan` 应能识别长期维护文档、任务证据和生成产物分类。
+- `runtime final-check` 必须确认当前任务范围内有通过证据，且没有失败证据。
+
+## 5. 生成记忆候选和 HTML artifact
+
+```bash
+scale memory pack --task-id 2026-05-18-oauth-state --session-id 2026-05-18-oauth-state --task "加固 OAuth state 校验" --level M --budget 4000
+scale memory settle --task-id 2026-05-18-oauth-state --session-id 2026-05-18-oauth-state --task "加固 OAuth state 校验" --level M
+```
+
+`memory pack` 用于恢复上下文，`memory settle` 用于把本次真实验证沉淀成可审查学习候选。候选仍需要人审后才能进入长期知识库或工程规范。
+
+```bash
+scale artifact render --task-id 2026-05-18-oauth-state --artifact-dir docs/worklog/tasks/2026-05-18-oauth-state
+scale artifact doctor --artifact-dir docs/worklog/tasks/2026-05-18-oauth-state
+scale artifact open --task-id 2026-05-18-oauth-state --artifact-dir docs/worklog/tasks/2026-05-18-oauth-state
+```
+
+HTML artifact 的价值是让人类更快评审 Agent 的思考、证据和风险。Markdown 仍然是源文件，HTML 是交付视图。
+
+## 6. 对比没有 SCALE 的情况
+
+没有 SCALE 时，Agent 很容易出现这些行为：
+
+- 直接改实现，不先说明验收标准。
+- 修了 happy path，却漏掉过期、已消费、不匹配等异常路径。
+- 说“测试通过”，但没有命令输出。
+- 写了临时脚本、截图、报告，却不知道哪些应该提交。
+- 发版前没有 review evidence 和风险记录。
+
+有 SCALE 后，这些行为会被命令、模板、门禁和证据文件显式化。它不能替代人类判断，但能让 Agent 的工作不再靠口头保证。
+