@hongmaple0820/scale-engine 0.25.0 → 0.27.0

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 的工作不再靠口头保证。
+

package/docs/start/quickstart.md

@@ -1,127 +1,137 @@
-# 3 分钟快速开始
-
-目标：在一个空目录中安装 SCALE 治理工作流，并看到可验证的项目产物。
-
-## 前置条件
-
-- Node.js 20 或更高版本。
-- 已安装 npm。
-- Windows PowerShell、Git Bash、macOS/Linux shell 都可以执行。
-
-## 1. 安装 CLI
-
-```bash
-npm install -g @hongmaple0820/scale-engine
-scale --version
-```
-
-如果你在开发 `scale-engine` 本仓库，也可以用本地构建后的命令：
-
-```bash
-node E:/project/scale-engine/dist/api/cli.js --help
-```
-
-## 2. 初始化一个空项目
-
-```bash
-mkdir scale-demo
-cd scale-demo
-scale init --governance-pack standard
-```
-
-这一步会生成：
-
-```text
-.scale/
-docs/
-scripts/
-AGENTS.md 或对应 Agent 入口文档
-```
-
-重点看这些文件：
-
-| 文件 | 用途 |
-| --- | --- |
-| `.scale/verification.json` | 本地验证 profile 和服务矩阵 |
-| `.scale/skills.json` | Agent 应该如何选择 skills，以及哪些需要证据 |
-| `.scale/tools.json` | CLI、MCP、浏览器、桌面自动化等工具使用策略 |
-| `.scale/resource-policy.json` | 文档、报告、截图、脚本、临时产物的生命周期规则 |
-| `.scale/engineering-standards.json` | 日志、安全、ORM、框架、测试、部署等工程规范 |
-| `docs/workflow/templates/` | M/L 任务使用的标准 artifact 模板 |
-
-## 3. 跑第一轮本地检查
-
-```bash
-scale preflight --preflight-profile quick
-scale status
-scale assets scan --dir .
-scale standards scan --dir .
-scale runtime doctor --level S
-```
-
-预期效果：
-
-- `preflight` 能说明当前治理文件是否完整。
-- `status` 会告诉 Agent 下一步应该做什么。
-- `assets scan` 会把文档、模板、脚本、报告等资源分类。
-- `standards scan` 会扫描日志噪音、敏感信息、危险输入、测试和架构风险。
-- `runtime doctor` 会检查本地运行时证据目录和最终交付证据状态。
-
-## 4. 建立第一个任务上下文
-
-```bash
-scale context init --name "Scale Demo"
-scale runtime start --session-id 2026-05-18-oauth-hardening --task-id 2026-05-18-oauth-hardening --level M --agent codex
-scale context grill --task-id 2026-05-18-oauth-hardening --task "加固 OAuth callback"
-scale diagnose plan --task-id 2026-05-18-oauth-hardening --symptom "callback 在 state 过期时返回 500"
-scale tdd slice --task-id 2026-05-18-oauth-hardening --behavior "拒绝过期 OAuth state" --public-interface "GET /oauth/callback" --failing-test "expired state returns 401" --test-file tests/oauth.test.ts --impl-files src/oauth.ts
-```
-
-这些命令的目的不是替代人类判断，而是把 Agent 必须做的思考显式记录下来：
-
-- `context grill`：逼 Agent 先澄清上下文、成功标准和风险。
-- `diagnose plan`：遇到问题先诊断，不允许盲修。
-- `tdd slice`：把行为、公共接口、失败测试和实现文件绑定成一个可检查切片。
-- `runtime start`：建立会话 ledger，后续命令、工具和验证证据可以绑定到同一个任务。
-
-完成真实验证后记录运行时证据：
-
-```bash
-scale runtime record --title "quick preflight" --kind command --status passed --command "scale preflight --preflight-profile quick" --exit-code 0 --summary "quick preflight passed"
-scale runtime final-check --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --level M
-scale memory pack --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --task "继续加固 OAuth callback" --level M --budget 4000
-scale memory settle --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --task "继续加固 OAuth callback" --level M
-```
-
-`memory pack` 用来恢复上下文，`memory settle` 用来在任务结束后生成学习候选。候选位于 `.scale/memory/learning-candidates/`，默认本地保留，确认稳定后再人工提升到知识库、规范或模块文档。
-
-## 5. 生成 HTML 交付视图
-
-```bash
-scale artifact render --task-id 2026-05-18-oauth-hardening --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
-scale artifact doctor --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
-scale artifact open --task-id 2026-05-18-oauth-hardening --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
-```
-
-规则：
-
-- Markdown 是长期维护源文件。
-- HTML 是给评审、对比、状态汇报、交付和发版使用的可视化产物。
-- `artifact doctor` 会检查 HTML 是否可追溯、是否引用远程资源、是否可能包含敏感信息。
-
-## 6. 下一步
-
-如果你只是试用，到这里已经能看到 SCALE 的价值：它把 Agent 的工作过程变成了可以审计的证据链。
-
-如果你要接入真实项目，按项目类型选择 governance pack：
-
-```bash
-scale init --governance-pack node-library
-scale init --governance-pack frontend-app
-scale init --governance-pack go-service-matrix
-scale init --governance-pack moe-workspace
-scale init --governance-pack resource-governance
-```
-
-继续阅读 [官方 Demo Walkthrough](agent-governance-demo.md)，看一个真实任务如何从需求到验证证据。
-
+# 3 分钟快速开始
+
+目标：在一个空目录中安装 SCALE 治理工作流，并看到可验证的项目产物。
+
+## 前置条件
+
+- Node.js 20 或更高版本。
+- 已安装 npm。
+- Windows PowerShell、Git Bash、macOS/Linux shell 都可以执行。
+
+## 1. 安装 CLI
+
+```bash
+npm install -g @hongmaple0820/scale-engine
+scale --version
+```
+
+如果你在开发 `scale-engine` 本仓库，也可以用本地构建后的命令：
+
+```bash
+node E:/project/scale-engine/dist/api/cli.js --help
+```
+
+## 2. 初始化一个空项目
+
+```bash
+mkdir scale-demo
+cd scale-demo
+scale init --governance-pack standard
+```
+
+这一步会生成：
+
+```text
+.scale/
+docs/
+scripts/
+AGENTS.md 或对应 Agent 入口文档
+```
+
+重点看这些文件：
+
+| 文件 | 用途 |
+| --- | --- |
+| `.scale/verification.json` | 本地验证 profile 和服务矩阵 |
+| `.scale/skills.json` | Agent 应该如何选择 skills，以及哪些需要证据 |
+| `.scale/tools.json` | CLI、MCP、浏览器、桌面自动化等工具使用策略 |
+| `.scale/resource-policy.json` | 文档、报告、截图、脚本、临时产物的生命周期规则 |
+| `.scale/engineering-standards.json` | 日志、安全、ORM、框架、测试、部署等工程规范 |
+| `docs/workflow/templates/` | M/L 任务使用的标准 artifact 模板 |
+
+## 3. 跑第一轮本地检查
+
+```bash
+scale preflight --preflight-profile quick
+scale status
+scale assets scan --dir .
+scale standards scan --dir .
+scale runtime doctor --level S
+```
+
+预期效果：
+
+- `preflight` 能说明当前治理文件是否完整。
+- `status` 会告诉 Agent 下一步应该做什么。
+- `assets scan` 会把文档、模板、脚本、报告等资源分类。
+- `standards scan` 会扫描日志噪音、敏感信息、危险输入、测试和架构风险。
+- `runtime doctor` 会检查本地运行时证据目录和最终交付证据状态。
+
+## 4. 建立第一个任务上下文
+
+```bash
+scale context init --name "Scale Demo"
+scale runtime start --session-id 2026-05-18-oauth-hardening --task-id 2026-05-18-oauth-hardening --level M --agent codex
+scale context grill --task-id 2026-05-18-oauth-hardening --task "加固 OAuth callback"
+scale diagnose plan --task-id 2026-05-18-oauth-hardening --symptom "callback 在 state 过期时返回 500"
+scale tdd slice --task-id 2026-05-18-oauth-hardening --behavior "拒绝过期 OAuth state" --public-interface "GET /oauth/callback" --failing-test "expired state returns 401" --test-file tests/oauth.test.ts --impl-files src/oauth.ts
+```
+
+这些命令的目的不是替代人类判断，而是把 Agent 必须做的思考显式记录下来：
+
+- `context grill`：逼 Agent 先澄清上下文、成功标准和风险。
+- `diagnose plan`：遇到问题先诊断，不允许盲修。
+- `tdd slice`：把行为、公共接口、失败测试和实现文件绑定成一个可检查切片。
+- `runtime start`：建立会话 ledger，后续命令、工具和验证证据可以绑定到同一个任务。
+
+完成真实验证后记录运行时证据：
+
+```bash
+scale runtime record --title "quick preflight" --kind command --status passed --command "scale preflight --preflight-profile quick" --exit-code 0 --summary "quick preflight passed"
+scale runtime final-check --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --level M
+scale memory pack --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --task "继续加固 OAuth callback" --level M --budget 4000
+scale memory settle --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --task "继续加固 OAuth callback" --level M
+```
+
+`memory pack` 用来恢复上下文，`memory settle` 用来在任务结束后生成学习候选。候选位于 `.scale/memory/learning-candidates/`，默认本地保留，确认稳定后再人工提升到知识库、规范或模块文档。
+
+## 5. 生成 HTML 交付视图
+
+```bash
+scale artifact render --task-id 2026-05-18-oauth-hardening --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
+scale artifact doctor --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
+scale artifact open --task-id 2026-05-18-oauth-hardening --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
+```
+
+规则：
+
+- Markdown 是长期维护源文件。
+- HTML 是给评审、对比、状态汇报、交付和发版使用的可视化产物。
+- `artifact doctor` 会检查 HTML 是否可追溯、是否引用远程资源、是否可能包含敏感信息。
+
+## 6. 下一步
+
+如果你只是试用，到这里已经能看到 SCALE 的价值：它把 Agent 的工作过程变成了可以审计的证据链。
+
+如果你要接入真实项目，按项目类型选择 governance pack：
+
+```bash
+scale init --governance-pack node-library
+scale init --governance-pack frontend-app
+scale init --governance-pack go-service-matrix
+scale init --governance-pack moe-workspace
+scale init --governance-pack resource-governance
+```
+
+已有项目升级工作流时不要盲目重跑 `scale init`。先走受保护的升级链路：
+
+```bash
+scale upgrade check --dir . --lang zh
+scale upgrade plan --dir . --html --lang zh
+scale upgrade apply --dir . --confirm --lang zh
+```
+
+需要英文输出时把 `--lang zh` 换成 `--lang en`。干净的 SCALE 受管文件可以自动刷新；已有本地改动的文件会进入人工审阅，不会被自动覆盖。
+
+继续阅读 [官方 Demo Walkthrough](agent-governance-demo.md)，看一个真实任务如何从需求到验证证据。
+