@hongmaple0820/scale-engine 0.21.1 → 0.23.0

package/README.en.md

@@ -1,23 +1,47 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.20.0-orange?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/version-0.23.0-orange?style=flat-square" alt="version" />
   <img src="https://img.shields.io/badge/platforms-16-blue?style=flat-square" alt="platforms" />
   <img src="https://img.shields.io/badge/agents-12-blue?style=flat-square" alt="agents" />
   <img src="https://img.shields.io/badge/workflows-10-green?style=flat-square" alt="workflows" />
   <img src="https://img.shields.io/badge/detectors-19-red?style=flat-square" alt="detectors" />
   <img src="https://img.shields.io/badge/tests-verified-brightgreen?style=flat-square" alt="tests" />
-  <img src="https://img.shields.io/badge/npm-0.20.0-cb3837?style=flat-square&logo=npm" alt="npm" />
-</p>
-
-# SCALE Engine v0.20.0
+  <img src="https://img.shields.io/badge/npm-0.23.0-cb3837?style=flat-square&logo=npm" alt="npm" />
+</p>
+
+# SCALE Engine v0.23.0
 
 SCALE Engine makes AI coding agents follow engineering rules through executable workflow gates, evidence files, and review constraints instead of relying on prompt discipline alone. It helps humans see what the agent explored, planned, verified, skipped, and why a task is or is not ready to ship.
 
-Repository: https://github.com/hongmaple0820/scale-engine
-Mirror: https://gitee.com/hongmaple/scale-engine
-npm: https://www.npmjs.com/package/@hongmaple0820/scale-engine
-Language: [English](README.en.md) | [Chinese](README.md)
-
-## What It Solves
+Repository: https://github.com/hongmaple0820/scale-engine
+Mirror: https://gitee.com/hongmaple/scale-engine
+npm: https://www.npmjs.com/package/@hongmaple0820/scale-engine
+Language: [English](README.en.md) | [Chinese](README.md)
+
+## Community
+
+SCALE Engine is an engineering workflow governance project for real AI-agent delivery. Contributions, issues, PRs, governance-pack ideas, and field reports are welcome through the source repositories. Chinese users can also follow the WeChat public account for updates, examples, and community entry points.
+
+| Platform | Link | Purpose |
+| --- | --- | --- |
+| GitHub | [https://github.com/hongmaple0820/scale-engine](https://github.com/hongmaple0820/scale-engine) | Source, issues, and PRs |
+| Gitee | [https://gitee.com/hongmaple/scale-engine](https://gitee.com/hongmaple/scale-engine) | China mirror and feedback |
+| npm | [https://www.npmjs.com/package/@hongmaple0820/scale-engine](https://www.npmjs.com/package/@hongmaple0820/scale-engine) | CLI package |
+
+<p align="center">
+  <img src="image/wechat-public.jpg" alt="SCALE Engine WeChat public account" width="220" />
+</p>
+
+## Sponsorship
+
+If SCALE Engine saves engineering governance time for your team, or helps move AI-agent work into a verifiable, reviewable, and releasable loop, voluntary sponsorship is welcome. Sponsorship supports maintenance, examples, documentation, test coverage, and community support. It is not a commercial support contract and does not change issue or PR priority.
+
+<p align="center">
+  <img src="image/wxPay.jpg" alt="Sponsor with WeChat Pay" width="220" />
+  &nbsp;&nbsp;
+  <img src="image/zfb.jpg" alt="Sponsor with Alipay" width="220" />
+</p>
+
+## What It Solves
 
 AI coding becomes hard when agents must behave consistently across real teams and real repositories:
 
@@ -55,8 +79,8 @@ scale context init --name "Scale Demo"
 scale context grill --task-id 2026-05-18-oauth-hardening --task "Harden OAuth callback"
 scale diagnose plan --task-id 2026-05-18-oauth-hardening --symptom "callback returns 500 when state expires"
 scale tdd slice --task-id 2026-05-18-oauth-hardening --behavior "reject expired OAuth state" --public-interface "GET /oauth/callback" --failing-test "expired state returns 401" --test-file tests/oauth.test.ts --impl-files src/oauth.ts
-scale artifact render --task-id 2026-05-18-oauth-hardening --artifact-dir .planning/tasks/2026-05-18-oauth-hardening
-scale artifact doctor --artifact-dir .planning/tasks/2026-05-18-oauth-hardening
+scale artifact render --task-id 2026-05-18-oauth-hardening --artifact-dir .planning/tasks/2026-05-18-oauth-hardening
+scale artifact doctor --artifact-dir .planning/tasks/2026-05-18-oauth-hardening
 ```
 
 Read [Quickstart](docs/start/quickstart.md) and [Agent Governance Demo](docs/start/agent-governance-demo.md) for the complete walkthrough.
@@ -182,6 +206,8 @@ SCALE Engine uses multiple enforcement layers:
 
 The `ship` command no longer stages the whole workspace. It stages only files covered by passing review records and blocks if new reviewable files appear after review.
 
+Git branch governance follows a GitLab Flow variant: short branches merge into `dev`, verified releases land on `master`, and production publishing is triggered by user-created `vX.Y.Z` tags on `master`. `scale ship` blocks direct governed commits on `dev`, `master`, `main`, or detached HEAD, and temporary worktree cleanup is blocked when the branch still has unpushed or unmerged commits. See [docs/GITLAB_FLOW.md](docs/GITLAB_FLOW.md).
+
 G7 `SecurityGate` includes a lightweight built-in scan for hardcoded secrets, private keys, disabled TLS verification, `eval`/`Function`, raw HTML injection, dangerous shell commands, shell execution, and empty `catch` blocks. Compatibility mode blocks CRITICAL findings; strict mode also blocks HIGH findings.
 
 ## Supported Platforms

package/README.md

@@ -1,35 +1,61 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.20.0-orange?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/version-0.23.0-orange?style=flat-square" alt="version" />
   <img src="https://img.shields.io/badge/platforms-16-blue?style=flat-square" alt="platforms" />
   <img src="https://img.shields.io/badge/agents-12-blue?style=flat-square" alt="agents" />
   <img src="https://img.shields.io/badge/workflows-10-green?style=flat-square" alt="workflows" />
   <img src="https://img.shields.io/badge/detectors-19-red?style=flat-square" alt="detectors" />
   <img src="https://img.shields.io/badge/tests-verified-brightgreen?style=flat-square" alt="tests" />
-  <img src="https://img.shields.io/badge/npm-0.20.0-cb3837?style=flat-square&logo=npm" alt="npm" />
-</p>
-
-# SCALE Engine v0.20.0
-
-SCALE Engine 让 AI Agent 不再只靠“自觉”遵守工程规范。它把探索、规划、实现、验证、评审、发版这些要求变成可执行的命令、门禁和证据文件，让人类可以看见 Agent 做了什么、跳过了什么、为什么不能交付。
-
-源码仓库：https://github.com/hongmaple0820/scale-engine
-国内镜像：https://gitee.com/hongmaple/scale-engine
-npm：https://www.npmjs.com/package/@hongmaple0820/scale-engine
-语言：[中文](README.md) | [English](README.en.md)
-
-## 🌐 社区与推广
-
-### 链接
-
-| 平台 | 链接 | 说明 |
-|------|------|------|
-| 🌐 **官网** | [https://scale-os.vercel.app](https://scale-os.vercel.app) | 在线配置器 + 完整文档 |
-| 📦 **GitHub** | [https://github.com/hongmaple0820/scale-os](https://github.com/hongmaple0820/scale-os) | 源码 + Issues + PR |
-| 🔧 **Gitee** | [https://gitee.com/hongmaple/scale-engine](https://gitee.com/hongmaple/scale-engine) | 国内镜像 |
-| 📦 **npm** | [https://www.npmjs.com/package/@hongmaple0820/scale-engine](https://www.npmjs.com/package/@hongmaple0820/scale-engine) | 包下载 |
-| 🧰 **项目脚手架** | [https://github.com/hongmaple0820/project-scaffold](https://github.com/hongmaple0820/project-scaffold) | 工程化工作流实践脚手架 |
-
-## 它解决什么问题
+  <img src="https://img.shields.io/badge/npm-0.23.0-cb3837?style=flat-square&logo=npm" alt="npm" />
+</p>
+
+# SCALE Engine v0.23.0
+
+SCALE Engine 让 AI Agent 不再只靠“自觉”遵守工程规范。它把探索、规划、实现、验证、评审、发版这些要求变成可执行的命令、门禁和证据文件，让人类可以看见 Agent 做了什么、跳过了什么、为什么能交付或不能交付。
+
+源码仓库：https://github.com/hongmaple0820/scale-engine
+国内镜像：https://gitee.com/hongmaple/scale-engine
+npm：https://www.npmjs.com/package/@hongmaple0820/scale-engine
+语言：[中文](README.md) | [English](README.en.md)
+
+## 先怎么学
+
+如果你第一次接触 SCALE，不要从完整命令列表开始读。按这个顺序更容易掌握：
+
+| 目标 | 入口 | 你应该学会什么 |
+| --- | --- | --- |
+| 先跑起来 | [3 分钟快速开始](docs/start/quickstart.md) | 安装 CLI、初始化治理文件、运行 preflight |
+| 看完整闭环 | [官方 Demo Walkthrough](docs/start/agent-governance-demo.md) | 任务上下文、诊断、TDD、artifact 和验证证据如何串起来 |
+| 接入已有项目 | [SCALE 工作流升级指南](docs/start/workflow-upgrade.md) | `init`、`upgrade check/plan/apply`、本地 `make` 包装入口怎么用 |
+| 选择治理包 | 本文的 Governance Pack 章节 | 不同项目形态应该选哪个 pack |
+| 维护或扩展 SCALE | [docs/README.md](docs/README.md) | 文档地图、内部模块和长期维护资料 |
+
+一句话理解：SCALE 不是让 Agent 多写文档，而是让“做了什么、验证了什么、没验证什么”可追踪。
+
+## 社区与推广
+
+SCALE Engine 是一个面向真实工程交付的 Agent 工作流治理项目。欢迎通过源码仓库提交 Issue、PR、场景反馈和治理包改进建议；中文用户也可以关注公众号获取更新、示例和社区入口。
+
+| 平台 | 链接 | 说明 |
+|------|------|------|
+| GitHub | [https://github.com/hongmaple0820/scale-engine](https://github.com/hongmaple0820/scale-engine) | 源码、Issues、PR |
+| Gitee | [https://gitee.com/hongmaple/scale-engine](https://gitee.com/hongmaple/scale-engine) | 国内镜像与反馈 |
+| npm | [https://www.npmjs.com/package/@hongmaple0820/scale-engine](https://www.npmjs.com/package/@hongmaple0820/scale-engine) | CLI 包下载 |
+
+<p align="center">
+  <img src="image/wechat-public.jpg" alt="SCALE Engine 微信公众号" width="220" />
+</p>
+
+## 赞助与支持
+
+如果 SCALE Engine 节省了你的工程治理时间，或帮助你的团队把 AI Agent 工作流落到可验证、可复盘、可发版的闭环里，欢迎自愿赞助。赞助用于持续维护、示例项目、文档、测试矩阵和社区支持，不构成商业支持承诺，也不会改变 Issue 或 PR 的处理优先级。
+
+<p align="center">
+  <img src="image/wxPay.jpg" alt="微信赞助" width="220" />
+  &nbsp;&nbsp;
+  <img src="image/zfb.jpg" alt="支付宝赞助" width="220" />
+</p>
+
+## 它解决什么问题
 
 AI 编码真正难的不是“写代码”，而是持续稳定地遵守工程纪律：
 
@@ -67,8 +93,8 @@ scale context init --name "Scale Demo"
 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
-scale artifact render --task-id 2026-05-18-oauth-hardening --artifact-dir .planning/tasks/2026-05-18-oauth-hardening
-scale artifact doctor --artifact-dir .planning/tasks/2026-05-18-oauth-hardening
+scale artifact render --task-id 2026-05-18-oauth-hardening --artifact-dir .planning/tasks/2026-05-18-oauth-hardening
+scale artifact doctor --artifact-dir .planning/tasks/2026-05-18-oauth-hardening
 ```
 
 完整教程见 [3 分钟快速开始](docs/start/quickstart.md) 和 [官方 Demo Walkthrough](docs/start/agent-governance-demo.md)。
@@ -124,9 +150,11 @@ scale skill outdated --dir .
 - `scale tools outdated` 和 `scale skill outdated` 只列出更新面、来源、信任等级和安全策略，不做自动安装。
 - 第三方社区来源默认人工评审，高权限桌面自动化默认阻断自动升级。
 
-详细说明见 [升级管理](docs/UPGRADE_MANAGEMENT.md)。
-
-## Governance Pack
+详细说明见 [升级管理](docs/UPGRADE_MANAGEMENT.md)。
+
+新用户和项目维护者可先看 [SCALE workflow upgrade guide](docs/start/workflow-upgrade.md)，它把 `scale init --interactive`、`scale upgrade check/plan/apply/rollback` 和仓库本地 `make workflow-upgrade-*` 入口放在一条可执行路径里。
+
+## Governance Pack
 
 在已有项目中安装治理工作流：
 
@@ -372,6 +400,8 @@ scale evolution hooks <session-id> --json
 
 `ship` 不再执行 `git add .`。它只会暂存已通过 review 记录覆盖的文件；如果 review 后出现新的可 review 变更，`ship` 会阻断并要求重新 review。
 
+Git 分支采用 GitLab Flow 变体：短分支合入 `dev`，验证后进入 `master`，生产发布由 `master` 上的 `vX.Y.Z` tag 触发。`scale ship` 会阻断在 `dev`、`master`、`main` 或 detached HEAD 上直接创建治理提交，并在临时 worktree 存在未推送或未合并提交时阻断清理。完整规则见 [docs/GITLAB_FLOW.md](docs/GITLAB_FLOW.md)。
+
 G7 `SecurityGate` 内置轻量安全扫描，覆盖硬编码密钥、私钥、TLS 校验关闭、`eval`/`Function`、原始 HTML 注入、危险 shell 命令、shell 执行和空 `catch` 等模式。兼容模式只阻断 CRITICAL；严格模式会同时阻断 HIGH。
 
 ## 支持的平台与角色