@hongmaple0820/scale-engine 0.24.0 → 0.26.0

package/docs/SKILL-REPOSITORY.md

@@ -0,0 +1,57 @@
+# SCALE Skill 仓库
+
+这个仓库视图用于让 Agent 按任务渐进式发现、激活和编排 skills/MCP/CLI，而不是一次性把所有能力塞进上下文。
+
+## 渐进式披露
+
+1. 启动时只读取 Skill 元数据和一句话描述。
+2. 任务命中时才读取完整 SKILL.md。
+3. scripts、references、assets 只在明确需要时懒加载。
+
+## 安全安装
+
+- 安装前必须执行安全扫描，阻断 `curl | bash`、`Invoke-Expression`、危险删除和非 HTTPS 来源。
+- npm/npx 来源必须补充 `npm audit signatures`、来源仓库、许可证和版本/commit 固定检查。
+- 任何第三方 Skill 都先进入隔离审查，再写入项目或全局 skills 目录。
+
+## 供应链防护清单
+
+- review-skill-frontmatter
+- inspect-scripts-directory
+- verify-license-and-source
+- verify-attribution-and-notice
+- pin-source-revision
+- npm-audit-signatures
+
+## Skill 目录
+
+| ID | 类别 | 信任 | 主要用途 | 组合建议 |
+| --- | --- | --- | --- | --- |
+| `planning-with-files` | planning | community | Use persistent planning files, progress logs, findings, active-plan selection, and plan attestation for long-running agent work. | memory-brain, web-access, code-reviewer |
+| `agentmemory` | memory | community | Use as an optional external memory provider via REST or MCP when teams want cross-agent persistent memory beyond SCALE local Memory Brain. | memory-brain, mcp-chrome-devtools, codex-cli |
+| `gbrain` | memory | community | Use as an optional graph-backed memory provider for long-running project knowledge, entity relationships, and background memory maintenance. | memory-brain, agentmemory, codegraph |
+| `frontend-design` | ui | official | UI 视觉方向、布局、组件状态和前端实现约束。 | awesome-design-md, ui-ux-pro-max, webapp-testing |
+| `awesome-design-md` | ui | ecosystem | 建立产品级设计规范和视觉语言。 | ui-ux-pro-max, frontend-design |
+| `ui-ux-pro-max` | ui | ecosystem | 补齐体验策略、交互状态和 UI 验收维度。 | awesome-design-md, webapp-testing |
+| `webapp-testing` | testing | official | 验证页面点击、表单、控制台、截图和端到端行为。 | agent-browser, mcp-chrome-devtools |
+| `web-access` | browser | ecosystem | 获取一手资料、动态页面内容、网页证据和来源引用。 | agent-browser, mcp-chrome-devtools |
+| `agent-browser` | browser | ecosystem | 与 Web 页面真实交互，补齐手工验收证据。 | web-access, webapp-testing, mcp-chrome-devtools |
+| `mcp-chrome-devtools` | browser | ecosystem | 调试控制台错误、网络请求、页面状态和性能问题。 | agent-browser, webapp-testing |
+| `cua` | desktop | ecosystem | 操作桌面应用并收集端侧截图、状态和副作用边界证据。 | web-access, agent-browser |
+| `code-reviewer` | review | official | 合并前分级审查缺陷、安全、可维护性和测试风险。 | security-and-hardening, update-docs |
+| `fix` | review | official | 提交前清理格式和 lint 问题。 | code-reviewer |
+| `pr-creator` | review | official | 生成标准 PR 描述和合并前说明。 | code-reviewer, update-docs |
+| `update-docs` | docs | official | 发现并更新受代码变更影响的长期文档。 | documentation-and-adrs |
+| `find-skills` | discovery | ecosystem | 按任务意图搜索合适 Skill，再进入安全扫描。 | web-access |
+| `codex-cli` | agent-cli | official | 外部 CLI 审查和命令级证据。 | gemini-cli, opencode-cli |
+| `gemini-cli` | agent-cli | official | 外部 CLI 审查和命令级证据。 | codex-cli, opencode-cli |
+| `opencode-cli` | agent-cli | ecosystem | 外部 CLI 审查和命令级证据。 | codex-cli, gemini-cli |
+| `agency-agents-zh` | role-library | community | 提供 CEO、CTO、工程、设计、产品等角色预设参考。 | skill-safety-scan |
+
+## Third-Party Attribution
+
+| ID | License | Usage | Notice |
+| --- | --- | --- | --- |
+| `planning-with-files` | MIT | adapted-concept | Inspired by and compatible with OthmanAdi/planning-with-files. SCALE should not copy upstream files unless the MIT license text and attribution are included. |
+| `agentmemory` | Apache-2.0 | external-reference | Optional external integration only. Do not vendor agentmemory code into SCALE without preserving Apache-2.0 license text, modification notices, and any upstream NOTICE obligations. |
+| `gbrain` | MIT | external-reference | Optional external provider only. Do not vendor GBrain code into SCALE without preserving MIT license text, source revision, and modification notices. |

package/docs/SKILL_RADAR.md

@@ -1,115 +1,122 @@
-# Skill Radar
-
-Skill Radar is the active capability selection layer for SCALE. It does not auto-install or blindly run skills. It scores relevant skills, MCP servers, browser tools, desktop automation, and external CLIs against the current task, then returns:
-
-- why the capability matches
-- confidence score
-- safety level
-- required evidence
-- fallback path
-- supply-chain checks before installation or promotion
-
-The goal is to make agents actively use useful tools without turning the project into an unsafe prompt or tool bundle.
-
-## Commands
-
-```bash
-scale skill radar --task "Design upload UI and run browser E2E checks" --files src/pages/upload.tsx
-scale skill radar --task "Automate WPS desktop workflow with CUA" --json
-scale skill radar --task "Review release PR" --phase review --level L --output docs/worklog/tasks/release/skill-radar.md
-scale skill doctor --supply-chain
-scale skill doctor --supply-chain --json
-```
-
-## Safety Levels
-
-| Level | Meaning | Default action |
-| --- | --- | --- |
-| `trusted` | Official or low-risk capability with policy enabled | May be recommended when confidence is high |
-| `review-required` | Third-party or ecosystem capability | Require source, license, scripts, and revision review |
-| `restricted` | Browser, desktop, or external execution boundary | Require explicit evidence and side-effect boundaries |
-| `blocked` | Disabled by policy or failed safety review | Do not run; use fallback |
-
-## Confidence
-
-Skill Radar combines:
-
-- task keywords and workflow phase
-- changed file patterns
-- local skill installation
-- tool availability
-- trust level
-- policy status
-- frontend/package evidence
-- safety penalties
-
-The score is not a promise that the tool will work. It is a routing signal. Any recommendation still needs real evidence before the agent can claim success.
-
-## Default Domains
-
-| Domain | Typical triggers | Recommended capability types |
-| --- | --- | --- |
-| `ui` | UI, UX, frontend, component, visual, layout | design skills, visual review, screenshot evidence |
-| `browserAutomation` | browser, E2E, Playwright, Chrome, DevTools | web access, browser automation, DevTools evidence |
-| `desktopAutomation` | desktop, GUI, WPS, WeChat, CUA | disabled by default; manual operator fallback |
-| `externalCli` | Codex, Gemini, OpenCode, external agent CLI | disabled by default; dry-run and output evidence |
-| `review` | PR, merge, release, code review | reviewer skills, severity findings |
-| `docs` | docs, README, ADR, governance asset | doc impact and source-of-truth evidence |
-| `discovery` | skill, MCP, tool, capability discovery | find-skills plus safety review |
-
-## Evidence Contract
-
-Each recommendation carries required evidence. Examples:
-
-- UI work: `ui-spec`, `design-rationale`, `screenshot`, `visual-review`
-- Browser work: `browser-evidence`, `console-summary`, `network-summary`, `scenario-result`
-- Desktop work: `operator-boundary`, `desktop-screenshot`, `affected-app`
-- External CLI work: `cli-version-check`, `command`, `exit-code`, `output-summary`
-- Review work: `review-report`, `finding-list`, `severity`
-
-If evidence is missing, the final delivery should list the capability as unverified rather than claiming it was used successfully.
-
-## Supply-Chain Doctor
-
-`scale skill doctor --supply-chain` reviews known skill sources and install commands for:
-
-- HTTPS source requirement
-- `curl | bash`, `wget | sh`, `Invoke-Expression`, and `iex` blocking
-- destructive install patterns
-- npm/npx lifecycle script review
-- required source, license, and revision checks
-
-This is intentionally conservative. Third-party skills should start in review-required mode and be promoted only after inspection.
-
-## Policy Integration
-
-Skill Radar reads `.scale/tools.json` through the Tool Policy layer. Defaults:
-
-- UI and browser capabilities are enabled but evidence-required.
-- Desktop CUA is disabled by default.
-- External agent CLIs are disabled by default.
-- Browser tools require captured evidence and should stay in approved domains.
-
-Use Tool Policy to enable a restricted capability deliberately rather than relying on an agent's assumption.
-
-## Fallback Rule
-
-Every recommendation must include a fallback. This prevents tool theater:
-
-```text
-If the capability is missing, unsafe, low-confidence, or policy-blocked,
-the agent must use the fallback and record why the capability was not used.
-```
-
-## Artifact Lifecycle
-
-Skill Radar reports can be written into task artifacts:
-
-```bash
-scale skill radar \
-  --task "Refactor upload page and verify browser flow" \
-  --files src/pages/upload.tsx \
-  --output docs/worklog/tasks/2026-05-19-upload-refactor/skill-radar.md
-```
-
-Keep the report when it is evidence for an M/L/CRITICAL task. Do not commit transient local detection output unless it is part of the reviewed task artifact set.
+# Skill Radar
+
+Skill Radar is the active capability selection layer for SCALE. It does not auto-install or blindly run skills. It scores relevant skills, MCP servers, browser tools, desktop automation, and external CLIs against the current task, then returns:
+
+- why the capability matches
+- confidence score
+- safety level
+- required evidence
+- fallback path
+- supply-chain checks before installation or promotion
+
+The goal is to make agents actively use useful tools without turning the project into an unsafe prompt or tool bundle.
+
+## Commands
+
+```bash
+scale skill radar --task "Design upload UI and run browser E2E checks" --files src/pages/upload.tsx
+scale skill radar --task "Automate WPS desktop workflow with CUA" --json
+scale skill radar --task "Review release PR" --phase review --level L --output docs/worklog/tasks/release/skill-radar.md
+scale skill doctor --supply-chain
+scale skill doctor --supply-chain --json
+```
+
+## Safety Levels
+
+| Level | Meaning | Default action |
+| --- | --- | --- |
+| `trusted` | Official or low-risk capability with policy enabled | May be recommended when confidence is high |
+| `review-required` | Third-party or ecosystem capability | Require source, license, scripts, and revision review |
+| `restricted` | Browser, desktop, or external execution boundary | Require explicit evidence and side-effect boundaries |
+| `blocked` | Disabled by policy or failed safety review | Do not run; use fallback |
+
+## Confidence
+
+Skill Radar combines:
+
+- task keywords and workflow phase
+- changed file patterns
+- local skill installation
+- tool availability
+- trust level
+- policy status
+- frontend/package evidence
+- safety penalties
+
+The score is not a promise that the tool will work. It is a routing signal. Any recommendation still needs real evidence before the agent can claim success.
+
+## Default Domains
+
+| Domain | Typical triggers | Recommended capability types |
+| --- | --- | --- |
+| `ui` | UI, UX, frontend, component, visual, layout | design skills, visual review, screenshot evidence |
+| `browserAutomation` | browser, E2E, Playwright, Chrome, DevTools | web access, browser automation, DevTools evidence |
+| `desktopAutomation` | desktop, GUI, WPS, WeChat, CUA | disabled by default; manual operator fallback |
+| `externalCli` | Codex, Gemini, OpenCode, external agent CLI | disabled by default; dry-run and output evidence |
+| `review` | PR, merge, release, code review | reviewer skills, severity findings |
+| `docs` | docs, README, ADR, governance asset | doc impact and source-of-truth evidence |
+| `planning` | plans, task_plan, findings, progress, long-running work | file-backed planning, progress logs, plan attestation |
+| `memory` | memory, recall, knowledge, persistent memory, agentmemory, gbrain | provider-routed memory through agentmemory, gbrain, or scale-local fallback |
+| `discovery` | skill, MCP, tool, capability discovery | find-skills plus safety review |
+
+## Evidence Contract
+
+Each recommendation carries required evidence. Examples:
+
+- UI work: `ui-spec`, `design-rationale`, `screenshot`, `visual-review`
+- Browser work: `browser-evidence`, `console-summary`, `network-summary`, `scenario-result`
+- Desktop work: `operator-boundary`, `desktop-screenshot`, `affected-app`
+- External CLI work: `cli-version-check`, `command`, `exit-code`, `output-summary`
+- Review work: `review-report`, `finding-list`, `severity`
+- Planning work: `task-plan`, `findings-log`, `progress-log`, `plan-attestation`
+- Memory work: `memory-provider-health`, `privacy-boundary`, `data-retention-policy`, `query-result`
+
+If evidence is missing, the final delivery should list the capability as unverified rather than claiming it was used successfully.
+
+## Supply-Chain Doctor
+
+`scale skill doctor --supply-chain` reviews known skill sources and install commands for:
+
+- HTTPS source requirement
+- `curl | bash`, `wget | sh`, `Invoke-Expression`, and `iex` blocking
+- destructive install patterns
+- npm/npx lifecycle script review
+- required source, license, and revision checks
+- third-party attribution and NOTICE checks
+
+This is intentionally conservative. Third-party skills should start in review-required mode and be promoted only after inspection.
+
+External skill references and acknowledgements are tracked in [Third-Party Skills and External References](THIRD_PARTY_SKILLS.md) and the full [External Reference Inventory](EXTERNAL_REFERENCES.md). SCALE should not vendor community skill code unless the license text, source revision, copyright notice, and modification notes are preserved.
+
+## Policy Integration
+
+Skill Radar reads `.scale/tools.json` through the Tool Policy layer. Defaults:
+
+- UI and browser capabilities are enabled but evidence-required.
+- Desktop CUA is disabled by default.
+- External agent CLIs are disabled by default.
+- Browser tools require captured evidence and should stay in approved domains.
+
+Use Tool Policy to enable a restricted capability deliberately rather than relying on an agent's assumption.
+
+## Fallback Rule
+
+Every recommendation must include a fallback. This prevents tool theater:
+
+```text
+If the capability is missing, unsafe, low-confidence, or policy-blocked,
+the agent must use the fallback and record why the capability was not used.
+```
+
+## Artifact Lifecycle
+
+Skill Radar reports can be written into task artifacts:
+
+```bash
+scale skill radar \
+  --task "Refactor upload page and verify browser flow" \
+  --files src/pages/upload.tsx \
+  --output docs/worklog/tasks/2026-05-19-upload-refactor/skill-radar.md
+```
+
+Keep the report when it is evidence for an M/L/CRITICAL task. Do not commit transient local detection output unless it is part of the reviewed task artifact set.

package/docs/THIRD_PARTY_SKILLS.md

@@ -0,0 +1,57 @@
+# Third-Party Skills and External References
+
+This document records external skill projects that SCALE may learn from, recommend, or integrate with. It is a governance boundary, not a vendoring manifest. The complete cross-repo inventory is maintained in [External Reference Inventory](EXTERNAL_REFERENCES.md).
+
+## Policy
+
+- Do not vendor third-party skill code, images, logos, examples, or marketing copy unless the license review explicitly allows redistribution.
+- Preserve upstream license text, copyright notices, NOTICE files, source URL, and source revision before any vendored or modified redistribution.
+- Mark modified files and document what changed from upstream.
+- Treat optional external services as review-required until privacy, retention, credential, and delete boundaries are reviewed.
+- `scale skill doctor --supply-chain` must include license, attribution, script, and pinned-revision checks for third-party skills.
+- Community skills start as `review-required`; promotion requires real installation evidence and a recorded safety decision.
+
+## Highlighted External References
+
+| Project | License | Upstream | SCALE usage | Redistribution status |
+| --- | --- | --- | --- | --- |
+| Planning with Files | MIT | [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files) | Adapt concepts for file-backed plans, findings, progress logs, active-plan routing, and plan attestation. | Not vendored. |
+| agentmemory | Apache-2.0 | [rohitg00/agentmemory](https://github.com/rohitg00/agentmemory) | Optional external memory provider via REST or MCP for teams that need cross-agent persistent memory beyond local SCALE Memory Brain. | Not vendored. |
+| GBrain | MIT | [garrytan/gbrain](https://github.com/garrytan/gbrain) | Optional graph memory provider for brain repos, hybrid search, entity relationships, MCP, and background maintenance. | Not vendored. |
+
+Other referenced skills, MCP servers, CLIs, discovery candidates, and adapter targets are listed in [External Reference Inventory](EXTERNAL_REFERENCES.md). Unknown licenses stay `review-required`; do not treat a repository link as redistribution permission.
+
+## Acknowledgements
+
+SCALE acknowledges these upstream projects and contributors:
+
+- `OthmanAdi/planning-with-files`, Copyright (c) 2026 Ahmad Adi.
+- `rohitg00/agentmemory` and its upstream contributors.
+- `garrytan/gbrain` and its upstream contributors.
+- All upstream projects listed in [External Reference Inventory](EXTERNAL_REFERENCES.md) according to their licenses and contribution histories.
+
+The current SCALE implementation records these projects as external references or adapted concepts. It does not copy their source code into this repository.
+
+## Vendoring Checklist
+
+If SCALE later vendors or modifies any third-party skill, the change must include:
+
+1. Full upstream license text in the distributed package.
+2. Upstream copyright and NOTICE material.
+3. Source repository URL and pinned revision.
+4. Modification notes for every copied or changed file.
+5. Tests or doctor checks proving the attribution metadata is present.
+6. README and generated skill repository documentation updates.
+
+## Runtime Boundaries
+
+External memory providers must not be enabled silently. Before use, record:
+
+- provider endpoint and health check evidence
+- project data scope
+- credential boundary
+- retention and deletion policy
+- whether data leaves the local machine or team-controlled infrastructure
+- whether provider writes are disabled, candidate-only, or explicitly enabled
+
+External planning skills must not replace SCALE task evidence. They can improve the plan artifact shape, but final delivery still requires verification output, changed-file evidence, and explicit unverified-risk notes.

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 证据时，不应宣称工作流能力已经提升。