@hongmaple0820/scale-engine 0.38.0 → 0.40.0

package/docs/start/quickstart.md

@@ -1,12 +1,15 @@
 # 3 分钟快速开始
 
-目标：在一个空目录中安装 SCALE 治理工作流，并看到可验证的项目产物。
+目标：在一个项目里安装 SCALE 工作流，完成依赖检查，并看到可验证的治理产物。
 
 ## 前置条件
 
-- Node.js 20 或更高版本。
-- 已安装 npm。
-- Windows PowerShell、Git Bash、macOS/Linux shell 都可以执行。
+- Node.js 20+
+- npm
+- Git
+- Windows PowerShell、Git Bash、macOS/Linux shell 均可
+
+Python、Bun、Rust/Cargo、uv/pipx 不是启动 SCALE 的硬要求。只有启用 Graphify、GBrain、RTK 等第三方能力时，安装器才会提示缺少哪些运行时以及可执行的修复命令。
 
 ## 1. 安装 CLI
 
@@ -15,13 +18,13 @@ npm install -g @hongmaple0820/scale-engine
 scale --version
 ```
 
-如果你在开发 `scale-engine` 本仓库，也可以用本地构建后的命令：
+本仓库开发时也可以直接运行源码入口：
 
 ```bash
-node E:/project/scale-engine/dist/api/cli.js --help
+node --import tsx E:/project/scale-engine/src/api/cli.ts --help
 ```
 
-## 2. 初始化一个空项目
+## 2. 初始化项目
 
 ```bash
 mkdir scale-demo
@@ -29,56 +32,93 @@ cd scale-demo
 scale init --governance-pack standard
 ```
 
-这一步会生成：
+初始化会生成 `.scale/`、`docs/`、`scripts/` 以及对应 Agent 入口文件。已有项目升级不要盲目重跑 `init`，优先使用：
+
+```bash
+scale upgrade check --dir . --lang zh
+scale upgrade plan --dir . --html --lang zh
+```
+
+## 3. 交互式安装第三方能力
+
+默认输出语言是中文。需要英文时加 `--lang en`，也可以设置 `SCALE_LANG=en`。
+
+推荐先只查看计划：
+
+```bash
+scale setup --pack full
+```
 
-```text
-.scale/
-docs/
-scripts/
-AGENTS.md 或对应 Agent 入口文档
+确认后安装：
+
+```bash
+scale setup --pack full --yes
+```
+
+机器可读输出：
+
+```bash
+scale setup --pack full --json
+```
+
+`setup` 和 `bootstrap deps` 都会输出 `runtimeChecks`。如果机器缺少 `python`、`bun`、`cargo`、`uv/pipx`、`node/npm/npx`，会先显示缺失项和修复建议，再决定是否执行 `--yes` 或 `--apply`，避免安装中途卡住。
+
+记忆供应商可以在安装入口直接切换，不需要手改 `.scale/memory-providers.json`：
+
+```bash
+scale setup --pack memory --memory-provider scale-local --json
+scale setup --pack memory --memory-provider gbrain --memory-mode external-first --json
 ```
 
-重点看这些文件：
+第三方能力的职责边界：
 
-| 文件 | 用途 |
-| --- | --- |
-| `.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 模板 |
+| 能力 | 默认定位 | 关键验证 |
+| --- | --- | --- |
+| `awesome-design-md` | 品牌、视觉语言、`DESIGN.md` 来源 | 是否同步上游 DESIGN.md catalog |
+| `ui-ux-pro-max` | UX、状态、可访问性、响应式验收 | 是否通过官方 `uipro-cli` 安装 |
+| `frontend-design` | 可选实现灵感，不再是 UI 默认必装项 | 需要时显式 `--include frontend-design` |
+| `rtk` | CLI proxy/token 节省能力 | `rtk gain` 和 `rtk init -g --codex` |
+| `gbrain` | 默认记忆供应商 | 检查 brain 是否已配置且连接/schema 可用，未初始化会提示 `gbrain init --pglite` |
+| `graphify` | 知识图谱产物供应商 | `graphify install --platform codex` 和 `graphify-out/graph.json` |
+| `codegraph` | 代码结构索引供应商 | `codegraph init -i` 和 `.codegraph/` |
 
-## 3. 跑第一轮本地检查
+低层命令仍可直接使用：
+
+```bash
+scale bootstrap deps --profile advanced --governance-pack frontend-app --lang zh
+scale bootstrap deps --profile advanced --governance-pack frontend-app --apply --lang zh
+```
+
+## 4. 验证闭环
 
 ```bash
-scale bootstrap deps --pack external-cli --json
 scale doctor
 scale preflight --preflight-profile quick
 scale status
 scale assets scan --dir .
 scale standards scan --dir .
 scale runtime doctor --level S
+scale memory provider status --json
+scale codegraph status --json
 ```
 
-预期效果：
-
-- `preflight` 能说明当前治理文件是否完整。
-- `bootstrap deps` 会告诉你第三方 skills、RTK、记忆/知识图谱依赖哪些已经装好，哪些只是治理规则已经生成。
-- `status` 会告诉 Agent 下一步应该做什么。
-- `assets scan` 会把文档、模板、脚本、报告等资源分类。
-- `standards scan` 会扫描日志噪音、敏感信息、危险输入、测试和架构风险。
-- `runtime doctor` 会检查本地运行时证据目录和最终交付证据状态。
-
-建议再跑一次 `scale doctor`。现在它会按当前 profile 输出 `bootstrap` 建议，并把 `gbrain / codegraph / graphify` 的状态一起列出来。
+未运行验证，不要声称通过。`setup --json` 和 `bootstrap deps --json` 只代表依赖计划可解析，不等于第三方服务已经可用。
 
-如果你确认要补环境依赖，再显式执行安装：
+真实第三方能力需要单独跑回放验证。默认命令会把未配置的远端能力标记为 `blocked`，但不会让本地发布门禁误失败；需要作为强制门禁时使用对应 npm script 或加 `--require-*`。
 
 ```bash
-scale bootstrap deps --profile advanced --governance-pack frontend-app --apply
+npm run smoke:providers
+npm run smoke:gbrain
+npm run smoke:graphify -- --large-project /path/to/large-project
 ```
 
-## 4. 建立第一个任务上下文
+验证语义：
+
+- `smoke:gbrain` 会先确认 gbrain 已配置且召回关键健康检查可用，通过后写入一个临时记忆页，再用独立 CLI 进程 `get/query/search` 回放，证明不是本地 mock。
+- `smoke:graphify` 默认对真实项目执行 `graphify update <project> --no-cluster`，走 AST/Python 无模型路径，检查 `graph.json`，再执行 `graphify query`；只有显式 `--semantic-extract` 才允许语义模型提取。
+- `graphify-out/` 是生成产物，不应该提交到 Git；长期知识沉淀应进入经过评审的 `memory/`、docs 或规则文件。
+
+## 5. 建立任务上下文
 
 ```bash
 scale context init --name "Scale Demo"
@@ -88,14 +128,7 @@ scale diagnose plan --task-id 2026-05-18-oauth-hardening --symptom "callback 在
 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"
@@ -104,51 +137,45 @@ scale memory pack --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-o
 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/`，默认本地保留，确认稳定后再人工提升到知识库、规范或模块文档。
+`memory settle` 默认只生成学习候选，不会自动把一次会话判断提升成长线规则。存在失败证据时，候选会要求先解决失败，避免把未闭环问题沉淀成经验。
+
+## 6. MOE/多仓工作区
 
-## 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
+scale init --governance-pack moe-workspace
 ```
 
-规则：
+MOE 默认把子工程配置为兄弟仓库或绝对路径，不建议把独立 Git 子工程放在主工程根目录下。`.scale/workspace.json` 中的典型写法：
 
-- Markdown 是长期维护源文件。
-- HTML 是给评审、对比、状态汇报、交付和发版使用的可视化产物。
-- `artifact doctor` 会检查 HTML 是否可追溯、是否引用远程资源、是否可能包含敏感信息。
+```json
+{
+  "topology": "moe",
+  "repositories": [
+    { "name": "root", "path": ".", "role": "root", "required": true },
+    { "name": "api", "path": "../api", "role": "external", "required": true, "remote": "origin" }
+  ]
+}
+```
 
-## 6. 下一步
+这样可以避免子工程 Git 状态、分支、提交和主工程互相污染。
 
-如果你只是试用，到这里已经能看到 SCALE 的价值：它把 Agent 的工作过程变成了可以审计的证据链。
+## 7. 安装烟测
 
-如果你要接入真实项目，按项目类型选择 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
+npm run smoke:setup
+npm run smoke:providers
+make setup-smoke
 ```
 
-已有项目升级工作流时不要盲目重跑 `scale init`。先走受保护的升级链路：
+`smoke:setup` 只验证安装计划、双语输出、运行时依赖诊断、记忆供应商切换和 CodeGraph/Graphify 状态路径，不会执行真实第三方安装。
+`smoke:providers` 会执行真实供应商回放；未配置 gbrain 或 graphify 时输出 `blocked` 和修复命令，只有 `smoke:gbrain`/`smoke:graphify` 或显式 `--require-*` 才会失败退出。
 
-```bash
-scale upgrade check --dir . --lang zh
-scale upgrade plan --dir . --html --lang zh
-scale upgrade apply --dir . --confirm --lang zh
-```
-
-如果升级计划提示 AI OS runtime 尚未接入，用一键接入命令生成运行态目录、首份 dry-run、benchmark 和 doctor 报告：
+遇到跨系统命令兼容、PATH 或运行时依赖问题时，先导出环境诊断：
 
 ```bash
-scale ai-os adopt --dir . --task "接入 AI OS runtime" --lang zh
+scale doctor env --json
 ```
-
-需要英文输出时把 `--lang zh` 换成 `--lang en`。干净的 SCALE 受管文件可以自动刷新；已有本地改动的文件会进入人工审阅，不会被自动覆盖。
-
-继续阅读 [官方 Demo Walkthrough](agent-governance-demo.md)，看一个真实任务如何从需求到验证证据。
-

package/docs/workflow/GATES_AND_SCORE.md

@@ -0,0 +1,56 @@
+# Gates and Task Score
+
+This document records the first deterministic optimization layer for gate visibility, architecture conformance, and task scoring.
+
+## Gate Status
+
+Use `scale gates status` to inspect the active gate catalog.
+
+```bash
+scale gates status --json
+```
+
+The report separates three concepts that were previously easy to confuse:
+
+- Core gates: `G0-G8`, used by workflow verification, preflight, and product smoke profiles.
+- Meta-governance gates: `G9-G15`, used by `scale meta-governance`.
+- Extension gates: policy-backed checks such as engineering standards, product smoke policy, and tool evidence.
+
+`scale gates status` is intentionally read-only. It does not execute checks; it explains which checks exist and which policies are blocking.
+
+## Architecture Standards Gate
+
+Architecture and engineering standards are driven by project configuration:
+
+- `.scale/verification.json` controls whether `engineeringStandardsGate` is `off`, `warn`, or `block`.
+- `.scale/engineering-standards.json` controls standards rules and baselines.
+- `.scale/frameworks.json` records project-specific framework and architecture conventions.
+
+Preflight now uses changed-file standards scope when the target is inside a Git worktree. Non-Git projects keep the old full-scan behavior so bootstrap and fixture projects still get complete feedback.
+
+## Task Score
+
+Use `scale score task` to produce an algorithmic completion score.
+
+```bash
+scale score task --changed --json
+scale score task --task-id TASK-123 --level L --changed-files src/api/foo.ts,src/workflow/bar.ts
+```
+
+The score is computed from evidence, not from a model:
+
+- Verification: recent gate pass rate.
+- Architecture standards: deterministic standards doctor result.
+- Evidence completeness: persisted gate evidence records.
+- Context and memory: CodeGraph/code intelligence readiness and memory provider readiness.
+- Cost efficiency: governance ROI and cache/context savings.
+- Risk control: task level, blocking standards, and blocking extension gates.
+
+Default thresholds:
+
+- `S`: 65
+- `M`: 75
+- `L`: 85
+- `CRITICAL`: 90
+
+Use `--warn-only` when the score should be reported without failing the command.

package/docs/workflow/PROMPT_OPTIMIZATION.md

@@ -0,0 +1,44 @@
+# Prompt Optimization
+
+`scale prompt optimize` is the deterministic pre-execution prompt rewrite layer for coding tasks. It turns a raw user instruction into a structured, professional, executable prompt before the workflow asks an agent to plan or implement.
+
+## Why It Exists
+
+- Reduce model ambiguity before expensive model calls.
+- Preserve the user's real intent instead of inventing a new requirement.
+- Add missing execution structure: objective, context, boundaries, acceptance criteria, validation, deliverables, and risks.
+- Make `scale define` start from a higher-quality requirement, so downstream planning and verification have clearer input.
+
+## CLI
+
+```bash
+scale prompt optimize --input "Build a CLI prompt optimizer that rewrites raw coding requests" --json
+```
+
+Useful options:
+
+- `--language auto|zh|en`: choose output language. `auto` detects Chinese vs English.
+- `--title "Prompt Optimizer"`: add a task title to the optimized objective.
+- `--files "src/api/cli.ts,src/prompts/PromptOptimizer.ts"`: add known file scope.
+- `--service "api,workflow"`: add known service scope.
+- `--success-criteria "structured prompt,preserves intent,validation evidence"`: seed acceptance criteria.
+
+## Workflow Integration
+
+`scale define` now runs prompt optimization before ambiguity scoring and spec creation:
+
+```bash
+scale define "Prompt Optimizer" \
+  --description "用户输入后自动整理成专业 coding prompt，要保留真实意图" \
+  --success-criteria "生成结构化提示词,保留用户原始意图,输出验收标准" \
+  --json
+```
+
+The JSON result includes `promptOptimization`, and `spec.payload.what` stores the optimized prompt used by the rest of the workflow.
+
+## Governance Rules
+
+- The optimizer is algorithmic and does not call a model.
+- It must not silently change the user's scope.
+- It may add generic execution standards, validation requirements, and clarification questions.
+- Vague input is still accepted, but the `quality.missingInfo` list must expose missing acceptance criteria, affected scope, or constraints.

package/docs/workflow/README.md

@@ -18,6 +18,9 @@ make explore FILES='AGENTS.md CLAUDE.md README.md package.json' MSG='main contra
 make gate-workflow
 make gate-quality
 make verify PROFILE=default
+scale gates status --json
+scale score task --changed --json
+scale prompt optimize --input "raw coding request" --json
 ```
 
 PowerShell:
@@ -26,6 +29,10 @@ PowerShell:
 powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/verify.ps1 -Profile default
 ```
 
+See [GATES_AND_SCORE.md](GATES_AND_SCORE.md) for gate catalog visibility, architecture standards gate scope, and deterministic task scoring.
+
+See [PROMPT_OPTIMIZATION.md](PROMPT_OPTIMIZATION.md) for the deterministic prompt rewrite layer used by `scale prompt optimize` and `scale define`.
+
 ## 门禁说明
 
 | Gate | 作用 |

package/docs/workflow/node-library.md

@@ -28,7 +28,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/verify.ps1
 ## Default Verification Matrix
 
 - quick loop: `npm run build`, `npm run lint`, `npm test`
-- release loop: add `npm run typecheck`, `git diff --check`, and `npm pack --dry-run`
+- release loop: run `npm run release:check` when available; otherwise add `npm run typecheck`, `npm run smoke:setup`, `npm audit --omit=dev`, `git diff --check`, and `npm pack --dry-run`
 - product smoke: enable a real probe in `.scale/product-smoke.json` instead of treating a health endpoint as completion proof
 
 ## Branch Policy
@@ -47,6 +47,6 @@ Before a package release or demo handoff:
 
 1. Run `bash scripts/preflight/all.sh` or the PowerShell equivalent.
 2. Run `scale preflight --preflight-profile full --json`.
-3. Run `npm pack --dry-run`.
-4. Run `git diff --check`.
+3. Run `npm run release:check` when the package exposes it, or run the equivalent build/test/smoke/audit/pack commands explicitly.
+4. Run `git diff --check` if it is not already included in the release command.
 5. Confirm runtime evidence and review artifacts for M/L/CRITICAL work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hongmaple0820/scale-engine",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Executable AI agent governance with workflow gates, evidence, skill/tool orchestration, and traceable HTML artifacts",
   "repository": {
     "type": "git",
@@ -47,7 +47,9 @@
     "docs/start",
     "docs/workflow",
     "image",
-    "examples/demo-projects/agent-governance-demo"
+    "examples/demo-projects/agent-governance-demo",
+    "scripts/workflow/setup-smoke.mjs",
+    "scripts/workflow/provider-rehearsal.mjs"
   ],
   "publishConfig": {
     "access": "public"
@@ -55,10 +57,15 @@
   "scripts": {
     "build": "tsc",
     "dev": "bun --watch src/api/cli.ts",
-    "test": "vitest run --reporter dot --pool=forks --poolOptions.forks.maxForks=1 --poolOptions.forks.minForks=1",
+    "test": "vitest run --reporter dot --pool=forks --maxWorkers=4 --minWorkers=1",
+    "test:serial": "vitest run --reporter dot --pool=forks --poolOptions.forks.maxForks=1 --poolOptions.forks.minForks=1",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/**/*.ts",
-    "release:check": "npm run typecheck && npm run lint && npm test && npm run build && npm audit --omit=dev && npm pack --dry-run",
+    "smoke:setup": "node scripts/workflow/setup-smoke.mjs",
+    "smoke:providers": "node scripts/workflow/provider-rehearsal.mjs",
+    "smoke:gbrain": "node scripts/workflow/provider-rehearsal.mjs --skip-graphify --require-gbrain",
+    "smoke:graphify": "node scripts/workflow/provider-rehearsal.mjs --skip-gbrain --require-graphify",
+    "release:check": "npm run typecheck && npm run lint && npm test && npm run smoke:setup && npm run build && npm audit --omit=dev && git diff --check && npm pack --dry-run",
     "mcp": "node dist/api/mcp.js",
     "serve": "node dist/api/http.js"
   },
@@ -88,7 +95,7 @@
     "@typescript-eslint/parser": "^8.59.3",
     "eslint": "^9.0.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.5.0",
+    "typescript": "^5.9.3",
     "vitest": "^2.0.0"
   },
   "engines": {