@hongmaple0820/scale-engine 0.25.0 → 0.27.0

package/docs/start/workflow-upgrade.md

@@ -17,7 +17,7 @@ SCALE 把更新分成三层：
 | 层级 | 命令支持 | 默认行为 |
 | --- | --- | --- |
 | SCALE CLI | `npm install -g @hongmaple0820/scale-engine@latest` | 用户显式安装或升级 |
-| 生成的工作流文件 | `scale upgrade check/plan/apply/rollback` | 先安全检查和生成计划，只有 `--confirm` 才应用 |
+| 生成的工作流文件 | `scale upgrade check/plan/apply/rollback` | 先安全检查和生成计划；干净的受管文件可自动刷新，有本地改动则进入人工审阅 |
 | 项目级验证 | 仓库 `make` 目标和 `scripts/workflow/*` | 必须保留项目语义；SCALE 不猜业务路由、凭据和服务拓扑 |
 
 这意味着工作流适配不是 Codex-only。Codex 可以帮助审阅和处理 `manual-review`，但常规路径应该是命令驱动。
@@ -40,13 +40,14 @@ scale init --interactive
 ```bash
 scale init --governance-pack standard
 scale init --governance-pack project-scaffold
+scale init --governance-pack scale-engine-repo
 scale init --governance-pack moe-workspace
 scale init --governance-pack go-service-matrix
 scale init --governance-pack node-library
 scale init --governance-pack frontend-app
 ```
 
-不确定时先用 `standard`。仓库形态明确时再用更具体的 pack。
+不确定时先用 `standard`。仓库形态明确时再用更具体的 pack。`scale-engine-repo` 是 `scale-engine` 仓库自身的自托管 pack，不是普通业务仓库默认选项。
 
 ## 更新已有工作流
 
@@ -59,6 +60,13 @@ scale upgrade apply --dir . --confirm
 scale preflight --dir . --service all --preflight-profile quick
 ```
 
+默认输出是中文。需要英文命令提示或英文 HTML 计划时加 `--lang en`：
+
+```bash
+scale upgrade check --dir . --lang en
+scale upgrade plan --dir . --html --lang en
+```
+
 如果仓库已有本地封装，优先使用本地命令，因为它们编码了项目默认值：
 
 ```bash
@@ -80,11 +88,27 @@ scale upgrade rollback --dir .
 | --- | --- | --- |
 | clean | 生成的工作流集合和 lock 文件一致 | 运行项目级验证 |
 | missing | 生成文件缺失 | 通常可用 `apply --confirm` 恢复 |
-| outdated | SCALE 有更新的生成模板 | 审阅计划，确认安全后应用 |
+| updates-available | SCALE 版本、governance pack 或受管文件存在可应用更新 | 审阅计划，确认安全后应用 |
 | manual-review | 生成文件已有本地修改 | 检查 diff，不要自动覆盖 |
 
 `manual-review` 是有意设计。SCALE 不应该抹掉本地项目知识、服务命令或 Agent 规则。
 
+## 自动升级边界
+
+`scale upgrade apply --confirm` 现在覆盖三类安全场景：
+
+- 受管文件缺失：从当前 governance pack 恢复缺失文件。
+- SCALE CLI 版本变化：刷新 `.scale/governance.lock.json`，让项目记录当前 CLI 版本。
+- governance pack 版本变化：如果受管文件内容仍与 lock 哈希一致，自动刷新这些干净文件，让新模板、新门禁、新脚本和新文档入口落到旧项目。
+
+下面场景不会自动覆盖：
+
+- 文件相对 lock 已有本地改动。
+- 缺少 `.scale/governance.lock.json`，无法判断哪些文件由 SCALE 管理。
+- 第三方 skills、MCP、浏览器、桌面自动化或外部 CLI 需要新增、升级、执行安装脚本。
+
+这些情况会进入 `manual-review`，由维护者或 Agent 先看计划和 diff，再决定合并、保留本地改动，或重新初始化。
+
 ## 项目级适配
 
 生成文件更新后，再按真实仓库适配这些文件：
@@ -127,13 +151,13 @@ scale upgrade rollback --dir .
 
 ```makefile
 workflow-upgrade-check:
-	scale upgrade check --dir .
+	scale upgrade check --dir . --lang zh
 workflow-upgrade-plan:
-	scale upgrade plan --dir . --html
+	scale upgrade plan --dir . --html --lang zh
 workflow-upgrade-apply:
-	scale upgrade apply --dir . --confirm
+	scale upgrade apply --dir . --confirm --lang zh
 workflow-upgrade-rollback:
-	scale upgrade rollback --dir .
+	scale upgrade rollback --dir . --lang zh
 workflow-upgrade-verify:
 	scale preflight --dir . --service all --preflight-profile quick
 ```
@@ -145,6 +169,6 @@ workflow-upgrade-verify:
 - `scale --version` 输出预期版本。
 - `scale upgrade check --dir .` 没有非预期 drift。
 - 有变更时，`scale upgrade plan --dir . --html` 能生成可审阅计划。
-- `scale upgrade apply --dir . --confirm` 只在审阅计划后使用。
+- `scale upgrade apply --dir . --confirm` 只在审阅计划后使用；干净受管文件可自动刷新，本地改动必须人工审阅。
 - 项目级验证通过，或记录清楚已知失败。
 - `README.md`、`AGENTS.md`、`CLAUDE.md`、`docs/workflow/README.md` 指向同一组工作流命令。

package/docs/workflow/README.md

@@ -0,0 +1,67 @@
+# SCALE Engine 仓库工作流
+
+这里描述的是 `scale-engine` 仓库自身的工程化工作流，不是终端用户如何使用 `scale` CLI。
+
+## 入口
+
+- 新维护者先读 [GETTING_STARTED.md](../guides/GETTING_STARTED.md)
+- 日常开发读 [DEVELOPMENT_WORKFLOW.md](../guides/DEVELOPMENT_WORKFLOW.md)
+- 机器可读分支策略看 [../../.scale/workspace.json](../../.scale/workspace.json)
+
+## 最小命令面
+
+```bash
+make preflight
+make new-task NAME=workflow-adaptation LEVEL=M
+make plan NAME=workflow-adaptation LEVEL=M
+make explore FILES='AGENTS.md CLAUDE.md README.md package.json' MSG='main contradiction'
+make gate-workflow
+make gate-quality
+make verify PROFILE=default
+```
+
+PowerShell:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/verify.ps1 -Profile default
+```
+
+## 门禁说明
+
+| Gate | 作用 |
+| --- | --- |
+| G1 | 探索是否记录到状态文件，且至少读了 3 个文件 |
+| G2 | 计划是否包含边界、异常、回滚、现实校验 |
+| G3 | `src/` 行为改动是否伴随测试改动 |
+| G4 | workflow 脚本是否可解析 |
+| G5 | `lint + typecheck + test + build` 是否通过 |
+| G6 | 任务证据和 `git diff --check` 是否通过 |
+| G7 | 安全面是否通过 |
+| G8 | Markdown 与工作流文档是否符合基础卫生规则 |
+
+## 分支策略
+
+当前仓库采用 GitLab Flow 风格：
+
+```text
+feature/fix/docs/chore/codex -> dev -> master
+```
+
+约束：
+
+- `dev` 是集成分支。
+- `master` 是生产基线。
+- `release/*` 只在必须从生产基线隔离发版时使用。
+- `hotfix/*` 用于生产紧急修复，并要求回流 `dev`。
+
+## 升级入口
+
+如果要把仓库工作流继续升级到更新的 `scale-engine` 版本，先跑：
+
+```bash
+make bootstrap-scale
+make workflow-upgrade-check
+make workflow-upgrade-plan
+```
+
+先审计划，再决定是否 `make workflow-upgrade-apply`。

package/docs/workflow/node-library.md

@@ -0,0 +1,52 @@
+# Generated by scale-engine governance pack: node-library@2
+# Edit policy: prefer editing the pack in scale-engine; local overrides should be documented.
+
+# Node Library Workflow
+
+This repository uses the latest SCALE repository workflow for Node/npm package delivery.
+
+## Command Entry Points
+
+```bash
+bash scripts/preflight/all.sh
+bash scripts/gates/all.sh --dry-run
+bash scripts/workflow/new-task.sh
+bash scripts/workflow/resume.sh
+bash scripts/workflow/verify.sh --preflight-profile quick
+```
+
+PowerShell:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/preflight/all.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/gates/all.ps1 --dry-run
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/new-task.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/resume.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/verify.ps1 --preflight-profile quick
+```
+
+## 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`
+- product smoke: enable a real probe in `.scale/product-smoke.json` instead of treating a health endpoint as completion proof
+
+## Branch Policy
+
+This repository follows a GitLab Flow variant:
+
+```text
+feature/fix/docs/chore/codex -> dev -> master -> tag/publish
+```
+
+Use short-lived branches for governed work. Direct governed commits on `dev`, `master`, or `main` are blocked by SCALE ship rules.
+
+## Release Expectations
+
+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`.
+5. Confirm runtime evidence and review artifacts for M/L/CRITICAL work.

package/docs/workflow/templates/api-contract.md

@@ -0,0 +1,29 @@
+# API Contract
+
+## Endpoint Or Interface
+
+TBD
+
+## Request
+
+TBD
+
+## Response
+
+TBD
+
+## Errors
+
+TBD
+
+## Permission Rules
+
+TBD
+
+## Compatibility Notes
+
+TBD
+
+## Acceptance Criteria
+
+- [ ] TBD

package/docs/workflow/templates/architecture-review.md

@@ -0,0 +1,23 @@
+# Architecture Review
+
+## Scope
+
+- Modules touched:
+- Public contracts touched:
+- Data flow touched:
+
+## Boundary Checks
+
+- [ ] API/controller layer does not bypass service/usecase layer
+- [ ] Domain layer is not coupled to infrastructure details
+- [ ] Repository/ORM usage follows project conventions
+- [ ] Shared framework components are reused instead of duplicated
+- [ ] New abstractions remove real complexity
+
+## Risks
+
+- TBD
+
+## Decision
+
+- Approved/changes required:

package/docs/workflow/templates/db-change-plan.md

@@ -0,0 +1,20 @@
+# DB Change Plan
+
+## Schema Or Data Change
+
+TBD
+
+## Backward Compatibility
+
+TBD
+
+## Migration Steps
+
+TBD
+
+## Rollback Plan
+
+TBD
+
+## Verification
+TBD

package/docs/workflow/templates/docs-impact.md

@@ -0,0 +1,17 @@
+# Docs Impact
+
+## Code Changes Requiring Docs
+
+- TBD
+
+## Documentation Updated
+
+- TBD
+
+## No-Docs-Needed Rationale
+
+TBD
+
+## Links Checked
+
+- TBD

package/docs/workflow/templates/e2e-plan.md

@@ -0,0 +1,20 @@
+# E2E Plan
+
+## User Paths
+
+TBD
+
+## Browser Coverage
+
+TBD
+
+## Test Data
+
+TBD
+
+## Assertions
+
+TBD
+
+## Evidence
+TBD

package/docs/workflow/templates/explore.md

@@ -0,0 +1,16 @@
+# Explore - {{TASK_ID}}
+
+Date: {{DATE}}
+Level: {{LEVEL}}
+
+## Files Read
+
+- TBD
+
+## Main Contradiction
+
+- TBD
+
+## Constraints
+
+- TBD

package/docs/workflow/templates/github-actions-scale-preflight.yml

@@ -0,0 +1,32 @@
+name: SCALE Preflight
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install project dependencies when present
+        shell: bash
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          elif [ -f package.json ]; then
+            npm install
+          fi
+
+      - name: Run SCALE preflight
+        run: npx @hongmaple0820/scale-engine@latest preflight --service all --preflight-profile ci

package/docs/workflow/templates/mini-prd.md

@@ -0,0 +1,16 @@
+# Mini PRD - {{TASK_ID}}
+
+Date: {{DATE}}
+Level: {{LEVEL}}
+
+## Goal
+
+- TBD
+
+## Non-Goals
+
+- TBD
+
+## Acceptance Criteria
+
+- TBD

package/docs/workflow/templates/plan.md

@@ -0,0 +1,37 @@
+# Plan - {{TASK_ID}}
+
+Date: {{DATE}}
+Level: {{LEVEL}}
+
+## Scope / Boundary
+
+- In scope:
+- Out of scope / non-goals:
+
+## Approach
+
+1. TBD
+2. TBD
+3. TBD
+
+## Exception / Failure Paths
+
+- Expected failure:
+- Error handling:
+- Manual recovery:
+
+## Rollback / Fallback
+
+- Rollback:
+- Fallback:
+- Disable path:
+
+## Acceptance Criteria
+
+- TBD
+
+## Verification
+
+- `make gate-quality`
+- `make verify PROFILE=default`
+- `git diff --check`

package/docs/workflow/templates/pre-push-scale-preflight.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env sh
+set -eu
+
+if command -v scale >/dev/null 2>&1; then
+  scale preflight --service all
+else
+  npx @hongmaple0820/scale-engine@latest preflight --service all
+fi

package/docs/workflow/templates/product-smoke.md

@@ -0,0 +1,61 @@
+# Product Smoke
+
+## Real Product Path
+
+Describe the smallest end-to-end path that proves the change works through the real product boundary.
+
+Example:
+
+```text
+UI or client -> gateway/router -> service -> database/storage/queue -> observable result
+```
+
+Do not use a green health endpoint as the only proof when the user-facing path depends on routing, authentication, storage, async tasks, browser behavior, or third-party integration.
+
+## Quick Setup
+
+1. Open `.scale/product-smoke.json`.
+2. Replace the example command with one real product path command.
+3. Set that probe's `enabled` field to `true`.
+4. Run `scale preflight --profile productSmoke --json`.
+5. Run `scale runtime final-check --level M --json`.
+
+`status: "skipped"` means no real product path was exercised. It does not count as completion evidence.
+
+## Setup
+
+- Base URL:
+- Test user or tenant:
+- Required fixtures:
+- Services that must be running:
+
+## Smoke Commands
+
+| Command | Expected Result | Evidence Artifact |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## Runtime Evidence
+
+Record at least one runtime evidence item:
+
+```bash
+scale runtime record \
+  --kind command \
+  --title "Product smoke: <flow>" \
+  --status passed \
+  --command "<exact smoke command>" \
+  --exit-code 0 \
+  --summary "<business result, task id, status, or observable output>" \
+  --artifacts ".agent/logs/<service>/<smoke>.json" \
+  --metadata-json '{"productSmoke":true,"realProductPath":true}'
+```
+
+## Assertions
+
+- [ ] Request crossed the real product boundary, not only an isolated unit.
+- [ ] Authentication or user identity path was exercised when relevant.
+- [ ] Persistence/storage/queue side effect was verified when relevant.
+- [ ] Async task or eventual state was polled to terminal status when relevant.
+- [ ] Failure output is specific enough to diagnose the failing layer.
+- [ ] Runtime artifacts are ignored or deliberately promoted according to resource governance.

package/docs/workflow/templates/reality-check.md

@@ -0,0 +1,28 @@
+# Reality Check - {{TASK_ID}}
+
+Date: {{DATE}}
+Level: {{LEVEL}}
+
+## Confirmed
+
+- TBD
+
+## Not Verified
+
+- TBD
+
+## Stub / Fake / Partial
+
+- TBD
+
+## Credential-Gated
+
+- TBD
+
+## Environment-Gated
+
+- TBD
+
+## User-Visible Risk
+
+- TBD

package/docs/workflow/templates/resource-cleanup.md

@@ -0,0 +1,17 @@
+# Resource Cleanup - {{TASK_ID}}
+
+Date: {{DATE}}
+Level: {{LEVEL}}
+
+## New Resources
+
+| Resource | Location | Keep / Move / Delete | Reason |
+| --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD |
+
+## Docs Promotion
+
+- Promote to `docs/`:
+- Keep in `.planning/`:
+- Keep local under `.agent/`:
+- Delete before handoff:

package/docs/workflow/templates/resource-impact.md

@@ -0,0 +1,25 @@
+# Resource Impact
+
+## Resources Created
+
+| Path | Type | Git Policy | Retention |
+| --- | --- | --- | --- |
+| TBD | canonical-doc/task-artifact/evidence-report/temporary/reusable-script/generated-media/contract/decision-record | commit/ignore/lfs/external/review | TBD |
+
+## Resources Updated
+
+- TBD
+
+## Resources Promoted To Maintained Docs
+
+- TBD
+
+## Resources To Delete Or Archive Before Finish
+
+- TBD
+
+## Source Of Truth Updates
+
+- [ ] .scale/resource-policy.json
+- [ ] .scale/assets.json
+- [ ] docs/modules/<module>/README.md

package/docs/workflow/templates/review.md

@@ -0,0 +1,12 @@
+# Review - {{TASK_ID}}
+
+Date: {{DATE}}
+Level: {{LEVEL}}
+
+## Findings
+
+- TBD
+
+## Residual Risk
+
+- TBD

package/docs/workflow/templates/runtime.md

@@ -0,0 +1,23 @@
+# Runtime Contract - {{TASK_ID}}
+
+Date: {{DATE}}
+Level: {{LEVEL}}
+
+## Configuration Source
+
+- Source: TBD
+- Environment/profile: TBD
+- Local override file: TBD
+
+## Service Topology
+
+| Service | URL / Command | Config source | Auth mode | Status |
+| --- | --- | --- | --- | --- |
+| primary | TBD | TBD | TBD | Not checked |
+
+## Verification Boundary
+
+- Confirmed:
+- Not covered:
+- Requires external credentials:
+- Requires shared/cloud environment:

package/docs/workflow/templates/security-review.md

@@ -0,0 +1,26 @@
+# Security Review
+
+## Assets And Trust Boundaries
+
+TBD
+
+## Authorization Rules
+
+TBD
+
+## Abuse Cases
+
+1. TBD
+2. TBD
+3. TBD
+
+## Sensitive Data Impact
+
+TBD
+
+## Rollback Or Disable Strategy
+
+TBD
+
+## Final Verdict
+TBD

package/docs/workflow/templates/skill-evidence.md

@@ -0,0 +1,33 @@
+# Skill Evidence
+
+## Planned Skills
+
+- TBD
+
+## Tool Selection Rationale
+
+TBD
+
+## Used Skills
+
+| Skill | Phase | Trigger | Evidence | Status |
+| --- | --- | --- | --- | --- |
+| skill-id | plan/build/verify/review | why it was selected | command, screenshot, report, or artifact path | executed/skipped/fallback |
+
+## Browser Or Web Evidence
+
+| Tool | Target | Evidence | Result |
+| --- | --- | --- | --- |
+| web-access/agent-browser/Chrome DevTools MCP | URL or local target | screenshot, console log, network finding, source URL | passed/failed/skipped |
+
+## Desktop Or External CLI Evidence
+
+| Tool | Scope | Safety Boundary | Evidence | Result |
+| --- | --- | --- | --- | --- |
+| cua/codex/gemini/opencode/wps/wechat | command or app target | read-only/dry-run/test account/manual approval | output summary, screenshot, or report path | passed/failed/skipped |
+
+## Skipped Skills
+
+| Skill | Reason | Fallback Evidence |
+| --- | --- | --- |
+| skill-id | why it could not run | manual review, alternate command, or explicit risk |