@hongmaple0820/scale-engine 0.25.0 → 0.26.0

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)，看一个真实任务如何从需求到验证证据。
+

package/docs/start/workflow-upgrade.md

@@ -17,7 +17,7 @@ SCALE 把更新分成三层：
 | 层级 | 命令支持 | 默认行为 |
 | --- | --- | --- |
 | SCALE CLI | `npm install -g @hongmaple0820/scale-engine@latest` | 用户显式安装或升级 |
-| 生成的工作流文件 | `scale upgrade check/plan/apply/rollback` | 先安全检查和生成计划，只有 `--confirm` 才应用 |
+| 生成的工作流文件 | `scale upgrade check/plan/apply/rollback` | 先安全检查和生成计划；干净的受管文件可自动刷新，有本地改动则进入人工审阅 |
 | 项目级验证 | 仓库 `make` 目标和 `scripts/workflow/*` | 必须保留项目语义；SCALE 不猜业务路由、凭据和服务拓扑 |
 
 这意味着工作流适配不是 Codex-only。Codex 可以帮助审阅和处理 `manual-review`，但常规路径应该是命令驱动。
@@ -40,13 +40,14 @@ scale init --interactive
 ```bash
 scale init --governance-pack standard
 scale init --governance-pack project-scaffold
+scale init --governance-pack scale-engine-repo
 scale init --governance-pack moe-workspace
 scale init --governance-pack go-service-matrix
 scale init --governance-pack node-library
 scale init --governance-pack frontend-app
 ```
 
-不确定时先用 `standard`。仓库形态明确时再用更具体的 pack。
+不确定时先用 `standard`。仓库形态明确时再用更具体的 pack。`scale-engine-repo` 是 `scale-engine` 仓库自身的自托管 pack，不是普通业务仓库默认选项。
 
 ## 更新已有工作流
 
@@ -59,6 +60,13 @@ scale upgrade apply --dir . --confirm
 scale preflight --dir . --service all --preflight-profile quick
 ```
 
+默认输出是中文。需要英文命令提示或英文 HTML 计划时加 `--lang en`：
+
+```bash
+scale upgrade check --dir . --lang en
+scale upgrade plan --dir . --html --lang en
+```
+
 如果仓库已有本地封装，优先使用本地命令，因为它们编码了项目默认值：
 
 ```bash
@@ -80,11 +88,27 @@ scale upgrade rollback --dir .
 | --- | --- | --- |
 | clean | 生成的工作流集合和 lock 文件一致 | 运行项目级验证 |
 | missing | 生成文件缺失 | 通常可用 `apply --confirm` 恢复 |
-| outdated | SCALE 有更新的生成模板 | 审阅计划，确认安全后应用 |
+| updates-available | SCALE 版本、governance pack 或受管文件存在可应用更新 | 审阅计划，确认安全后应用 |
 | manual-review | 生成文件已有本地修改 | 检查 diff，不要自动覆盖 |
 
 `manual-review` 是有意设计。SCALE 不应该抹掉本地项目知识、服务命令或 Agent 规则。
 
+## 自动升级边界
+
+`scale upgrade apply --confirm` 现在覆盖三类安全场景：
+
+- 受管文件缺失：从当前 governance pack 恢复缺失文件。
+- SCALE CLI 版本变化：刷新 `.scale/governance.lock.json`，让项目记录当前 CLI 版本。
+- governance pack 版本变化：如果受管文件内容仍与 lock 哈希一致，自动刷新这些干净文件，让新模板、新门禁、新脚本和新文档入口落到旧项目。
+
+下面场景不会自动覆盖：
+
+- 文件相对 lock 已有本地改动。
+- 缺少 `.scale/governance.lock.json`，无法判断哪些文件由 SCALE 管理。
+- 第三方 skills、MCP、浏览器、桌面自动化或外部 CLI 需要新增、升级、执行安装脚本。
+
+这些情况会进入 `manual-review`，由维护者或 Agent 先看计划和 diff，再决定合并、保留本地改动，或重新初始化。
+
 ## 项目级适配
 
 生成文件更新后，再按真实仓库适配这些文件：
@@ -127,13 +151,13 @@ scale upgrade rollback --dir .
 
 ```makefile
 workflow-upgrade-check:
-	scale upgrade check --dir .
+	scale upgrade check --dir . --lang zh
 workflow-upgrade-plan:
-	scale upgrade plan --dir . --html
+	scale upgrade plan --dir . --html --lang zh
 workflow-upgrade-apply:
-	scale upgrade apply --dir . --confirm
+	scale upgrade apply --dir . --confirm --lang zh
 workflow-upgrade-rollback:
-	scale upgrade rollback --dir .
+	scale upgrade rollback --dir . --lang zh
 workflow-upgrade-verify:
 	scale preflight --dir . --service all --preflight-profile quick
 ```
@@ -145,6 +169,6 @@ workflow-upgrade-verify:
 - `scale --version` 输出预期版本。
 - `scale upgrade check --dir .` 没有非预期 drift。
 - 有变更时，`scale upgrade plan --dir . --html` 能生成可审阅计划。
-- `scale upgrade apply --dir . --confirm` 只在审阅计划后使用。
+- `scale upgrade apply --dir . --confirm` 只在审阅计划后使用；干净受管文件可自动刷新，本地改动必须人工审阅。
 - 项目级验证通过，或记录清楚已知失败。
 - `README.md`、`AGENTS.md`、`CLAUDE.md`、`docs/workflow/README.md` 指向同一组工作流命令。

package/docs/workflow/README.md

@@ -0,0 +1,67 @@
+# SCALE Engine 仓库工作流
+
+这里描述的是 `scale-engine` 仓库自身的工程化工作流，不是终端用户如何使用 `scale` CLI。
+
+## 入口
+
+- 新维护者先读 [GETTING_STARTED.md](../guides/GETTING_STARTED.md)
+- 日常开发读 [DEVELOPMENT_WORKFLOW.md](../guides/DEVELOPMENT_WORKFLOW.md)
+- 机器可读分支策略看 [../../.scale/workspace.json](../../.scale/workspace.json)
+
+## 最小命令面
+
+```bash
+make preflight
+make new-task NAME=workflow-adaptation LEVEL=M
+make plan NAME=workflow-adaptation LEVEL=M
+make explore FILES='AGENTS.md CLAUDE.md README.md package.json' MSG='main contradiction'
+make gate-workflow
+make gate-quality
+make verify PROFILE=default
+```
+
+PowerShell:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/verify.ps1 -Profile default
+```
+
+## 门禁说明
+
+| Gate | 作用 |
+| --- | --- |
+| G1 | 探索是否记录到状态文件，且至少读了 3 个文件 |
+| G2 | 计划是否包含边界、异常、回滚、现实校验 |
+| G3 | `src/` 行为改动是否伴随测试改动 |
+| G4 | workflow 脚本是否可解析 |
+| G5 | `lint + typecheck + test + build` 是否通过 |
+| G6 | 任务证据和 `git diff --check` 是否通过 |
+| G7 | 安全面是否通过 |
+| G8 | Markdown 与工作流文档是否符合基础卫生规则 |
+
+## 分支策略
+
+当前仓库采用 GitLab Flow 风格：
+
+```text
+feature/fix/docs/chore/codex -> dev -> master
+```
+
+约束：
+
+- `dev` 是集成分支。
+- `master` 是生产基线。
+- `release/*` 只在必须从生产基线隔离发版时使用。
+- `hotfix/*` 用于生产紧急修复，并要求回流 `dev`。
+
+## 升级入口
+
+如果要把仓库工作流继续升级到更新的 `scale-engine` 版本，先跑：
+
+```bash
+make bootstrap-scale
+make workflow-upgrade-check
+make workflow-upgrade-plan
+```
+
+先审计划，再决定是否 `make workflow-upgrade-apply`。