@hongmaple0820/scale-engine 0.46.0 → 0.48.0

package/docs/guides/FAST_COMMIT_GUIDE.md

@@ -0,0 +1,136 @@
+# Fast-lane 快速提交指南
+
+**适用场景**: S 级任务（typo、注释、配置改动、文档修正）
+**目标耗时**: <120s（vs 标准流程 200s+）
+
+---
+
+## 什么时候用 Fast-lane
+
+| 用 Fast-lane | 不用 Fast-lane |
+|---|---|
+| 修 typo | 新增功能 |
+| 改注释 | 修改业务逻辑 |
+| 调配置值 | 涉及安全/认证 |
+| 更新文档链接 | 数据库变更 |
+| 格式化代码 | 架构调整 |
+
+**判断标准**: 改动不涉及 `src/` 下的业务代码，或改动量 <10 行且无逻辑变化。
+
+---
+
+## 使用方法
+
+### Shell（推荐）
+
+```bash
+bash scripts/gates/all.sh --fast-lane
+```
+
+### Makefile
+
+```bash
+make gate-fast-lane
+```
+
+### CLI
+
+```bash
+scale preflight --preflight-profile fast-lane
+```
+
+---
+
+## Fast-lane 运行哪些 Gate
+
+| Gate | 名称 | 说明 |
+|------|------|------|
+| G3 | TDD Evidence | 检查测试文件是否同步修改 |
+| G0 | Build | 构建必须通过 |
+| G4 | Lint | 代码风格检查 |
+| G5 | Tests | 测试必须通过 |
+
+### 跳过的 Gate
+
+| Gate | 名称 | 为什么跳过 |
+|------|------|-----------|
+| G1 | Exploration | S 级不需要探索记录 |
+| G2 | Planning | S 级不需要规划文档 |
+| G6 | Coverage | S 级改动小，覆盖率影响可忽略 |
+| G7 | Security | S 级不涉及安全变更 |
+| G8 | Doc Standards | 文档标准在 G4 lint 中覆盖 |
+| G9-G15 | Meta Governance | 元治理对 S 级过重 |
+| G16-G22 | Enhanced Gates | 增强门禁对 S 级过重 |
+
+---
+
+## 工作流对比
+
+```
+标准流程 (M/L 级):
+  explore → plan → execute → gate-workflow → gate-quality → verify
+  耗时: ~200s
+
+Fast-lane (S 级):
+  edit → gate-fast-lane → commit
+  耗时: <120s
+```
+
+---
+
+## 示例
+
+### 修复文档 typo
+
+```bash
+# 1. 修改文件
+vim README.md
+
+# 2. 跑 fast-lane
+make gate-fast-lane
+
+# 3. 提交
+git add README.md
+git commit -m "docs: fix typo in README"
+```
+
+### 调整配置值
+
+```bash
+# 1. 修改配置
+vim .scale/verification.json
+
+# 2. 跑 fast-lane
+make gate-fast-lane
+
+# 3. 提交
+git add .scale/verification.json
+git commit -m "chore: update verification config"
+```
+
+---
+
+## 常见问题
+
+### Q: Fast-lane 可以用于 M/L 级任务吗？
+
+**不行。** M/L 级任务必须走标准流程（gate-workflow + gate-quality）。Fast-lane 仅适用于 S 级。
+
+### Q: Fast-lane 失败了怎么办？
+
+如果 G0/G3/G4/G5 任何一个失败，说明改动有问题，需要修复后重跑。Fast-lane 失败不应该被忽略。
+
+### Q: 如何确认任务是 S 级？
+
+按 SCALE 任务分级：
+- **S 级**: ≤30 行改动 / typo / 注释 / 配置
+- **M 级**: 30-200 行 / 2-5 文件 / 有逻辑变化
+- **L 级**: ≥200 行 / 跨模块 / 架构变更
+
+---
+
+## 相关文档
+
+- [DEVELOPMENT_WORKFLOW.md](DEVELOPMENT_WORKFLOW.md) - 完整开发流程
+- [GATES_AND_SCORE.md](../workflow/GATES_AND_SCORE.md) - 门禁定义
+- [IMPROVEMENT_ROADMAP.md](../workflow/IMPROVEMENT_ROADMAP.md) - 改进项 #1

package/docs/guides/LEARNING_PATH.md

@@ -0,0 +1,237 @@
+# SCALE Engine 学习路径
+
+**目标**: 从零到精通，5 个级别，每级 <1 小时
+
+---
+
+## Level 1: 体验者 (Explorer)
+
+**目标**: 跑通第一个 gate，理解 SCALE 是什么  
+**耗时**: 15 分钟  
+**前置**: 已安装 Node.js 18+
+
+### 步骤
+
+```bash
+# 1. 安装 SCALE Engine
+npm install -g @hongmaple0820/scale-engine
+
+# 2. 进入你的项目
+cd your-project
+
+# 3. 一键初始化
+scale init --quick
+
+# 4. 跑一次 preflight
+scale preflight
+```
+
+### 你会学到
+- SCALE 的门禁系统是什么
+- `.scale/` 目录的作用
+- `preflight` 和 `verify` 的区别
+
+### 通关标准
+- [ ] `scale preflight` 输出 PASS
+- [ ] 能解释 G0/G4/G5 分别检查什么
+
+---
+
+## Level 2: 使用者 (User)
+
+**目标**: 日常开发中使用 SCALE 管理任务和门禁  
+**耗时**: 30 分钟  
+**前置**: 完成 Level 1
+
+### 步骤
+
+```bash
+# 1. 创建第一个任务
+scale create "fix: typo in README" --level S
+
+# 2. 使用 fast-lane 提交 S 级改动
+make gate-fast-lane
+
+# 3. 创建 M 级任务，体验完整流程
+scale create "feat: add user auth" --level M
+
+# 4. 运行完整验证
+make gate-workflow
+make gate-quality
+```
+
+### 你会学到
+- 任务分级 (S/M/L/CRITICAL)
+- Fast-lane vs 标准流程
+- 如何读 gate 报告
+
+### 通关标准
+- [ ] 成功用 fast-lane 提交一个 S 级任务
+- [ ] 成功用标准流程完成一个 M 级任务
+- [ ] 能说出 S/M/L 级的区别
+
+---
+
+## Level 3: 配置者 (Configurator)
+
+**目标**: 自定义 SCALE 行为，适配项目需求  
+**耗时**: 45 分钟  
+**前置**: 完成 Level 2
+
+### 步骤
+
+```bash
+# 1. 查看当前配置
+scale config show
+
+# 2. 切换 profile
+scale config profile standard
+
+# 3. 配置验证命令
+# 编辑 .scale/verification.json
+# 添加自定义 services 和 commands
+
+# 4. 设置第三方能力
+scale setup --pack full --apply
+
+# 5. 运行 doctor 检查配置健康
+scale doctor
+```
+
+### 你会学到
+- 4 种 profile (minimal/standard/advanced/china-local)
+- verification.json 的结构
+- 如何配置 skills、memory、knowledge providers
+- doctor 诊断工具
+
+### 通关标准
+- [ ] 修改 verification.json 添加自定义 service
+- [ ] `scale doctor` 输出 healthy
+- [ ] 理解 profile 和 governance pack 的关系
+
+---
+
+## Level 4: 治理者 (Governor)
+
+**目标**: 掌握高级治理功能，包括 meta-governance 和 evolution  
+**耗时**: 60 分钟  
+**前置**: 完成 Level 3
+
+### 步骤
+
+```bash
+# 1. 查看所有门禁状态
+scale gates status
+
+# 2. 启用 meta-governance (G9-G15)
+scale governance mode --task "governance setup" --files ".scale/*"
+
+# 3. 运行 Cortex 进化
+scale cortex evolve --project .
+
+# 4. 查看 evolution 报告
+scale evolution stats
+
+# 5. 配置 resource policy
+# 编辑 .scale/resource-policy.json
+# 设置模块 owner 和权限
+
+# 6. 运行完整 meta-governance
+bash scripts/gates/all.sh --all
+```
+
+### 你会学到
+- 23 个门禁的完整体系 (G0-G22)
+- Meta-governance 的作用
+- Cortex 进化循环 (observe → reflect → extract → inject)
+- Resource policy 和模块治理
+
+### 通关标准
+- [ ] 能解释 G9-G15 各检查什么
+- [ ] 运行过 cortex evolve 并理解输出
+- [ ] 配置过 resource-policy.json
+
+---
+
+## Level 5: 贡献者 (Contributor)
+
+**目标**: 为 SCALE Engine 本身贡献代码  
+**耗时**: 60 分钟  
+**前置**: 完成 Level 4
+
+### 步骤
+
+```bash
+# 1. 克隆 SCALE Engine 仓库
+git clone https://github.com/hongmaple0820/scale-engine.git
+cd scale-engine
+
+# 2. 阅读开发者指南
+cat docs/guides/GETTING_STARTED.md
+cat docs/guides/DEVELOPMENT_WORKFLOW.md
+
+# 3. 跑通开发环境
+make preflight
+make verify PROFILE=default
+
+# 4. 理解门禁系统源码
+# src/workflow/GateCatalog.ts — 门禁定义
+# src/workflow/GateSystem.ts — 门禁执行
+# scripts/gates/all.sh — Shell 入口
+
+# 5. 提交你的第一个 PR
+# 遵循 DEVELOPMENT_WORKFLOW.md 的 5 阶段流程
+```
+
+### 你会学到
+- SCALE Engine 的架构
+- 如何添加新门禁
+- 如何添加新 CLI 命令
+- 贡献流程和规范
+
+### 通关标准
+- [ ] 能解释 GateCatalog.ts 的结构
+- [ ] 成功运行 `make gate` 并理解输出
+- [ ] 提交过至少一个 PR
+
+---
+
+## 快速参考
+
+| 级别 | 名称 | 耗时 | 核心技能 |
+|------|------|------|----------|
+| L1 | 体验者 | 15min | 安装、初始化、跑 preflight |
+| L2 | 使用者 | 30min | 任务分级、fast-lane、标准流程 |
+| L3 | 配置者 | 45min | profile、verification、doctor |
+| L4 | 治理者 | 60min | meta-governance、cortex、resource policy |
+| L5 | 贡献者 | 60min | 源码、架构、PR 流程 |
+
+**总耗时**: ~3.5 小时从零到贡献者
+
+---
+
+## 常见问题
+
+### Q: 我应该从哪个级别开始？
+
+如果你是第一次接触 SCALE，从 Level 1 开始。如果你已有 CI/CD 经验，可以跳到 Level 2。
+
+### Q: 每个级别可以跳过吗？
+
+不建议。每个级别建立在前一级的基础上。跳级可能导致配置错误或误解门禁含义。
+
+### Q: 学完后我能做什么？
+
+- Level 1-2: 日常开发中使用 SCALE
+- Level 3: 为团队定制 SCALE 配置
+- Level 4: 管理多项目治理
+- Level 5: 为 SCALE Engine 贡献代码
+
+---
+
+## 相关文档
+
+- [GETTING_STARTED.md](GETTING_STARTED.md) - 开发者快速上手
+- [DEVELOPMENT_WORKFLOW.md](DEVELOPMENT_WORKFLOW.md) - 完整开发流程
+- [FAST_COMMIT_GUIDE.md](FAST_COMMIT_GUIDE.md) - S 级快速提交
+- [MIGRATION.md](MIGRATION.md) - 版本迁移指南

package/docs/guides/UPGRADE_AUTOMATION.md

@@ -0,0 +1,199 @@
+# SCALE Engine 升级自动化指南
+
+**版本**: v0.46.0+
+
+---
+
+## 概述
+
+SCALE Engine 提供安全的升级流程，从检查到应用到回滚，每一步都有保护。
+
+```
+scale upgrade check       → 查看当前状态
+scale upgrade recommend   → 自动评估风险，推荐操作
+scale upgrade plan        → 生成详细计划 (HTML)
+scale upgrade apply       → 安全应用 (带备份)
+scale upgrade rollback    → 回滚到上一版本
+```
+
+---
+
+## 快速升级 (推荐)
+
+```bash
+# 1. 一键推荐 + 自动应用
+scale upgrade recommend --dir . --auto-apply
+
+# 等价于:
+#   scale upgrade recommend --dir .   # 评估风险
+#   scale upgrade apply --dir . --confirm --auto-backup  # 安全应用
+```
+
+---
+
+## 命令详解
+
+### `scale upgrade recommend`
+
+自动分析升级风险，计算风险分数，推荐操作。
+
+```bash
+scale upgrade recommend --dir .
+scale upgrade recommend --dir . --json
+scale upgrade recommend --dir . --auto-apply
+```
+
+**输出示例**:
+```
+SCALE 升级推荐
+  项目: /path/to/project
+  🟢 风险分数: 2 (low)
+  ✅ 推荐: safe-to-apply
+  摘要: 2 step(s), risk score 2; SCALE Engine up to date
+  应用模式: safe
+  建议命令:
+    scale upgrade apply --dir . --confirm --auto-backup
+    scale preflight --preflight-profile quick
+```
+
+**风险分数**:
+- 每个步骤根据风险等级计分: low=1, medium=3, high=5
+- 每个 blocker 额外 +5 分
+- 总分 <4 = low, 4-9 = medium, >=10 = high
+
+**推荐类型**:
+- `safe-to-apply`: 无 blocker，applyMode=safe，可直接应用
+- `review-first`: 有本地改动或需要人工审查
+- `blocked`: 有 blocker，需先解决
+
+---
+
+### `scale upgrade apply --auto-backup`
+
+应用升级前自动创建 git 分支备份。
+
+```bash
+scale upgrade apply --dir . --confirm --auto-backup
+```
+
+**自动备份流程**:
+1. 检查是否在 git 仓库中
+2. 如有未提交更改，先 `git stash`
+3. 创建备份分支 `scale-backup-<timestamp>`
+4. 恢复 stash (如有)
+5. 继续正常的文件级备份和升级应用
+
+**回滚到 git 备份**:
+```bash
+# 查看备份分支
+git branch | grep scale-backup
+
+# 回滚到备份
+git reset --hard scale-backup-2026-06-03T12-00-00-000Z
+```
+
+---
+
+### `scale upgrade check`
+
+检查当前升级状态。
+
+```bash
+scale upgrade check --dir .
+scale upgrade check --dir . --json
+```
+
+**状态说明**:
+- `clean`: 一切最新，无需升级
+- `updates-available`: 有可用更新
+- `local-changes`: 生成文件有本地改动
+- `missing-lock`: 缺少 governance.lock.json
+
+---
+
+### `scale upgrade plan`
+
+生成详细的非破坏性升级计划。
+
+```bash
+scale upgrade plan --dir .
+scale upgrade plan --dir . --html  # 生成 HTML 报告
+```
+
+---
+
+### `scale upgrade rollback`
+
+回滚最近一次升级。
+
+```bash
+scale upgrade rollback --dir .
+```
+
+---
+
+## 升级故障排查
+
+### 常见问题
+
+#### 1. `applyMode: manual-review`
+
+**原因**: 生成文件有本地改动，SCALE 不会自动覆盖。
+
+**解决**:
+```bash
+# 查看哪些文件有改动
+scale upgrade check --dir .
+
+# 手动审查改动
+git diff .scale/
+
+# 确认后强制应用
+scale upgrade apply --dir . --confirm
+```
+
+#### 2. `missing-governance-lock`
+
+**原因**: 没有 governance.lock.json，SCALE 无法追踪文件状态。
+
+**解决**:
+```bash
+scale init --governance-pack standard
+```
+
+#### 3. Git 备份失败
+
+**原因**: 不在 git 仓库中，或 git 配置问题。
+
+**解决**: 文件级备份仍会创建在 `.scale/backups/` 中，可手动回滚:
+```bash
+scale upgrade rollback --dir .
+```
+
+#### 4. 升级后测试失败
+
+**解决**:
+```bash
+# 回滚
+scale upgrade rollback --dir .
+
+# 或回滚到 git 备份
+git reset --hard scale-backup-<timestamp>
+```
+
+---
+
+## 最佳实践
+
+1. **总是先 recommend**: `scale upgrade recommend --dir .` 了解风险
+2. **使用 --auto-backup**: 升级前创建 git 备份点
+3. **升级后跑 preflight**: `scale preflight --preflight-profile quick`
+4. **保留备份分支**: 确认升级无问题后再删除: `git branch -d scale-backup-<timestamp>`
+
+---
+
+## 相关文档
+
+- [MIGRATION.md](MIGRATION.md) — 版本迁移指南
+- [DEVELOPMENT_WORKFLOW.md](DEVELOPMENT_WORKFLOW.md) — 开发流程
+- [PERFORMANCE_BASELINE.md](../PERFORMANCE_BASELINE.md) — 性能基准

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hongmaple0820/scale-engine",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Executable AI agent governance with workflow gates, evidence, skill/tool orchestration, and traceable HTML artifacts",
   "repository": {
     "type": "git",
@@ -82,6 +82,7 @@
     "@types/better-sqlite3": "^7.6.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.14.0",
+    "@typescript-eslint/eslint-plugin": "^8.60.1",
     "@typescript-eslint/parser": "^8.59.3",
     "eslint": "^9.0.0",
     "tsx": "^4.21.0",