# Clavue v8.11.0 — Release Notes

**发布日期**：2026-05-17
**npm**：`clavue@8.11.0`
**GitHub**：https://github.com/mycode699/clavue/releases/tag/v8.11.0
**升级命令**：

```bash
npm install -g clavue@8.11.0
# 或一次性：
npx -y clavue@8.11.0
```

---

## TL;DR

8.11.0 是 v11 路线图的兑现版本。v10 把 `RuntimeDecision` 写进了 `src/` 的契约层；v11 在此之上**对标真正的对手 Claude Code 上游**，把 v10 的承诺全部转成 CI gate，并启动 1943 行 `queryLoop` 的纯函数抽提。

User-visible 行为变化仍然为零（除一个新的硬性 verify gate，可由 env 闸退到 reminder 模式），但工程形状显著前进：

1. **三条 release-preflight gate** — Mao supervisor delivery gate / provider route matrix baseline / world-class eval baseline，全部纳入 `npm run release:preflight`。回归 → release 自动 fail。
2. **Verify hard gate (S3)** — 检测到 "完成/done/finished" 等终结词但 `markVerified` 未触发 → 自动 inject 一轮 verify 提示。`CLAVUE_VERIFY_HARD_GATE=0/false/off/no` 可退到 reminder。
3. **Mao supervisor 红队 eval (S1)** — 6 个对抗式场景测试 (liar worker / hidden scope violation / chained conflict / release claim with blocking / adversarial ledger / missing-key bypass)，supervisor 实现在 6 场景下都正确 block delivery。
4. **C1 turn-loop 教科书化** — `query.ts::queryLoop` 中的 PRE 阶段抽出 6 个纯函数到 `src/runtime/turn-loop-pre.ts`，可独立单元测试；附带状态机文档 + 双向 grep gate。
5. **C3 cold-start baseline** — `--version` 316ms / `--help` 447ms 落 baseline，C3 native binary PR 落地必须打 ≥20% 改进。

测试基线 v10 1372 pass / 0 fail / 3 skipped → v11 **1453 pass / 0 fail / 6 skipped**（+81 active 测试，+3 default-skipped cold-start benchmark）。

升级风险：**极低**。Verify hard gate 是行为变更，但带 escape hatch；其余全部是测试与 gate 增强。

---

## 1. 三条 release-preflight gate（守城 S 系列）

### 1.1 Provider route matrix gate (S2a)

`docs/evals/world-class/provider-route-baseline-v11.json` 落 9 路 routing 零点（chat-only / degraded / missing-credentials / 等）。`scripts/check-provider-matrix.mjs` 比对 baseline，回归 → exit 非 0。

落地证据：
- `scripts/lib/provider-matrix.mjs` 共享生成逻辑（消除原 `run-provider-matrix.mjs` 与 checker 之间的逻辑重复）
- `tests/check-provider-matrix.test.mjs` (8 测试)
- `release-preflight.mjs` `checkProviderRouteMatrix()` + `--skip-provider-matrix` escape hatch
- 顺手发现：旧 `provider-route-matrix.json`（2026-05-01 写）有 3 行已与 generator 漂移，无 gate 时无人发现 — gate 价值即时显现

### 1.2 World-class eval baseline gate (C2)

`docs/evals/world-class/world-class-eval-baseline-v11.json` 落 7 个 gate 零点。`scripts/check-world-class-eval-baseline.mjs` 比对 baseline。

落地证据：
- `scripts/lib/world-class-eval-gates.mjs` 共享 GATES 定义
- `tests/check-world-class-eval-baseline.test.mjs` (6 测试)
- `release-preflight.mjs` `checkWorldClassEvalBaseline()` + `--skip-eval-baseline` escape hatch
- 顺手发现：旧 `world-class-eval-report.json` 仍记 `totalGates: 6`，但 runner 已加到 7 (platform-autoresearch 后加入)。同样无 gate 时无人发现。

### 1.3 Mao supervisor 红队 eval (S1)

`tests/mao-supervisor-redteam.test.mjs` (6 adversarial 场景)：
- liar worker（worker 谎报 tests pass 但无 verify）
- hidden scope violation（worker 写了 contract 外文件）
- chained conflict（多 agent 同文件写）
- release claim with blocking（release/publish 必须经过 final gate）
- adversarial ledger end-to-end（finding 必须能从 ledger 读出）
- missing-key bypass attempt

现有 supervisor 实现在所有 6 场景下都正确 block delivery — 这条 gate 把"已 work 的护城河"锚点固化。

---

## 2. Verify hard gate (S3)

### 行为

当 assistant 输出 "完成/done/finished/搞定/收工/ready to ship" 等终结词，但本轮 `VerifyPlan` 未触发 → 自动 inject 一轮 verify 提示，turn 不放过。

`computeVerifyHardGate()` 是纯函数：检测 EN/ZH 完成短语 ∩ pending verify-bearing steps ∩ NOT 同 turn `VerifyPlan`，返回 `{reason, pendingIndices, matchedPhrase}` 或 null。

### Escape hatch

`CLAVUE_VERIFY_HARD_GATE=0/false/off/no` → 退到 reminder 模式（旧行为）。任一不区分大小写的"假值"匹配都接受。

### 落地证据

- `src/services/plan/verifyHardGate.ts` 纯函数 (~120 行)
- `src/utils/attachments.ts` 加 `verify_hard_gate` attachment + builder（注册在 `verify_finish_line_reminder` 之后；带"上一条 attachment 已是 hard gate 且无新 assistant turn"冷却）
- `src/utils/messages.ts` 加 `verify_hard_gate` system-reminder renderer
- `tests/verify-hard-gate.test.mjs` (19 测试) pin 函数边界 + escape hatch 匹配器

---

## 3. C1 turn-loop 教科书化（D1 → D3 step 6）

`src/query.ts::queryLoop` 是 1943 行 single function。v11 不一次性抽 orchestrator（高 blast，按 plan 是单独 PR / RC），而是**契约先行 + 逐 phase 抽纯函数**：

### D1: 状态机文档 + grep gate

- `docs/runtime-turn-state-machine.md` — 六阶段 (PRE / ROUTE / DISPATCH / TOOL-LOOP / POST-TURN / RECOVER) + 8 个 `queryCheckpoint` 锚点表 + 12 个 `Terminal reason` 列表
- `tests/turn-loop-state-machine-pin.test.mjs` (5 测试，双向 grep gate：源 → 文档、文档 → 源；phase 名称表)

### D2: 类型契约

- `src/runtime/turn-loop.ts` — 纯 type + sentinel 数组 (`TurnPhase` × 6 / `TerminalReason` × 12 / `RetryReason` × 7 / `PhaseOutcome<T>` / `PhaseFn<T>` / `TurnLoopState`)。esbuild erase，无运行时副作用
- `tests/turn-loop-type-contract.test.mjs` (4 测试) lock 三方契约：types ↔ docs ↔ src/query.ts

### D3 step 0: phase banners

`src/query.ts::queryLoop` 体内加入 5 条 phase banner 注释 (PRE / ROUTE / DISPATCH / TOOL_LOOP / POST_TURN，RECOVER 通过"早期 return/continue 即 RECOVER 决策"约定)。零语义改动，给 1943 行函数加视觉断点。

### D3 step 1–5: PRE 阶段纯函数抽提

`src/runtime/turn-loop-pre.ts` 6 个 helper：

| Helper | 调用点 | 用途 |
|---|---|---|
| `shouldPersistContentReplacements` | content-replacement gate | `agent:` / `repl_main_thread` 前缀 → persist；否则 ephemeral |
| `selectUnboundedResultToolNames` | `applyToolResultBudget` skip-set | 非有限 `maxResultSizeChars` 的工具 opt out |
| `nextAutoCompactTracking` | autocompact post-call | 三分支：fresh / failure-only / 透传；`mintTurnId` 注入 |
| `nextTaskBudgetRemaining` | PRE + TOOL_LOOP 双站 | `max(0, (prev ?? total) - finalContextTokens)` 单点公式 |
| `nextQueryChainTracking` | chainId/depth bookkeeping | First turn mints chainId；continuation 增 depth |
| `buildAutoCompactSucceededEvent` | `tengu_auto_compact_succeeded` payload | 纯 payload；`logEvent` 副作用留 call site |

`tests/turn-loop-pre.test.mjs` 27 个测试 pin 全部边界。

### D3 step 6: PRE helper 契约表 + 双向 grep gate

`docs/runtime-turn-state-machine.md` "PRE phase pure helpers" 章节列出 6 个 helper × 调用点 × 用途。`tests/turn-loop-pre.test.mjs` 加 2 个双向 grep gate：

- 文档表每个 helper 名必须在 `turn-loop-pre.ts` 真有 `export`
- `turn-loop-pre.ts` 每个 `export function` 必须在文档表里被列出

任一方向漂移 → 测试失败 + 错误消息直接指出"加一行到 docs/runtime-turn-state-machine.md"。

---

## 4. C3 cold-start baseline（C3 prep）

C3 native binary launcher 是单独 PR，本版只落 baseline 防退步。

`tests/cold-start-benchmark.test.mjs` 默认 skipped（避免与 1400+ test worker pool 抢 CPU），`CLAVUE_RUN_COLD_START=1` 显式 opt-in：

- `--version` median **316ms**（heap reexec fast path）
- `--help` median **447ms**（含 reexec roundtrip + 完整 module graph）
- `docs/perf/cold-start-baseline.json` 落零点（Node v22.22.0 / macOS Darwin 24.6.0）
- 回归 gate `REGRESSION_CEILING_RATIO=1.5` 自动阻止 startup 退步 50% 以上
- escape hatch `CLAVUE_SKIP_COLD_START_GATE=1` / `CLAVUE_UPDATE_COLD_START_BASELINE=1`

C3 native binary PR 落地后必须打这个 baseline ≥20% 改进 → help 路径 <357ms。

---

## 5. 验证

- `npm test` **1453 pass / 0 fail / 6 skipped** (v10 1372 → v11 +81 active 新测试 + 3 default-skipped cold-start)
- `npm run check:provider-matrix` exit 0
- `npm run check:eval-baseline` exit 0
- `npm run release:preflight` 全绿，新增三行 OK gate

---

## 6. 显式不做（v11 显式排除）

防 v9 cargo-cult 重启：

- ❌ 不抄 Claude Code 上游 changelog
- ❌ 不拆 `REPL.tsx` / `main.tsx`
- ❌ 不上图形化 dashboard
- ❌ 不引入新 LLM framework 依赖（LangChain / LlamaIndex / DSPy）
- ❌ 不为了对标分加新功能 — 所有改动都锚在 `PRODUCT.md` / `ARCHITECTURE.md`

---

## 7. v11 未交付（明确 defer）

按 v11 plan，以下两条都是单独 PR / RC：

- **C1 D3 真抽 orchestrator** — `src/runtime/turn-loop.ts` ≤300 行，逐 phase 把代码块移出 `queryLoop`。需要在契约保护下做（D1/D2/D3-step0~6 的 contract 已就绪）。
- **C3 native binary 实施** — Node 22 SEA 需 CJS bundle，dist 当前 ESM。blast 高，单独 RC。

详见 `docs/clavue-roadmap-v11.md`。

---

## 升级路径

```bash
npm install -g clavue@8.11.0
clavue --version
# Clavue 8.11.0
```

或一次性试用：
```bash
npx -y clavue@8.11.0
```

如果你 pin 了 verify hard gate 行为：
```bash
# 退到 v10 reminder 模式
export CLAVUE_VERIFY_HARD_GATE=0
```
