@hongmaple0820/scale-engine 0.25.0 → 0.27.0

package/docs/THIRD_PARTY_SKILLS.md

@@ -1,57 +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.
+# 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 证据时，不应宣称工作流能力已经提升。

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/`、日志或截图提交进仓库。