@hongmaple0820/scale-engine 0.21.1 → 0.23.0

package/dist/workflow/types.d.ts

@@ -1,4 +1,4 @@
-export type GateStage = 'G0' | 'G1' | 'G2' | 'G3' | 'G4' | 'G5' | 'G6' | 'G7' | 'G8';
+export type GateStage = 'G0' | 'G1' | 'G2' | 'G3' | 'G4' | 'G5' | 'G6' | 'G7' | 'G8' | 'G9' | 'G10' | 'G11' | 'G12' | 'G13' | 'G14' | 'G15';
 export type GateStatus = 'PENDING' | 'PASSED' | 'FAILED' | 'BLOCKED';
 export type ModelTier = 'LOW' | 'MEDIUM' | 'HIGH';
 export type Verdict = 'APPROVE' | 'ITERATE' | 'REJECT';
@@ -18,6 +18,11 @@ export interface GateEvidence {
     stdoutTail?: string;
     stderrTail?: string;
     outputHash?: string;
+    rawEstimatedTokens?: number;
+    compressedEstimatedTokens?: number;
+    savedEstimatedTokens?: number;
+    compressionRatio?: number;
+    commandRunEvidenceId?: string;
     source?: string;
 }
 export interface GateResult {

package/docs/GITLAB_FLOW.md

@@ -0,0 +1,125 @@
+# GitLab Flow Branch and Worktree Policy
+
+SCALE Engine uses a GitLab Flow variant for this repository:
+
+```text
+feat/* / fix/* / chore/* / docs/* / codex/*
+        -> dev
+        -> master
+        -> vX.Y.Z tag
+        -> npm publish
+
+hotfix:
+        fix forward on dev first when possible
+        -> cherry-pick to hotfix/*
+        -> master
+        -> vX.Y.Z tag
+        -> sync master back to dev
+
+selective release, only when dev contains work that must not ship:
+        master
+        -> release/vX.Y.Z
+        -> cherry-pick selected commits
+        -> master
+        -> vX.Y.Z tag
+        -> sync master back to dev
+```
+
+## Branch Roles
+
+| Branch | Role | Rule |
+| --- | --- | --- |
+| `dev` | Integration and test branch | Merge reviewed short branches here. Do not create direct governed commits on `dev`. |
+| `master` | Production branch | Only verified release/hotfix results land here. Publish from user-created `vX.Y.Z` tags on `master`. |
+| `feat/*`, `feature/*` | Feature branches | Start from current `dev`, merge back to `dev`, then delete. |
+| `fix/*` | Normal bug fix branches | Start from current `dev`, merge back to `dev`, then delete. |
+| `chore/*`, `docs/*`, `codex/*` | Maintenance branches | Short-lived work branches that merge back to `dev`. |
+| `hotfix/*` | Production patch branches | Use only for production fixes. Fix forward to `dev` first when possible, then cherry-pick to hotfix/master. |
+| `release/*` | Selective release branch | Use only when `dev` contains work that must not ship. Start from `master` and cherry-pick the release list. |
+
+## Required Checks
+
+Run the release-grade verification set before merging to `master` or tagging:
+
+```bash
+npm run build
+npx vitest run
+git diff --check
+npm pack --dry-run
+```
+
+Every merge request should run the relevant build/lint/test checks before review is accepted. Do not wait until `master` to discover broken tests.
+
+## Merge and Conflict Rules
+
+- Public branches are not rebased: `dev`, `master`, `release/*`, and `hotfix/*` keep realistic history.
+- Personal short branches may be rebased before merge, but only with `--force-with-lease` and only before review is accepted.
+- Prefer squash merge from short branches into `dev` when one logical change should be easy to revert.
+- Resolve conflicts on the source branch, rerun verification, then merge. Do not resolve release conflicts directly on `master`.
+- Fix bugs forward first: land the fix on `dev` when possible, then cherry-pick the same commit to `hotfix/*` or the selected patch release branch.
+- Commit messages should explain intent and why the chosen path was selected when the decision is not obvious.
+
+## Ship Gate Rules
+
+`scale ship <task-id>` now enforces the branch lifecycle:
+
+- blocked on `dev`, `master`, `main`, and detached HEAD
+- allowed on configured short branches such as `feat/*`, `fix/*`, `chore/*`, `docs/*`, `codex/*`, `release/*`, and `hotfix/*`
+- still requires verification evidence, passing review evidence, and reviewed-file-only staging
+- still blocks dirty or unsafe child repositories in MOE/submodule workspaces
+
+Use:
+
+```bash
+scale workspace status --summary
+scale workspace finish --summary
+scale workspace finish --json
+```
+
+The report includes branch role, whether governed shipping is allowed, and cleanup blockers.
+
+## Worktree Lifecycle
+
+Temporary agent worktrees are safe to remove only when all of these are true:
+
+- root worktree is clean
+- child repositories are clean and pushed when required
+- the temporary branch has no unpushed commits
+- a branch with no upstream is already merged into `dev`/`master`, or it contains no unique work
+
+Cleanup remains dry-run by default:
+
+```bash
+scale workspace cleanup --dir <temporary-worktree> --dry-run --json
+scale workspace cleanup --dir <temporary-worktree> --apply --confirm <branch-or-head> --json
+```
+
+If cleanup is blocked, push the branch, merge it, cherry-pick it into the selected release, or explicitly discard it before removing the worktree.
+
+## Repository Bootstrap
+
+This repository currently treats `dev` as the integration branch and `master` as production. If `dev` falls behind `master` and has no unique commits, fast-forward `dev` to `master` before starting new feature work:
+
+```bash
+git fetch --all --prune
+git switch dev
+git merge --ff-only master
+git push origin dev
+git push github dev
+```
+
+After that, normal work should start from `dev`:
+
+```bash
+git switch dev
+git pull --ff-only origin dev
+git switch -c feat/<short-name>
+```
+
+Before creating a normal release from `dev`, inspect the release delta:
+
+```bash
+git log --oneline master..dev
+```
+
+If every listed commit is intended for the next production release, merge `dev` through the normal release path. If any commit must be excluded, create `release/vX.Y.Z` from `master` and cherry-pick only the approved release list.

package/docs/README.md

@@ -9,6 +9,7 @@
 | [start/README.md](start/README.md) | 入门路径总览 |
 | [start/quickstart.md](start/quickstart.md) | 3 分钟快速开始 |
 | [start/agent-governance-demo.md](start/agent-governance-demo.md) | 官方 demo walkthrough |
+| [start/artifact-lifecycle.md](start/artifact-lifecycle.md) | Artifact 生命周期完整 walkthrough |
 | [../README.md](../README.md) | 项目主页和能力总览 |
 
 ## 当前治理能力
@@ -28,6 +29,8 @@
 | [UPGRADE_MANAGEMENT.md](UPGRADE_MANAGEMENT.md) | SCALE CLI、governance pack、skills、MCP 和 CLI 工具的安全升级流程 |
 | [GOVERNANCE_DASHBOARD.md](GOVERNANCE_DASHBOARD.md) | Runtime、eval、memory、resource、HTML artifact 的统一治理面板 |
 | [RELEASE_READINESS.md](RELEASE_READINESS.md) | 发版前质量门槛、官方 demo 和真实项目落地验收 |
+| [DOCUMENT_STANDARDS.md](DOCUMENT_STANDARDS.md) | 文档编写与维护规范 |
+| [GITLAB_FLOW.md](GITLAB_FLOW.md) | GitLab Flow 分支、发版、tag 和临时 worktree 生命周期规范 |
 | [SKILL-REPOSITORY.md](SKILL-REPOSITORY.md) | 受治理 skill repository 和安装安全策略 |
 | [VIBE-TEMPLATES.md](VIBE-TEMPLATES.md) | 可复制的 Vibe Coding 提示词模板 |
 | [LEADERSHIP-PRESETS.md](LEADERSHIP-PRESETS.md) | CEO、CTO、PM、Architect 等内置领导者角色预设 |

package/docs/start/README.md

@@ -1,16 +1,19 @@
 # SCALE Engine 入门路径
 
-这个目录只放面向新用户的上手内容。目标是让用户先跑通，再理解完整体系。
+这个目录面向新用户。目标是先跑通一条最小路径，再理解完整体系，不要求一开始掌握所有命令。
 
 ## 推荐阅读顺序
 
 1. [3 分钟快速开始](quickstart.md)
    从空目录初始化治理工作流，看到 `.scale`、模板、验证 profile 和状态输出。
 
-2. [官方 Demo Walkthrough](agent-governance-demo.md)
+2. [Artifact 生命周期](artifact-lifecycle.md)
+   完整走一遍 Need → Spec → Plan → Task → Change → Evidence → Release，理解 FSM 和 Guard 如何用物理约束替代提示词建议。
+
+3. [官方 Demo Walkthrough](agent-governance-demo.md)
    用一个 OAuth state 加固任务演示：上下文对齐、诊断计划、TDD 切片、HTML artifact、资源治理和工程规范扫描。
 
-3. 回到根目录 [README](../../README.md)
+4. 回到根目录 [README](../../README.md)
    理解 SCALE Engine 的核心能力和 governance pack 选择。
 
 4. [升级管理](../UPGRADE_MANAGEMENT.md)
@@ -19,6 +22,25 @@
 5. 查看 [文档地图](../README.md)
    区分哪些文档是用户指南、哪些是参考资料、哪些是历史规划和过程记录。
 
+## 15 分钟学习路径
+
+```bash
+npm install -g @hongmaple0820/scale-engine
+scale --version
+mkdir scale-demo && cd scale-demo
+scale init --governance-pack standard
+scale preflight --preflight-profile quick
+scale status
+```
+
+跑完后先回答三个问题：
+
+- `.scale/verification.json` 里定义了哪些验证 profile？
+- `docs/workflow/templates/` 里有哪些任务产物模板？
+- `scale status` 建议下一步做什么？
+
+如果这三个问题答不上来，先不要继续看高级命令。
+
 ## 你应该先看到什么
 
 跑完 quickstart 后，至少应该能看到：
@@ -44,3 +66,7 @@
 | 文档、报告、截图、脚本混乱 | `scale init --governance-pack resource-governance` |
 | 工作流或第三方能力要升级 | `scale upgrade check && scale upgrade plan --html` |
 
+
+## 工作流升级短路径
+
+已有项目先看 [SCALE workflow upgrade guide](workflow-upgrade.md)。它说明 `scale init --interactive`、`scale upgrade check/plan/apply/rollback`、仓库本地 `make workflow-upgrade-*` 入口，以及生成文件更新和项目级验证之间的边界。

package/docs/start/artifact-lifecycle.md

@@ -0,0 +1,326 @@
+<!--
+  Version: 1.0
+  Last Updated: 2026-05-19
+  Scope: Tutorial — Artifact lifecycle from Need to Release
+  Maintainer: SCALE Engine Team
+-->
+# Artifact Lifecycle Walkthrough
+
+This tutorial walks through a **complete Artifact lifecycle**: Need → Spec → Plan → Task → Change → Evidence → Release. It demonstrates how SCALE's FSM, Gates, and Guardrails work together to enforce quality through physical constraints.
+
+## Prerequisites
+
+- SCALE Engine installed (`npm install -g @hongmaple0820/scale-engine`)
+- Node.js 20+
+- A project directory initialized with `scale init`
+
+## The Scenario
+
+You have a simple calculator library. The user requests: **"Add a multiply function"**. We'll trace this request through the entire SCALE lifecycle.
+
+---
+
+## Step 1: Create a Need
+
+Every request starts as a **Need** — the raw user intent.
+
+```bash
+scale create need "Add multiply function to calculator"
+```
+
+Output:
+```json
+{
+  "id": "ART-need-20260519-0001",
+  "type": "Need",
+  "status": "DRAFT",
+  "title": "Add multiply function to calculator"
+}
+```
+
+The Need starts in `DRAFT` state. It's fuzzy — no success criteria, no scope boundaries.
+
+```bash
+scale transition ART-need-20260519-0001 clarify \
+  --reason "Added success criteria and scope"
+```
+
+**FSM Path:** `DRAFT → CLARIFIED`
+
+---
+
+## Step 2: Create a Spec from the Need
+
+A **Spec** is the requirements contract — WHAT to build, not HOW.
+
+```bash
+scale create spec "Multiply function spec" \
+  --from ART-need-20260519-0001 \
+  --payload '{
+    "what": "Add multiply(a, b) function that returns the product of two numbers",
+    "successCriteria": [
+      "multiply(2, 3) returns 6",
+      "multiply(-1, 5) returns -5",
+      "multiply(0, 100) returns 0",
+      "multiply(2.5, 4) returns 10"
+    ],
+    "outOfScope": ["Division", "Modulo", "Complex numbers"],
+    "edgeCases": ["Overflow", "NaN inputs", "Infinity"],
+    "northStar": "Reliable basic arithmetic operations"
+  }'
+```
+
+Output:
+```json
+{
+  "id": "ART-spec-20260519-0002",
+  "type": "Spec",
+  "status": "DRAFT",
+  "parents": ["ART-need-20260519-0001"]
+}
+```
+
+### Spec State Machine
+
+```
+                  ┌──── reject ────┐
+                  ▼                │
+   DRAFT ──refine──▶ REVIEWING ──approve──▶ FROZEN
+```
+
+The Spec must be **FROZEN** before downstream artifacts (Plan, Task) can be created. This prevents building on unstable requirements.
+
+```bash
+# Move to review
+scale transition ART-spec-20260519-0002 review --reason "Ready for review"
+
+# Approve and freeze
+scale transition ART-spec-20260519-0002 approve --reason "Requirements clear, scope defined"
+```
+
+**FSM Path:** `DRAFT → REVIEWING → FROZEN`
+
+---
+
+## Step 3: Create a Plan
+
+A **Plan** is the technical approach — HOW to build it.
+
+```bash
+scale create plan "Multiply implementation plan" \
+  --from ART-spec-20260519-0002 \
+  --payload '{
+    "approach": "Add multiply function to existing calculator module",
+    "techChoices": [
+      {
+        "decision": "Simple function, not a class method",
+        "rationale": "Consistent with existing add/subtract pattern",
+        "alternatives": ["Class method", "Operator overloading"]
+      }
+    ],
+    "modules": [
+      {"path": "src/calculator.ts", "action": "modify", "reason": "Add multiply export"},
+      {"path": "tests/calculator.test.ts", "action": "modify", "reason": "Add multiply tests"}
+    ],
+    "rollbackStrategy": "Revert git commit",
+    "estimatedComplexity": 0.2
+  }'
+```
+
+```bash
+scale transition ART-plan-20260519-0003 approve --reason "Plan is straightforward"
+```
+
+**FSM Path:** `DRAFT → APPROVED`
+
+---
+
+## Step 4: Create and Execute a Task
+
+A **Task** is the atomic execution unit.
+
+```bash
+scale create task "Implement multiply function" \
+  --from ART-plan-20260519-0003 \
+  --payload '{
+    "description": "Write multiply function and tests",
+    "filesInvolved": ["src/calculator.ts", "tests/calculator.test.ts"],
+    "requiredRole": "implementer",
+    "requiredCapabilities": ["can_modify_code", "can_run_tests"]
+  }'
+```
+
+### Task State Machine with Guards
+
+```
+PENDING ──schedule──▶ READY ──start──▶ RUNNING ──complete──▶ COMPLETED
+                                                        │
+                                                        └── BLOCKED by Guards
+```
+
+The Task has **physical guards** that prevent false completion:
+
+```bash
+# Schedule and start
+scale transition ART-task-20260519-0004 schedule --reason "Ready"
+scale transition ART-task-20260519-0004 start --reason "Starting implementation"
+
+# Agent writes code (simulated)
+# ... src/calculator.ts modified ...
+
+# Agent tries to complete WITHOUT verification
+scale transition ART-task-20260519-0004 complete --reason "Done"
+```
+
+**Output (BLOCKED):**
+```json
+{
+  "success": false,
+  "blockedBy": [
+    {
+      "guard": "build_passed",
+      "message": "Task must pass build verification before completion. Run: scale verify-task <id>"
+    },
+    {
+      "guard": "lint_passed",
+      "message": "Task must pass lint before completion. Run: scale verify-task <id>"
+    },
+    {
+      "guard": "tests_passed",
+      "message": "Task must pass tests before completion. Run: scale verify-task <id>"
+    }
+  ]
+}
+```
+
+**The transition is physically blocked.** The agent cannot claim completion without running verification.
+
+### Run Verification
+
+```bash
+scale verifyTask ART-task-20260519-0004
+```
+
+Output:
+```
+Running build...
+   Build passed
+
+Running lint...
+   Lint passed
+
+Running tests...
+   Tests passed
+
+Verification results:
+  Build:  success (exit code: 0)
+  Lint:   success
+  Tests:  passed
+
+All checks passed! Task can now be completed.
+```
+
+Now the transition succeeds:
+
+```bash
+scale transition ART-task-20260519-0004 complete --reason "Verified and all checks passed"
+```
+
+**FSM Path:** `PENDING → READY → RUNNING → COMPLETED`
+
+---
+
+## Step 5: Record the Change
+
+A **Change** tracks the actual code modification (git commit/PR).
+
+```bash
+scale create change "Multiply function implementation" \
+  --from ART-task-20260519-0004 \
+  --payload '{
+    "commitSha": "abc123",
+    "filesChanged": [
+      {"path": "src/calculator.ts", "additions": 8, "deletions": 0},
+      {"path": "tests/calculator.test.ts", "additions": 20, "deletions": 0}
+    ],
+    "diffSummary": "Added multiply function with type safety and edge case handling"
+  }'
+
+scale transition ART-change-20260519-0005 commit --reason "Committed"
+scale transition ART-change-20260519-0005 verify --reason "Tests pass"
+```
+
+**FSM Path:** `DRAFT → COMMITTED → VERIFIED`
+
+---
+
+## Step 6: Record Evidence
+
+An **Evidence** artifact captures verification results.
+
+```bash
+scale create evidence "Multiply function test results" \
+  --from ART-change-20260519-0005 \
+  --payload '{
+    "testPlanId": "ART-testplan-...",
+    "toolUsed": "pnpm test",
+    "passed": true,
+    "output": "Tests: 4 passed, 4 total. Coverage: 95%",
+    "duration": 1200,
+    "artifacts": ["coverage/lcov-report/index.html"]
+  }'
+```
+
+---
+
+## Step 7: Close the Release
+
+A **Release** bundles everything together. It can only be created when all Defects are closed.
+
+```bash
+scale create release "v1.1.0 - Add multiply" \
+  --payload '{
+    "version": "v1.1.0",
+    "includesSpecs": ["ART-spec-20260519-0002"],
+    "includesChanges": ["ART-change-20260519-0005"],
+    "rolloutStrategy": "all_at_once"
+  }'
+
+scale transition ART-release-20260519-0007 prepare --reason "Ready"
+scale transition ART-release-20260519-0007 ship --reason "Deploying"
+scale transition ART-release-20260519-0007 verify --reason "Deployed and verified"
+```
+
+**FSM Path:** `PLANNED → READY → DEPLOYING → DEPLOYED`
+
+---
+
+## The Complete Artifact DAG
+
+```
+Need (CLARIFIED)
+  └── Spec (FROZEN)
+        └── Plan (APPROVED)
+              └── Task (COMPLETED)
+                    └── Change (VERIFIED)
+                          └── Evidence (PASS)
+                                └── Release (DEPLOYED)
+```
+
+Every arrow represents a parent-child relationship. Every state transition went through the FSM with Guards. The agent **could not skip verification** — it was physically blocked.
+
+---
+
+## Key Takeaways
+
+1. **FSM enforces order** — You can't create a Plan from a non-FROZEN Spec
+2. **Guards prevent false completion** — Task completion is blocked without verification
+3. **Event sourcing records everything** — Every transition is logged as an immutable event
+4. **Defects create feedback loops** — If Evidence fails, a Defect is created and the cycle continues
+5. **Lessons are extracted** — After 3+ similar Defects, SCALE proposes a Lesson; after review, it becomes a Rule; after violation, it becomes a Hook
+
+## Next Steps
+
+- [Agent Governance Demo](agent-governance-demo.md) — See a real-world task walkthrough
+- [Task Guard Workflow Demo](../TASK_GUARD_WORKFLOW_DEMO.md) — Deep dive into Guard mechanics
+- [Data Model](../02-DATA-MODEL.md) — Understand Artifact types, events, and FSM definitions

package/docs/start/workflow-upgrade.md

@@ -0,0 +1,150 @@
+# SCALE 工作流升级指南
+
+本文是已有仓库安装、更新、适配 SCALE 工作流资产的短路径。
+
+适合三类人：
+
+| 角色 | 关注点 |
+| --- | --- |
+| 项目维护者 | 如何把 SCALE 接入已有仓库，并避免覆盖本地规则 |
+| 普通开发者 | 拉取仓库后如何检查或安装正确的 SCALE 版本 |
+| Agent 使用者 | 哪些步骤可以命令化，哪些必须人工或 Agent 审阅 |
+
+## 哪些可以自动化
+
+SCALE 把更新分成三层：
+
+| 层级 | 命令支持 | 默认行为 |
+| --- | --- | --- |
+| SCALE CLI | `npm install -g @hongmaple0820/scale-engine@latest` | 用户显式安装或升级 |
+| 生成的工作流文件 | `scale upgrade check/plan/apply/rollback` | 先安全检查和生成计划，只有 `--confirm` 才应用 |
+| 项目级验证 | 仓库 `make` 目标和 `scripts/workflow/*` | 必须保留项目语义；SCALE 不猜业务路由、凭据和服务拓扑 |
+
+这意味着工作流适配不是 Codex-only。Codex 可以帮助审阅和处理 `manual-review`，但常规路径应该是命令驱动。
+
+## 首次安装
+
+```bash
+npm install -g @hongmaple0820/scale-engine
+scale --version
+```
+
+已有项目可以用交互式初始化选择最接近的 governance pack：
+
+```bash
+scale init --interactive
+```
+
+也可以直接指定：
+
+```bash
+scale init --governance-pack standard
+scale init --governance-pack project-scaffold
+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。
+
+## 更新已有工作流
+
+按这个顺序运行：
+
+```bash
+scale upgrade check --dir .
+scale upgrade plan --dir . --html
+scale upgrade apply --dir . --confirm
+scale preflight --dir . --service all --preflight-profile quick
+```
+
+如果仓库已有本地封装，优先使用本地命令，因为它们编码了项目默认值：
+
+```bash
+make workflow-upgrade-check
+make workflow-upgrade-plan
+make workflow-upgrade-apply
+make workflow-upgrade-verify
+```
+
+回滚只撤回最近一次 SCALE 管理的安全应用：
+
+```bash
+scale upgrade rollback --dir .
+```
+
+## 如何读取结果
+
+| 结果 | 含义 | 下一步 |
+| --- | --- | --- |
+| clean | 生成的工作流集合和 lock 文件一致 | 运行项目级验证 |
+| missing | 生成文件缺失 | 通常可用 `apply --confirm` 恢复 |
+| outdated | SCALE 有更新的生成模板 | 审阅计划，确认安全后应用 |
+| manual-review | 生成文件已有本地修改 | 检查 diff，不要自动覆盖 |
+
+`manual-review` 是有意设计。SCALE 不应该抹掉本地项目知识、服务命令或 Agent 规则。
+
+## 项目级适配
+
+生成文件更新后，再按真实仓库适配这些文件：
+
+- `.scale/verification.json`: service matrix, required checks, optional UI or E2E checks.
+- `.scale/workspace.json`: branch model, protected branches, monorepo or workspace boundaries.
+- `AGENTS.md` and `CLAUDE.md`: short agent entry rules.
+- `docs/workflow/README.md`: human-readable workflow and verification commands.
+- Repository wrappers such as `Makefile` and `scripts/workflow/verify.ps1`.
+
+对 `netdisk-project` 这类多服务产品，不能把 `/health` 当作充分验证。验证必须覆盖本次变更影响的真实产品路径，例如 gateway 路由、`/api/v1/*` 请求、OAuth callback、存储驱动、UI 调用和数据持久化。
+
+## Agent 本地产物忽略规则
+
+工作流资产和团队协作规则可以提交；Agent 平台的本地状态、临时 worktree、缓存、日志和会话产物不应提交。已有项目接入或升级 SCALE 时，检查根 `.gitignore` 是否至少覆盖这些本地产物：
+
+```gitignore
+.claude/worktrees/
+.claude/tmp/
+.claude/local/
+.codex/worktrees/
+.codex/tmp/
+.codex-tmp/
+.cursor/tmp/
+.continue/
+.aider*
+.gemini/tmp/
+.omc/
+.roo/tmp/
+.cline/tmp/
+.windsurf/
+.playwright-mcp/
+```
+
+不要为了省事直接忽略所有协作配置目录。像 `AGENTS.md`、`CLAUDE.md`、`.cursor/rules/`、团队共享的 `.claude/settings.json`、`.scale/governance.lock.json` 这类稳定规则可以进入版本库。
+
+## 推荐仓库封装
+
+接入 SCALE 的仓库建议暴露这些命令：
+
+```makefile
+workflow-upgrade-check:
+	scale upgrade check --dir .
+workflow-upgrade-plan:
+	scale upgrade plan --dir . --html
+workflow-upgrade-apply:
+	scale upgrade apply --dir . --confirm
+workflow-upgrade-rollback:
+	scale upgrade rollback --dir .
+workflow-upgrade-verify:
+	scale preflight --dir . --service all --preflight-profile quick
+```
+
+如果 Windows 环境没有 `make`，提供等价 PowerShell 脚本，或在文档里写清原始 `scale` 命令。
+
+## 完成检查
+
+- `scale --version` 输出预期版本。
+- `scale upgrade check --dir .` 没有非预期 drift。
+- 有变更时，`scale upgrade plan --dir . --html` 能生成可审阅计划。
+- `scale upgrade apply --dir . --confirm` 只在审阅计划后使用。
+- 项目级验证通过，或记录清楚已知失败。
+- `README.md`、`AGENTS.md`、`CLAUDE.md`、`docs/workflow/README.md` 指向同一组工作流命令。