@hongmaple0820/scale-engine 0.18.0 → 0.20.0

package/docs/start/README.md

@@ -0,0 +1,42 @@
+# SCALE Engine 入门路径
+
+这个目录只放面向新用户的上手内容。目标是让用户先跑通，再理解完整体系。
+
+## 推荐阅读顺序
+
+1. [3 分钟快速开始](quickstart.md)
+   从空目录初始化治理工作流，看到 `.scale`、模板、验证 profile 和状态输出。
+
+2. [官方 Demo Walkthrough](agent-governance-demo.md)
+   用一个 OAuth state 加固任务演示：上下文对齐、诊断计划、TDD 切片、HTML artifact、资源治理和工程规范扫描。
+
+3. 回到根目录 [README](../../README.md)
+   理解 SCALE Engine 的核心能力和 governance pack 选择。
+
+4. 查看 [文档地图](../README.md)
+   区分哪些文档是用户指南、哪些是参考资料、哪些是历史规划和过程记录。
+
+## 你应该先看到什么
+
+跑完 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` |
+

package/docs/start/agent-governance-demo.md

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

package/docs/start/quickstart.md

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

package/examples/demo-projects/agent-governance-demo/README.md

@@ -0,0 +1,37 @@
+# Agent Governance Demo
+
+这是 SCALE Engine 的最小官方 demo 项目，用来演示 Agent 如何在治理工作流下完成一个安全敏感任务。
+
+业务场景：OAuth callback 必须拒绝过期、已消费或不匹配的 state。
+
+## 运行
+
+```bash
+npm install
+npm test
+```
+
+## 接入 SCALE
+
+```bash
+scale init --governance-pack node-library
+scale preflight --preflight-profile quick
+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
+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
+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
+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 命令会生成任务证据、运行证据、记忆候选和 HTML 交付视图，避免 Agent 只口头说“已完成”。
+

package/examples/demo-projects/agent-governance-demo/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "scale-agent-governance-demo",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 src/oauth-state.ts tests/oauth-state.test.ts",
+    "lint": "tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 src/oauth-state.ts tests/oauth-state.test.ts",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.9"
+  }
+}
+

package/examples/demo-projects/agent-governance-demo/src/oauth-state.ts

@@ -0,0 +1,39 @@
+export type OAuthStateFailure = 'missing-record' | 'state-mismatch' | 'state-expired' | 'state-consumed'
+
+export interface OAuthStateRecord {
+  state: string
+  userId: string
+  expiresAt: number
+  consumedAt?: number
+}
+
+export interface OAuthStateVerification {
+  ok: boolean
+  userId?: string
+  reason?: OAuthStateFailure
+}
+
+export function verifyOAuthState(
+  record: OAuthStateRecord | undefined,
+  providedState: string,
+  now: number = Date.now()
+): OAuthStateVerification {
+  if (!record) {
+    return { ok: false, reason: 'missing-record' }
+  }
+
+  if (record.state !== providedState) {
+    return { ok: false, reason: 'state-mismatch' }
+  }
+
+  if (record.expiresAt <= now) {
+    return { ok: false, reason: 'state-expired' }
+  }
+
+  if (record.consumedAt !== undefined) {
+    return { ok: false, reason: 'state-consumed' }
+  }
+
+  return { ok: true, userId: record.userId }
+}
+

package/examples/demo-projects/agent-governance-demo/tests/oauth-state.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import { verifyOAuthState, type OAuthStateRecord } from '../src/oauth-state.js'
+
+const future = 2_000
+const now = 1_000
+
+function record(overrides: Partial<OAuthStateRecord> = {}): OAuthStateRecord {
+  return {
+    state: 'state-123',
+    userId: 'user-1',
+    expiresAt: future,
+    ...overrides
+  }
+}
+
+describe('verifyOAuthState', () => {
+  it('accepts a valid unexpired state', () => {
+    expect(verifyOAuthState(record(), 'state-123', now)).toEqual({
+      ok: true,
+      userId: 'user-1'
+    })
+  })
+
+  it('rejects a missing record', () => {
+    expect(verifyOAuthState(undefined, 'state-123', now)).toEqual({
+      ok: false,
+      reason: 'missing-record'
+    })
+  })
+
+  it('rejects a mismatched state', () => {
+    expect(verifyOAuthState(record(), 'other-state', now)).toEqual({
+      ok: false,
+      reason: 'state-mismatch'
+    })
+  })
+
+  it('rejects an expired state', () => {
+    expect(verifyOAuthState(record({ expiresAt: now }), 'state-123', now)).toEqual({
+      ok: false,
+      reason: 'state-expired'
+    })
+  })
+
+  it('rejects a consumed state', () => {
+    expect(verifyOAuthState(record({ consumedAt: 900 }), 'state-123', now)).toEqual({
+      ok: false,
+      reason: 'state-consumed'
+    })
+  })
+})
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hongmaple0820/scale-engine",
-  "version": "0.18.0",
-  "description": "SCALE Engine v0.18.0 - governed HTML artifacts, visual review reports, and traceable Markdown-to-HTML task outputs",
+  "version": "0.20.0",
+  "description": "Executable AI agent governance with workflow gates, evidence, skill/tool orchestration, and traceable HTML artifacts",
   "type": "module",
   "bin": {
     "scale": "dist/api/cli.js"
@@ -15,7 +15,18 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs/README.md",
+    "docs/CODE_INTELLIGENCE.md",
+    "docs/CONTEXT_BUDGET.md",
+    "docs/WORKFLOW_EVAL.md",
+    "docs/SKILL_RADAR.md",
+    "docs/MEMORY_BRAIN.md",
+    "docs/GOVERNANCE_DASHBOARD.md",
+    "docs/MEMORY_FABRIC.md",
+    "docs/RUNTIME_EVIDENCE.md",
+    "docs/start",
+    "examples/demo-projects/agent-governance-demo"
   ],
   "publishConfig": {
     "access": "public"