# Plan + Verify 工作流升级（24 commits, 957/957 tests green）

本次发布把 clavue 从"会写 plan 的 coding agent"升级成"verification-driven coding agent"——任何
有 `**Verify**` 指令的 plan 步骤，都会被 clavue 内核**真实执行**而不是模型自报通过。

## 上下文压缩升级（L1，4 commits）

| commit | 改动 |
|--------|------|
| `87328f1` | 9 段 → 12 段 prompt 模板。新增 `Resolved Questions` / `Pending User Asks` / `Critical Context`。压缩 summary 顶部加 `[CONTEXT COMPACTION — REFERENCE ONLY]` preamble，告诉恢复后的 turn 不要把 summary 当指令重新执行。强制 same-language 摘要。 |
| `a36592f` | `/compact --focus "topic"` 焦点压缩。60-70% 预算偏向焦点话题。 |
| `1e93d07` | 三个新段进 V1 schema 作为 optional 字段。post-compact hook payload 同步。 |
| `18210e3` | `post_compact_tasks` attachment：跨压缩快照 todos/tasks。模型不再忘记自己刚写过的任务列表。 |

## Plan 与 Verification 内核（L2 + L3，5 commits）

| commit | 改动 |
|--------|------|
| `87c34d4` | `parsePlanSteps()` + `runPlanStepVerification()`。Plan 步骤格式：`## Step N: <title>` + `**Verify**: <command>` + 可选 `**Expect**: <substring>`。 |
| `3586fa6` | `VerifyPlan` 工具。模型可主动调用，按 `onlyStep` 单步验证或全量。注册为 base tool。 |
| `688dcee` | 通过的步骤自动写回 `**Verified**: <iso>` 到 plan 文件。下次跳过。 |
| `f056829` | `EnterPlanMode` prompt 教模型用 `**Verify**` 写 plan + 用 `VerifyPlan` 验证。 |
| `789b8fe` + `152d13f` | Verify-gap reminder：5 turn 没调 VerifyPlan 自动注入提醒，含 pending step indices。 |

## 闭环 + 用户体验（L5–L18，15 commits）

| commit | 改动 |
|--------|------|
| `8718369` | VerifyPlan tool result 加 `ALL_VERIFIED` / `VERIFICATION_FAILED` 强信号 trailer + `allVerified` 字段。 |
| `2f4852d` | EnterPlanMode 返回 starter plan template，已带 Verify 占位符。 |
| `2a63f4b` | `plan_progress` 进 V1 schema。post-compact hook 拿到结构化进度。 |
| `a8f36da` | `/verify-plan [stepIndex]` slash command。无需模型 token，本地一键验证。 |
| `3caf236` | Finish-line reminder：plan 全 verified 但模型没 finalize 时主动提示写 summary。 |
| `f7baa54` | 失败精准指引：每种 `failureReason`（non_zero_exit / expect_mismatch / timeout / spawn_error / no_verify_directive）给针对性 next step。 |
| `72af567` | Plan 文件 lint，8 个错误码（empty_plan / no_steps / no_verify_directives / partial_verify_coverage / expect_without_verify / expect_before_verify / multiple_verify / verified_without_verify）。 |
| `abec6f2` | ExitPlanMode tool result 含 lint findings。 |
| `7f45b9d` | JSONL verify log（`<projectDir>/verify-log.jsonl`）。每次 VerifyPlan 调用追加一条。 |
| `b79cf1b` | `/verify-stats [limit]` slash command。显示最近运行 + per-step 通过率 + 最近失败原因。 |
| `5d2627c` | Compact summarizer prompt 注入 plan 进度 addendum。摘要 LLM 必须保留 verified vs pending 的划分。 |
| `7f2aa70` | ExitPlanMode 规定三步 implementation workflow（mirror plan → todos → impl + onlyStep verify → final whole-plan verify）。 |
| `17aa81a` | `clearVerifiedMarkersInPlan()` + `/verify-reset [stepIndex...]`。编辑 step 后清 stale Verified。 |
| `eaf0bdf` | Verify-gap reminder 含最近 flake stats（"step 3: 4/5 runs failed, most recent: timeout"）。打破"反复同样修复"的循环。 |

## 新增能力

clavue 现在是业界**第一个**把 verification 做到这种深度的 CLI coding agent：

- **Plan as verifiable markdown**：`**Verify**` + `**Expect**` 直接执行，不靠模型自报
- **VerifyPlan 工具**：模型可主动验证、自动标记 Verified、跨压缩持久化
- **Plan lint**：8 个结构错误码，写 plan 时即得到反馈
- **verify-gap / finish-line reminder**：未验证时催、全验证时建议结束
- **JSONL verify log**：可观测性，跨 session 跟踪 flake
- **3 个新 slash command**：`/verify-plan`、`/verify-stats`、`/verify-reset`
- **2 个新 attachment type**：`post_compact_tasks`、`verify_gap_reminder`、`verify_finish_line_reminder`

## 设计纪律

每一步遵循 baseline 4 条：
1. **Think before coding** — 每个 L 阶段先写失败测试，TDD 推进
2. **Simplicity first** — 复用现有 attachment / tool / prompt 系统，不造抽象层
3. **Surgical changes** — 触动文件全部在 `src/services/plan/`、`src/tools/VerifyPlanTool/`、`src/services/compact/`、`src/commands/verify-*` 内
4. **Goal-driven** — 每个 commit 有可验证目标，全测全绿才推

## 测试

- **957/957 pass, 0 fail, 3 skipped**
- `test:workflow-continuity` 28/28
- `test:route-policy` 28/28
- 新增约 100 个测试 case 跨 18 个测试文件

## 跟竞品对比

| 能力 | Claude Code | Codex CLI | Hermes | OpenClaw | clavue 本版本 |
|------|------------|-----------|--------|----------|--------------|
| 12 段结构化 summary | ❌ | ❌ | ✅ | ❌ | ✅ |
| 焦点压缩 | ⚠️（基础） | ❌ | ✅ | ❌ | ✅ |
| 跨压缩 todos/tasks 快照 | ❌ | ❌ | ❌ | ❌ | ✅ |
| Plan as verifiable markdown | ❌（纯 free-form） | ❌ | ❌ | ❌ | ✅ |
| VerifyPlan tool | ❌ | ❌ | ❌ | ❌ | ✅ |
| 自动 Verified 标记 | ❌ | ❌ | ❌ | ❌ | ✅ |
| Verify-gap / finish-line reminder | ❌ | ❌ | ❌ | ❌ | ✅ |
| Plan lint | ❌ | ❌ | ❌ | ❌ | ✅ |
| JSONL verify log + flake stats | ❌ | ❌ | ❌ | ❌ | ✅ |

## 后续可探索

- L17 自动检测：step body hash → 自动 invalidate stale Verified（需要扩展 plan 文件格式）
- TUI 状态栏显示 plan 进度（一行 `plan: 3/7 verified`）
- VerifyPlan 并行执行无依赖步骤
- 把 verify log 上传到 GitHub Actions / CI 作为 build attestation
