@accelerator-mzq/forge 1.4.0

package/dist/core/templates/skills/verifying-three-dimensions.md

@@ -0,0 +1,245 @@
+---
+name: forge:verifying-three-dimensions
+description: Use when verifying a forge change — analyze Completeness / Correctness / Coherence three dimensions to produce verify_findings with concrete evidence and severity, instead of degenerate "tests pass" binary
+---
+
+# forge verifying-three-dimensions
+
+> 本 skill 走 `forge:writing-skills` 协议开发(非 bootstrap exception,沿 design §2.9.5 dogfood)。SKILL.md + scenarios 经过 RED → GREEN → REFACTOR 完整链(plan-9d Task 1 + Task 2 + Task 7)。
+
+## Overview
+
+forge v0.4 的 verify 阶段退化为"测试 pass + log_hash"二值判定(沿 design §2.2.1)。测试 pass 不等于实施完整 — spec 里没被测试覆盖的 Requirement 完全不会被发现。本 skill 移植 OpenSpec `verify-change.ts` 的三维度方法论,把 verify 阶段从二值判定升级为带证据的 finding 数组,**配合 forge fence 反向加固让 AI 不能偷懒推 SUGGESTION**。
+
+## Methodology (reference superpowers 上游)
+
+**REQUIRED BACKGROUND**:必须先懂 `forge:verification-before-completion`(证据先于声称的纪律)。
+
+核心论点:
+
+- "测试 pass 不等于 spec 覆盖 — 没测试覆盖的 Requirement 完全无声音失败"(沿 design §2.2.1)
+- 三维度协议来自 OpenSpec `src/core/templates/workflows/verify-change.ts` 第 4-7 步,forge 化的关键是**反向加固 AI 倾向**:OpenSpec verify-change.ts:152 "When uncertain, prefer SUGGESTION over WARNING" 在 AI 手里是放水按钮(沿 design §2.2.4 关键差异化)
+
+## When to Use
+
+- `/forge:verify <change-id>` slash command 调用本 skill(沿 commands/verify.md 重构后协议)
+- AI agent 主体在 verify 阶段产 `.verify-passed` / `.verify-failed` marker 的 `verify_findings` 数组前
+- 手动 review 一个 change 实施完整度(三维度作为 checklist)
+
+## When NOT to Use
+
+- 写 `forge plan`(那是 `forge:writing-plans`)
+- 写新 skill(那是 `forge:writing-skills`)
+- code review(那是 `forge:receiving-code-review` 或 `/forge:review` slash)
+- archive 阶段 fence 校验(那是 `forge archive` CLI 自动做,不需 AI 调 skill;沿 design §2.2.4)
+
+## 三维度协议
+
+| 维度             | 检查项                                                                  | 自动 / LLM    | 产 finding 路径                                                                                                     |
+| ---------------- | ----------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- |
+| **Completeness** | task 完成度(checkbox 计数)                                              | 自动          | `forge validate` 已做(走 ValidationError → Finding;沿 plan-9d Task 4)                                               |
+|                  | spec 覆盖度(每个 Requirement 在 codebase 有实施证据)                    | 自动 + LLM    | `forge validate` 已做(走 coverage_gap candidate,沿 §11.1bis;grep + 0 命中);AI 调本 skill 在 grep 命中后再判语义偏离 |
+| **Correctness**  | requirement 实施映射(file:line)                                         | LLM(本 skill) | AI 调本 skill 给具体 file:line                                                                                      |
+|                  | scenario 覆盖(WHEN/THEN/AND 条件在 code 或 test 中体现)                 | LLM(本 skill) | AI 调本 skill 给 file:line + scenario-id                                                                            |
+| **Coherence**    | design 决策追溯(design.md `## Decision:` / `## Approach:` 段是否被实施) | LLM(本 skill) | AI 调本 skill grep design.md 关键词 + 比对 codebase                                                                 |
+|                  | 代码 pattern 一致性(命名 / 目录 / 风格 vs 项目惯例)                     | LLM(本 skill) | AI 调本 skill 比对项目惯例 → 通常产 SUGGESTION                                                                      |
+
+### 主流程
+
+每次 verify 必须**三维度全跑**,不允许跳维度:
+
+1. **Completeness**:
+   - 先看 `forge validate` 自动产的 finding(含 spec-files-missing / coverage_gap 类,沿 §11.1bis)
+   - 对 spec 每个 Requirement,grep codebase 找实施证据;**完全无证据 → CRITICAL `coverage_gap`**(automated=true,工具自动判,沿 design line 446;若 spec 列了但 grep 0 命中,validate 已自动产此类 finding,AI 调本 skill 时合并即可)
+   - 对 tasks.md 标 [x] 但 git diff 反向 0 改动:走 `fake_completion` 路径(verify slash 阶段 AI 主动跑 `git diff` 产 CRITICAL finding,automated=true,candidate_type 不填 — 沿 v3 B-3 边界 case;**不**走 evidence_missing,因 evidence_missing 语义是 evidence.log_path 文件缺失,不同)
+2. **Correctness**:
+   - 对 spec 每个 Requirement,定位实施 file:line;**WHEN/THEN/AND scenario 在 test 或 code 中找证据;若找不到 → WARNING `scenario-coverage`**
+3. **Coherence**:
+   - design.md `## Decision:` / `## Approach:` 段提到的关键词,grep codebase 比对;**实施偏离决策 → WARNING `design-traceability`**
+   - 命名 / 目录 / 风格比对项目惯例;**偏离 → SUGGESTION `pattern-consistency`**(沿 \_shared/scope-category-guidance.md)
+
+每个 finding 必须填(8 必填字段沿 design §2.2.3 + master §3.12.1):
+
+- `id`(单调递增整数)
+- `dimension`(`completeness` / `correctness` / `coherence`)
+- `check_type`(细分,如 `task-completion` / `spec-coverage` / `requirement-mapping` / `scenario-coverage` / `design-traceability` / `pattern-consistency`)
+- `severity`(`CRITICAL` / `WARNING` / `SUGGESTION`)
+- `automated`(true if 工具可判,false if LLM 判)
+- `evidence`(必须含 file:line 或 spec:Requirement-id 或 design.md:段落标题;**禁止 vague "could be reviewed"**)
+- `recommendation`(具体下一步,如 "在 src/auth/rate-limit.ts 加 sliding-window 实现" — 不允许 "consider reviewing")
+- `resolved`(true / false)
+
+## 4-6 标定 example
+
+### Example 1 — Completeness/spec-coverage CRITICAL(automated)
+
+```yaml
+- id: 1
+  dimension: completeness
+  check_type: spec-coverage
+  severity: CRITICAL
+  automated: true # 工具可判 — codebase grep 0 个 file 提及该 Requirement 关键词
+  evidence: "specs/auth/spec.md Requirement #3 'refresh rate limit' 在 src/auth/ 0 个 file 提及 'rate-limit' / 'rateLimit' / 'throttle' 关键词"
+  recommendation: '在 src/auth/rate-limit.ts 实现 sliding-window 限流,或修订 spec 移除 #3'
+  resolved: false
+```
+
+**为什么 CRITICAL automated**:工具可独立验证(grep + AST 双重 0 命中是机器判定),沿 design §2.3.3 critical_candidate 协议 candidate_type=`coverage_gap`(spec 列 requirement 但 codebase 完全 0 命中,沿 design line 446)。AI 不能降级。**注**:`evidence_missing` 是 candidate_type 6 类之一但语义不同 — 它检查 `evidence.log_path` 文件是否存在(沿 design line 445),不适用于本 example 的 spec→codebase 覆盖检查。
+
+### Example 2 — Correctness/requirement-mapping WARNING(LLM)
+
+```yaml
+- id: 2
+  dimension: correctness
+  check_type: requirement-mapping
+  severity: WARNING
+  automated: false # LLM 判 — 需 AI 比对 spec 描述 vs 实施语义
+  evidence: "specs/auth/spec.md Requirement #2 'expiry window 默认 24h' 在 src/auth/refresh.ts:42 实现为 expiryHours = 12(与 spec 不一致)"
+  recommendation: '改 expiryHours = 24,或修订 spec 改默认值'
+  resolved: false
+  severity_acked_by: null # WARNING 必须 ack 才能 archive
+  severity_acked_at: null
+```
+
+**为什么 WARNING**:语义不一致非 0/1 判定(LLM 需读 spec + 代码语境),且可改 → 不该 CRITICAL 强 fence。AI ack 路径走 `forge ack propose`(沿 9a)。
+
+### Example 3 — Coherence/design-traceability WARNING(LLM)
+
+```yaml
+- id: 3
+  dimension: coherence
+  check_type: design-traceability
+  severity: WARNING
+  automated: false
+  evidence: "design.md '## Decision: 选用 sliding-window 限流' 在 src/auth/ 实施为 fixed-window(rate-limit.ts:15 用 expiryAt + bucket 模式,sliding-window 关键词 0 命中)"
+  recommendation: '实施 sliding-window(按 design 决策),或修订 design.md 改决策为 fixed-window 并写理由'
+  resolved: false
+  severity_acked_by: null
+  severity_acked_at: null
+```
+
+**为什么 WARNING 而非 CRITICAL**:design 决策偏离不直接威胁系统正确性(沿 design §2.3.2),但需用户 ack。
+
+### Example 4 — Coherence/pattern-consistency SUGGESTION(LLM)
+
+```yaml
+- id: 4
+  dimension: coherence
+  check_type: pattern-consistency
+  severity: SUGGESTION
+  automated: false
+  evidence: 'src/auth/login.ts:23 函数名 doLogin 与项目 7 个 handler 文件 (src/handlers/) 统一 handleXxx 命名风格不一致'
+  recommendation: 'rename doLogin → handleLogin'
+  resolved: false # SUGGESTION 不要求 resolved,允许带 finding archive
+```
+
+**为什么 SUGGESTION**:命名风格非核心目标 + 可不改 + 改起来简单,符合 \_shared/scope-category-guidance.md "本 change 内 nice-to-have" 判定。
+
+### Example 5 — Completeness/task-completion CRITICAL(automated,verify slash 阶段产)
+
+```yaml
+- id: 5
+  dimension: completeness
+  check_type: task-completion
+  severity: CRITICAL
+  automated: true # 工具自动判 — git diff 是机器判定
+  # 注:candidate_type 字段不填(下文解释)
+  evidence: "tasks.md#task-4 '加 rate-limit middleware' 标 [x] 但 git diff src/middleware/ 无相关改动(命令:git diff HEAD~1 -- src/middleware/)"
+  recommendation: '完成 task-4 实施,或把 task-4 改回 [ ]'
+  resolved: false
+```
+
+**注**(v3 B-3 修订):本类 finding(标 [x] 但 git diff 空,即 fake-completion)由 `/forge:verify` slash 阶段 AI 调本 skill 时**主动跑 `git diff <previous-base>..HEAD -- <expected-path>` 命令**产生(plan-9d v2 Task 4 `forge validate` CLI 仅产 `coverage_gap` spec-side 类 finding + `test_failure` stub,**不内嵌 git CLI** — git diff fake-completion 检测在 verify slash 路径产,沿 commands/verify.md Task 5)。automated=true 合理:git diff 命令输出是机器判定。
+
+**关于 candidate_type 字段**:design line 443-448 列了 6 类 enum(test_failure / hash_mismatch / evidence_missing / coverage_gap / api_contract / manual_claim),但本 example "task 标 [x] 但 git diff 反向 0 改动" 不严格归入任何一类:
+
+- **不是 `coverage_gap`**(spec→code 方向的 grep,本 example 是 task→code 方向的 git diff 反向)
+- **不是 `manual_claim`**(manual_claim 工具不能自动判;本 example git diff 可自动判)
+- **不是 `hash_mismatch`**(hash_mismatch 重算 tasks_hash/content_hash/log_hash/git.diff_hash,task 标 [x] 后 hash 已更新无 mismatch)
+- **`fake_completion`** 不在 design 6 类 enum 之内(`Finding.candidate_type` 是 optional 字段,沿 9a severity.ts:75;不填合规)
+
+**v1.0 处理**:`candidate_type` 字段不填(沿 9a Finding.candidate_type 是 optional);check_type=`task-completion` 即可区分本类。**v1.1 计划**:design §3.1 推迟项可加 `fake_completion` candidate_type 第 7 类(若 verify slash 场景多,值得正式 enum 化)。
+
+**为什么 automated=true 仍合理**:design §2.3.3 表区分"工具自动产 CRITICAL"(line 457)与"AI 候选 + 工具验证"两种路径 — `git diff` 是工具自动判,落"工具自动产"路径(line 457 "forge validate 跑测试 fail / 算 hash mismatch / process_evidence 不变量违反等"语义涵盖 git diff 类工具自动判),不需要走 candidate 路径。
+
+### Example 6 — Correctness/scenario-coverage SUGGESTION(LLM)
+
+```yaml
+- id: 6
+  dimension: correctness
+  check_type: scenario-coverage
+  severity: SUGGESTION
+  automated: false
+  evidence: "specs/auth/spec.md Scenario 'expired token retry' 的 WHEN/THEN/AND 在 tests/auth/refresh.test.ts 仅覆盖 happy-path,边缘 case (token 刚过期) 无 test"
+  recommendation: "加 tests/auth/refresh.test.ts:'expired-token retry edge case'"
+  resolved: false
+```
+
+**为什么 SUGGESTION**:增测试是 nice-to-have(主流程已测),不影响 core verify pass。
+
+## forge-specific 反向加固
+
+forge v1.0 比 OpenSpec verify-change.ts 走更远 — 假设 AI 在 verify 阶段倾向偷懒。本 skill 配合 fence 反向加固:
+
+### 1. automated=true CRITICAL 不可降级
+
+工具自动判的 CRITICAL findings(v8 M-1 修订:口径与 §11.1bis 一致):
+
+- `forge validate` 阶段产:**spec-files-missing**(specs/ 空)+ **coverage_gap**(spec Requirement grep 0 命中)
+- `forge archive` 现有路径产:**hash_mismatch**(marker tasks_hash / content_hash 重算不一致,line 274-289)
+- `/forge:verify` slash AI 调 skill 阶段产:**fake_completion**(tasks 标 [x] 但 git diff 反向 0 改动,automated=true 因 git 是机器判定;candidate_type 字段不填,沿 v3 B-3 边界 case)
+- **不在 v1.0 实施**(沿 §11.1bis):`evidence_missing` 由 9a candidate-validators.ts framework 处理 / `api_contract` 推迟 v1.1 / `manual_claim` 走 9a ack 流程 / `test_failure` 走 stub warning,9g 完成后接 reporter parser
+
+上述所有 CRITICAL finding 都由对应工具产 `finding_hash`(JCS SHA256,沿 9a `computeFindingHash`):
+
+- AI 改 severity 重算 hash 即不一致 → archive fence 拒签(沿 design §2.2.4)
+- AI 改 evidence / recommendation 也会改 hash,同样拒签
+- AI 唯一合规路径:走 `forge ack propose` 启动两步 ack 流程(沿 9a;CI 模式直接拒绝)
+
+### 2. WARNING 必须 ack 才能 archive
+
+LLM 判的 WARNING(automated=false)路径:
+
+- AI 必须真给具体证据 + 具体 recommendation(不允许 vague "consider reviewing")
+- archive 阶段 fence 校验 `severity_acked_by` + `severity_acked_at` 非空,否则拒签
+
+### 3. SUGGESTION 不是放水按钮
+
+OpenSpec verify-change.ts:152 "When uncertain, prefer SUGGESTION over WARNING" 在 forge 是 anti-pattern:
+
+- SUGGESTION 累积到 `archive_summary` 的 `pending_suggestions` 数组(沿 9e),v1.1 backlog registry 全表索引(沿 design §3.1)
+- AI 偷懒推 SUGGESTION 会留下持续可见的 SUGGESTION 堆积反向暴露
+- 沿 `skills/_shared/scope-category-guidance.md`:"本 change 不做但跨 change 项" 应走 Out of Scope / Future Work / Non-Goal,不是 SUGGESTION
+
+### 4. 三维度必须全跑
+
+不允许跳维度。即使 Completeness 全 pass 也必须跑 Correctness + Coherence(典型借口:"测试都过了,看着没问题")。
+
+## 红旗清单 — STOP and Start Over
+
+| 想法                                                             | 现实                                                                                                                                                                                      |
+| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "测试都 pass 了,跳 Correctness/Coherence"                        | 测试 pass 只覆盖被写出来的 test。spec 里没测试覆盖的 Requirement 完全 silent。**跳维度 = 重新走第 1 维度**                                                                                |
+| "这个 Requirement 在 codebase 没找到,但应该不重要,推 SUGGESTION" | `coverage_gap` 是 automated CRITICAL candidate(沿 §11.1bis;evidence_missing 仅指 evidence.log_path 文件缺失);推 SUGGESTION = 偷懒。fence 拒签的不是你判定 SUGGESTION,而是你没让工具自动判 |
+| "vague 'consider reviewing X'"                                   | fence 看不到具体证据 → recommendation 等价无效。重写带 file:line / spec:Requirement-id                                                                                                    |
+| "WARNING 我直接给 severity_acked_by = ai-agent 算自 ack"         | WARNING ack 必须走 `forge ack propose` 两步流程(沿 9a),AI 自 ack 不存在;archive fence 校验 ack-log.jsonl 一致性                                                                           |
+| "automated=true CRITICAL 我改成 false 让 LLM 判"                 | finding_hash 重算 + 比对会拒签。修法是让工具自动产,不是改 automated 字段                                                                                                                  |
+| "三个维度合并写成一段总论"                                       | finding 是结构化数组,每项必须明确 dimension / check_type;合并 = 工具无法解析,fence 报 schema 错                                                                                           |
+| "时间紧,只跑 Completeness"                                       | 跳维度是 baseline AI 的典型失败模式(沿 plan-9d scenario pressure-skip-coherence)。本 skill 存在的全部理由就是挡这个                                                                       |
+
+**全部触发表示:回归三维度协议,从 Completeness 开始**。
+
+## 配套引用
+
+- `skills/_shared/scope-category-guidance.md`(9b 落地;**plugin runtime 下:`_shared/scope-category-guidance.md`** — 沿 receiving-code-review SKILL.md:292 convention):决策表区分 "本 change SUGGESTION" vs "跨 change Out of Scope / Future Work / Non-Goal"
+- design §2.2.3 verify_findings YAML schema(权威字段定义)
+- design §2.3.3 critical_candidate 协议(automated CRITICAL 不可降级机制)
+- design §2.3.6 finding_hash JCS 算法(9a 实施)
+- 9a `src/core/schemas/severity.ts`:Finding / FindingHashPayload 接口
+- 9b `src/core/scope/aggregator.ts`:跨 change followups 数据源
+
+## Bottom Line
+
+**verify 不只是测试 pass — 是三维度评估** + **fence 反向加固让"偷懒推 SUGGESTION"不再是低风险选择**。
+
+每次 verify 产出的 verify_findings 数组 = 后续 archive / `archive_summary` handoff / v1.1 backlog 的全链数据源;偷懒会留下持续可见的痕迹。

package/dist/core/templates/skills/writing-plans.md

@@ -0,0 +1,259 @@
+---
+name: forge:writing-plans
+description: Use when you have a spec or requirements for a multi-step task, before touching code
+---
+
+# Writing Plans
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the forge:writing-plans skill to create the implementation plan."
+
+**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
+
+**Save plans to:** `forge/changes/<change-id>/tasks.md`(forge 把 plan 直接落到 change 的 tasks.md;design.md 与 specs/ 由 propose 模板另行生成)
+
+- (User preferences for plan location override this default)
+
+## Scope Check
+
+If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
+
+## Scale-aware mode (P3 fix from v0.2 fixture testing)
+
+**Before writing tasks**, decide between **light mode** (1-2 tasks, ~50-80 lines) vs **full mode** (5+ tasks, ~200+ lines with strict RED → GREEN → REFACTOR + verification per task).
+
+### Decision logic
+
+1. **Read** `forge/changes/<change-id>/proposal.md` — count the line number (e.g., `wc -l`)
+2. **Read** `forge/config.yaml#writing_plans.light_threshold`(if exists);默认 200(由 `validateWritingPlansConfig` fallback,见 `src/core/schema/writing-plans-config.ts`)
+3. **Check** `--light` flag(若用户 `/forge:propose <id> --light` 显式传 → 强制 light mode,跳过 threshold 判定)
+4. **Decide**:
+   - proposal 行数 < `light_threshold` 或 `--light` flag → **light mode**
+   - proposal 行数 >= `light_threshold`(默认)→ **full mode**
+
+### Light mode template (trivial change)
+
+- 1-2 tasks(typically 1 task with multiple steps)
+- 跳过 RED → GREEN → REFACTOR 三段强约束(直接写实现 + 写测试,合并到 1-2 step)
+- 跳过 per-task verification + commit(只在 task 末尾一次性 verify + commit)
+- 总长度 ~50-80 行 tasks.md
+
+**适用场景**:加 1 个字段、加 1 个 CLI flag、改 1 个常量、修 1 个简单 bug、纯文本修改 / docs 改动
+
+### Full mode template (complex feature, 默认)
+
+- 5+ tasks,each with `RED → GREEN → REFACTOR` + verification + commit
+- 每 task 独立可 review,每 step 2-5 分钟可执行
+- 总长度 200+ 行(参见现有 forge-repo plans)
+
+**适用场景**:新模块、跨多文件 refactor、协议变动、新增子系统
+
+### Why this matters (v0.2 P3 fixture test 教训)
+
+v0.2 fixture 测试发现:trivial change(用户原话"加 1 个 priority 字段 + `-p` flag")被 writing-plans 强制套 5-task 完整模板 + 每 task RED/GREEN/REFACTOR + verification → tasks.md **511 行**(后续 Plan 0b.1 实测进一步发现可达 1378 行)。
+
+scale-aware mode 让 trivial change 走 light mode,避免:
+
+- 文档冗长降低 review 体验
+- AI 单次输出长度边界压力
+- "为了 TDD 而 TDD" 形式主义
+
+## File Structure
+
+Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
+
+- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
+- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
+- Files that change together should live together. Split by responsibility, not by technical layer.
+- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
+
+This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
+
+## Bite-Sized Task Granularity
+
+**Each step is one action (2-5 minutes):**
+
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use forge:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. (forge v0.1 不提供 inline executing 模式,统一用 subagent 派发)
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## No Placeholders
+
+Every step must contain the actual content an engineer needs. These are **plan failures** — never write them:
+
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" (without actual test code)
+- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
+- Steps that describe what to do without showing how (code blocks required for code steps)
+- References to types, functions, or methods not defined in any task
+
+## Remember
+
+- Exact file paths always
+- Complete code in every step — if a step changes code, show the code
+- Exact commands with expected output
+- DRY, YAGNI, TDD, frequent commits
+
+## Path Pre-flight Verify(plan-v1.1 Task 6 加 — Pattern X #2/#3/#4 实证)
+
+**Trigger**:plan writer 起草 plan 时引用 file path / yaml 名 / skill 名 / SKILL.md §X.Y 字面位置。
+
+**Required action**:**plan writer 起草 plan 前必跑 grep verify** path / yaml / skill / section 真实存在;**不假定 prefix 或路径**(忌"我以为在 .claude/skills/")。
+
+**Why**(Pattern X #2/#3/#4 累计实证 — REINFORCE Pattern S):
+
+- **plan-9z plan v1 起草字面错 4 处**:
+  - 假定 `.claude/skills/writing-skills/` prefix(**实际** `skills/writing-skills/` 无 prefix — 顶层 skills/)
+  - 假定 `main-agent-stop.yaml` 名(**实际** merge 进 SDD yaml `subagent-driven-development.yaml`)
+  - 假定 `forge:subagent-driven-discipline` §"STOP Triggers"(**实际** 段在 `forge:subagent-driven-development`)
+  - plan-9z Task 4/5 实施第一步 grep 真实路径才发现(implementer commit 字面用真实路径,但 plan v1 字面错保留)
+- **plan-v1.1 Task 0 起草自身同款实证**:
+  - v1 假定 `.claude/skills/writing-plans/` prefix(**实际** `skills/writing-plans/SKILL.md` 顶层 skills/ 无 prefix)
+  - v3 起草时 plan writer 自身 grep verify 才 catch + 修(plan-v1.1 §14 v3 起草过程 self-aware retrospect)
+- **root cause** 是 plan writer 同源审查盲点(Pattern S),不是 implementer 错;Codex external review 也兜底找到字面错
+
+**Plan writer checklist(起草 plan 前 — 不眼测,跑 grep)**:
+
+```bash
+# 1. 引用的每个 file path 都跑 ls verify
+ls .claude/skills/<scope-skill>/SKILL.md  # 路径是否存在(对 .claude/ 下 skill)
+ls skills/<scope-skill>/SKILL.md  # 路径是否存在(对顶层 skills/ 下 skill — 无 .claude/ prefix)
+
+# 2. 引用的 section §X.Y 字面是否存在
+grep -n "<section-title>" <skill-path>  # section 字面是否在 SKILL.md 内
+
+# 3. 引用的 yaml 文件名是否存在
+grep -rn "<yaml-name>" forge-eval/scenarios/  # yaml 文件名是否存在
+ls forge-eval/scenarios/<yaml-name>.yaml  # yaml 路径是否存在
+
+# 4. 引用的 file:line 字面是否在 file 内
+sed -n '<line>,<line+5>p' <file-path>  # 实际看 line range 内容是否符 plan claim
+```
+
+若 verify 失败 → **改 plan 字面用真实路径 / yaml / section**;不假定 prefix。
+
+**Implementer 兜底**(双层防护):
+
+若 plan 字面与实际路径不符,implementer 第一步 grep 真实路径 verify(沿 `forge:subagent-driven-discipline §2.1.1 External Protocol Assumption Verify` 协议)— 但 implementer commit 字面用真实路径,plan v1 字面错保留 → **plan writer 仍是 root cause 防线**;implementer 兜底不能 substitute plan writer verify。
+
+**参考**:`forge:subagent-driven-discipline §2.1.1 External Protocol Assumption Verify`(implementer verify 协议);
+plan-v1.1 Task 0 `docs/plans/2026-05-14-plan-v1.1-polish-leftover.md` §14 v3 起草过程 self-aware retrospect(`.claude/skills/writing-plans/` 假定 prefix 错 → grep verify catch + 修)。
+
+## Self-Review
+
+After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.
+
+**1. Path verify(plan-v1.1 Task 6 加 — Pattern S REINFORCE)**:
+
+引用的每个 file path / yaml 名 / skill 名 / SKILL.md §X.Y 是否真实存在?跑 `ls <path>` / `grep -n "<section>" <file>` / `sed -n '<line>p' <file>` verify;若 verify 失败 → 改 plan 字面;**不假定 prefix**(沿 plan-v1.1 §14 v3 自身实证)。
+
+**2. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.
+
+**3. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.
+
+**4. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.
+
+If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+> "Plan complete and saved to `forge/changes/<change-id>/tasks.md`. Execution will use the **Subagent-Driven** approach: each task is dispatched to a fresh subagent with two-stage review (spec compliance + code quality)."
+
+**REQUIRED SUB-SKILL:** Use forge:subagent-driven-development to implement this plan task-by-task.
+
+Note: forge v0.1 仅提供 subagent-driven 模式,无 inline executing 模式。
+
+---
+
+## CLI validation step (Tier 2/3 OpenCode/Codex 路径用,Plan 0a 实测 Variant B PASS)
+
+**仅 OpenCode + Codex 路径**(Tier 1 Claude Code 路径走 commands.md `/forge:propose` 调 helper,不需要本段)。
+
+After generating `forge/changes/<id>/{proposal,specs,design,tasks}.md`, you **MUST** execute the following and include output verbatim in your reply:
+
+```bash
+node "${FORGE_HELPER}" validate <change-id>
+```
+
+**`FORGE_HELPER` 解析(per harness)**:
+
+- OpenCode:`FORGE_HELPER = <plugin_dir>/scripts/run-forge.mjs`(`__dirname` reachable from plugin entry)
+- Codex:`FORGE_HELPER = $HOME/.codex/forge/scripts/run-forge.mjs`(`os.homedir()` 解析,Windows USERPROFILE OK)
+- 找不到 helper(用户路径不标准)→ fallback `npx -y --package @accelerator-mzq/forge@^1.4.0 -- forge validate <change-id>`(直接调 npx)
+
+**失败处理**:
+
+- exit 0 + "validation OK" → 继续 propose 收尾(回到主 commands 流程的 `forge/drafts/.consumed/` move + commit)
+- exit 非零 → stop,把 stderr 报给用户;**不要**继续到 archive 流程