@hongmaple0820/scale-engine 0.27.0 → 0.28.0

package/README.en.md

@@ -1,14 +1,14 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.27.0-orange?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/version-0.27.1-orange?style=flat-square" alt="version" />
   <img src="https://img.shields.io/badge/platforms-22-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.27.0-cb3837?style=flat-square&logo=npm" alt="npm" />
+  <img src="https://img.shields.io/badge/npm-0.27.1-cb3837?style=flat-square&logo=npm" alt="npm" />
 </p>
 
-# SCALE Engine v0.27.0
+# SCALE Engine v0.27.1
 
 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.
 
@@ -33,6 +33,71 @@ scale ai-os plan \
 
 This is not a claim that SCALE replaces human judgment. It is the first testable, explainable, and measurable runtime planning layer for the AI Engineering OS direction.
 
+The near-term target is `0.28.0` as a usable closed-loop enhancement: connect `ai-os plan`, `ai-os run`, verification recommendations, failure learning, dashboard, benchmark, migration, and adoption into one verifiable loop. The long-range target is an AI Engineering OS beta in 8-12 weeks, a stable governance runtime in 3-6 months, and a cross-agent engineering operating layer in 6-12 months. See the full roadmap in [AI Engineering OS Strategic Positioning](docs/AI_ENGINEERING_OS_POSITIONING.md).
+
+The current 0.27.0 beta runtime now includes the controlled run entry point: `scale ai-os run --dry-run` reuses the unified plan, produces execution steps, evidence requirements, next actions, and writes the run report to `.scale/ai-os/runs/`. When real verification is required, use guarded mode with explicit `--verify` commands. Commands run through the safe runner by default and are recorded as runtime evidence; failed verification returns a `blocked` JSON report and a non-zero CLI exit code.
+
+```bash
+scale ai-os run \
+  --task-id TASK-123 \
+  --task "Fix OAuth callback auth token handling and verify browser callback flow" \
+  --level L \
+  --files src/auth/oauth.ts,src/ui/callback.tsx \
+  --dry-run \
+  --json
+```
+
+```bash
+scale ai-os run \
+  --task-id TASK-123 \
+  --task "Fix OAuth callback auth token handling and verify browser callback flow" \
+  --level L \
+  --files src/auth/oauth.ts,src/ui/callback.tsx \
+  --mode guarded \
+  --verify "npm test -- tests/auth/oauth.test.ts" \
+  --json
+```
+
+After multiple runs, use the dashboard to summarize ready/blocked runs, verification commands, pending evidence, and failure learning:
+
+```bash
+scale ai-os status --lang en
+scale ai-os dashboard --json
+```
+
+`status` is the 0.28.0 closed-loop visibility entry point. It checks runtime directories, plan/run evidence, guarded verification, dashboard health, benchmark evidence, and the adoption report in one place.
+When guarded verification evidence is missing, it also recommends concrete commands from `.scale/verification.json` or `package.json` scripts so an agent can choose the next governed `--verify` step without guessing.
+
+Before a release or milestone review, run the fixed benchmark scenarios to compare context, memory, skill, governance, and dashboard metrics:
+
+```bash
+scale ai-os benchmark --json
+```
+
+Before adopting the AI OS beta runtime in an existing project, create or verify the AI OS runtime state directories:
+
+```bash
+scale ai-os migrate --json
+```
+
+You can also use the one-command adoption path. It runs migrate, the first dry-run, benchmark, and doctor in order, then writes the adoption report to `.scale/ai-os/adoption.json`:
+
+```bash
+scale ai-os adopt \
+  --task "Adopt AI OS runtime and generate the first governance evidence" \
+  --files "README.md,src/runtime/AiOsRuntime.ts" \
+  --json
+```
+
+For project-level readiness, run the AI OS doctor. It checks runtime directories, run history, dashboard health, benchmark freshness, and prints the next required action in English or Chinese:
+
+```bash
+scale ai-os doctor --lang en --json
+scale ai-os doctor --lang zh
+```
+
+The standard upgrade path also surfaces this readiness. `scale upgrade check --json` now includes the AI OS doctor result, and `scale upgrade plan --json` adds explicit `ai-os adopt`, `ai-os migrate`, and `ai-os doctor` steps when a project has not yet adopted the runtime state. Human-facing `scale upgrade check/plan --lang en` prints localized next commands; keep `--json` for scripts, CI, and agent integrations.
+
 ## 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.
@@ -170,6 +235,12 @@ scale upgrade apply --dir . --confirm --lang en
 scale upgrade rollback --dir . --lang en
 ```
 
+If the upgrade plan says the AI OS runtime has not been adopted yet, run:
+
+```bash
+scale ai-os adopt --dir . --task "Adopt AI OS runtime" --lang en
+```
+
 Chinese output is the default. Add `--lang en` for English prompts and English HTML plans.
 
 Upgrade rules:

package/README.md

@@ -1,14 +1,14 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.27.0-orange?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/version-0.27.1-orange?style=flat-square" alt="version" />
   <img src="https://img.shields.io/badge/platforms-22-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.27.0-cb3837?style=flat-square&logo=npm" alt="npm" />
+  <img src="https://img.shields.io/badge/npm-0.27.1-cb3837?style=flat-square&logo=npm" alt="npm" />
 </p>
 
-# SCALE Engine v0.27.0
+# SCALE Engine v0.27.1
 
 SCALE Engine 让 AI Agent 不再只靠“自觉”遵守工程规范。它把探索、规划、实现、验证、评审、发版这些要求变成可执行的命令、门禁和证据文件，让人类可以看见 Agent 做了什么、跳过了什么、为什么能交付或不能交付。
 
@@ -33,6 +33,72 @@ scale ai-os plan \
 
 这不是“完全替代人类判断”的声明；它是把 AI Engineering OS 的核心闭环先做成可测试、可解释、可度量的运行时规划层。
 
+短期目标是把 `0.28.0` 做成可用闭环增强版：让 `ai-os plan`、`ai-os run`、验证建议、失败沉淀、Dashboard、benchmark、迁移和 adoption 串成可验证闭环。远景目标是 8-12 周形成 AI Engineering OS beta，3-6 个月进入稳定治理运行时，6-12 个月沉淀为跨 Agent 的工程操作层。完整路线图见 [AI Engineering OS 战略定位](docs/AI_ENGINEERING_OS_POSITIONING.md)。
+
+当前 0.27.0 beta runtime 已包含受控运行入口：`scale ai-os run --dry-run` 会复用统一 plan，生成执行步骤、证据要求、下一步动作，并把运行报告写入 `.scale/ai-os/runs/`。需要真实验证时可切到 guarded 模式并显式传入 `--verify`，命令默认通过 safe runner 执行并写入 runtime evidence；验证失败时 JSON 报告会返回 `blocked`，CLI 退出码为非零。
+
+```bash
+scale ai-os run \
+  --task-id TASK-123 \
+  --task "修复 OAuth callback auth token 并验证浏览器回调流程" \
+  --level L \
+  --files src/auth/oauth.ts,src/ui/callback.tsx \
+  --dry-run \
+  --json
+```
+
+```bash
+scale ai-os run \
+  --task-id TASK-123 \
+  --task "修复 OAuth callback auth token 并验证浏览器回调流程" \
+  --level L \
+  --files src/auth/oauth.ts,src/ui/callback.tsx \
+  --mode guarded \
+  --verify "npm test -- tests/auth/oauth.test.ts" \
+  --json
+```
+
+运行多次后可以用 dashboard 汇总 ready/blocked、验证命令、pending evidence 和 failure learning：
+
+```bash
+scale ai-os status --lang zh
+scale ai-os dashboard --json
+```
+
+当 guarded verification 证据缺失时，`status` 会从 `.scale/verification.json` 或 `package.json` scripts 推导具体验证命令，帮助 agent 自主选择下一条受治理的 `--verify` 步骤。
+
+`status` 是 0.28.0 闭环可见性入口，会一次性检查 runtime 目录、plan/run 证据、guarded verification、dashboard health、benchmark 和 adoption 报告是否齐全。
+
+发版或阶段验收前，用 benchmark 固定样例对比 context、memory、skill、governance 和 dashboard 指标：
+
+```bash
+scale ai-os benchmark --json
+```
+
+旧项目接入 AI OS beta runtime 前，可先创建或核验 AI OS 运行态目录：
+
+```bash
+scale ai-os migrate --json
+```
+
+也可以使用一键接入入口，它会按顺序执行 migrate、首个 dry-run、benchmark、doctor，并把采用报告写入 `.scale/ai-os/adoption.json`：
+
+```bash
+scale ai-os adopt \
+  --task "接入 AI OS runtime 并生成首份治理证据" \
+  --files "README.md,src/runtime/AiOsRuntime.ts" \
+  --json
+```
+
+项目级就绪检查可使用 AI OS doctor。它会检查运行态目录、运行历史、dashboard 健康度、benchmark 新鲜度，并按中英文输出下一步动作：
+
+```bash
+scale ai-os doctor --lang zh --json
+scale ai-os doctor --lang en
+```
+
+标准升级入口也会带出这项检查。`scale upgrade check --json` 会包含 AI OS doctor 结果；当项目尚未接入运行态目录时，`scale upgrade plan --json` 会补充明确的 `ai-os adopt`、`ai-os migrate` 和 `ai-os doctor` 步骤。面向人使用的 `scale upgrade check/plan --lang zh` 会输出中文 task 和中文下一步命令；`--json` 保留给脚本、CI 和 Agent 集成。
+
 ## 先怎么学
 
 如果你第一次接触 SCALE，不要从完整命令列表开始读。按这个顺序更容易掌握：
@@ -176,6 +242,12 @@ scale tools outdated --dir .
 scale skill outdated --dir .
 ```
 
+如果升级计划提示 AI OS runtime 尚未接入，先运行：
+
+```bash
+scale ai-os adopt --dir . --task "接入 AI OS runtime" --lang zh
+```
+
 升级原则：
 
 - `scale upgrade check` 读取 `.scale/governance.lock.json`，判断当前项目是干净、缺文件、模板过期，还是存在本地改动。