@hongmaple0820/scale-engine 0.25.0 → 0.26.0

package/docs/WORKFLOW_EVAL.md

@@ -1,151 +1,151 @@
-# Workflow Eval Harness
-
-Status: implemented baseline
-Since: v0.22 development branch
-
-Workflow Eval Harness 用来证明工作流是否真的提升了 Agent 的工程交付质量，而不是只依赖主观感觉。它会运行轻量 eval suite，记录 pass@k、修复迭代、工具调用、token 估算、人类纠偏次数，并在失败时保留 Failure Replay。
-
-## Commands
-
-初始化默认基线套件：
-
-```bash
-scale eval init
-scale eval init --suite workflow-baseline --json
-```
-
-运行套件：
-
-```bash
-scale eval run --suite workflow-baseline
-scale eval run --suite workflow-baseline --json
-```
-
-对比两次运行：
-
-```bash
-scale eval compare --baseline <run-id> --candidate <run-id>
-scale eval compare --baseline <run-id> --candidate <run-id> --json
-```
-
-生成 Markdown 报告：
-
-```bash
-scale eval report --run <run-id>
-scale eval report --run <run-id> --output docs/worklog/eval-report.md
-```
-
-查看和提升失败重放：
-
-```bash
-scale eval failures --since 30d
-scale eval replay <failure-id>
-scale eval replay --task-id <task-id>
-scale eval promote-failure <failure-id>
-```
-
-## Failure Replay To Memory
-
-Failure Replay is local eval evidence first. When a failure pattern is useful for future work, ingest it into Memory Brain as an `incident` candidate:
-
-```bash
-scale memory ingest --from failure --failure-id <failure-id>
-scale memory query "missing verification evidence"
-scale memory promote <memory-node-id>
-```
-
-This does not auto-change standards or hooks. It only makes the failure queryable and evidence-backed so repeated mistakes can be promoted deliberately after review.
-
-## Storage
-
-```text
-.scale/evals/
-├── suites/
-├── runs/
-├── failures/
-└── improvements/
-```
-
-These files are local runtime evidence by default. Commit only curated summaries or intentional benchmark fixtures.
-
-## Suite Shape
-
-```json
-{
-  "version": "1.0",
-  "id": "workflow-baseline",
-  "name": "SCALE workflow baseline",
-  "cases": [
-    {
-      "id": "governance-command-smoke",
-      "type": "bugfix",
-      "title": "Command evidence smoke",
-      "task": "Verify that a local command can produce concrete eval evidence.",
-      "phase": "verify",
-      "successCriteria": ["command exits 0"],
-      "attempts": [
-        {
-          "id": "attempt-1",
-          "command": "node -e \"console.log('scale-eval-ok')\"",
-          "expectedExitCode": 0,
-          "outputContains": "scale-eval-ok"
-        }
-      ]
-    }
-  ]
-}
-```
-
-## Metrics
-
-| Metric | Meaning |
-| --- | --- |
-| `passAt1Rate` | 一次完整尝试就通过的比例 |
-| `passAt3Rate` | 三次以内通过的比例 |
-| `averageFixIterations` | 首次失败后的平均修复循环 |
-| `totalToolCalls` | eval attempts 数量，可近似衡量工具调用成本 |
-| `estimatedTokens` | task 与输出摘要的估算 token 成本 |
-| `humanCorrections` | 人类纠偏次数 |
-| `failureReplayCount` | 失败重放记录数量 |
-
-## Failure Replay
-
-失败不只记录最终失败状态，还会保存：
-
-- task and success criteria
-- phase
-- wrong turn
-- evidence
-- correction
-- prevention
-- replay command
-- redaction status
-
-Failure category 当前包括：
-
-- `wrong-exploration-path`
-- `hallucinated-project-fact`
-- `missing-codegraph-or-graph-fallback`
-- `over-broad-context-load`
-- `bad-skill-recommendation`
-- `missing-verification-evidence`
-- `failed-security-or-resource-gate`
-- `human-correction-after-agent-confidence`
-- `command-failure`
-- `unknown`
-
-`scale eval promote-failure` 会把失败重放提升为 improvement candidate，但不会自动修改项目规范。是否进入长期标准仍需要人工或后续 review 确认。
-
-## Governance Use
-
-- v0.22 的默认 suite 是轻量 smoke baseline，用来验证 eval 管线可运行。
-- 真实项目应逐步增加 bugfix、feature、security、frontend、release、resource 类型案例。
-- Failure Replay 应与 Resource Governance 配合：默认本地保留，只有总结、基准或明确要长期维护的案例才提交。
-- Workflow Eval 的数据可以进入后续 Governance ROI，用来判断某个治理模块是否真的减少 rework、tool calls、token 或人类纠偏。
-
-## Policy
-
-- 不允许用 eval 通过率替代真实项目验证。
-- 失败记录中的命令输出会做基础脱敏，但仍应避免把敏感原始日志写入 suite。
-- 低成本 smoke suite 可以频繁运行；重型项目 suite 应按需运行。
-- 没有 eval 证据时，不应宣称工作流能力已经提升。
+# Workflow Eval Harness
+
+Status: implemented baseline
+Since: v0.22 development branch
+
+Workflow Eval Harness 用来证明工作流是否真的提升了 Agent 的工程交付质量，而不是只依赖主观感觉。它会运行轻量 eval suite，记录 pass@k、修复迭代、工具调用、token 估算、人类纠偏次数，并在失败时保留 Failure Replay。
+
+## Commands
+
+初始化默认基线套件：
+
+```bash
+scale eval init
+scale eval init --suite workflow-baseline --json
+```
+
+运行套件：
+
+```bash
+scale eval run --suite workflow-baseline
+scale eval run --suite workflow-baseline --json
+```
+
+对比两次运行：
+
+```bash
+scale eval compare --baseline <run-id> --candidate <run-id>
+scale eval compare --baseline <run-id> --candidate <run-id> --json
+```
+
+生成 Markdown 报告：
+
+```bash
+scale eval report --run <run-id>
+scale eval report --run <run-id> --output docs/worklog/eval-report.md
+```
+
+查看和提升失败重放：
+
+```bash
+scale eval failures --since 30d
+scale eval replay <failure-id>
+scale eval replay --task-id <task-id>
+scale eval promote-failure <failure-id>
+```
+
+## Failure Replay To Memory
+
+Failure Replay is local eval evidence first. When a failure pattern is useful for future work, ingest it into Memory Brain as an `incident` candidate:
+
+```bash
+scale memory ingest --from failure --failure-id <failure-id>
+scale memory query "missing verification evidence"
+scale memory promote <memory-node-id>
+```
+
+This does not auto-change standards or hooks. It only makes the failure queryable and evidence-backed so repeated mistakes can be promoted deliberately after review.
+
+## Storage
+
+```text
+.scale/evals/
+├── suites/
+├── runs/
+├── failures/
+└── improvements/
+```
+
+These files are local runtime evidence by default. Commit only curated summaries or intentional benchmark fixtures.
+
+## Suite Shape
+
+```json
+{
+  "version": "1.0",
+  "id": "workflow-baseline",
+  "name": "SCALE workflow baseline",
+  "cases": [
+    {
+      "id": "governance-command-smoke",
+      "type": "bugfix",
+      "title": "Command evidence smoke",
+      "task": "Verify that a local command can produce concrete eval evidence.",
+      "phase": "verify",
+      "successCriteria": ["command exits 0"],
+      "attempts": [
+        {
+          "id": "attempt-1",
+          "command": "node -e \"console.log('scale-eval-ok')\"",
+          "expectedExitCode": 0,
+          "outputContains": "scale-eval-ok"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Metrics
+
+| Metric | Meaning |
+| --- | --- |
+| `passAt1Rate` | 一次完整尝试就通过的比例 |
+| `passAt3Rate` | 三次以内通过的比例 |
+| `averageFixIterations` | 首次失败后的平均修复循环 |
+| `totalToolCalls` | eval attempts 数量，可近似衡量工具调用成本 |
+| `estimatedTokens` | task 与输出摘要的估算 token 成本 |
+| `humanCorrections` | 人类纠偏次数 |
+| `failureReplayCount` | 失败重放记录数量 |
+
+## Failure Replay
+
+失败不只记录最终失败状态，还会保存：
+
+- task and success criteria
+- phase
+- wrong turn
+- evidence
+- correction
+- prevention
+- replay command
+- redaction status
+
+Failure category 当前包括：
+
+- `wrong-exploration-path`
+- `hallucinated-project-fact`
+- `missing-codegraph-or-graph-fallback`
+- `over-broad-context-load`
+- `bad-skill-recommendation`
+- `missing-verification-evidence`
+- `failed-security-or-resource-gate`
+- `human-correction-after-agent-confidence`
+- `command-failure`
+- `unknown`
+
+`scale eval promote-failure` 会把失败重放提升为 improvement candidate，但不会自动修改项目规范。是否进入长期标准仍需要人工或后续 review 确认。
+
+## Governance Use
+
+- v0.22 的默认 suite 是轻量 smoke baseline，用来验证 eval 管线可运行。
+- 真实项目应逐步增加 bugfix、feature、security、frontend、release、resource 类型案例。
+- Failure Replay 应与 Resource Governance 配合：默认本地保留，只有总结、基准或明确要长期维护的案例才提交。
+- Workflow Eval 的数据可以进入后续 Governance ROI，用来判断某个治理模块是否真的减少 rework、tool calls、token 或人类纠偏。
+
+## Policy
+
+- 不允许用 eval 通过率替代真实项目验证。
+- 失败记录中的命令输出会做基础脱敏，但仍应避免把敏感原始日志写入 suite。
+- 低成本 smoke suite 可以频繁运行；重型项目 suite 应按需运行。
+- 没有 eval 证据时，不应宣称工作流能力已经提升。

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-*` 入口，以及生成文件更新和项目级验证之间的边界。