@hongmaple0820/med-scale-research-os 0.43.0

package/docs/start/README.md

@@ -0,0 +1,79 @@
+# SCALE Engine 入门路径
+
+这个目录面向新用户。目标是先跑通一条最小路径，再理解完整体系，不要求一开始掌握所有命令。
+
+## 推荐阅读顺序
+
+1. [3 分钟快速开始](quickstart.md)
+   从空目录初始化治理工作流，看到 `.scale`、模板、验证 profile 和状态输出。
+
+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、资源治理和工程规范扫描。
+
+4. 回到根目录 [README](../../README.md)
+   理解 SCALE Engine 的核心能力和 governance pack 选择。
+
+4. [工作流升级指南](workflow-upgrade.md)
+   理解工作流更新、第三方 skills/MCP/CLI 更新时如何先检查、生成计划、自动刷新干净受管文件，并避免覆盖本地改动。
+
+5. 查看 [文档地图](../README.md)
+   区分哪些文档是用户指南、哪些是参考资料、哪些是历史规划和过程记录。
+
+如果你要开发的是 `scale-engine` 仓库本身，而不是把 SCALE 接入别的项目，改看：
+
+- [../guides/GETTING_STARTED.md](../guides/GETTING_STARTED.md)
+- [../guides/DEVELOPMENT_WORKFLOW.md](../guides/DEVELOPMENT_WORKFLOW.md)
+- [../workflow/README.md](../workflow/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 后，至少应该能看到：
+
+- `scale preflight --preflight-profile quick` 可以执行。
+- `scale status` 能告诉你当前项目下一步该做什么。
+- `.scale/verification.json` 存在，并描述本地验证 profile。
+- `docs/workflow/templates/` 存在，并包含 Mini-PRD、plan、verification、review、summary 等模板。
+- `scale artifact render` 可以把任务 Markdown 证据渲染成 HTML。
+
+如果其中任何一步失败，先看命令输出，不要假设是环境问题。SCALE 的原则是：没有真实命令结果，就不声称通过。
+
+## 场景选择
+
+| 场景 | 推荐入口 |
+| --- | --- |
+| 第一次试用 | [3 分钟快速开始](quickstart.md) |
+| 想看 Agent 治理闭环 | [官方 Demo Walkthrough](agent-governance-demo.md) |
+| 前端项目 | `scale init --governance-pack frontend-app` |
+| Node/TypeScript 包 | `scale init --governance-pack node-library` |
+| Go 多服务后端 | `scale init --governance-pack go-service-matrix` |
+| 多仓库/MOE 工作区 | `scale init --governance-pack moe-workspace` |
+| 文档、报告、截图、脚本混乱 | `scale init --governance-pack resource-governance` |
+| 工作流或第三方能力要升级 | `scale upgrade --lang zh` |
+| 已有项目接入 AI OS runtime | `scale ai-os adopt --task "接入 AI OS runtime" --lang zh` |
+
+
+## 工作流升级短路径
+
+已有项目先看 [SCALE 工作流升级指南](workflow-upgrade.md)。它说明 `scale init --interactive`、`scale upgrade` 默认向导、`scale upgrade check/plan/apply/rollback` 高级入口、`scale ai-os adopt`、`--lang zh/en` 双语输出、仓库本地 `make workflow-upgrade-*` / `make workflow-aios-adopt` 入口，以及生成文件更新和项目级验证之间的边界。

package/docs/start/agent-governance-demo.md

@@ -0,0 +1,107 @@
+# 官方 Demo Walkthrough：让 Agent 不再跳过工程纪律
+
+这个 demo 用一个很小的 OAuth state 校验任务，演示 SCALE 如何把“应该做”的工程动作变成可检查证据。
+
+## Demo 目标
+
+我们要实现并验证一个安全敏感行为：
+
+> 当 OAuth callback 的 state 过期、被消费或不匹配时，系统必须拒绝请求，而不是返回模糊 500。
+
+SCALE 关注的不是这段业务逻辑有多复杂，而是 Agent 是否：
+
+- 先澄清上下文和验收标准。
+- 先诊断失败模式，不盲修。
+- 写出可检查的 TDD 切片。
+- 运行验证命令并留下证据。
+- 生成可评审的 Markdown 和 HTML artifact。
+- 不把临时报告、截图、脚本、敏感信息乱提交。
+
+## 1. 准备 demo 项目
+
+从仓库复制官方 demo：
+
+```powershell
+Copy-Item -Recurse E:\project\scale-engine\examples\demo-projects\agent-governance-demo .\scale-agent-demo
+Set-Location .\scale-agent-demo
+npm install
+npm test
+```
+
+macOS/Linux 可以用：
+
+```bash
+cp -R /path/to/scale-engine/examples/demo-projects/agent-governance-demo ./scale-agent-demo
+cd scale-agent-demo
+npm install
+npm test
+```
+
+## 2. 安装治理工作流
+
+```bash
+scale init --governance-pack node-library
+scale preflight --preflight-profile quick
+scale status
+```
+
+你应该看到 SCALE 生成 `.scale`、`docs/workflow/templates` 和项目治理规则。
+
+## 3. 建立任务证据
+
+```bash
+scale context init --name "Agent Governance Demo"
+scale runtime start --session-id 2026-05-18-oauth-state --task-id 2026-05-18-oauth-state --level M --agent codex
+scale context grill --task-id 2026-05-18-oauth-state --task "加固 OAuth state 校验"
+scale diagnose plan --task-id 2026-05-18-oauth-state --symptom "OAuth callback 在 state 过期或不匹配时行为不明确"
+scale tdd slice --task-id 2026-05-18-oauth-state --behavior "拒绝过期、已消费或不匹配的 OAuth state" --public-interface "verifyOAuthState(record, providedState, now)" --failing-test "expired, consumed, mismatched state should return ok=false" --test-file tests/oauth-state.test.ts --impl-files src/oauth-state.ts
+```
+
+这一步会在任务目录中沉淀探索、诊断和 TDD 证据。
+
+## 4. 运行真实验证
+
+```bash
+npm test
+scale standards scan --dir .
+scale assets scan --dir .
+scale runtime record --title "demo business tests" --kind command --status passed --command "npm test" --exit-code 0 --summary "official demo OAuth state tests passed"
+scale runtime final-check --task-id 2026-05-18-oauth-state --session-id 2026-05-18-oauth-state --level M
+```
+
+验收标准：
+
+- `npm test` 必须真实通过。
+- `standards scan` 不能发现阻断级别问题。
+- `assets scan` 应能识别长期维护文档、任务证据和生成产物分类。
+- `runtime final-check` 必须确认当前任务范围内有通过证据，且没有失败证据。
+
+## 5. 生成记忆候选和 HTML artifact
+
+```bash
+scale memory pack --task-id 2026-05-18-oauth-state --session-id 2026-05-18-oauth-state --task "加固 OAuth state 校验" --level M --budget 4000
+scale memory settle --task-id 2026-05-18-oauth-state --session-id 2026-05-18-oauth-state --task "加固 OAuth state 校验" --level M
+```
+
+`memory pack` 用于恢复上下文，`memory settle` 用于把本次真实验证沉淀成可审查学习候选。候选仍需要人审后才能进入长期知识库或工程规范。
+
+```bash
+scale artifact render --task-id 2026-05-18-oauth-state --artifact-dir docs/worklog/tasks/2026-05-18-oauth-state
+scale artifact doctor --artifact-dir docs/worklog/tasks/2026-05-18-oauth-state
+scale artifact open --task-id 2026-05-18-oauth-state --artifact-dir docs/worklog/tasks/2026-05-18-oauth-state
+```
+
+HTML artifact 的价值是让人类更快评审 Agent 的思考、证据和风险。Markdown 仍然是源文件，HTML 是交付视图。
+
+## 6. 对比没有 SCALE 的情况
+
+没有 SCALE 时，Agent 很容易出现这些行为：
+
+- 直接改实现，不先说明验收标准。
+- 修了 happy path，却漏掉过期、已消费、不匹配等异常路径。
+- 说“测试通过”，但没有命令输出。
+- 写了临时脚本、截图、报告，却不知道哪些应该提交。
+- 发版前没有 review evidence 和风险记录。
+
+有 SCALE 后，这些行为会被命令、模板、门禁和证据文件显式化。它不能替代人类判断，但能让 Agent 的工作不再靠口头保证。
+

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/quickstart.md

@@ -0,0 +1,191 @@
+# 3 分钟快速开始
+
+目标：在一个项目里安装 SCALE 工作流，完成依赖检查，并看到可验证的治理产物。
+
+## 前置条件
+
+- Node.js 20+
+- npm
+- Git
+- Windows PowerShell、Git Bash、macOS/Linux shell 均可
+
+Python、Bun、Rust/Cargo、uv/pipx 不是启动 SCALE 的硬要求。只有启用 Graphify、GBrain、RTK 等第三方能力时，安装器才会提示缺少哪些运行时以及可执行的修复命令。
+
+## 1. 安装 CLI
+
+```bash
+npm install -g @hongmaple0820/scale-engine
+scale --version
+```
+
+本仓库开发时也可以直接运行源码入口：
+
+```bash
+node --import tsx E:/project/scale-engine/src/api/cli.ts --help
+```
+
+## 2. 初始化项目
+
+```bash
+mkdir scale-demo
+cd scale-demo
+scale init --governance-pack standard
+```
+
+初始化会生成 `.scale/`、`docs/`、`scripts/` 以及对应 Agent 入口文件。已有项目升级不要盲目重复 `init`，优先使用升级向导：
+
+```bash
+scale upgrade --dir .
+```
+
+向导会生成升级计划、写入 HTML 报告，并在安全时询问是否应用。CI 或高级用户仍可使用分步命令：
+
+```bash
+scale upgrade check --dir . --lang zh
+scale upgrade plan --dir . --html --lang zh
+scale upgrade apply --dir . --confirm --lang zh
+```
+
+## 3. 交互式安装第三方能力
+
+默认语言是中文。需要英文时加 `--lang en`，也可以设置 `SCALE_LANG=en`。
+
+直接进入交互式安装：
+
+```bash
+scale setup
+```
+
+交互式安装会询问：
+
+- 语言：默认中文。
+- 安装包：标准、前端/UI、AI OS、完整、自定义。
+- 记忆供应商：默认 `gbrain`，也可切换到 `scale-local`。
+- 记忆路由模式：默认 `external-first`。
+- 是否执行安装：可跳过、全量安装、或只安装选中的第三方项。
+
+只查看计划：
+
+```bash
+scale setup --pack full
+```
+
+确认后执行安装：
+
+```bash
+scale setup --pack full --apply --yes
+```
+
+机器可读输出：
+
+```bash
+scale setup --pack full --json
+```
+
+`setup` 和 `bootstrap deps` 都会输出 `runtimeChecks`。如果机器缺少 `python`、`bun`、`cargo`、`uv/pipx`、`node/npm/npx`，会先显示缺失项和修复建议，再决定是否执行 `--apply`，避免安装中途卡住。
+
+记忆供应商可在安装入口直接切换，不需要手改 `.scale/memory-providers.json`：
+
+```bash
+scale setup --pack memory --memory-provider scale-local --json
+scale setup --pack memory --memory-provider gbrain --memory-mode external-first --json
+```
+
+## 4. UI Skills 默认策略
+
+| 能力 | 默认定位 | 安装方式 | 关键验证 |
+| --- | --- | --- | --- |
+| `awesome-design-md` | 品牌、视觉语言、`DESIGN.md` 来源 | `scale setup --pack ui --include awesome-design-md --apply` | 生成 `~/.agents/skills/awesome-design-md/SKILL.md`，同步 `~/.scale/vendor/awesome-design-md` |
+| `ui-ux-pro-max` | UX、状态、可访问性、响应式验收 | `scale setup --pack ui --include ui-ux-pro-max --apply` | 生成 `~/.agents/skills/ui-ux-pro-max/SKILL.md`，同步 `~/.scale/vendor/ui-ux-pro-max` |
+| `frontend-design` | 可选实现陪跑，不再是 UI 默认必装项 | `scale setup --pack ui --include frontend-design --apply` | 需要时显式安装 |
+
+安装器优先使用 `git clone --depth 1` 同步上游仓库；如果没有 Git 但有 npx，会退回 `npx degit`。缺少两者时不会硬跑失败，会在安装计划里标记为需要人工处理并给出下一步。
+
+## 5. 其他第三方能力边界
+
+| 能力 | 默认定位 | 关键验证 |
+| --- | --- | --- |
+| `rtk` | CLI proxy/token 节省能力 | `rtk gain` 和 `rtk init -g --codex` |
+| `gbrain` | 默认记忆供应商 | 检查 brain 是否已配置且连接/schema 可用；未初始化会提示 `gbrain init --pglite` |
+| `graphify` | 知识图谱产物供应商 | `graphify install --platform codex` 和 `graphify-out/graph.json` |
+| `codegraph` | 代码结构索引供应商 | `codegraph init -i` 和 `.codegraph/` |
+
+底层命令仍可直接使用：
+
+```bash
+scale bootstrap deps --profile advanced --governance-pack frontend-app --lang zh
+scale bootstrap deps --profile advanced --governance-pack frontend-app --apply --lang zh
+```
+
+## 6. 验证闭环
+
+```bash
+scale doctor
+scale setup --verify --pack full --json
+scale preflight --preflight-profile quick
+scale status
+scale assets scan --dir .
+scale standards scan --dir .
+scale runtime doctor --level S
+scale memory provider status --json
+scale codegraph status --json
+```
+
+未运行验证，不要声称通过。`setup --json` 和 `bootstrap deps --json` 只代表依赖计划可解析，不等于第三方服务已经可用。
+
+真实第三方能力需要单独跑回放验证。默认命令会把未配置的远端能力标记为 `blocked`，但不会让本地发布门禁误失败；需要作为强制门禁时使用对应 npm script 或加 `--require-*`。
+
+```bash
+npm run smoke:providers
+npm run smoke:gbrain
+npm run smoke:graphify -- --large-project /path/to/large-project
+```
+
+验证语义：
+
+- `smoke:gbrain` 会先确认 gbrain 已配置且关键健康检查可用，通过后写入一个临时记忆页，再用独立 CLI 进程 `get/query/search` 回放，证明不是本地 mock。
+- `smoke:graphify` 默认对真实项目执行 `graphify update <project> --no-cluster`，走 AST/Python 无模型路径，检查 `graph.json`，再执行 `graphify query`；只有显式 `--semantic-extract` 才允许语义模型提取。
+- `graphify-out/` 是生成产物，不应该提交到 Git；长期知识沉淀应进入经过评审的 `memory/`、`docs` 或规则文件。
+
+## 7. 建立任务上下文
+
+```bash
+scale context init --name "Scale Demo"
+scale runtime start --session-id 2026-05-18-oauth-hardening --task-id 2026-05-18-oauth-hardening --level M --agent codex
+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
+```
+
+任务完成后记录验证证据并沉淀候选经验：
+
+```bash
+scale runtime record --title "quick preflight" --kind command --status passed --command "scale preflight --preflight-profile quick" --exit-code 0 --summary "quick preflight passed"
+scale runtime final-check --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --level M
+scale memory pack --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --task "继续加固 OAuth callback" --level M --budget 4000
+scale memory settle --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --task "继续加固 OAuth callback" --level M
+```
+
+`memory settle` 默认只生成学习候选，不会自动把一次会话判断提升成长线规则。存在失败证据时，候选会要求先解决失败，避免把未闭环问题沉淀成经验。
+
+## 8. MOE/多仓工作区
+
+多仓项目使用：
+
+```bash
+scale init --governance-pack moe-workspace
+```
+
+MOE 默认把子工程配置为兄弟仓库或绝对路径，不建议把独立 Git 子工程放在主工程根目录下。`.scale/workspace.json` 中的典型写法：
+
+```json
+{
+  "workspace": {
+    "type": "moe",
+    "repositories": [
+      { "name": "api", "path": "../api", "role": "service" },
+      { "name": "web", "path": "../web", "role": "frontend" }
+    ]
+  }
+}
+```