@jack200714/mafw 4.5.1

package/.opencode/skills/mafw-desktop-inspector/SKILL.md

@@ -0,0 +1,170 @@
+# MAFW Desktop Inspector Skill
+
+## 角色
+
+Desktop Inspector — 通过 6 个 CLI 工具操作 MAFW Desktop GUI，截取视觉反馈，验证 UI 是否达到预期效果。
+
+## 入口条件
+
+- MAFW Desktop 应用正在运行（Electron 窗口可见）
+- Gateway 已连接（检查 `mafw_list_automation_rules` 可用）
+- `~/.config/mafw/desktop-automation.json` 存在（Desktop 启动时自动写入）
+- 调用 `mafw_desktop_*` 之前无需额外初始化
+
+## 可用工具（6 个）
+
+| 工具 | 层 | 用途 | 返回 |
+|------|----|------|------|
+| `mafw_desktop_screenshot(selector?)` | 1 | 截取全屏或指定区域，保存 PNG | `{ filePath, width, height }` |
+| `mafw_desktop_get_ui_state()` | 1 | 获取当前 UI 结构和可见元素 | `{ tab, elements[], dimensions, scrollPos }` |
+| `mafw_desktop_navigate(tab)` | 2 | 切换到指定标签页 | `{ ok, currentTab }` |
+| `mafw_desktop_click(selector)` | 2 | 用 CSS 选择器点击元素 | `{ clicked, element: {tag,text,bbox} }` |
+| `mafw_desktop_type(selector, text)` | 2 | 向输入框填写文字 | `{ typed, value }` |
+| `mafw_desktop_scroll(direction, amount?)` | 2 | 滚动页面 | `{ ok }` |
+
+## 工作流程
+
+### 标准检查流（最常用）
+
+```
+1. mafw_desktop_navigate({ tab: "目标页" })
+   → 导航到目标标签页
+2. mafw_desktop_get_ui_state()
+   → 读取当前 DOM，确认关键元素存在、文本正确
+3. mafw_desktop_screenshot({ selector: ".mafw-content" })
+   → 截取证据，保存到 .mafw/screenshots/ss-xxx.png
+4. 使用 Read 工具读取截图文件，进行视觉比对
+5. 输出结构化检查报告
+```
+
+### 交互流（需要操作 UI 时）
+
+```
+1. navigate → get_ui_state（确认目标元素存在且可见）
+2. click / type / scroll（执行操作）
+3. get_ui_state（确认状态变化）
+4. screenshot（保留前后对比证据）
+5. 输出报告
+```
+
+### 恢复流（操作后还原状态）
+
+```
+1. get_ui_state → 记录操作前状态
+2. 执行操作（click/type）
+3. 截图 + 验证
+4. 执行反向操作恢复原状态
+5. 输出报告
+```
+
+## CSS 选择器最佳实践
+
+优先使用以下选择器类型：
+- 语义标签: `button`, `h2`, `input[type=text]`
+- 指定 class: `.mafw-tab`, `.mafw-content`, `.mafw-rail`
+- 层级组合: `.automations-panel button:first-child`, `.mafw-tab:nth-child(3)`
+- 文本属性: `[aria-label="Automation"]`, `[title="Configuration"]`
+- 文本内容: `button:has-text("Enable")`（如果框架支持）
+
+避免：
+- 自动生成的 hash class（如 `css-1abc2de`）
+- ID 选择器 `#xxx`（可能动态变化）
+- 过于复杂 > 4 层的嵌套选择器
+
+## 标签页映射
+
+| Tab 值 | 对应页面 | DOM 特征 |
+|--------|----------|----------|
+| `chat` | 对话页面 | `.mafw-chat`, `.mafw-session-turn-container` |
+| `goals` | Goal 看板 | Dashboard KPI 卡片 + Goal 列表 |
+| `memory` | 记忆搜索 | 搜索框 + 记忆单元列表 |
+| `approvals` | 审批队列 | 待审批问题列表 |
+| `triage` | 问题分类 | Triage 条目列表 |
+| `automation` | 自动化规则 | 规则卡片（enable/disable 开关） |
+
+## 输出报告格式
+
+每次检查完成后，必须输出结构化报告：
+
+```json
+{
+  "page": "automation",
+  "checks": [
+    { "type": "element_exists", "selector": "h2", "expected": "MAFW", "actual": "MAFW", "pass": true },
+    { "type": "element_count", "selector": ".rule-card", "expected": 4, "actual": 4, "pass": true },
+    { "type": "text_match", "selector": ".rule-card:first-child span.status", "expected": "ON", "actual": "ON", "pass": true },
+    { "type": "screenshot", "filePath": ".mafw/screenshots/screenshot-xxx.png", "pass": true }
+  ],
+  "screenshots": [".mafw/screenshots/screenshot-xxx.png"],
+  "verdict": "PASS",
+  "issues": []
+}
+```
+
+## 约束
+
+- **不要连续快速截图**：每次截图间隔至少 500ms，等渲染完成
+- **click 前必须 get_ui_state**：确认目标元素在当前视口内，且 boundingBox 有合理值
+- **navigate 后等待 300ms**：等 SolidJS 响应式渲染完成再执行下一步
+- **screenshot 返回的是文件路径**：需要用 Read 工具读取截图文件进行视觉验证
+- **type 仅对 INPUT/TEXTAREA/contentEditable 生效**：对其他元素使用 type 会返回错误
+- **scroll 对 .mafw-content 容器最有效**：这是主内容区的滚动容器
+- **click 后必须 verify**：调用 get_ui_state 确认 click 产生了预期效果
+- **所有操作有 10 秒超时**：如果 Desktop 无响应，调用会超时报错
+
+## 典型场景
+
+### 场景 1：验证自动化规则列表渲染正确
+
+```
+1. mafw_desktop_navigate({ tab: "automation" })
+2. mafw_desktop_get_ui_state()
+   → 检查 elements 中是否包含预期规则名
+3. mafw_desktop_screenshot({ selector: ".mafw-content" })
+   → 保存截图到 .mafw/screenshots/ss-xxx.png
+4. [Read 工具] 读取截图文件
+5. 输出报告（含 veredict）
+```
+
+### 场景 2：测试规则启用/禁用开关
+
+```
+1. navigate → get_ui_state → 记录切换前状态
+2. click(".rule-card:first-child button.toggle")
+3. get_ui_state → 验证状态翻转（ON→OFF 或 OFF→ON）
+4. screenshot → 保留证据
+5. click(".rule-card:first-child button.toggle")  ← 恢复原状态
+6. 输出报告
+```
+
+### 场景 3：导航到多个页面，分别截图
+
+```
+1. navigate → screenshot ("chat")
+2. navigate → screenshot ("memory")
+3. navigate → screenshot ("automation")
+4. 输出报告（含多页对比）
+```
+
+### 场景 4：填写搜索框并验证结果
+
+```
+1. navigate("memory")
+2. get_ui_state() → 确认搜索框存在
+3. type("input[type=search]", "memory decay")
+4. 等待 500ms
+5. get_ui_state() → 检查搜索结果是否出现
+6. screenshot → 保留证据
+7. 输出报告
+```
+
+## 自检清单
+
+每次任务完成后必须回答：
+- [ ] 是否 navigate 到了正确 tab？
+- [ ] 是否 get_ui_state 确认了目标元素存在且可见？
+- [ ] 是否有 screenshot 作为视觉证据？
+- [ ] 输出报告是否 JSON 格式，含 veredict？
+- [ ] 如果执行了 click/type，是否 verify 了状态变化？
+- [ ] 截图文件路径是否正确（`.mafw/screenshots/`）？
+- [ ] 如果修改了 UI 状态（toggle），是否恢复了原状态？

package/.opencode/skills/mafw-execute/SKILL.md

@@ -0,0 +1,62 @@
+# MAFW Execute Agent — Execution Skill
+
+## 角色
+
+Execute Agent — 根据 Plan 编写代码，生成 Receipt。
+
+## 职责
+
+1. 读取 Task 定义（验收标准 + affected_files + constraints）
+2. 读取 Waves 配置
+3. 准备 Goal Worktree（goal/{goalId} 分支）
+4. 串行执行 Wave，Wave 内 Task 并行（各自 change/{taskId} 分支）
+5. 每个 Task: 调用 LLM 编写代码，git commit
+6. 合并 Wave 到 Goal 分支
+7. 远程 CLI 同步（如果配置）
+8. 写入 receipts/{goalId}/
+9. **【显式】更新 state.json → nextAction: CREATE_REVIEW_SESSION**
+
+## 输入
+
+- waves.json（Plan 产出）
+- tasks/{id}.md（Task 定义）
+- L3 Constraint Δ（硬边界）
+- L3 Prompt Δ（认知偏差修正）
+
+## 输出
+
+- 代码变更（Git diff on change/{taskId} 分支）
+- receipts/{goalId}/（执行结果）
+- state/{goalId}.json（nextAction: CREATE_REVIEW_SESSION）
+
+## 核心约束
+
+- 验收标准必须满足，否则标记为 FAILED
+- 遵守 L3 硬约束，违反必须标记为 DEGRADED
+- 每个功能必须有边界测试（空值、超长输入、特殊字符、时序攻击）
+- 加密配置必须引用 AGENTS.md，禁止直觉选择
+- 测试覆盖率 < 80% 且非 prototype/spike → 标记 DEGRADED
+- 每个 Task 使用独立 Git 分支（change/{taskId}）
+- Wave 间串行，Wave 内并行
+
+## 状态更新
+
+Skill Entry 函数末尾必须显式调用：
+```typescript
+await transitionPhase(goalId, {
+  from: 'EXECUTING',
+  to: 'EXECUTING_COMPLETE',
+  nextAction: 'CREATE_REVIEW_SESSION',
+  artifacts: { execute: 'receipts/{goalId}/' }
+});
+```
+
+## 自检清单
+
+执行完成后，必须回答：
+1. [ ] 验收标准是否全部满足？
+2. [ ] 是否有边界测试？
+3. [ ] 是否遵守了 L3 硬约束？
+4. [ ] 覆盖率是否达标？
+5. [ ] 是否有 lint 错误？
+6. [ ] **是否显式更新了 state.json？**

package/.opencode/skills/mafw-gateway-restart/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: mafw-gateway-restart
+description: 当需要重启或自更新 MAFW Gateway 时使用。覆盖完整流程：判断是否需要重启、修改代码、构建门禁、写重启令牌、goal state 续跑标记、等待更新完成通知。触发词：重启 gateway / 更新 gateway / 让改动生效 / self-update。
+---
+
+# MAFW Gateway 重启 / 自更新 Skill
+
+## 第一步：判断是否需要重启
+
+| 改动对象 | 是否需要重启 |
+|---|---|
+| `.mafw/config.yaml`（搜索/记忆/成本参数等） | ❌ 热生效（gateway watch config 文件，~300ms 内自动 reload；server/paths 段会提示"需重启"） |
+| `.mafw/automations/*.json` | ❌ 热生效（规则自动 reload） |
+| `gateway/src/**`、`gateway/package.json` | ✅ **必须走本 Skill 的重启流程** |
+| `.mafw/constraints.json` 等运行期读取文件 | ❌ 每次请求读取 |
+
+只有"gateway 代码/依赖"改动才需要重启。改配置类文件直接写即可，**不要**为此重启。
+
+## 流程（七步）
+
+### ① 修改代码
+改动面限定：`gateway/src/**`、`gateway/package.json`。所有文件写入/命令执行都会走 MAFW 审批（PermissionCard），无需额外申请。
+
+> **注意**：manager agent 的 `edit`/`write`/`apply_patch` 工具已被权限配置禁用（与 plan 对齐）。**本流程的全部文件操作（改码、写令牌）必须用 bash 命令执行**（bash 默认允许）。gateway 的 MCP 工具（`mafw_*`）不受影响，可正常使用。
+
+### ② 构建（必须通过）
+```powershell
+cd gateway; npm run build
+```
+- 构建失败 → 修复后重试，**禁止**继续后续步骤（旧 gateway 继续运行不受影响）
+- 建议先 `git add -A; git commit -m "..."` 留下回滚点（回滚：`git reset --hard <commit>`）
+
+### ③ 写重启令牌（原子写，先 .tmp 再 rename）
+```powershell
+$token = @{
+  target = "gateway"
+  action = "update"
+  reason = "<简要说明>"
+  requestedAt = (Get-Date).ToString("o")
+  delayMs = 5000
+  commit = (git rev-parse --short HEAD 2>$null)
+} | ConvertTo-Json
+$dst = "$env:USERPROFILE\.mafw\pending-restart.json"
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.mafw" | Out-Null
+Set-Content -Path "$dst.tmp" -Value $token -Encoding UTF8
+Rename-Item "$dst.tmp" $dst -Force
+```
+- `action` 必须是 `update`（gateway 自行 build）或 `restart`（已手动 build，仅重启）
+- `delayMs` 默认 5000：给 agent 时间把回复发给用户，重启发生在回复送达后
+- gateway 每 2s 轮询该文件；发现后先删除（防循环），按 delayMs 延迟后自举重启
+
+### ④ goal state 写续跑标记
+```powershell
+# 用 mafw_update_state 工具或直接更新 state/{goalId}.json 的 nextAction，
+# 让重启后恢复的 agent 知道下一步做什么
+```
+
+### ⑤ 回复用户
+"已修改 X 并请求重启 gateway，约 5 秒后生效，完成后我会在本会话继续。"
+
+### ⑥ 等待更新完成通知
+重启完成后，新 gateway 会向**本会话**注入一条 `[MAFW SYSTEM] Gateway 自更新已完成...` 消息（触发新一轮 turn）：
+- 收到通知 → 读 goal state → 继续执行 `nextAction`
+- **兜底**：若 60 秒内未收到通知，检查 `$env:USERPROFILE\.mafw\last-restart.json`：
+  - `notified: true` → 更新已完成，正常继续
+  - `notifyFailed: true` / 文件不存在 → 手动确认 gateway 健康（`Invoke-WebRequest http://127.0.0.1:3000/health`）后继续
+
+### ⑦ 继续执行
+读 goal state，执行 `nextAction`，向用户汇报结果。
+
+## 等价路径
+- 用户/其他会话也可执行 `mafw update`（CLI 写同一令牌；无会话上下文，通知走 manager 会话兜底）
+
+## 错误排查
+
+| 现象 | 处理 |
+|---|---|
+| build 失败 | 修复代码重新 build；gateway 不受影响继续运行 |
+| 写令牌后无反应（>10s） | 检查 `$env:USERPROFILE\.mafw\pending-restart.json` 是否还在（gateway 未删=未处理）；`mafw status` 确认 gateway 在跑；令牌内容是否正确（target/action） |
+| 重启后起不来 | gateway 会先 spawn 新进程并确认存活才退出旧进程；新进程 2s 内崩溃则旧进程取消重启继续服务。检查 `~/.mafw/logs/mafw.log` 的 `[SelfUpdate]`/`[Scheduler]` 日志 |
+| 令牌是坏 JSON | gateway 连续 5 次解析失败后删除并记录错误（不重启） |
+| 通知没收到 | 按第⑥步兜底检查 last-restart.json；gateway 健康检查 |
+
+## 非目标
+- 不修改 `package.json` version（版本记录用 commit+时间戳，见 last-restart.json）
+- dev 模式（ts-node）下自举以 dist 产物为准；开发调试请手动重启
+- 不支持 git 远端拉取（当前无 remote）

package/.opencode/skills/mafw-github-scanner/SKILL.md

@@ -0,0 +1,38 @@
+# MAFW GitHub Scanner Skill
+
+## 职责
+
+扫描 GitHub 仓库，发现需要 Agent 处理的工作。
+
+## 工作流程
+
+1. 读取 args.repo 确定目标仓库
+2. 读取 args.filters 确定扫描范围
+3. 调用 GitHub API 获取数据
+4. 返回 findings 列表
+
+## 输入
+
+```json
+{
+  "repo": "my-org/myapp",
+  "filters": ["open_prs", "pending_reviews", "ci_failed"]
+}
+```
+
+## 输出
+
+```json
+{
+  "findings": [
+    { "type": "open_pr", "count": 3 },
+    { "type": "ci_failed", "count": 1 }
+  ]
+}
+```
+
+## 约束
+
+- 需要 GitHub token（从环境变量读取）
+- 不直接创建 Goal，只返回 findings
+- Automation Engine 决定如何处理 findings

package/.opencode/skills/mafw-goal/SKILL.md

@@ -0,0 +1,76 @@
+# MAFW Goal Agent — Interview Skill
+
+## 角色
+
+Goal Agent — 在 Phase 接力启动前与用户进行 Interview，确立目标、指标、边界。
+
+## 职责
+
+1. 追问用户，明确 Goal 的具体需求
+2. 确立可量化的指标（metrics）
+3. 确立不可逾越的边界（boundaries）
+4. 输出 Goal Charter（goals/{id}.md）
+5. 写入请求文件（requests/{id}.json）
+6. **初始化状态机（state/{id}.json → nextAction: CREATE_PLAN_SESSION）**
+7. 等待用户确认（说"确认"）
+
+## 输入
+
+用户输入的初始 Goal 描述，如："实现用户认证系统"
+
+## 输出
+
+```markdown
+# Goal Charter — 用户认证系统
+
+> Goal ID: 001-auth
+> 创建时间: 2026-06-21T15:00:00Z
+
+## 目标
+
+实现用户认证系统，包含 JWT 登录、注册、refresh token 功能。
+
+## 指标（必须可量化）
+
+| 指标 | 目标值 | 验证方式 |
+|------|--------|----------|
+| 测试覆盖率 | >= 80% | jest --coverage |
+| lint 错误 | 0 | eslint |
+| 接口响应时间 | < 200ms | 集成测试 |
+
+## 边界（不可逾越）
+
+- [ ] 禁止使用内存 Map 存储 refresh token（生产环境必须用 Redis）
+- [ ] 所有 JWT 必须使用 RS256 算法（AGENTS.md §3.1）
+- [ ] 密码必须 bcrypt 加密，禁止明文存储
+
+## 范围
+
+- 包含：登录 API、注册 API、refresh token API、JWT 中间件
+- 不包含：前端 UI、OAuth 第三方登录、权限管理（RBAC）
+
+## 风险
+
+| 风险 | 概率 | 影响 | 缓解 |
+|------|------|------|------|
+| JWT 算法选择错误 | 中 | 高 | 强制引用 AGENTS.md §3.1 |
+| 覆盖率不足 | 高 | 中 | 自动标记 DEGRADED |
+
+## 确认
+
+用户确认后，此 Goal Charter 锁定，Scheduler 自动创建 Plan Session。
+```
+
+## 追问模板
+
+1. 目标具体化："实现用户认证系统" → 需要哪些功能？登录/注册/refresh token？
+2. 指标量化：测试覆盖率期望多少？lint 标准？
+3. 边界明确：是否有特定算法要求？是否有外部依赖限制？
+4. 范围排除：明确哪些功能不在本次范围内。
+
+## 约束
+
+- 用户未确认前，不得写入 state.json
+- 指标必须可量化，不可模糊（如"尽量好"不可接受）
+- 边界必须引用 AGENTS.md 条款（如存在）
+- 必须初始化 state.json（nextAction: CREATE_PLAN_SESSION）

package/.opencode/skills/mafw-interview/SKILL.md

@@ -0,0 +1,68 @@
+# MAFW Interview Skill — Goal Interview Agent
+
+## 职责
+
+在 Phase 接力启动前与用户进行 Interview，确立目标、指标、边界。
+
+## 工作流程
+
+1. 追问用户，明确 Goal 的具体需求（3-5 个问题）
+2. 确立可量化的指标（metrics）
+3. 确立不可逾越的边界（boundaries）
+4. 输出 Goal Charter（goals/{id}.md）
+5. 写入请求文件（requests/{id}.json）
+6. 初始化状态机（state/{id}.json → nextAction: CREATE_PLAN_SESSION）
+7. 等待用户确认（说"确认"）
+
+## 输出格式
+
+```markdown
+# Goal Charter — {title}
+
+> Goal ID: {goalId}
+> 创建时间: {createdAt}
+
+## 目标
+
+{description}
+
+## 指标（必须可量化）
+
+| 指标 | 目标值 | 验证方式 |
+|------|--------|----------|
+| test_coverage | >= 80% | jest --coverage |
+
+## 边界（不可逾越）
+
+- [ ] 禁止使用内存 Map 存储 refresh token
+- [ ] 所有 JWT 必须使用 RS256 算法
+
+## 范围
+
+- 包含：...
+- 不包含：...
+
+## 风险
+
+| 风险 | 概率 | 影响 | 缓解 |
+|------|------|------|------|
+| ... | 中 | 高 | ... |
+
+## 确认
+
+用户确认后，此 Goal Charter 锁定，Gateway 自动创建 Plan Session。
+```
+
+## 约束
+
+- 用户未确认前，不得写入 state.json
+- 指标必须可量化，不可模糊（如"尽量好"不可接受）
+- 边界必须引用 AGENTS.md 条款（如存在）
+- 必须初始化 state.json（nextAction: CREATE_PLAN_SESSION）
+
+## 状态更新
+
+用户确认后，写入：
+- goals/{goalId}.md
+- requests/{goalId}.json
+- state/{goalId}.json（nextAction: CREATE_PLAN_SESSION）

package/.opencode/skills/mafw-memory-extractor/SKILL.md

@@ -0,0 +1,65 @@
+# MAFW Memory Extractor — Δ Extraction Skill
+
+## 角色
+
+Memory Extractor Agent — 从 Review 失败中提取参数化记忆（Δ）。
+
+## 职责
+
+1. 读取 L2 压缩后的 YAML lesson
+2. 分析 Review 报告中的失败原因
+3. 从 AGENTS.md 检测规范引用
+4. 提取 0~2 个 Δ（Constraint / Prompt / Pattern）
+5. 自检：是否可验证、是否过于刚性、是否重复
+
+## 输入
+
+- L2 YAML Lesson（compacted）
+- Review 报告（verdict=fail）
+- AGENTS.md（检测规范引用）
+
+## 输出
+
+0~2 个 Δ yaml，例如：
+
+```yaml
+id: "review-coverage-v2"
+scope: ["plan", "execute"]
+enforcement: "hard"
+trigger_condition:
+  domain: ["auth", "api"]
+  task_type: ["coding", "test"]
+  loop_stage: ["planning", "executing"]
+rule: "测试覆盖率低于 80% 的代码必须标记为 DEGRADED，除非 Task 标签包含 'prototype' 或 'spike'。"
+origin:
+  goal: "001-auth"
+  loop: 1
+  task: "001-2-jwt-config"
+  lesson_anchor: "lessons/001-auth.md#L12"
+created_at: "2026-06-21T15:00:00Z"
+energy_score: 0.65
+verified: false
+priority: 9
+```
+
+## 提取规则
+
+1. **Constraint Δ**：从 violation.rule 提取，必须可验证（布尔判断）
+2. **Prompt Δ**：从 lesson 中的检查清单提取，软提示
+3. **Pattern Δ**：仅在特定 domain（auth/api/user-system）的 Wave 分解模式提取
+
+## 核心约束
+
+- 只输出 `enforcement: hard` 的布尔约束（可验证）
+- 禁止软性建议（如"建议"、"可以考虑"）
+- 必须标注 origin_loop 和 origin_task
+- 最多 2 个 Δ，避免过度约束
+- 必须与 AGENTS.md 已有条款对比，避免重复
+
+## 自检清单
+
+提取完成后，必须回答：
+1. [ ] 这个 Δ 是否可验证？（是/否 能判断）
+2. [ ] 是否过于刚性？（会不会导致误伤）
+3. [ ] 是否与已有 Δ 重复？
+4. [ ] 是否标注了 origin_loop 和 origin_task？

package/.opencode/skills/mafw-plan/SKILL.md

@@ -0,0 +1,58 @@
+# MAFW Plan Agent — Planning Skill
+
+## 角色
+
+Plan Agent — 根据 Goal Charter 生成详细的 Waves 和 Tasks 执行计划。
+
+## 职责
+
+1. 读取 Goal Charter (L1)
+2. 读取相关 Lessons (L2 检索)
+3. 加载 Parametric Δ (L3 注入)
+4. 拼接完整 Prompt
+5. 调用 LLM 生成 Plan
+6. 解析回复为 waves.json
+7. 写入 tasks/{id}.md
+8. **【显式】更新 state.json → nextAction: CREATE_EXECUTE_SESSION**
+
+## 输入
+
+- goals/{goalId}.md (Goal Charter)
+- lessons/ (L2 检索结果)
+- parametric/ Δ (L3 注入)
+- state/{goalId}.json (当前 loop)
+
+## 输出
+
+- waves.json (Plan 产出)
+- tasks/{id}.md (Task 定义)
+- state/{goalId}.json (nextAction: CREATE_EXECUTE_SESSION)
+
+## 核心约束
+
+- Plan 必须包含可验收的指标
+- 每个 Wave 的 Task 必须标注 affected_files
+- 必须考虑 L3 Δ 约束（如覆盖率检查清单）
+- 多 Loop 时，必须读取上一 Loop 的 Lesson
+
+## 状态更新
+
+Skill Entry 函数末尾必须显式调用：
+```typescript
+await transitionPhase(goalId, {
+  from: 'PLANNING',
+  to: 'PLANNING_COMPLETE',
+  nextAction: 'CREATE_EXECUTE_SESSION',
+  artifacts: { plan: 'waves.json' }
+});
+```
+
+## 自检清单
+
+Plan 完成后，必须回答：
+1. [ ] 是否读取了 Goal Charter？
+2. [ ] 是否加载了相关 Lessons？
+3. [ ] 是否注入了 Parametric Δ？
+4. [ ] 是否生成了 waves.json？
+5. [ ] 是否写入 tasks/{id}.md？
+6. [ ] **是否显式更新了 state.json？**