# Changelog ## 4.1.22 — 2026-10-25（把"只测了两个子命令"的漏测补上，把"不是缺陷"的两条说准） **版本级别**：候选 **patch**（沿用常设规则"默认版本新增采用最小的版本位"）。本次**没有**改任何运行时语义、 **没有**动 mutation 阈值、**没有**碰发布流程；三个代码切片各自只加守卫、**零清单改动**，本切片只做 **版本锁步 + 生成清单重生成 + 这段 CHANGELOG**。 **一句话：`peaks mut` 指向一个**不存在**的 `--test-files` 时，`mut mutants` 过去会**静默回退**到默认发现， 为一个从未存在过的文件报出**满分 kill rate**（exit 0）—— 而最初的记录只测了 `run` 与 `asserts`、**漏了 `mutants`**；这一版三个子命令统一 **exit 1 + 具名码 `MUT_TEST_FILE_NOT_FOUND`**。** ### 1. 缺陷：`peaks mut` 缺失 `--test-files` 路径时的静默回退（三个子命令这一版统一堵上） 同一夹具、同一台机器上的**前后两侧实测**（改前取自 `HEAD` 的隔离树，改后取自本仓库的工作树）： | 子命令 | 改前 | 改后 | |---|---|---| | `mut mutants` | **exit 0、写出了报告、killRate 1、mutantsTotal 2** | **exit 1 `MUT_TEST_FILE_NOT_FOUND`，无报告** | | `mut run` | exit 1 `MUT_FAILED`（裸 ENOENT + 机器绝对路径） | exit 1 `MUT_TEST_FILE_NOT_FOUND`，无报告 | | `mut asserts` | exit 1 `UNHANDLED_ERROR`（裸 ENOENT + 机器绝对路径） | exit 1 `MUT_TEST_FILE_NOT_FOUND`，无报告 | **"静默回退"不是推测，是可比对的 digest。** 改前 `mut mutants` + 缺失文件写出的报告，digest 与 `mut mutants` + **一个能用的 glob** 写出的报告**完全相同**（两者都是 `339e74cc…`）—— 缺失的路径被 Stryker 的文件匹配丢掉，vitest runner 跑了项目自己的默认发现，然后为一个**从未存在过的文件**报出了满分。 改后同一个 glob 仍然 exit 0、digest 仍是 `339e74cc…`（能用的 glob 保持能用），而缺失文件一律 exit 1。 改后三个子命令的消息**逐字节相同**，且**只给相对 `--project` 的路径**，并附近邻候选： ``` Test file not found: tests/does-not-exist.test.ts Near-miss candidates: - tests/add.test.ts ``` **快乐路径没变**：有效测试文件下 `mut run` 的报告 digest 改前改后**都是 `96595ff6…`**（`killRate` 1、 `mutantsTotal` 2）。守卫 `tests/unit/cli/mut-test-file-not-found.test.ts` **15 个用例全绿**。 **这一段要更正的是一条"不可复现"的判断。** 最初的记录写的是"缺失 `--test-files` 路径静默回退默认发现、 可能报出完美 kill rate"**不可复现** —— 那条判断**只测了 `run` 与 `asserts`**，**漏了 `mutants`**；在 `mutants` 上它**确实复现**（exit 0 + 满分 kill rate）。本批的三个子命令现在统一成同一个具名码。 ### 2. 生成的插件清单：`prettier --check` 从 exit 1 变成 exit 0（本次 bump 没有把形状缺陷带回来） 清单是**受版本控制的生成产物**（`npm run plugin:manifest`），渲染器过去把**每个**数组都展开， 所以清单**不是** prettier-clean 的。实测（用仓库自己的 prettier 与仓库自己的 prettier 配置）： | | 改前（`HEAD` 的渲染） | 改后（本切片 bump 之后的渲染） | |---|---|---| | `prettier --check` | **exit 1（不是 prettier-clean）** | **exit 0** | | 行数（按换行计数） | 200 | **197** | | 行数（按 `split("\n").length`） | 201 | **198** | 唯一的变化是 `"args": ["mcp", "serve"]`（4 行 → 1 行）。改前的清单经 prettier 规范化后的输出， sha256 是 `849e6168…`，与**本切片 bump 之前**工作树里那份清单（切片 B 的渲染，版本 4.1.21） **逐字节相同** —— 说明新的渲染器产出的正是 prettier 自己的形状。本切片 bump 之后的清单 sha256 是 `fd087f50…`，同样 prettier-clean。 **依赖集不变**：根 manifest 的 `dependencies`（12 项）与 `devDependencies`（19 项）与 bump 前**逐字段相同** （本切片实测：五个 manifest 各自只有 `version` 一个键变了）；`prettier` 仍在 `devDependencies`、 **不在** `dependencies`（实测 `prettier in dependencies: false`），发布包的运行时依赖集没有变化。 **版本戳在两处**：`metadata.version` 与 `plugins[0].version` 都读 `4.1.22`；连跑两次生成**逐字节相同** （sha256 `fd087f50…`）。 ### 3. 包入口不变量（只加守卫，**零清单改动**） 根包声明 **1** 个入口（`bin.peaks → ./bin/peaks.js`），`peaks-loop-mut` 声明 **2** 个 （`exports["."].types`、`exports["."].default`）。守卫 `tests/unit/release/package-entry-points-guard.test.ts` **9 passed | 1 skipped**（构建产物在 → 磁盘检查**跑起来**：2 checked、0 skipped）。守卫钉住三条不变量： 声明的入口必须落在该包自己的 `files` 白名单里；`main` 与 `exports["."].default` 若同时声明必须一致； 根包**不得**把副作用型 CLI 模块声明成库入口。 ### 4. 两条必须说准的事（一条"不是缺陷"，一条"更正旧判断"） **(1)"包缺 `main`"不是缺陷 —— 它不是这次修的东西。** `peaks-loop-mut` 的主入口**已经**由 `exports["."]` 表达 （`exports["."].default → ./dist/index.js`）。实测（本机 Node v24.12.0）： - 一个同时声明 `main` 与 `exports` 的包，被 import 时加载的是 **`exports`** 那个目标（输出 `LOADED:EXPORTS`） —— Node 解析 `exports` 优先于 `main`，`main` 被忽略； - **`require()` 一个纯 ESM 包在 Node v24.12.0 上是成功的**（实测 `REQUIRE_OK`；`ERR_REQUIRE_ESM` 只对 Node < 22.12 成立）。所以诚实的理由是**"冗余且会误导"**，而**不是**"无法 require"； - 根包则**绝不能**加 `main`/`exports`：`dist/cli/index.js` 在**模块顶层**就 `program.parseAsync(process.argv)`（`src/cli/index.ts:61`），实测**import 它就会把 CLI 跑起来** —— 导入过程中就打出了 CLI 的帮助横幅。 **(2)"静默回退不可复现"这条旧判断本身不成立 —— 这一版是真的堵上了。** 它在 `mut mutants` 上**确实复现** （exit 0 + 满分 kill rate），缺的只是那次测量里的**第三个子命令**。所以这里不是"没有缺陷"，而是 "缺陷是真的、这一版三个子命令统一堵上了"。 ### 5. 版本号本身 | 包 | 从 | 到 | |---|---|---| | `peaks-loop` | 4.1.21 | **4.1.22** | | `peaks-loop-shared` | 0.0.110 | 0.0.111 | | `peaks-loop-mut` | 0.1.75 | 0.1.76 | | `peaks-loop-shared-channel` | 0.0.78 | 0.0.79 | | `peaks-loop-internal-runtime` | 0.0.61 | 0.0.62 | 版本号由 `scripts/bump-version.mjs` 产生（不是手打的）：根 `4.1.21 → 4.1.22`，四个 workspace 包在同一次 lockstep 里各 +1，五个 manifest **各自只有 `version` 一个键变了**；`scripts/sync-version.mjs` 把 `CLI_VERSION` 与 `RUNTIME_VERSION` 写成 `4.1.22`，`node scripts/verify-version-parity.mjs runtime-src` **exit 0**。 **发布顺序（发版前必须知道）**：`pnpm pack` 会把根包 `workspace:*` 依赖改写成**精确 semver pin**， 所以 `peaks-loop@4.1.22` 打包后的 manifest 依赖的是 `peaks-loop-mut@0.1.76`、 `peaks-loop-shared@0.0.111`、`peaks-loop-shared-channel@0.0.79`、`peaks-loop-internal-runtime@0.0.62` （实测：从 tarball 里读出的 `package/package.json`）。这四个版本**在 registry 上都不存在**（实测 `E404`）， 所以**这四个包必须先发布**，`peaks-loop@4.1.22` 才能被消费者装上；在它们发布之前，根包是不可安装的。 ## 4.1.21 — 2026-10-25（把"返工循环"数对，把"没测过"说出来） **版本级别**：候选 **patch**（沿用常设规则"默认版本新增采用最小的版本位"）。本次**没有**改 fail-open 策略、 没有动 auto-compact 三档阈值，peaks-code 的 11 步工序与 Gate A–G **一字不改**；改的是**一个度量的口径**、 **两个门禁的诚实性**、**CI 的一个咨询性作业**、**一个算错单位的守卫**，以及**版本号本身**。 **一句话：`peaks observability` 之前把 QA 自己的内部迁移当成了"返工循环"数出来，于是 108 个切片里有 82 个 "超了帽"。这一版把它数对了 —— 真正超帽的只有 1 个。** ### 1. 缺陷：返工循环数的是 QA 的内部迁移 旧口径数的是每一条 `detail.artifactRole === 'qa'` 的 slice-transition 事件。那是 QA 阶段内部的迁移， 和"RD 被打回去重做"没有关系。四个**各自独立**的缺陷叠在一起： | # | 缺陷 | 实测 | |---|---|---| | 1 | 数的是 QA 内部迁移 | 与返工无关 | | 2 | 一次迁移发**两条**事件 | 约 8ms 间隔，其中一条没有 `detail.from` | | 3 | `detail.from` 不可信 | 仅 606/1102 存在，其中 **395 条与事件顺序矛盾** ⇒ 绝不读它 | | 4 | `qa-handoff` 是 **RD 的状态** | 正常收尾 `verdict-issued→qa-handoff→handed-off` 是**快乐路径**，不是返工 | **实测对比**（10 个会话目录、108 个切片、1102 条事件）： | 口径 | ≥cap(3) 的切片 | 分布 | 峰值 | |---|---|---|---| | 旧（QA 事件计数） | **82 / 108** | `0:11 1:1 2:14 3:2 4:50 5:12 6:5 7:2 8:7 9:1 11:2 24:1` | **24** | | 新（返工循环） | **1 / 108** | `0:93 1:13 2:1 5:1` | **5** | 唯一真正超帽的那一个，序列是真的：`implemented→qa-handoff→running→verdict-issued→implemented→…`，五轮。 ### 2. 度量版本化：v2 与 v1 并列，不让新旧数被静默对比 - `metricVersion: 2`；旧计数保留在 `legacyQaEventCount` 下，`capHitCount` 用 v2。 - 返工循环的判定：QA 阶段后回到 RD **工作态**（`draft|spec-locked|implemented`）才算；一次返工只计一次； 重复发射折叠；**绝不读 `detail.from`**；纯 QA 往返单列为 QA rounds，不混进返工。 ### 3. 新命令与可复算的基线产物 - `peaks observability repair-cycles --all-sessions --json` - `peaks observability baseline [--write|--check]` → `.peaks/observability/results-baseline.json` 基线行只用**率与峰值**；人口描述被单独隔离并注明"不得作为门禁"，产物里写明 `ciEnforceable: false` 及其原因（观测数据在 gitignored 的会话空间里，CI 拿不到，硬接只会造一条假门禁）。 ### 4. 没测过的门禁，必须说"没测过" Phase A benchmark 门禁从二态改成**三态**： | 状态 | 退出码 | `passesGate` | |---|---|---| | `measured-and-passed` | 0 | `true` | | `measured-and-failed` | 1 | `false` | | `not-measured` | **3** | **`null`** | | runner 报错 | 2 | — | 旧的 `passesGate: false` 既可能是"测了没过"，也可能是"根本没测"，读者分不出来，而根因恰恰是**零次测量**。 现在未决绝不等同于通过。runner 也拒绝把 `--out` 指向记忆库（exit 2）—— 它以前每次运行都会往 `.peaks/memory/` 里写一份 `_TBD_` 存根，覆盖掉平台预留给人类真实测量的那个文件。 ### 5. 一个算错单位的守卫 `peaks-loop-internal-runtime` 的 resource-budget 守卫里，`process.cpuUsage()` 返回**微秒**， 而旧式算法 `/1e6 × 100` 得到的是**厘秒**。于是 `maxCpuPct: 5` 实际约束的是 **50 毫秒** CPU，不是 5%。 现在 `cpuPct` 是**占单核百分比**，另出 `cpuCentiseconds` 字段，字段名与 `Sample` 形状保持不变。 ### 6. CI 增加一个咨询性作业 `changed-tests-subset`：**只在 PR、只在 ubuntu**、`continue-on-error: true`（咨询性，不挡合并）、 `fetch-depth: 0` + 显式 merge-base、`PEAKS_VITEST_MAX_WORKERS: 4`、`timeout-minutes: 60`。 权威门禁仍是全量 `test` 作业。 ### 7. 这次发版带走了什么 `v4.1.20..HEAD` 的 44 个改动文件里，**13 个真正进入已发布产物**（12 个经 `src/**→dist/**`， 1 个是 `peaks-loop-internal-runtime`）；`dist/` 占 tarball 2889 条目中的 2670（92.4%）。 发版影响面按**输入集**算：展开 `package.json#files` 白名单得直发集，再补上 `src/**→dist/**` 与 `packages/**→内部包` 的间接集，最后排除发布元数据。 ### 8. 版本号本身 | 包 | 从 | 到 | |---|---|---| | `peaks-loop` | 4.1.20 | **4.1.21** | | `peaks-loop-shared` | 0.0.109 | 0.0.110 | | `peaks-loop-mut` | 0.1.74 | 0.1.75 | | `peaks-loop-shared-channel` | 0.0.77 | 0.0.78 | | `peaks-loop-internal-runtime` | 0.0.60 | 0.0.61 | ## 4.1.20 — 2026-10-25（从 4.1.18 起装不上的根包，修好了） **版本级别**：候选 **patch**（沿用常设规则"默认版本新增采用最小的版本位"）。本次**没有**新增门禁族、 没有改 fail-open 策略、没有动 auto-compact 三档阈值，peaks-code 的 11 步工序与 Gate A–G **一字不改**； 改的是**根包自己的打包白名单**（§1–§2）、**消费者能看到的说法**（§3–§4）与**版本号本身**（§5）。 **一句话：`npm i -g peaks-loop` 从 4.1.18 起就是装不上的。这一版把它修好了。** ### 1. 缺陷：白名单少了一行，于是整个安装死在 postinstall 根包的 `package.json#files` 是**白名单** —— 只有被它点名的文件才会进 tarball。 `scripts/install-skills-bundles.mjs`（**在包里**）import 了 `./canonical-store-report.mjs`， 而后者**不在白名单里**，于是 npm 发出去的是**一个没有同伙的 import 方**。 Node 的 ESM 加载器在跑任何代码之前就要把整张模块图解析完，所以这不是"少了个功能"， 是**图连不上**，安装死在 `postinstall`，CLI 根本轮不到上场： ``` npm error Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../node_modules/peaks-loop/scripts/canonical-store-report.mjs' imported from .../node_modules/peaks-loop/scripts/install-skills-bundles.mjs ``` **根因提交**是 `12c71e55`（"fix(gates): a surface must not say what the code does not do"）。 那一个提交在 `scripts/` 下**新增了 3 个** canonical-store 脚本（`canonical-store-fs.mjs`、 `canonical-store-marker.mjs`、`canonical-store-report.mjs`），给 importer 接上了其中的**第三个**， 而白名单**只加了那 3 个里的 2 个** —— 漏掉的正是 `-report`。该提交落在 `v4.1.17` 与 `v4.1.18` 之间（`git merge-base --is-ancestor` 实测：在 `v4.1.18`/`v4.1.19` 之内，在 `v4.1.16`/`v4.1.17` 之外）。 ### 2. 实测证据（每个数字都来自本次实测） **两个互相独立的方法**，同一个结论： | 方法 | 4.1.17 | 4.1.18 | 4.1.19 | |---|---|---|---| | **真实 `npm install`**（隔离 prefix + 隔离 HOME） | **exit 0**，`added 127 packages in 10s` | **exit 1**，`ERR_MODULE_NOT_FOUND` | **exit 1**，`ERR_MODULE_NOT_FOUND` | | **静态解析已发布 tarball**（`scripts/*.mjs` 数 / 本地相对 import 数 / **未命中**的目标数） | 16 / 24 / **0** | 18 / 27 / **1** | 18 / 27 / **1** | 那个"**1**"在 4.1.18 与 4.1.19 里是**同一个**目标：`install-skills-bundles.mjs -> ./canonical-store-report.mjs`。 **4.1.19 tarball 里所有已发布脚本的本地相对 import 全被枚举过一遍，未命中的只有这一个** —— 其余没进包的 `scripts/*.mjs` 都是本就不该进包的 dev / build / 测试脚本。 **不是 4.1.19 那一批引入的**：`v4.1.18` 与 `v4.1.19` 之间，`package.json#files` 的脚本条目 **增 0 减 0**，importer 的 blob 哈希**完全相同**（`05e80b3da11df0fee5f870fa3285a0fe153d0ff3`）。 4.1.19 是**继承**了这个缺陷，不是**造成**了它。 **修好之后的实测**（不只是"打包内容看着对"，是**真的装得上、跑得起来**）： - 把修好的树 `pnpm pack` 出来的 tarball 里，`scripts/*.mjs` 共 **19** 个， `scripts/canonical-store-report.mjs` **在包里**，已发布脚本的本地相对 import **未命中 0 个**。 - **真实安装**：把那个 tarball 装进一个隔离的 prefix（`HOME`、`PEAKS_CLAUDE_SKILLS_DIR`、 `PEAKS_CLAUDE_AGENTS_DIR` 全部指到临时目录），`npm install` **退出 0** （`added 293 packages in 40s`），**没有** `ERR_MODULE_NOT_FOUND`，postinstall 跑完。 - **装完就能用**：装好的包里 `peaks --version` 打出 **4.1.20**（退出 0）， `peaks mut --help` 打出完整命令树（退出 0）。 - 说明一句方法上的诚实：这 4 个 workspace 子包在本次版本里是**新版本号**，registry 上**还没有** （实测 `npm view peaks-loop-mut@0.1.74` → **404**），所以端到端安装里这 4 个内部依赖是用 **本树自己打出来的 tarball**（`file:` spec）解析的，其余依赖全部走 registry。 这正是发布流程"先发子包、后发根包"之后的拓扑；**打包白名单这件事本身**由上面的 tarball 内容测量直接回答。 ### 3. 修法：一行白名单 + 一个防回归守卫 **修法就是一行** —— 根 `package.json#files` 里加一条 `"scripts/canonical-store-report.mjs",`， `files` 的其余部分**一字未动**。白名单**没有**被放宽成整个 `scripts/`：那些 dev / build / 测试 脚本是**故意**不进包的，放宽会把它们一起发出去。 **现在有了防回归守卫**：`tests/unit/release/packaging-shipped-scripts-import-guard.test.ts` （**13** 个用例）。它**静态**地读根 manifest 的白名单，取出 `scripts/*.mjs` 条目作为**已发布脚本集**， 解析每个已发布脚本的本地相对 import，断言**每个被 import 的目标也在已发布集里**。 **不联网、不查 registry、不做真实 `npm install`**。 它守的是"**已发布脚本之间的**本地相对 import"，**不会**要求 dev / build / 测试脚本进包。 而且它被证明**真的会红**：临时把那一行从 `files` 里去掉 → 守卫 **exit 1**（`4 failed | 9 passed (13)`）； 逐字节还原（sha256 比对一致）→ 再跑 → **exit 0**（`13 passed (13)`）。**只看到绿不算验证过。** 守卫在修好的树上的数字：**已发布脚本条目 19 个**，**检查的本地相对 import 27 个**，**未命中 0 个**。 ### 4. 顺手拆掉的一颗雷：`main` 指向了不在白名单里的文件 工作树里根 `package.json` 带着 4 处**与本次缺陷无关**的改动（`repository.url`、`bin.peaks`， 以及新增的 `main`、`directories`）。其中 **`main: "stryker.conf.js"`** 是一颗雷： `stryker.conf.js` **不在 `files` 白名单里**，所以它**不会**进 tarball —— 而 `main` 正是消费者 `import 'peaks-loop'` 解析到的入口。 留着它，就等于**修好一个"装得上"的包，再塞一个"装上了但主入口用不了"的坑**。 这 4 处已全部**还原成 `HEAD` 的原值**（`main` 与 `directories` 直接删掉）。 **成因是查出来的，不是猜的**：`npm pkg fix` 会把 `repository.url` 归一化成 `git+https://` 形式、 把 `bin` 的 `./` 前缀去掉；`npm pkg set` 会写入 `main` 与 `directories`。 而**本次用的版本锁步脚本不会**（实测：跑一次 `scripts/bump-version.mjs`，这 4 个字段 **0 个**被改动）。 ### 5. 版本号与发布含义 - 根包 `peaks-loop` **4.1.19 → 4.1.20**。`packages/` 下**实际只有 4 个**可发布 workspace 包， 由正路脚本**锁步升**（子包规则 = patch 位 +1，major/minor 不变）： | 包 | 改前 | 改后 | | ----------------------------- | ------- | ---------- | | `peaks-loop`（根） | 4.1.19 | **4.1.20** | | `peaks-loop-mut` | 0.1.73 | **0.1.74** | | `peaks-loop-shared` | 0.0.108 | 0.0.109 | | `peaks-loop-shared-channel` | 0.0.76 | 0.0.77 | | `peaks-loop-internal-runtime` | 0.0.59 | 0.0.60 | - 两个**受版本控制**的版本戳同步为 4.1.20：`packages/peaks-loop-shared/src/version.ts` 的 `CLI_VERSION` 与 `packages/peaks-loop-internal-runtime/src/index.ts` 的 `RUNTIME_VERSION`。 - **版本字段一个都没手改**：全部由 `scripts/bump-version.mjs --to 4.1.20` 与 `scripts/sync-version.mjs` 产生。逐字段比对证明：**5 个 manifest 各自只有 `version` 一个键变了**；根 manifest 相对 `HEAD` 只多两处 —— `version` 与 `files` 里的那一行。 - **维护者要做的**（本次**没有**做）：合并后 `git tag v4.1.20` + push，由发布流程发包。 **本次不打 tag、不发布、不提交。** ### 6. 验证 - `node scripts/verify-version-parity.mjs runtime-src` 退出 **0**（`RUNTIME_VERSION=4.1.20`）。 - `pnpm install --frozen-lockfile` 退出 **0**，而且**锁文件一个字都没改** —— sha256 前后同为 `7f60e065a8df3a63d7b03a2fc8f91db9628362387997fc77655c8c75ef46cc72`， `git diff pnpm-lock.yaml` 为**空**。workspace 包在锁文件里是 `link:` 引用（**不记版本号**）， 所以版本号变动**不需要**动锁文件。 - 逐字段比对：**5 个 manifest 各自只有 `version` 一个键变了**。 - 新守卫 `tests/unit/release/packaging-shipaged-scripts-import-guard.test.ts`： **13 passed (13)**；去掉那一行白名单则 **4 failed | 9 passed (13)**，逐字节还原后回到全绿。 - **端到端**：修好的树 `pnpm pack` → 隔离 prefix 里 `npm install` **退出 0** （`added 293 packages in 40s`）、**无** `ERR_MODULE_NOT_FOUND`；装好的包里 `peaks --version` 打出 **4.1.20**，`peaks mut --help` 退出 **0**。 - `.claude-plugin/marketplace.json` 由 `npm run plugin:manifest` 重生成，**跑两次逐字节相同**。 - `tsc -p tsconfig.json --noEmit` 退出 **0**；`prettier --check` 对本次改动的清单文件退出 **0**； `eslint --config config/eslint/.peaks-rules.cjs --no-ignore` 对本次改动的文件 **0 findings**。 ## 4.1.19 — 2026-10-24（`peaks mut` 在真实用户机器上**真的能跑**） **版本级别**：候选 **patch**（沿用常设规则"默认版本新增采用最小的版本位"）。本次**没有**新增门禁族、 没有改 fail-open 策略、没有动 auto-compact 三档阈值，peaks-code 的 11 步工序与 Gate A–G **一字不改**； 改的是 `peaks mut` 这一条线上的**依赖位置、作用域与文档**（§1–§5），以及**版本号本身**（§6）。 这一批做的是**同一件事**：让 `peaks mut` 从"消费者装上就崩"走到"消费者装上就能跑"。 崩的原因**不是代码写错了**，是**依赖放错了地方**：变异测试引擎只挂在根包的 `devDependencies` 上， 而真正 import 它的是 `peaks-loop-mut` —— 一个**要被发布出去**的包。消费者装到的是 registry 上的 `peaks-loop-mut@0.1.72`，它的 dependencies 只有 `{zod, ecc-universal}`，**不带 stryker**， 于是 `Cannot find package '@stryker-mutator/core'`。 这一批把它修好，并且补上三件一直缺的东西：**项目作用域正确**（改谁就只改谁）、 **文档说真话**（文档里每句话都对得上代码）、**过期接受退休**（一条理由已经不成立的"豁免"从名单里划掉）。 **消费者要多付一点下载体积：约 2.66 MB。** 这件事写在 §1，不藏着。 ### 1. 变异引擎落到生产依赖（以及它到底值不值这 2.66 MB） - 现在 `@stryker-mutator/core`（Stryker 的变异引擎）与 `@stryker-mutator/vitest-runner` 是 `peaks-loop-mut` 的**生产依赖**（`dependencies`，不是 `devDependencies`），两者同为 **9.6.1**。 - **消费者视角 —— `@stryker-mutator/vitest-runner` 是干什么的**：它是把 Stryker 的变异引擎接到 vitest 上的**适配器**。没有它，Stryker 只能退回"跑一条命令看退出码"的粗粒度跑手， **算不出逐 mutant 的 kill rate** —— 而 `peaks mut` 卖的**正是这个数字**。所以它不是可选项。 - **代价**：安装会多出 stryker 引擎闭包 **9 个包 / 约 2.66 MB**。 - **vitest 那部分不会自动来**：vitest-runner 声明的 peer 是 `vitest >=2.0.0`，而 pnpm 的 peer 自动安装 **只在 peer 缺失时**发生。vitest / vite 家族共 **11 个包 / 约 5.30 MB**，**只有在你的机器上 还没有 vitest 时**才会被自动装上 —— 而要跑 `peaks mut` 的项目**必然已经有 vitest**。 - 说人话：**你装 peaks-loop 多下载了约 2.7 MB**。参照：`peaks-loop-mut` 现有的生产依赖树是 **344 个包 / 156.6 MB**（大头是 `sql.js` 23.0 MB、`typescript` 22.5 MB、`ecc-universal` 18.6 MB， **与本次改动无关**），2.66 MB 相对可忽略。（这一段的 MB 一律是**二进制 MB**：三个大头由同一份实测 脚本以 `/1024/1024` 从按 `KB` 记的实测字节换算，与上面 2.66 / 5.30 / 156.6 同一口径。） - **为什么这一节必须配一次版本号**：发布脚本**先发子包、后发根包**，并且**跳过 registry 上已存在的同版本**。 `peaks-loop-mut@0.1.72` 已经在 registry 上，它不带 `dist/version.js` 所以不会被判 stale —— 版本不动，**这个改动到不了任何用户**。 ### 2. core / vitest-runner 的大版本互斥修好了；那个**从来没激活过**的 checker 被移除 - 此前：vitest-runner 9.6.1 声明的 peer 要求 core **9.6.1**，而根包 `devDependencies` 里 core 停在 **^8.7.1** ⇒ 每次安装都有一条 unmet peer。 - 现在：core 与 vitest-runner 同为 **9.6.1**，**全量重解析零 unmet peer**。 - `@stryker-mutator/typescript-checker` **已移除**：**移除之前**全仓只有 **5 处**提到它 —— 根清单的 `devDependencies` 一行、锁文件里的 importer 条目 / package 条目 / peer 快照条目三条，以及 `.peaks/docs/lint-rule-divergences.md` 里的一句散文记录。**这 5 处没有一处是插件**： `stryker.conf.js` 的 `plugins` 里**从来就没有它**（移除前的版本也没有），它**从来没有被激活过**。 而它声明的 peer 是 core `~8.7.0`，与 9.6.1 **互斥**，于是每次安装都报一条 unsatisfied binding。 移除后那条警告消失。这一版发出去的树里，它**只剩两处**被提到：那一句散文记录，和本节的这一句。 - 锁文件的改动**有闭包证明**，不是"看着像"：把两份锁文件的 stryker 传递闭包逐键比对，结论是 **每一处改动都在闭包内**（**PASS**）。checker 移除那一轮单独是 **26 删 / 0 增 / 1 改**， 删掉的正是 checker 的子树；028 这一轮合起来，importer 只动了 `.` 与 `packages/peaks-loop-mut`。 ### 3. `peaks mut` 的项目作用域与程序化配置（改谁就只改谁） - 此前：`--project` 被**忽略** —— Stryker 读配置、解析 `mutate` / `testFiles` 模式都按 `process.cwd()` 来， `--test-files` 根本没传到 Stryker；项目根的 `stryker.conf.js` 是**必须**的。 - 现在：作用域由 `--project` 决定，配置由 CLI **程序化**构建；项目根的 `stryker.conf.js` 降级为**可选的向后兼容兜底**（项目自己写的 `mutate` 仍然优先于 CLI 的默认值）。 - **实测（真实夹具，在仓库之外：没有 `node_modules`、没有 `stryker.conf.js`）**： `mutantsTotal 4 / killed 2 / survived 2 / killRate 0.5`； 从**另一个工作目录**发起时，被改的是夹具里的文件，调用者 cwd 里的诱饵文件**没被改** （`decoyUnchanged = true`）。**stdout 恰好 1 行**，可解析。 - 失败现在有**具名错误码**，不再是 `UNHANDLED_ERROR`： `MUT_MUTATE_PATTERN_REQUIRED`、`MUT_NO_MUTANTS`、`MUT_TOOLCHAIN_UNAVAILABLE`。 - 测试：纯配置构建器 **13 passed**、CLI 标志解析 **5 passed**、集成 **2 个文件 / 5 个测试全绿**。 - 报告 schema 的源文件**逐字节未改** （sha256 `bc675a8521601c8edb2cd217ccbe9972fe6ed2040b79701e3870cd1f3db60d1d` 前后相同）。 ### 4. 文档与脚本说真话（每一句都对得上代码） - `peaks-mut` 技能文档：**18 处校正 + 3 处收紧**（逐条"原句 → 现句"在切片载体里）。 - 守卫测试对着**真实的 commander 命令对象**比对，不是对着手抄的标志清单 ⇒ 标志改名/增删都会红。 当前 **12/12 绿**；红复现实测 **1 failed / 11 passed，退出码 1**。 - 仓库自己的 `stryker.conf.js` 此前指向 **4 个没有任何测试 import 的文件** ⇒ dogfood 运行必然 `killRate 0`、退出码 1（**不是配置写错了，是那几个文件根本没有测试**）。现在 4 个 mutate 目标 **每一个都有测试 import**。 - 根脚本 `mut:run` / `mut:scan` 现在带的参数**就是解析器认的参数**（之前那两个脚本各缺必需参数）。 ### 5. `mut/mut-report.json` 的过期接受条目退休 - 此前：种子名单里有一条针对 `mut/mut-report.json` 的"过期可接受"豁免，它给的理由**两半都是假的** （"没有生产者"、"peaks tact read 不是注册命令"）。现在 `peaks mut run` **真的**产出报告， `peaks tact read` **真的**是注册命令 —— 理由不成立了，条目就该退休。 - 退休范围**只有那一条接受条目**：那行 `backCompat` / `backCompatUntil` 的**窗口本身一字未改** （窗口仍在，缺的报告仍是软通过）；另一条接受**保留**。 - 真实报告（`mut/mut-report.json`）：`mutantsTotal 21 / killed 20 / survived 1`、 `killRate 0.9523809523809523`、`totalAssertions 29`、`weakAssertions 0`、`weakRate 0`、 `thresholds.passed true`。 - 阈值**一个都没改**（`mutationKillRateMin 0.80` / `weakAssertionRateMax 0.05`）， 受影响的 **7 个测试文件 / 93 个测试全绿**。 ### 6. 版本号与发布含义 - 根包 `peaks-loop` **4.1.18 → 4.1.19**。`packages/` 下**实际只有 4 个**可发布 workspace 包 （发现规则是扫 `packages/` 的直接子目录、且要求其中有 `package.json`）， 由正路脚本**锁步升**（子包规则 = patch 位 +1，major/minor 不变）： | 包 | 改前 | 改后 | | ----------------------------- | ------- | ---------- | | `peaks-loop`（根） | 4.1.18 | **4.1.19** | | `peaks-loop-mut` | 0.1.72 | **0.1.73** | | `peaks-loop-shared` | 0.0.107 | 0.0.108 | | `peaks-loop-shared-channel` | 0.0.75 | 0.0.76 | | `peaks-loop-internal-runtime` | 0.0.58 | 0.0.59 | - 两个**受版本控制**的版本戳同步为 4.1.19：`packages/peaks-loop-shared/src/version.ts` 的 `CLI_VERSION` 与 `packages/peaks-loop-internal-runtime/src/index.ts` 的 `RUNTIME_VERSION`。 - **版本字段一个都没手改**：全部由 `scripts/bump-version.mjs --to 4.1.19` 与 `scripts/sync-version.mjs` 产生。逐字段比对证明：**5 个 manifest 各自只有 `version` 一个键变了**。 - **维护者要做的**（本次**没有**做）：合并后 `git tag v4.1.19` + push，由发布流程发包。 **本次不打 tag、不发布、不提交。** - 为什么**必须**动版本号（再说一次，因为它就是本节存在的理由）：发布脚本**先发子包、后发根包**， 并且**跳过 registry 上已存在的同版本**；线上根包 pin 的是 `peaks-loop-mut: 0.1.72`， 而 registry 上的 0.1.72 **不带 stryker** ⇒ 版本不动，§1 的依赖**到不了用户**。 ### 7. 验证 - `node scripts/verify-version-parity.mjs runtime-src` 退出 **0**（源码层，不需 build）。 - 源码 CLI `node node_modules/tsx/dist/cli.mjs src/cli/index.ts --version` 打印 **4.1.19**。 - `pnpm install --frozen-lockfile` 退出 **0**，而且**锁文件一个字都没改** —— workspace 包在锁文件里是 `link:` 引用（**不记版本号**），所以版本号变动**不需要**动锁文件。 - 依赖守卫测试 `tests/unit/release/mut-runtime-dependency.test.ts` **13 passed (13)**。 - `tsc -p tsconfig.json --noEmit` 退出 **0**；`prettier --check` 对本次改动的清单文件退出 **0**； `eslint --config config/eslint/.peaks-rules.cjs --no-ignore` 对两个版本戳文件 **0 findings**。 - 逐字段比对：**5 个 manifest 各自只有 `version` 一个键变了**。 ## 4.1.18 — 2026-10-23（下游机器的技能商店会说谎了；门禁不再对自己的沉默撒谎） **版本级别**：候选 **patch**（沿用常设规则"默认版本新增采用最小的版本位"）。本次是**纯修复**： 既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、 peaks-code 的 11 步工序与 Gate A–G **一字不改**。 本次修的是同一条线上的**七个洞**，它们是**同一类**：**一个表面说自己做了、其实没做的事**。 下游 macOS 机器报告"`~/.peaks/skills/peaks-code` 在，但 `~/.claude/skills/peaks-code` 软链后面的内容没有完整更新" —— 查到最后，**发布包是好的**（4.1.16 / 4.1.17 的 tarball 里 49 个 reference 文件一个不少）， 坏的是**商店那一侧**，而且坏的方式是：**没有任何地方记录版本号**，所以"冻结在 4.1.15"和"是当前的" **长得一模一样**。 **下游那台机器要做的：装上这个版本，跑 `peaks skill sync`。** 这次切片要的是一条**命令**， 不是一个诊断。 ### 1. 商店的陈旧必须**可检测**，也必须**可修复** - 此前：`~/.peaks/skills/.peaks-managed` 这个 sidecar **只记了来源路径**，不记版本。 归属靠"sidecar 在不在"判定，刷新靠**逐字节比对**。没有版本 ⇒ 陈旧**不可知** —— 安装器不知道、`peaks doctor` 不知道、用户不知道。 - 现在：sidecar 记**两个事实** —— 来源路径 **和** 产出这份副本的**包版本**（一行 JSON）。 **旧格式仍然读得动**：只有路径的老 sidecar 解析成"是我们的，但版本未知"，而**版本未知即陈旧** （当前来源才是权威）—— 一个会在旧格式上抛错的读取器会**弄坏每一个已存在的安装**。 - 陈旧现在**按版本**判定，不只按字节。所以**记录的路径已经失效**（npm 全局前缀换了）但版本落后时， 照样刷新；而路径失效、版本却对得上时，**不重拷**，只**订正 marker** —— 一条指向已经不存在的路径的 marker，本身就是一条陈旧的事实。 - **用户自己写的那份仍然受保护**：**没有 marker** 的商店条目**永远不会被覆盖**。 - **doctor 检查** `skills:store-version:store` 比的是**商店记录的版本 ↔ 已安装包的版本**， **永远只出一行**：落后=红并给出补救命令 `peaks skill sync`；当前=绿并**同时写出两个版本**； 没有商店=绿且只是"无可比较"（没有商店的机器不是坏机器）；读不出来=红、severity `warning`。 **它只读，不写。** - **修复命令**是 `peaks skill sync`。它对 legacy、v2、以及**路径已经失效**的 marker **一律能修**。 ### 2. 为什么已有的那条检查看不见它（这一条比修复本身更值得记） `skills:reference-parity` 检查的名字里就写着下游那个形状，它比对的是**商店 ↔ IDE 树**。 但那台机器上 `~/.claude/skills/peaks-code` 是**指向商店的软链** —— 两棵树**是同一棵树**， 永远"一致"。**一份冻结在旧版本的商店是完全自洽的**，所以 parity 检查永远沉默。 **store↔IDE 的一致性看不见 store↔package 的陈旧** —— 这是两个不同的轴，此前只有一个。 新加的那条检查在**另一个轴**上，它**不是** parity 检查的替代品。 ### 3. 同样这一类：门禁说的和门禁做的不一致 - **`peaks hooks install --help`** 描述了一个命令**早就不做**的效果：`--no-progress` 说自己会"跳过 progress-start 那个 PreToolUse 条目"，而**父命令自己的描述**说那个条目 **早已不再安装**（slice #014）。这个参数被穿了四层、最终进到一个**下划线开头、根本没被读**的参数里。 它的帮助文本还**没提**全局安装会往用户全局的 `~/.claude/skills/peaks-code/hooks/` 里拷两个脚本 —— 下游那台机器正是跑过这条命令的机器。 - **`build-integrity`**：零个带 `.ts` 源码的包，会打出和"核对了二十个包"**一模一样**的 `build-integrity: OK`。空集是**合法的**，所以**退出码仍然是 0**；变的是**那句话**，而且它 **刻意不含那个全清字符串** —— `build-integrity: OK (nothing to check)` 仍然**包含** `build-integrity: OK`，而那正是这条切片要防的"读平了"。 - **提交门**：本次之前，同一个切片里有**三个**文件**带着未格式化**的状态进了 commit， 而**提交时跑的每一个门都是绿的**；是**推送门**把它们拦下来的。原因是 `lint-staged` 把 `tests/**` 当作"在 lint scope 之外"**直接丢掉了**。 现在提交门多了一条**宽格式腿**：scope 之外但在宽 glob 之内的**已暂存**文件不干净就**拒**， 并**点名文件与确切的修法**。 **宽检查的基线集合是空的**（债在 2026-10-17 收干净了），所以这条规则字面上就是 "**不许有未格式化的文件**"，**不需要逐文件的基线行** —— 它和提交门那条**逐文件棘轮** 是**两种**机制，owner 2026-10-03 的 lint scope 决定**没有被重开**，eslint 腿**也没有被放宽**。 - **叶子代理的临时目录**不再依赖 cwd：派发提示里现在**机器注入**一块绝对路径的说明 —— 和 Karpathy 那一块**同一个机制**（"一个忙起来会忘掉的义务不是执行器"）。 路径是 `/.peaks/_runtime///scratch/`，且用**正斜杠** —— 因为反斜杠对 POSIX shell 是转义字符，`> D:\repo\x.log` 在那里写的是 `D:repox.log`， **就落在 cwd 里**。**那正是这个泄漏本身，被"修"出来时的形状。** - **auto-compact 的延后**此前**在生产里从来没有触发过**：探针被喂了空的图（`graphs: []`）， 即使有图也**不可能**满足 —— 它要的是 `status === 'running'` **且**带心跳的节点， 而图的三处写入方**从不**产出这两样。现在延后读**派发账本**（owner 2026-10-22 裁定： 账本是唯一真相源），"在飞"= **未终态且新鲜**，新鲜度复用既有的 30 分钟阈值（**没有重复一个常量**）。 **六种"不知道"全部延后**：账本读不出、记录读不出、状态不认识、新鲜度解析不出、 记录版本不认识、记录越出账本。 - **`.sh` 兄弟实现**（Code-Gate 的那份）现在是 **Node 命令的薄壳**：找 CLI（`PATH` 上的 `peaks`， 否则安装器写在旁边的包根指针），`exec` 过去，子进程继承 stdin —— 载荷**原样**抵达，薄壳**不读**它。 - **`peaks skill sync --dry-run`** 以前**会建目录**，还会报"装了 184 个符号链接"——而它一个链接都没建。 现在 dry run **什么都不写**，报 0。 ### 4. 被有意接受的取舍（写在这里以免看起来像疏漏） - **兄弟实现的 fallback 路径**（**没有 CLI 可达**的那种情形）**仍然是第二份实现**，仍然带着 bash 规则， 仍然和命令在 **336 行矩阵里的 130 行**上分歧：**116 行误拒**（fallback 自己的拒绝）与 **14 行偏放行**（全是同一种形状：项目内的**绝对路径** —— fallback 没有 payload 自己拼写下的项目根， **无法相对化**）。那 14 行**既有的、未变的**，而且**薄壳委派时它不存在**。 **更便宜也更诚实的修法没有被采纳**（把 fallback 变成**一律拒绝**就能关掉那 14 行、 让"一份实现"字面为真），代价是**在一台没有 Node CLI 的机器上拒绝一切编辑**。 **这是 owner 的取舍，留着。** - **doctor 的一条检查"干净时不说一声"这件事没有在本版修**。`compareSkillReferenceParity` 在完全一致时返回 `[]` —— 没有"干净"这一行，所以报告**分不清**"跑了、没发现问题"和"根本没跑"。 本机实测：`peaks doctor --json` 出了 **88 条检查，没有一条**带 `skills:` 前缀。 改**所有**检查的报告形状是另一件事（另一个决定、另一条切片），**不在本次**； 本次新增的商店版本检查**干净时会出一行**。 - **`--no-progress` 没有被删掉**：它是已发布的 CLI 表面，删是破坏性变更。 这次只把它的帮助文本**改成它实际的样子**，并用一条测试把这个事实**钉住** （`resolveHookEntries` 两种参数返回**同一组**条目 —— 将来谁给它加上效果，那条测试会红）。 - **auto-compact 延后的"不知道就延后"是**没有时间上限**的**（+6 个月仍然如此）， 只有红线或 6 小时回收器能解开它；**三档阈值一个数字没动**，变的是**延后真的会触发**。 - **本版找到了 `diff-proj-*` 那些残留的来源，而它不是一段签进来的测试**：`diff-proj` 这个字符串在 `src/`、`scripts/`、`tests/`、`.husky/` 里**一处都没有**，那些 fixture 的 `link` 是一个指向 MSYS 风格 `/d/projects/peaks-loop/...` 的 POSIX 软链 ⇒ 是**上一轮会话里一条临时 bash 命令**， 从仓库根按 **cwd 相对**路径写进去的。**这恰恰是本切片要治的那个习惯本身** —— 比任何测试都更有 力地说明"规则必须机器注入"。 那一类才是主题；找到那一个测试是另一条请求。 ### 5. 验证 - **每个切片的 QA 判决**：技能商店的版本可检测性 `pass-with-notes`；D-1（宽格式腿） `pass-with-notes`；§2.18（nothing-to-check）`pass`；§2.31（scratch 路径块）`pass-with-notes`； D-3（hook 帮助文本）`pass-with-notes`；§20（ledger 延后）`pass-with-notes`； §19.1（薄壳）`pass-with-notes`，**外加一条被点名的 finding**。 - **每一条天花板都没有涨**：eslint 1696/1700、错误 560/561、prettier 0、tsc 0、 注释死引用 0、叙述行 22/22、文件尺寸 77/77 与 21935/21935、静默告警 44/44 与 60/60。 - **商店那条**：owner 的形状被**原样重建并修好** —— legacy marker + 旧字节 + 删掉的 `references/fast-lane-norm.md` ⇒ `peaks doctor` **点名了它**（"2 of 23 … peaks-code (no version recorded)"） ⇒ `peaks skill sync` ⇒ 文件回来了、`SKILL.md` 是当前的、marker 变成 v2（记着当时的包版本 4.1.17）。 **用户自己写的那一份 survived**（没有 marker 的条目**没有被覆盖**，也**没有被塞进 sidecar**， 并且被报成"没有动它"）。doctor 检查**永远只出一行**，**没有继承** parity 检查"干净时不出声"的形状。 该切片动过的文件里 **0** 个失败。 - **§20 的延后现在真的会在生产里触发**（对着真 CLI 端到端量过）：ledger 1 分钟 ⇒ `"decision": "in-flight-batch"`；31 分钟 ⇒ 照常压缩；没有 ledger ⇒ 照常压缩； **读不出来的 ledger ⇒ 也延后**（安全方向）；红线 0.96 仍然压过一切。 reader 热态成本 **2.03 ms**（5 条记录的会话上）。 - **§19.1 的差分**：**薄壳委派与 Node 命令 0 行分歧**（一份实现，结构上不可能分歧）。 **fallback 与命令的分歧**：**336 行矩阵里的 130 行**（116 误拒 + 14 偏放行）； QA 另在 **448 行**上重新导出 **15** 行偏放行 —— **同一种形状**，**既有**，**没有一行是回归**。 **仍然开着的一条残留，而且被直接量过**：`file_path = /src/x.ts` ⇒ **Node 命令 deny** （`data.action = deny`）、**fallback allow**（exit 0）—— fallback 没有 payload 自己拼写下的项目根， **无法相对化一个绝对路径**。**既有残留**，且**只在 fallback 路径上**。记在 backlog §19.2 与安全审计里， **没有当作已修**。 - **§19.1 的 QA 找到一条 finding，并且它推翻了刚刚重发的安全审计里的一句话**：fallback 的 payload 扫描当时是 `grep -oE '"cwd":…' | head -n1`，扫的是**整个** payload，所以一个**嵌套**的 `cwd` 键会 抢到首次匹配 —— 此时 fallback **不拒绝**，按 `$PWD` 读，于是**放行**了 Node 命令**拒绝**的文件。 这与文件自己的注释和审计摘要里的断言**矛盾**（那句断言说 fallback 现在"拒绝而不是猜"）。 **洞是既有的、只在 Mode 2 上、且可达性很窄**（Claude Code 的 Edit/Write/MultiEdit 的 `input` 里没有 `cwd`）。**本次修掉了**：扫描换成一段**带深度感知**（认识字符串和花括号）的 `awk`， 读**顶层**的 `tool_name`/`tool`/`cwd` 与 `tool_input`/`input` 里的 `file_path`/`path`/`notebook_path`；**读不懂的 payload（括号不平衡、值里带换行）一律拒绝**。 **编排器直接对着当前代码量过**：Node 命令拒，fallback 现在也拒。**审计因此又重发了一次** —— **审计不是最后一句话**。 - **BDD 测试风格契约**（本仓库有检查器，但**没有 CI 门**）：本次动过的测试文件里 **21 个**不合规， 拆开是 **11 个在 HEAD 上就已经不合规**（本次**没有引入**那份债，记在 backlog §21.9 里 作为另一条更大的改动）**和 12 个本次新增的**，那 12 个本次全部改到合规。 - **lint scope 的影子（`scripts/` + `tests/`）**的文件数从 818 涨到 842 —— 按 owner 2026-10-03 的决定， **影子目录是豁免的**，所以这条**不是** finding。 ## 4.1.17 — 2026-10-22（相对路径按它**在哪个目录**判，不按它**怎么拼写**判） **版本级别**：候选 **patch**（沿用常设规则"默认版本新增采用最小的版本位"）。本次是**纯修复**： 既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、 peaks-code 的 11 步工序与 Gate A–G **一字不改**。 上一版（4.1.16）把相对路径的**基准**改成了"工具调用实际所在的目录"，但**基准与项目根是按字面比较的** —— 本次把这个洞收口。 ### 1. 一个目录可以有两种拼法，判决不能因此不同 - 此前：相对路径的**基准**（工具调用的目录）与**项目根**按**字面**比较。路径里有符号链接时， 两者对不上 ⇒ 门禁判定"文件在项目外" ⇒ 退回**按拼写读** ⇒ 拼得像 `src/` 的写法**被放行**。 - **macOS 上这不是假设**：测试 harness 的项目根来自 `mkdtempSync(tmpdir())`，是**非规范**的 `/var/folders/...`；而门禁进程自己的工作目录是**规范**的 `/private/var/...`（`/var` 是 `private/var` 的符号链接）。两者一错配就中招 ⇒ **4.1.16 推上去时 `macos-latest` 那条 job 是红的**， 8 个用例失败。**Windows 一个月没暴露，只因为本机 temp 路径里没有符号链接。** - 现在：路径读**两遍** —— **词面**（怎么写的）与**规范**（文件真实在哪）—— 判决取**最严**的那个。 **白名单是每一遍各自先判的**：一遍命中白名单不会因为另一遍命中族而变成拒绝。 - **裁决原则用的是本仓库自己的那条**（见 4.1.15）：**误放是漏洞，误拒只是碍事**。 所以**不是**"规范读法当权威"——那会在 `src` → `shared/src` 这种常见布局里**放宽**门禁 （词面 `src/x.ts` 拒、规范 `shared/src/x.ts` 放行）；而是**任一遍命中族就拒**。 ### 2. `.sh` 兄弟实现也走同一条规则 它原本只按**拼写**判，于是和 Node 版**越漂越远**：Node 拒的写法它放行。 现在它取同样两遍读法、取同样的最严判决，而且**规范读法相对的是它自己解析出来的那个基准** —— 两套实现因此不可能对"文件在哪"给出不同答案。 **两个实现同一条规则，就必须互相测，而不是各自对着自己的预期测。** ### 3. 被有意接受的取舍（写在这里以免看起来像疏漏） - **落在项目之外的相对路径**仍按"拼写相对项目根"读 ⇒ **不会放宽**门禁。 - **一个被纠正的误拒**：当**基准在非族目录**（例如 `/docs`）时，旧的拼写锚定规则会把 `src/x.ts` 这类写法**拒**掉，而那些文件其实落在 `/docs/…`、**在所有硬阻断族之外**。 现在按文件真实所在判 ⇒ **放行**。这是**放宽**，方向是裁定自己的不变量（判决跟文件走，不跟拼写走）， **已接受并记录**（不 claim 掉）。 - **兄弟实现还有三处已知短板**（它**读不到** payload 顶层 `cwd`、**推导**项目根、**无法相对化绝对路径**）， 归在 backlog §19.1/§19.2 的 owner 决策里，不在本次收口。 ### 4. 验证 - 与**改动前**的代码逐行对照：**896 行里 0 行**让任一实现放行了落在拒绝族里的文件。 - **不得放宽**：Node 命令**收紧 92 / 放宽 0**；兄弟实现**收紧 76 / 放宽 0**。 相对**切片前**的代码，Node 112/40、兄弟 108/36 —— 那 76 个放宽**全部**在非族目录的基准上， 每个文件都落在所有族之外（§3 那个被纠正的误拒），**不是洞**。 - 家族成员零行改动，fail-open 不变，fast lane 仍然打开这些族。 - **顺手订正一句注释**：它描述了一种代码并不做的比较（审计里的第六条 LOW）——现在它说的是代码做的事。 - 另附一条**实测**：门禁读的 payload 顶层 `cwd` **确实是 PreToolUse payload 的顶层字段** （对着本机装的 Claude Code 二进制读到构造点，不是推断）；**任何 IDE 都会这么发**这一条**仍未实测**。 ## 4.1.16 — 2026-10-22（相对路径按工具调用实际所在的目录解析） **版本级别**：候选 **patch**（沿用常设规则"默认版本新增采用最小的版本位"）。本次是**纯修复**： 既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、 peaks-code 的 11 步工序与 Gate A–G **一字不改**。 上一版（4.1.15）在 QA 复核里**诚实记下了一个洞**：工具调用的工作目录不是项目根时， 相对路径落在 `src/` 里却被放行 —— "判定只由文件落在哪个目录决定"这条不变量**还没有完全成立**。 **本次把它收口。** ### 1. 相对路径的基准：工具调用实际所在的目录 - 此前：相对路径按**调用方指定的项目根**解析。于是 cwd 是 `/src`、payload 是 `deep/x.ts` 时，这个路径其实指向 `/src/deep/x.ts` —— **落在 `src/` 里、应当被拒**， 而门禁**放行**了。逃逸是**静默**的。 - 现在：相对路径按**工具调用实际所在的目录**解析。来源有两条，先用前者： payload **顶层**的 `cwd`（IDE 给了就用），否则**门禁进程自己的工作目录**。 **族仍然相对调用方指定的项目根**比；**绝对路径规则不变**；**嵌在 git 仓库里的项目仍然判自己**。 - **代价（有意接受，写在这里以免看起来像疏漏）**：基准选错会误拒邻近目录的文件。而回退基准是 门禁进程的 cwd —— 正常调用里 hook 就跑在工具调用的目录上，所以那条回退**就是**工具调用的目录。 ### 2. 两个逃逸 - ⚠️ **`.sh` 兄弟实现的 `./` 剥离**：它把 `.//deep/x.ts` 剥成前导 `/`，于是被当成**绝对路径**、 **永不相对化** ⇒ 落在所有族之外 ⇒ **放行**。而那个文件在 `/src/deep/x.ts`，**在 `src/` 里**。 **同一个文件的 10 种拼法里 6 种，两套实现的判决相反** —— 而**两套实现各自的单测都是绿的**。 现在："是不是绝对路径"按**未经剥离的原样拼写**判定。 - ⚠️ **Node 命令信任了一个不是目录的 payload `cwd`**：payload 说了一个不存在、或者不是目录、 或者相对的地方，路径因此解析到项目之外，"按拼写回退"那条老路又被走到 ⇒ **逃逸重新打开**。 现在 payload `cwd` **只有**在"**绝对路径 + 存在的目录 + 在指名的项目之内**"三件事同时成立时才被采信； 否则用**门禁进程自己的工作目录**。⇒ **修复不依赖 payload 的 `cwd` 存在或正确**。 ### 3. 必须保持的性质（逐条复验） - **fail-open 策略不变**：payload 判不了时**仍然放行**，stderr 上仍留 `PEAKS_CODE_GATE_UNDECIDABLE`。 - **六个族的成员不变**：`HARD_BLOCKED_PATH_FAMILIES` 与 `ALLOW_LISTED_PATH_PATTERNS` **零行改动**。 - **fast lane 仍然打开这些族**：租约是 `peaks-race-code` 时，`src/` 的编辑仍然**放行**。 - **门禁没有被削弱**：本次**多拒**了原先放行的（那正是逃逸），方向是**收紧**而不是放宽。 ### 4. 留下的东西（写清楚，免得看起来像漏了） - **落在项目之外的相对路径**仍按"拼写相对项目根"读 ⇒ **不会放宽**门禁：它会拒一个拼得像族、 而文件其实没落在那里的路径 —— **误拒只是碍事，误放才是漏洞**。 - **一个残留**：payload `cwd` 不可用**且**门禁进程不在工具调用的目录里时，路径会按错误的树解析， 项目内的文件**可能**被放行。**改动前同样放行**（它按项目根解析）⇒ **残留，不是回归**； 而门禁本来就不装在那个位置。**这个形状与 §2.13 的根 `dist/` 轴同源**：拿一个不属于自己的基准去解析。 - **任何 IDE 报的顶层 `cwd` 至今未实测**（PATH 上的 `claude.exe` 是个 546 KB 启动器，没有 payload 字符串；本机装的 `@anthropic-ai/claude-code` 二进制里读到的 hook-input 形状是**一次 grep 的转述**， QA **没能复现**它）⇒ 所以修复**不依赖**它，回退路径自己扛得住。 ### 5. QA 独立复核 **PASS**（8 条验收标准）。两轮 RD、两轮 QA：QA 第一轮 `return-to-rd`，给的两条缺陷都被独立复现过。 证据： - 与**改动前**的代码逐行对照 **72 组（action + reason）：0 处差异**； - 两套实现在 **29 种拼法上 29/29 一致**，**65 行族矩阵 65/65 都拒**； - **10 种拼法 0 分歧**（改动前 6 种分歧）； - **六种不可用的 `cwd` + 完全没有 `cwd`：全部拒**。 ## 4.1.15 — 2026-10-22（门禁剩下的三种写法也不再决定判定） **版本级别**：候选 **patch**（沿用常设规则"默认版本新增采用最小的版本位"）。本次是**纯修复**： 既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、 peaks-code 的 11 步工序与 Gate A–G **一字不改**。 上一版（4.1.14）诚实记录为"留待后续决定"的残留写法里，与本切片同类的三条 （**大小写变体** / **没解析的 `..`** / **项目嵌在 git 仓库里**），本次全部收口。 ### 1. 族名的大小写：比较时不区分大小写 - 六个族名全是小写，而 `SRC/foo.ts` 在**任何大小写不敏感的文件系统上**（Windows、默认的 macOS） **就是** `src/foo.ts`。按字面比较，等于**让写法决定判定**。 - 现在：**只在比较时**折叠大小写；给调用方的报错里仍然显示**工具实际请求的那个路径**（原样）。 - **代价（有意接受，写在这里以免看起来像疏漏）**：在**大小写敏感**的文件系统上， 一个仓库同时有 `src/` 和 `SRC/` 时，`SRC/` 也会被拒。 **误放是漏洞，误拒只是碍事** —— 判别的不对称被选在了这一边。 ### 2. 相对路径里没解析的 `..` - 现在：匹配之前把 `..` 解析掉，**基准是调用方指定的项目根**。这条基准不是猜的： IDE 以 `peaks code-gate --project "<项目目录>"` 调用门禁，而工具调用的工作目录**就是项目目录**。 - 解析后**逃出项目根**（`../../elsewhere/src/x.ts`）⇒ 目标在项目之外 ⇒ 不属于任何族 ⇒ **放行**， 与"项目根之外的绝对路径放行"是同一条规则。 - **代价**：基准选错会误拒邻近目录的文件；项目根是调用方与工具调用**唯一都认**的那个基准， 所以它被选作基准，并把这条取舍写进了代码注释。 ### 3. 项目嵌在 git 仓库里：族相对**调用方指定的项目根**比 - 此前 `resolveCanonicalProjectRoot` 把根提升到 **git 根**，于是族是相对 git 根比的： 绝对写法 `/app/src/x.ts` 落在 `app/` 下 → **不在 `src/` 里** → 放行； 而相对写法 `src/x.ts` → **被拒**。**同一个文件，两种写法，两个判定。** - 现在：**硬阻断族相对 `--project` 指名的项目根**比；**租约查找仍然用规范根** （会话和租约住在那里）—— 本次只改路径比对，没有顺手改租约查找。 ### 4. 三条必须保持的性质（逐条复验） - **fail-open 策略不变**：payload 判不了时**仍然放行**，只是 stderr 上仍留 `PEAKS_CODE_GATE_UNDECIDABLE`。 - **六个族的成员不变**：`HARD_BLOCKED_PATH_FAMILIES` 与 `ALLOW_LISTED_PATH_PATTERNS` **零行改动**。 - **fast lane 仍然打开这些族**：租约是 `peaks-race-code` 时，`src/` 的编辑仍然**放行**。 ### 5. `.sh` 兄弟脚本 它**没有项目根**（不收环境变量、没有参数），所以**不假装能判绝对路径** —— 这一条仍然如此。 它能做的两件同类的事做了：比较时折叠大小写、相对路径的 `..` 折叠。 它**仍然不**解析 driver —— 那会是同一个决定的第二个实现。 ### 6. QA 独立复核推翻了一个理由，并挖出一个洞 - ⚠️ **"两组模式不相交"是错的。** RD 报告说"大小写折叠同时作用于白名单是安全的"，理由是两组模式 不相交。QA 实测**推翻了它**：有 **12 种路径形态同时命中两组**（`.md` / `.peaks_` 是**后缀**模式， 族是**前缀**模式）。**结论仍然成立，但理由必须换成 QA 实测的那一个**：折叠让判定**恰好等于**它的 小写写法（84 条路径 0 例外），而每一个"新被放行"的路径，**它的小写写法在修之前就已被放行** ⇒ **折叠没有放进任何新文件**。 - ⚠️ **一个 RD 报告没有提到的洞**（QA 挖出来的；**既有问题，不是本次回归**）：当**工具调用的工作目录 不是项目根**时 —— 例如 cwd 是 `/src`、payload 是 `deep/x.ts` —— 这个路径其实指向 `/src/deep/x.ts`，**落在 `src/` 里、应当被拒**，而门禁**放行**了。 本切片写下的不变量是"判定只由文件落在哪个目录决定"，**这一条还没有完全成立**。 它的成因与 `..` 那一族同源：**相对路径的基准**。本切片选了"调用方指定的项目根"， 而这个洞是"**工具调用自己的工作目录**" —— 两者只在 cwd == 项目根时一致。 - **一个覆盖缺口**（不是缺陷）：套件钉住的是**词法**的 `..` 折叠，不是**基于根**的折叠 —— 换一种写法只红一次，而那种写法会放行一个"逃出去又绕回来"的 `..`。 **发出去的代码是更强的那一版**（基于根），所以这是覆盖缺口，不是缺陷。 - **一个数字不复现**：RD 报 `..` 那个变异"5 红"；QA 试了 **10 种**改法，得到 9/9/4/14/14/14/2/2/1/1， **没有一种得到 5**。**每一种都变红** ⇒ 结论成立，**数字不复现**。 ### 7. QA 的结论 **PASS，0 个缺陷，2 个 LOW 发现**；门禁**没有被削弱**（fail-open 不变、六个族成员零行改动、 fast lane 仍打开这些族）。全量 `pnpm test:unit`：**568 文件 / 6236 通过 / 3 skip / 0 失败**。 真实环境：5 个 tarball 装进**仓库之外**的全新目录、npm 自己的提升布局、没手工挪 ⇒ **装好的那个 CLI** 对三种残留写法全部 DENY，嵌套 git 仓库那一档也 DENY； 用**抽取出来的 pre-fix 源码**跑同一批路径，三种都 **allow** ⇒ 缺陷复现、修复闭合。 ## 4.1.14 — 2026-10-21（门禁按文件判而不是按写法判、发布包在任何 npm 布局下都能启动、门禁判不了时说得出来） **版本级别**: 未发布区间 `v4.1.13..HEAD` 共 **4 个 commit**（**3 fix / 1 docs**）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。本次是**纯修复**：既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、peaks-code 的 11 步工序与 Gate A–G **一字不改**。两处行为变化都是本次要修的：**硬阻断路径的绝对写法现在被拒**（原先放行），以及**判不了的 payload 从静默放行变成留下可见标记**。 ### 1. 门禁按文件判，不按写法判（`eeb02060`） - 门禁此前用**裸 `startsWith`** 把硬阻断族和 payload 里的路径对起来，**整条门禁路径上没有任何归一化**。 族是项目相对前缀（`src/` `tests/unit/` …），于是 `src/x.ts` **被拒**，而 `./src/x.ts` 和**同一个文件的绝对写法被放行** —— 同一处编辑，换个写法就过，**而且过的正是那个写法**。门禁自己的测试**只用过相对写法**，另两种从未被执行。 - 现在：项目根**以内**的绝对路径先变成项目相对形式再匹配，开头的 `./` 去掉，分隔符折成 `/`。 **项目根之外**的绝对路径保持绝对：这些族名的是**本项目**的目录，别的仓库是别的仓库的事， 而且**修之前所有绝对路径本来就放行**，所以这**不是放宽**。 - `..` 段**故意不解析**：相对路径是相对**工具调用自己的工作目录**的，门禁并不知道那个目录， 拿项目根去解析是猜。 - `.sh` 兄弟脚本只做**拼写层面**的折叠：它不收环境变量也没有参数，**没有项目根**，硬猜会变成误拦； 它仍然**不**解析 driver —— 那会是同一个决定的第二个实现。 ### 2. 发布包在任何 npm 布局下都能启动（`386ff9d9`） - `peaks-loop-shared` **只发布 `dist/**`**（里面没有 `skills/`），所以它**永远不可能**是"skills 在哪"的答案； 旧的查找靠向上找一个**同时有 `package.json` 和 `skills/`** 的目录。 ⇒ 只有当子包**嵌套在根包之下**时才找得到 —— 而那恰好是 npm **全局**安装的布局， 所以 `npm i -g peaks-loop` 一直好用；**本地**安装把子包**提升**到根包旁边，于是发布的 CLI **一 import 就死**： `Error: Unable to locate Peaks repository root from .../node_modules/peaks-loop-shared/dist`。 **README 只写了全局安装**，所以坏掉的正是没写的那条路。 - 现在：查找在**每一层**都多问一句"根包是不是**在我旁边**"，嵌套、提升、pnpm store 三种布局都覆盖； 根包根本不在盘上时，回落到**真源资产库**（`PEAKS_HOME` 或 `~/.peaks`）—— skills 的法定居所。 - 共享包只发布 `dist/**`，**不能** import 根包的脚本，所以那个环境变量名在**两处各写一遍**， 并在两处都记下了原因。 ### 3. 门禁判不了的时候，说得出话（`8060706e`） - payload 缺失或解析不了时门禁**仍然放行**，这是有意的：payload 送不到时**每次编辑都被拦**比放行更糟。 但那个放行**是静默的**，而它藏起来的失败恰是最贵的那种 —— 用管道喂 payload 的验收（有些 shell 根本不往进程转发 stdin）会**每个用例都过，却什么都没验**。 - 现在判不了的那一处在 **stderr 上留下 `PEAKS_CODE_GATE_UNDECIDABLE`**（PreToolUse 的 stderr 本来就喂给 LLM）， 并把"用**文件重定向**喂 payload"的配方一并写出来。 ### 4. 三个残留，**诚实记录**（不是本次的回归） QA 独立复核时把 pre-fix 的源码抽出来实际跑过，确认以下三种写法**修之前也放行**，所以不是本次引入的： | 残留 | 修前 | 修后 | 严重度 | |---|---|---|---| | `SRC/foo.ts` —— 族名的**大小写变体** | allow | allow | LOW | | `docs/../src/foo.ts` —— 相对路径里**没解析的 `..`** | allow | allow | LOW | | `.sh` 兄弟脚本 vs Node 命令（绝对硬阻断路径） | 都 allow | shell allow / node **deny** | MEDIUM | | 项目**嵌在 git 仓库里** —— 绝对写法按 git 根判 | allow | allow | MEDIUM | ⇒ **"拼写无关"这条不变量，只在「项目根就是 git 根」时成立。** 前两条与刚修的缺陷**同类** （大小写不敏感的文件系统上 `SRC/foo.ts` **就是** `src/foo.ts`）。判 LOW 的理由：这道门防的是 **误操作**，不是敌手。**留待后续决定是否再开一个 slice。** ### 5. 证据 - QA **独立复核**（不是采信 RD 的报告）：三个变异**自己重推**，结果与 RD 报的**完全一致** （归一化关掉 8 红 / 「根包在旁边」关掉 1 红 / 去掉两处 `reportUndecidable` 2 红）。 - 全量 `pnpm test:unit`：**565 文件 / 6204 通过 / 3 skip / exit 0，零失败**； `tsc` 0 错；`node .husky/peaks-gate.mjs repo` 绿且**每个上限未动**（两个 eslint 上限各**降** 1）。 - 真实环境：5 个打包好的 tarball 装进**仓库之外**的全新目录，**npm 自己的提升布局、没手工挪** ⇒ `peaks --version` 起得来；**pre-fix** 的查找在同一条路径上**复现**了 `Unable to locate Peaks repository root`。 - 拼写矩阵（**文件重定向**喂 payload，绝不走管道）：相对 / `./` / Windows 反斜杠 / `.\` / 绝对 —— **五种写法同一个判定，全部 deny**。 ## 4.1.13 — 2026-10-21（peaks-race-code 批量模式：一次门禁归因、scoped test 前置的修复阶段、上下文监控） **版本级别**: 未发布区间 `v4.1.12..HEAD` 共 **32 个 commit**（**10 feat / 11 fix / 11 docs**）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。本次是**纯追加**：新的 `peaks batch` 命令组、新的 `src/services/batch/**` 与 `src/services/lint/**` 模块；既有 CLI 参数、peaks-code 的 11 步工序、Gate A–G 与 transition 状态机**一字不改**。唯一触及既有共享路径的两处 —— `auto-compact-decision.ts` 的可选 `atPhaseBoundary`、`skill-context-verdict.ts` 的可选 `batch` 参数 —— **缺省时行为逐字不变**，对非批量用户无影响。 ### 1. 批量模式骨架与只读诊断（`d860b4cc`） - `decideBatchMode(itemCount)`：**一项 ⇒ 走今天的路**。批量机制（诊断 fan-out、规则预读、定档）存在的意义是把准备成本摊到多项上；用在一项上，它花掉的和省下的一样多，还改动了单任务路径的行为 —— 而那正是批量模式被禁止做的事。所以**一项读作 `single`**。 - 拓扑由**实测文件集**决定：波次规划器按**字符串全等**匹配文件，Windows 上 `src\a.ts` 与 `src/a.ts` 是两个不同文件 ⇒ 碰同一个文件的两项会看起来不相干、落进同一波、两个 agent 同时改一个文件。归一化在**喂进去之前**做（`normalizeFileSet`），规划器只做它那一件事。 - 诊断 prompt **复用共享的 dispatch 前缀**而不是手搓一份会漂移的副本，并且**禁止 Edit / Write / MultiEdit** —— 诊断 agent 报告的文件集是定档唯一的输入，一个边写边报的 agent 报的是猜测。 ### 2. 统一验证：门禁一次跑完，而且能归因（`7a495a3c` / `60a4f147`） - 门禁就是单任务 lane 跑的那一个，逐字相同：`['test','tsc','lint']`。批量模式把它**跑一次**而不是每项一次 ⇒ **严格程度一点没降**，变的只是次数。 - 红灯要能说清是哪一类坏：每项 scoped test 都绿 ⇒ `integration`（问题在项与项之间）；有项没绿 ⇒ `single-item`，并在 detail 里**点名是哪一项**。 - ⚠️ **构建产物缺失不是红灯**。`tsc -p tsconfig.json` 把子路径导出解析进未跟踪的 `packages/*/dist`，而 `pnpm test` **不会**触发 `pretest`（pnpm 10 默认不跑 pre/post 脚本）⇒ dist 缺失时 tsc 全是 TS2307/TS7016。这种形状现在是 **`blocked`**、归因 `unknown`、**不点名** —— 否则一个构建产物问题会被**伪造成某个无辜项的失败**。仓库自己的门禁早就这么处理（`.husky/gate/repo.mjs`）。 ### 3. 修复阶段：scoped test 是状态翻转的前置条件（`05d8077f`） - 修完一项 → **立刻**跑该项的 scoped test → 绿了才 `appendBatchItem(status:'fixed')`；红则状态留在 `diagnosed`，失败信息随结果回传。 - 这一步是第 2 节归因的**前提**：统一门禁只有知道每项自己那次的结果，才分得清"一项坏了"和"合在一起坏了"。**scoped test 不能攒到最后一起跑。** - 测试用**变异**证明这个顺序是承重的：把状态翻转移到 scoped test 之前 ⇒ 3 个测试变红（含专门盯顺序的那个）。 ### 4. 上下文监控（`c29bf911` / `6f9e4cdd` / `d00bd364`） - **报告落盘，窗口里只留 ≤2 KB 摘要**（结论 + 文件集 + 一行草图）。批量模式下 N 份报告一次性涌入是真实风险（实测 20 份 ≈ 60 KB ≈ 15K token），完整报告留在盘上，编排器按需再读。 - **阶段边界是最佳压缩点，不是推迟的理由**。既有的 in-flight 推迟会把压缩推到整个批次之后 —— 而那正是窗口最胀的时候（该推的先被推了）。到边界时（①→② / ③→④）压缩**现在就发生**。缺省 `atPhaseBoundary` 时行为逐字不变。 - **提醒只陈述事实，绝不把压缩甩给用户**：≤0.80 完全不说；≥0.80 之后**每个阶段边界说一次**，不是每轮说。 - 阶段推进只有**一个主人**（`batch-phase-advance.ts`），所以两个边界不可能各自漂移；边界那句话的措辞仍然只有**一个来源**（第 2 节的 `buildPhaseBoundaryNotice`）。 ### 5. 规范预读与 micro-cycle 的 lint 腿（`249cdf5c` / `1a259471`） - 生效规则有**三个来源**，缺一不可：项目自己的规则、OCR delegate 的规则、ECC 的规则。预读是**项目无关、语言无关**的 —— 识别 eslint / stylelint / golangci-lint / ruff / flake8 / gofmt / swiftlint，**没有语言分叉**；项目没声明 lint 工具时返回**显式理由**而不是假装有。 - 命名空间决定身份：`lint:silent-warning` 是 lint 步，`test:lint` 是测试（它跑的是 lint 配置的测试）。按**第一段命名空间**判断，才不会把"恰好碰到 lint 的测试"算成 lint 步。 ### 6. 进度落盘与用户可见表面（`7f2690b7` / `8240e6b6`） - 批量的阶段、条目、实测文件集落盘 ⇒ **一次压缩丢不掉它**，定档才有输入。 - `skills/peaks-race-code/SKILL.md` 加一节"批量模式"：什么时候进（≥2 项互不依赖）、四个阶段、诊断阶段**只读**、风险面**逐项**判定（命中就退出批量走单任务路）。风险面清单**不复制** —— 单一真源在 fast-lane norm。 ### 7. 两个只在共享路径上才暴露的缺陷（`60a4f147` / `ee5e48c2`） - 批量查询**曾经**把 `getSessionDir` 放在 `try` 之外 ⇒ session id 不是单段时抛出去，而它在**每一次** auto-compact 都会经过 ⇒ 压缩路径被批量代码搞崩。抓住它的是一个**本次功能之前就存在**的测试。 - 现在：不可用的 session id ⇒ "没有批次可列"（只读方不写，所以拒绝**查找**就是全部答案）；`resolveBatchCompactionBoundary` **永不抛** ⇒ 判断不出边界就当"不在边界"，压缩路径照旧。 - 教训进了项目记忆：**改了共享路径，就要去跑那条路径上既有的测试**；只跑"我改的那个目录"的 scoped 测试不够。 ### 8. 证据 - 全量 `pnpm test:unit`：**562 files / 6181 passed / 3 skipped**，exit 0。 - `tsc --noEmit` 0 error；`node .husky/peaks-gate.mjs repo` **exit 0，全部 ceiling 持平**（逐个比对未动，17 个上限一个没涨）；`peaks workflow verify-pipeline` `complete: true`；`no-ai-co-author-trailer` 红线测试通过。 - 其余 CI 各腿本地实测：silent-warning 门、workspace packages、vitest lint 配置、format / coverage ratchet、e2e、capability-guard 全绿。 - 十个切片都走 PRD → RD → QA；security / perf 审计由 CLI 出件，karpathy 复核 4 项全 pass。 - 棘轮基线刷新 7 次，每次都只刷新**因新增 in-scope 文件而陈旧**的普查记录，**没有一次抬高上限**。 ## 4.1.12 — 2026-10-20（macOS CI 红灯、frontend-only 正面证据制，与 Node 门槛声明修正） **版本级别**: 未发布区间 `v4.1.11..HEAD` 共 **5 个 commit**（**3 fix / 1 docs / 1 chore**）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。`ProjectArchetype` 新增 `cli` 取值、`ArchetypeReport.detected` 新增 `hasBin` 与 `frontendEvidence` 两个字段，均为**追加**；既有 archetype 取值、`frontendOnly` 的布尔语义与全部 CLI 参数不变，无破坏性变更。 ### 1. macOS CI 的唯一红灯来自 Q2 探针预算（`8e7a1cac`） - 4.1.11 的 CI 在 `macos-latest` 上只有一条失败：`orchestrator-can-do.test.ts` 的 Q2 探针。用例耗时 **5035 ms**，而探针的 `execFile` 预算是 **5000 ms**——超时被 `catch` 统一读成 `false`，于是"慢"变成了"sub-agent dispatch 不可用"。 - 同一次 CI 里，Q4 探针用 10000 ms 预算并通过；这就是对照证据。本次把 Q2 预算提为具名常量 `SUB_AGENT_PROBE_TIMEOUT_MS = 15_000`，Q4 也改为具名 `CONTEXT_RATIO_PROBE_TIMEOUT_MS = 10_000`（值未动）。 - 新增回归断言：**Q2 预算不得低于 Q4 预算**，失败信息点名被改小的常量。负向对照（把 Q2 改回 `5_000`）确实变红，断言不是同义反复。 - 断言放在新文件 `orchestrator-can-do-probe-budgets.test.ts`：`orchestrator-can-do.test.ts` 在 HEAD 已 564 行、超过 tests 的 500 行上限，staged size ratchet 拒绝增长。 ### 2. frontend-only 不再等于"没有后端"（`20062aa3`） - `decideFrontendOnly` 此前只有一条判据：`arctype === frontend-monorepo` 或 `!hasBackend && !hasSwaggerOrProto`。一个没有任何前端产物的 TypeScript CLI 因此被报成 `frontend-monorepo` + `frontendOnly: true`，并写进 project-scan 供 PRD/RD 读取。 - 现在要求**正面证据**（任一）：前端框架/运行时依赖；CSS 相关依赖；或 `src|app|pages|components|public` 下存在 `css|scss|sass|less|styl|html|htm|vue|svelte` 文件。目录遍历跳过 `node_modules|dist|build|out|coverage` 与点目录，并且**只认应用根**——本仓库 `examples/**` 与 `skills/**` 里的样式不计入。 - 新增 `cli` archetype：`bin` 非空 + 无后端 + 无前端证据。本仓库自扫现在是 `cli` / `false` / `archetype=cli`，monorepo 分支不再把它吞掉。 - 探测放在新模块 `src/services/scan/frontend-evidence.ts`：`archetype-detection.ts` 已 363 行、超过 src 的 300 行上限，闸门拒绝增长。 - 测试 fixture 里原本断言 `frontendOnly: true` 的用例都补上了真实证据；旧的 `no-backend-no-swagger` 期望被替换，而不是作为期望值保留。 ### 3. 证据标签与 bin 探针分支（`4c338be4`） - 文件证据的 reason 从 `css-under-` 改为 `asset-under-`：HTML 与 `.vue`/`.svelte` 此前被标成 CSS。 - 新增 `readRootBin` 的直接单测：manifest 缺失 / 非法 JSON / `bin: {}` → false；字符串 `bin` 与非空对象 → true。 ### 4. README 的 Node 门槛（`a6233fc4`） - 两个 README 的徽章从 `node ≥20` 改为 `≥24`。真实门槛由 `bin/node-floor.mjs` 的 `MIN_NODE_MAJOR = 24` 决定，`package.json#engines` 也已是 `>=24`；旧徽章会让 Node 20–23 的用户按错误的前提安装。 ### 5. 证据 - 全量 `pnpm test:unit`：**540 files / 5980 passed / 3 skipped**，exit 0（3 个 skip 为既有 `@slow` / `@replay` 标记）。首轮曾因新测试文件未进体积基线而红了两条 standards 测试（census 784 vs `shadow.measuredFiles` 783），重生成基线后转绿；`shadow` 783→784，17 个 ceiling 逐一比对未动。 - `tsc --noEmit` 0 error；`pnpm build` 成功且 `dist` 携带 4.1.12；`node .husky/peaks-gate.mjs repo` 全部 ceiling 持平；`peaks changeset check` 通过；`no-ai-co-author-trailer` 红线测试通过。 - 三个代码切片均走 PRD → RD → QA：security / perf 审计由 CLI 出件（全部 `pass`，0 violations），karpathy 复核 4 项全部 pass，`peaks workflow verify-pipeline` 三份均 `gateC=pass / gateH=pass`、0 violations。 - OCR 1.x 补充评审：直接调用在 60 s 预算处超时；改走无凭据的 delegation 路径（出包 → 宿主模型按包内规则审 → `ocr-delegate-record` 回录），抓到一条 LOW——正是第 3 节修掉的 `css-under-` 标签。ESLint 仍是主闸，全程 0 findings。 ## 4.1.11 — 2026-10-20（生产依赖升版、OCR 全语言路由，与 delegation 双阶段评审路径） **版本级别**: 未发布区间 `v4.1.10..HEAD` 共 **3 个 commit**（**2 feat / 1 refactor**）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。`peaks code-review run-ocr-18` 新增 `--languages auto|` 与 `--delegate` 两条路径、新增 `peaks code-review ocr-delegate-record` 一个动词，均是在既有 service 之上的新入口；既有的 `--language ` 单语言路径与 API 路径行为不变，无破坏性变更。 ### 1. 五个生产依赖升到各自大版本内最新（`194eccf5`） - `@alibaba-group/open-code-review` `^1.8.9` → `^1.13.1`；`@upstash/context7-mcp` `^4.0.2` → `^4.4.4`；`picomatch` `4.0.4` → `4.0.7`（保留精确 pin）；`yaml` `^2.9.0` → `^2.9.1`；`zod` `^4.4.3` → `^4.6.7`（根包与 `peaks-loop-mut` 同步）。 - `commander ^12.1.0`、`fzf ^0.5.2`、`@colbymchenry/codegraph 1.6.2` **经实测已是各自大版本内最新**，未改版本号——先量后改，而不是把所有条目都动一遍。 - `devDependencies` 全程未动，含被锁定的 `vitest 4.1.10`。锁文件里仍会解析出 `picomatch@4.0.4`，那是 vitest 自身钉死的传递依赖，不是漏升。 ### 2. OCR 桥的既有缺陷（`194eccf5`） 升级过程中量出该桥**从未真正工作过**：它把 `--filter-language` 传给一个在 1.8.9 与 1.13.1 中都不存在的参数，并按 `findings[]` 解析一个真实信封里没有的字段（真实为 `comments[]`，字段是 `path` / `content` / `start_line` / `end_line` / `severity` / `category`）。测试一直是绿的，因为测试 mock 了子进程、喂的是适配器自己编造的 payload。 - `OCR_18_PACKAGE` 同步到 `1.13.1`——只改 `package.json` 不会改变运行时，npx 取的是这个常量。 - argv 去掉不存在的参数，保留 `--format json` 与 git 范围参数；解析改为读真实 `comments[]`，severity 映射扩展到 `critical/high/medium/low`。 - 语言路由改为**评审后按扩展名过滤**，并在代码里写明：评审仍覆盖整个 diff，被限定的是上报结果，而不是 LLM 被要求查看的范围。 ### 3. 全语言覆盖与自动识别（`e905f8eb`） - 语言表**以上游自身的 `supported_file_types.json` 与 `rule_docs` 为准**内置，57 语言 / 97 扩展名；有漂移测试盯着内置副本与路由表，语言缺路由会直接红。 - `--languages auto` 从 git 范围识别语言，**一次 OCR 调用**产出按语言分组的 findings——Python+Go 的改动此前要跑两次同样的全量评审。范围里没有可路由语言时**完全不启动**（实测 128ms、零 spawn），而不是花一次调用去发现无事可做。 - 四种结果保持可区分：有发现 / 零发现 / 格式不受支持（`unsupportedFiles`）/ OCR 不可用（`state`）；测试断言的是"干净但空"与"没跑成"**不相等**，不是两个不同的名字。 - `.mts` / `.cts` 不路由：上游 1.13.1 的白名单确实没有它们，`--preview` 报 `unsupported_ext`——已实测量并记录，不是遗漏。 - peaks-rd Gate B3 在 diff 命中任一语言时调用该步骤；TS/JS 双轨，ESLint 仍为主闸、OCR 为辅，每条 finding 标注来源工具。调用方传入的 ref 若以 `-` 开头在边界处即被拒，避免选项注入。 ### 4. Delegation 成为真正的评审路径（`7dc79de1`） - 此前 `ocr-18-delegate-preview` 拿**评审解析器**去解析一个**文件清单**，从未产出过 finding。现在拆成两阶段：CLI 产出评审包（选中的文件与其 pattern、被排除的文件、按组解析后的规则文本、git 范围、成本面），宿主 agent 用自己的模型审，再由 `ocr-delegate-record` 校验并记录。 - **不需要任何 API key，不写 `~/.opencodereview`**。评审发生在会话本身的模型上。 - 记录下来的 finding 带 `attribution: ocr-delegate`，宿主模型的结论不会继承 OCR 的 benchmark 背书。 - **"没跑"与"干净"是两个文件而非两个名字**：包是 `state: awaiting-envelope` + `findings: null`，完成的评审是另一份带 `findings: []` 的文档；不存在任何一份文档能同时读成两者。 - 信封按不可信输入处理：逐字段类型校验，未知 severity 拒绝而非降级为 `info`，格式错误指名条目下标而非跳过；包路径限制在项目根内。 - 该路径在实现过程中被**真实跑通并用于审查自身**：出包 → 宿主模型按包内规则审 → 回录，抓到一个真实缺陷（`findings !== null` 的判断与自身报错语义相反），修复后重跑一致。 ### 5. 证据 - 全量 `pnpm test:unit`：**538 files / 5967 passed / 3 skipped**，exit 0（3 个 skip 为既有 `@slow` / `@replay` 标记）。 - 作用域运行：`tests/unit/services/lint/` + `tests/unit/cli/commands/` 58 files / 597 passed；树型层（`standards` + `lint` + 根）60 files / 616 passed。 - `tsc --noEmit`、`pnpm build`、`node .husky/peaks-gate.mjs repo` 全绿；构建后工作树保持干净（已提交的生成物与源码一致）；`peaks changeset check` 通过；`no-ai-co-author-trailer` 7/7。 - 三个 slice 均 `verify-pipeline complete: true`、0 个失败 gate；security / perf 审计各自出件（delegation slice 两门均为 `pass`）；karpathy 复核共 7 条发现全部关闭。 - 未执行且如实记录：OCR 自身的付费 `ocr review` 路径从未真正跑过——delegation 落地后它不再是必需路径。 ## 4.1.10 — 2026-10-20（STRAT→TACT→MUT 生产者链，canonical digest 递归修复） **版本级别**: 未发布区间 `v4.1.9..HEAD` 共 **3 个 commit**（**1 feat / 1 fix / 1 docs**）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。CLI 新增 `peaks strat` / `peaks tact` 两个动词组，均为既有 service 的薄包装；无破坏性变更（canonical digest 的值变了，但只影响修复前产生的临时 artifact）。 ### 1. STRAT → TACT → MUT 生产者链（`45b378e9`，backlog §16 / §9.2） - `peaks strat write`：写 strategy.md + `.json`，生成 STRAT.sig。 - `peaks tact write`：校验 strategy JSON 的递归 sha256 与 markdown 的 `STRAT.sig:` 行，注册 STRAT.sig，跑 AST gate，写 impl.json（`inputSig` = STRAT.sig）。 - `peaks tact read`：重新校验 impl.json 并输出 `{ sha256, inputSig, changedFiles, astGateResult }`——文档里长期缺失的命令现在真实存在。 - 单轴写入守卫（`--session-id` 必填、`--out` 必须在 `.peaks/_runtime//` 下）、`--changed-files` 项目内包含校验、AST 违规/篡改 artifact 的命名 refusal。 - 端到端测试：`strat write → tact write → tact read → mut`，`mut-report.json#inputSig` 等于 TACT.sig，并覆盖 passing-threshold 分支。 ### 2. Canonical digest 递归修复（`45b378e9`） - 旧实现 `JSON.stringify(rest, Object.keys(rest).sort())` 是数组 replacer，会在每一层过滤 key，导致嵌套对象（`astGateResult` 等）被哈希成 `{}`；伪造嵌套 verdict 仍能通过验证。 - 现在逐层排序 key，verifier 对**解析前原始 JSON**求哈希，`StrategyOutput` / `ImplOutput` 及嵌套 schema 均为 `.strict()`。嵌套字段、数组项、未知字段的篡改全部拒绝。 - 注：digest 是 checksum 不是 MAC；同时改内容并重算签名的 artifact 仍会通过（H8 固有）。 ### 3. Backlog 与测试稳定性（`442c0e96`、`77a38b82`） - §2.38 关闭：`peaks job add-slice` 已存在并追加 ledger。 - §9.50 关闭：AC-6 的 macOS gate 已在 CI 中通过。 - 全量 pre-push 暴露并修复：`tact read` 注册后的 invocation-check 夹具，以及 rule-D 对 `requireSessionAxis` 守卫的识别（补 `isUnsafePathInput`）。 ### 4. 证据 - 531 files / 5798 tests 在 pre-push 全量套件中通过；`tsc --noEmit`、`pnpm build`、repo/staged gate 全绿。 - code review（两轮，HIGH 已修）PASS-WITH-FINDINGS；Karpathy pass；security `warn`（1 LOW，词法单轴 symlink）；perf `warn`（1 LOW，AST gate 双跑）；QA PASS（AC1–AC9）；`verify-pipeline complete: true`。 ## 4.1.9 — 2026-10-19（Step 0.8 gate：remedy 豁免、provisional 决策与 exit code 可见性） **版本级别**: 未发布区间 `v4.1.8..HEAD` 共 **6 个 commit**（**2 fix / 1 style / 3 docs**）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。无破坏性 CLI 变更。 ### 1. Step 0.8 gate 不再阻塞自己的 remedy（`ec106774`，backlog §17.1 (1)+(2)） - `peaks code gate-step-08` 在 `--prompt` 缺省时读取 PreToolUse hook 的 stdin JSON，识别真实的 `peaks code detect-job` 调用并以 `allow-remedy-command` 放行。解析刻意收窄：分隔符、引号/注释/heredoc 提及、反引号与 `$(` 仍然关闭；豁免不写 `job-shape.json`。 - `peaks code detect-job --is-job false` 的 `--suggested-job-id` 变为可选，默认 `single-task`；`--is-job true` 仍必填，显式 id 仍优先。 ### 2. Ledger 必有决策，gate 必报 exit code（`d08cf12f`，backlog §17.1 (3)+(4)） - `peaks job init` 创建 ledger 后，若 session 没有 `job-shape.json`，写入一条 provisional 决策（`isJob: true`、job id、请求的 strategy、`confidence: medium`，rationale 标注 provisional）。已有决策只读不覆盖；不可读文件以 `invalid-existing` 上报并给出带 `--force` 的 remedy；写失败同样显式上报。 - 打印的 provisional remedy 被集成测试逐字执行，保证它不是一条会失败的命令。 - `gate-step-08` 的两条 block 路径现在在 JSON envelope 中携带 `exitCode: 2`，并在 stderr 中明确写出 `exit 2`。 ### 3. 证据与测试 - 两个切片合计：单测 38 项、集成 38 项；`tsc --noEmit`、`pnpm build`、repo/staged gate 全绿。 - code review 对第二个切片曾给出 BLOCK（`runJobInit` 超 50 行），修复后 PASS-WITH-FINDINGS；Karpathy review 两个切片均为 pass（各经过一轮修复：`$(`/反引号与 `--force` remedy）；security audit `warn`（仅 LOW，均是已知的 §16 单段路径缺口与非逃逸面）；perf audit pass。 - CI run `39253585358`（`c7947285`）全绿后才发版。 ### 4. 残留（非阻塞，已记录） - 窄解析的 fail-closed 情形、2s stdin timeout 无自动化测试、schema 不接受的 job id、跨 job 的 `suggestedJobId` 保留、`isJob:false` + 新 ledger 不拒绝、并发 `JOB_SHAPE_ALREADY_DECIDED` 分支未测、PowerShell native exit 2→1 映射。 ## 4.1.8 — 2026-10-19（24h backlog 清扫：25 个切片，棱镜与证据链收紧，测试判定重新成为代码属性） **版本级别**: 未发布区间 `v4.1.7..HEAD` 共 **57 个 commit**（**5 feat / 14 fix / 2 refactor / 3 test / 1 ci / 31 docs / 1 memory**）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。本版**无破坏性 CLI 变更**；有两处刻意的行为收紧（`config` 请求的 security review 现在按 rid 分文件；reviewer 的 `schemaPath` 缺失会在 provider 调用前拒绝），升级路径均已覆盖。 ### 1. 证据链与前置条件（`4f15ccaf`、`3ad4aef4`、`bd559bc4`、`2468133e`、`fbb98dc9`） - **缺失与存在但不合法被区分**：前置条件检查现在返回 `absent` / `body` 两种 kind，`LINT_GATE_FAILED` 点名具体 artifact 与行号，不再让"文件不存在"和"文件在但内容不合规"共用一句报错。 - **`- type:` / `- state:` 在作者时校验**：角色感知的取值校验，缺失 `- state:` 行也会被 lint 抓住；`request init` 写出裸 token，`feature (…)` 这类括注不再能通过。 - **`getSessionDir` 真正执行单段契约**：`a/b` 不再被当作合法 session id，34 个调用点不受影响。 - **`rd/security-review.md` / `rd/third-party-review.md` 按 rid 分文件**：两个切片在同一次会话中不再互相覆盖；裸路径保留为 back-compat legacy 层。 ### 2. Third-party reviewer（`64238afa`、`bedfb7af`、`e5f839cb`） - `skip` 不再伪装成 `passed: true`；`peaks reviewer config` 有完整的 flag 驱动面，`status` 区分未配置 / provider 不足 / 已配置。 - `THIRD_PARTY_REVIEW` 解析 `rd/third-party-review-.md`；producer 在第一次 `mkdir` 前用 `REQUEST_ID_PATTERN` 校验 rid；commit-leg 接受清单按 declared 路径键控，并接受该行自己的 legacy 层作为同 `until` 的别名——v4.1.7 播种的旧清单不会被升级打断。 - `distinctFromKarpathy` 两侧都把 `skipped`/空视为"无可比 family"；`schemaPath` 变为真正读取项：绝对路径 → 项目副本 → 包内副本，全部缺失时在调用 provider 前以 `SCHEMA_MISSING` 拒绝并列出所有候选，`status` 报告获胜路径与来源。 ### 3. Lint 与策略（`f4809134`、`6b733390`、`cd3f5637`） - eslint 的 dot-directory 不再静默跳过；`peaks lint --config` 与 `lint baseline --baseline-file` 的读/写路径一致；空作用域有显式 `EMPTY_SCOPE` 而非静默零。baseline 只减不增的棘轮保持，三个切片期间曾两次拒绝上涨。 ### 4. Dispatch / job（`8fec96be`、`ad3a72a2`、`aee3532d`） - `--isolation container` 恢复真实退出码与 JSON envelope（`child.unref()` 推迟到 `close`）。 - `job subagent-cleanup` 只在真正收尾了 ledger 行时报告 `cleaned:true`。 - `--from-dag` 校验每个节点的 role。 ### 5. Release 与模板（`59867889`、`41073d7a`） - `readReleaseState` 对未知 stage 失败关闭。 - QA 模板在 `openspec/changes/` 缺失时渲染 `- N/A — …`，不再把无法填写的 `` 段交给 QA 再因未填而拒绝；目录存在时保持原文。 ### 6. 测试判定成为代码属性（`b6174b8c`） - **daemon spawn lock 的真实 bug**：`writeFileSync({flag:'wx'})` 是先建后写，并发读者把零字节 body 当 stale，删除活锁后各自起一个 daemon。现在"年轻且不可读"视为持有，回收是原子 quarantine rename + moved-body + own-create 校验，还原用 `COPYFILE_EXCL`，release 不删不属于自己的年轻锁。 - 六个负载敏感测试：四个按文件超时、walker 只排除自己的临时 fixture 树、`staged-size-leg` 的判定改为 `judgeChangeSet`（非空但全在策略外的变更集与干净树同义），并带 synthetic 输入与 throwing control——回退修复在干净 checkout 上也会变红。 ### 7. CI（`ec477874`） - `ci.yml` 的七个 job 全部设置 `timeout-minutes`（20–60），不再继承 GitHub 的 360 分钟默认。 ### 8. 文档与记忆（`df379817`、`83373f67`、`15ba24bd`、`92b17867`、`664de2b5`） - `docs/superpowers/**` 的历史计划文档显式豁免引用完整性；`.peaks/memory/` 的 36 个指针类 / 47 处机械修复（skill 迁移、mut 包抽取、`integration/` 缩写）。 - security-audit SKILL 写明 `--judged` 循环的终止条件（先冻结 `src/`、审计最后、修复后只重跑一次、其余记为 accepted residual）。 - backlog 增加 `## Decision record — 2026-10-19`：meta 层保持冻结、体积债只维持 ratchet、integration 不进入默认配置、覆盖率地板等首个全绿 CI、中文 README 为权威；其余残余逐条写明接受理由。 ## 4.1.7 — 2026-10-18（提交腿硬门、契约表派生、过期债棘轮，以及 canonical store 与 IDE skill 树的漂移检查） **版本级别**: 未发布区间 `v4.1.6..HEAD` 共 **5 个 commit**（**1 feat / 2 refactor / 1 chore / 1 docs**）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。 ### 1. `backCompatUntil` 在提交腿真正关闭（`0cfc25c0`） `prerequisite-checks.ts` 早就算出 `expiredWindow` 并把它写进软 warning，但没有任何边界把它变成失败；到 4.1.6 为止，`mut/mut-report.json` 与 `rd/third-party-review.md` 已在声明窗口之后约二十个 minor 仍然软通过。现在 `peaks workflow verify-pipeline` 在"过期 + 缺 artifact + 无当前接受"时返回 `complete:false`；`peaks request transition` 仍保持软 warning。接受清单在 `.peaks/lint/backcompat-expired-acceptance.json`，每条带 reason 与 `reviewBy`（上限 installed + 2 minor）；`initWorkspace` 幂等播种，`reviewBy` 在播种时推导；缺失清单 fail-closed，doctor 以 `error` 报告。路径解析抽到 leaf 模块，transition 与 commit gate 共用。 ### 2. `rdGatesForType` 从契约表派生（`98f5ed60`） 三个手写的请求类型列表（`bugfix`、`!docs/chore/config`、`feature|refactor|bugfix|config`）被一张 `RD_EVIDENCE_GATES` 表和 `contractEvidencePaths` 取代；重复的 `RD_EVIDENCE_PROBE` 映射删除，`pipeline-verify-gate-support.ts` 净减 75 行。六种类型的 gate 列表逐项不变，由表驱动测试钉住；一个 lookup seam 与两个 binding 用例证明生产函数确实走契约，而不是另一份列表。 ### 3. 过期 grace 标记的只减不增棘轮（`f02c6be6`） 129 个 `grace: 1 minor release (v2.14.0)` 标记分布在 83 个已跟踪的 `src/**` 文件里，宽限期早已过去而没有机制执行。新增 `expired-grace-ratchet.test.ts` + `_expired-grace-scan.ts`，以 `git ls-files` 为人口、以 `.peaks/lint/expired-grace-baseline.json` 为基线：新未登记标记、计数变化或陈旧条目都会变红。控制臂与两次真实控制（删一条基线、加一条假条目）都按预期失败。**129 个 catch 没有逐个改写**——棘轮记录债务并禁止增长。 ### 4. canonical store 与 IDE skill 树的漂移检查（`f1525621`） 新增只读 doctor 检查 `skills:reference-parity`：比较 `$PEAKS_HOME`（或 `~/.peaks`）下的 canonical skill store 与每个已存在的 IDE skill 根，点名"一侧有、另一侧没有"的文件，并提示 **"Ask the LLM to run `peaks skill sync`"**。junction 比较相等；realpath visited set 防 symlink 环；store 不可读时报告 warning。schema 增加加法式 `skills:::` id 形状。顺带修复 `peaks skill doctor` 忽略 `severity` 的问题：warning 现在只展示，不再把 exit code 置 1。 ### 5. backlog 重测（`2e6fd7e9`） §14.5 的 `--rid` 穿越在 HEAD 上已由 request-id 校验拒绝，重测记录在案；§14.8 关闭；新增 §16 记录本轮两个切片与两个 `backCompatUntil` 软门。 ### 用户可见行为 - `peaks workflow verify-pipeline` 新增一个提交腿硬失败；`peaks request transition` 保持软。 - `peaks doctor` 新增 `skills:reference-parity` 检查。 - `peaks skill doctor` 的 warning 不再导致 exit 1。 - 无破坏性变更；4.1.6 的行为除上述三点外保持不变。 ## 4.1.6 — 2026-10-18（三类闸规则收紧：配置路径的 reader、skip 允许列表、声明类型；两个 refactor 切片被自己新增的规则抓住） **版本级别**: 未发布区间 `v4.1.5..HEAD` 共 **38 个 commit**（**2 feat / 11 fix / 3 refactor / 7 chore / 8 docs / 4 test+style**）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。**本版含两处用户可见的行为收紧**，按 4.1.5 的先例明写：声明为 `docs`/`chore`/`config` 的请求不能再携带产品源码；`config` 不再能通过 skip 记录跳过它的 QA 阶段。 ### 1. 声明类型第一次被改动内容佐证（`f7de7828`） 前置表由 rid 的**声明类型**选择，而没有任何东西检查类型与 diff 是否一致——一个标成 `chore` 的请求可以改运行时代码并通过提交闸。现在 `docs`/`chore`/`config` 的请求若触及 `src/**` 或 `packages//src/**`，会在 `rd:implemented`、`rd:qa-handoff` 和 `rd:handed-off` 被拒绝；工具链路径（`scripts/`、`tests/`、`.husky/`、配置、lockfile）不受影响。规则与 file-size 棘轮**共用一次 git 枚举**（`-z` + `--relative`），非 ASCII 路径不能借 C-quote 逃过 `src/` 判定。**原建议"把 `checkTypeSanity` 接到提交腿"被测量否决**：它对 `chore` 只与纯 lockfile 一致，会拒掉本仓库自己的基础设施切片；提交腿也没有 rid↔commit 绑定。 **这个切片被它自己的规则抓住了**：它声明 `chore` 却改 `src/`，于是重定向为 `refactor`，走完 handoff / code review / security / perf / QA 的完整证据链，而不是给自己开豁免。perf 在 `qa-handoff`/`handed-off` 记了一个 `block`（+2 次 git spawn，约 126 ms 一次性），为关闭"`implemented` 之后再加 `src/` 变更"的窗口而**显式豁免并记录**。 ### 2. skip 允许列表从 QA-free 类型派生（`98614528`） `SKIPPABLE_TYPES` 此前是手写列表 `['docs','config','chore']`，而 `typeRequiresQaPhase('config')` 为 **true**——一条本地 skip 记录可以跳过 config 本来要求的 `SECURITY_REVIEW` 与 `TEST_REPORT`。现在 `QA_FREE_TYPES = VALID_REQUEST_TYPES.filter(t => !typeRequiresQaPhase(t))`，允许列表就是它（今天 `docs` + `chore`），`config` 退出。读路径还拒绝写入侧不可能产生的记录：空 reason、空/未 trim/含控制字符的 gate 名（C0/DEL/C1）、控制字符字段；坏记录读成 `null`，闸照常执行。署名行改成 **"record says applied by …"**——它是自述，不是证明。 ### 3. 配置路径的 reader 不再在复合 diff 里消失（`43f3cc51`） 分类器只看映射决定网：一个不映射到任何测试的路径既不触发全量回退，也不扩大子集。`.gitignore + src/` 因此会跳过读根 `.gitignore` 的 `tests/unit/workspace/top-level-change-id-guard.test.ts`——用线上分类器扫全部 2246 个非空提交，**9 个提交就是这个复合形状**。落地的是一条**声明映射**（`.gitignore`、`pnpm-workspace.yaml`）+ `/^\.gitattributes$/` 全量触发器（它没有根 reader，记下的映射指向的测试只把键写在注释里）。arm 要求一行非注释代码同时命名键、带读/join 调用、绑定 `REPO_ROOT`、且不带写调用；红控包括注释-only、临时根读取、写操作和缺失的 reader。 ### 4. 两个"把崩溃/竞态读成通过"的修复（`988c6197`、`1cba9312`） - **format 棘轮把 prettier 崩溃读成干净树**：`typeof '' === 'string'` 让 exit 1 + 空 stdout 返回 `''`，腿打印 `0 unformatted file(s)` + held。现在只有 prettier **确实列出**了文件才返回列表。 - **树扫描器在文件消失时杀死整个测试文件**：`ENOENT` 发生在枚举与读取之间，而扫描在模块作用域运行，失败是 `(0 tests)`。现在只容忍 `ENOENT`，并报告 `listed/read/vanished`，缺口可见而不是被吞掉。 ### 5. 其余已落地 - **A–F sweep 的闸改进**：`.github/` 与 `.husky/` 成为全量触发器（`af8f8053`）；`GATE_GUARD_SUITES` 的根层按规则并入每个子集（`27a85b7f`）；`src/` 的每一段都映射到 `tests/unit/`，130 个孤儿测试降到 6 个且逐个记录（`7fa29669`）；类型表决定 QA 相位（`d62eda51`）。 - **CI 与门禁**：覆盖率地板成为 CI 可执行的棘轮（`87b76fa3`）；coverage 地板测量它记录的人口（`b1c5c89e`）；一个要求 100% 且无人调用的门被移除（`888fb3e9`）。 - **CLI**：`peaks scan best-practice` 可以真正查阅文档（`195f573b`）；VM isolation 表面（从未运行）被移除（`0172d89f`）；路径守卫判断目录本身而不是调用者的拼写（`82c6f384`）。 ### 已知残余（记录，不粉饰） - ③c 的反向不可发现性（未在映射中的 reader）、tooling 路径的误标、skip 记录 provenance 不可验证。 - 13 个 A–F 的 RD 工件停在 `implemented`——**grandfathered**；现在回溯关闭会触发 ③c。 - ③c 的 perf `block` 已显式豁免；③b 的安全/文档 LOW 已记录。 - 4 个 workspace 包随根版本各 +1 patch（internal-runtime 0.0.46、mut 0.1.60、shared 0.0.95、shared-channel 0.0.63），`CLI_VERSION` 与 `RUNTIME_VERSION` 由 `scripts/sync-version.mjs` 同步。 ## 4.1.5 — 2026-10-14 (快车道从设计走到落地并带来一个新命令族；代码门与提交禁令第一次真的会拒绝；提交边界补齐三道门；派发提示第一次被自己的 CLI 校验；artifact 按 rid 落盘，两条切片停止互相覆写) **版本级别**: 未发布区间 `v4.1.4..HEAD` 共 **125 个 commit**（**13 feat / 37 fix / 2 refactor / 5 chore / 3 test / 3 style** / 其余 62 docs+memory）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。 **此处必须如实记一笔，与 4.1.3 面对 `peaks mcp` 时是同一情形**：本版**确实新增了命令族**——`peaks race`（`pilot-status` 只读判定与 `pilot-gate record` 唯一写入者两个动词，`src/cli/commands/race-commands.ts`）与 `request retag`（`src/cli/commands/request-retag-command.ts`）。按严格语义化版本，新增用户可见命令应当取 **minor**。取 patch 是常设规则的默认，不是"没有新增命令"。4 个 workspace 包各 +1 patch（internal-runtime 0.0.44→**0.0.45**、mut 0.1.58→**0.1.59**、shared 0.0.93→**0.0.94**、shared-channel 0.0.61→**0.0.62**），`CLI_VERSION` 与 `RUNTIME_VERSION` 由 `scripts/sync-version.mjs` 同步。 ### 1. 快车道：从一份设计到一条真能开门的路径 `peaks-race-code` 是本版的核心新能力。它的设计先被写死、再被对抗性评审推翻重写过一次（`9da13bc0` 的设计记录、`304e4e2e` 评审后的重写、`8d3f2896` 拆成四个 slice），落地时 `9bad2be1` 把它交付为 `peaks-code` 的**兄弟**而不是模式——它去掉的正是让 peaks-code 开独立上下文窗口的那条红线：在这个车道里，编排的窗口同时就是改源码的窗口。技能树因此从 22 走到 **23**（14 个顶层 + 9 个 bee 级，`tests/unit/ide/` 的三条计数断言随之更新）。门槛只有一个事实：为会话解析出的 driver 读到 `peaks-race-code`，而这个事实是**自报的**，文档自己也这么说。 **但代码门此前在这条路径上是死的，这是本版最该被读到的一段。** `401b44f7` 之前 `peaks code-gate` 按 `tool` / `input` 读工具调用，而真实的 PreToolUse 投递的是 `tool_name` / `tool_input`；工具名到达时是 `undefined`，而 `decideGateAction` 的第一个判断放行任何不叫 Edit / Write / MultiEdit 的名字——**在读路径之前**，于是它对每一次调用都返回 allow。修法在命令层归一化顶层载荷，接受两种拼写（与既有 shell sibling `pre-tool-code-gate.sh` 一致），`GateInput` 与 `decideGateAction` 不动。 **这是一次会到达每一个既有安装的行为变更，故明写**：注册了 code-gate 条目的仓库会从"这门从不拒绝"变成"按路径族拒绝"——对 `src/`、`tests/unit/`、`tests/integration/`、`config/`、`bin/`、`scripts/` 的直接 Edit / Write / MultiEdit 会被 `PEAKS_CODE_PROHIBITED_DIRECT_EDIT` 拒绝，除非解析出的 driver 是快车道。用户没有理由预期这件事，因为这条条目**从未拒绝过一次调用**，它的第一次拒绝会是一次普通的 `src/**` 编辑。 放行必须精确。`adff480b` 只认**精确匹配** `peaks-race-code`，无前缀匹配也不做大小写折叠，于是一个未来的 `peaks-race-` 兄弟不会继承源码编辑权——顺带把这条钉死的是 `938b92a1`：唯一的负例 `peaks-code` 在 `startsWith('peaks-race')`、大小写折叠、`trim`/`contains` 三种放宽下**全都仍然通过**，所以四条新负例各对一种放宽。`f5612cde` 从 hook payload 读 caller identity（`caller_id`，回退 `session_id`），把 lease 查询**限定在该 caller**，再交给 `decideGateAction` 的第三个参数。 **提交禁令（AI 署名红线）有三处只存在于代码里的事实。** 它只有一个调用点，且只在 `peaks hook handle` 下运行——即 trae / cursor / codex；Claude Code、hermes 与 openclaw 拿到的是 `gate enforce`，其中**不含**禁令。它此前能被任意字符串解除：`79b20add` 证实任何带 `session_id: "anything"` 的载荷都会让一个本该被拒的提交通过，因为判别说的是"载荷里有没有非空字符串"而不是"那个字符串有没有指到一个 lease"；`a8f94c89` 证实什么都没解析出来时，`if (skill !== null)` 会让整条禁令跳过自己。`023235e2` 补上最后一块：`callerId` 过滤器一直有效，但**没有任何生产调用点传它**，于是"谁在驱动"由 `readdirSync` 第一个产出回答——一个没有 peaks 技能的会话的 `git commit` 会被另一个窗口的 peaks-code lease 禁掉。而 `0c08be62` 让 driver 解析器与 statusline 读者对同一份 lease 集合给出同一答案（按 `lastHeartbeat` 再按 `startedAt` 的共享 comparator）；此前它取 `readdirSync` 的第一个，在 Windows 上就是文件名顺序。 ### 2. gate 2 从"没有阈值"变成有策略的判定；车道相位搬进一个有语法的载体 `peaks-race-code` 的 pilot 信任门原先有四个可数量、零个阈值，于是"pilot 清关了吗"无法可复现地回答。`21304696` 补上 `src/services/race/gate2-policy.ts`、`gate2-evaluator.ts`、`pilot-gate-store.ts` 与两个动词：`peaks race pilot-status`（只读判定，fail 时 exit 1）与 `peaks race pilot-gate record`（唯一写入者，幂等 upsert）。策略 `race-gate2-policy-v1` 有七条阈值，其中 `taskCount >= 10` 取 rule-of-three（十次干净跑把失败率上界锁在约 26%）；安全臂计入**全部**记录（含 escalated）而 `taskCount` 只计 landed，这条不对称是刻意的。覆盖面是**推导出来的**，永不自报：`filesChanged × HARD_BLOCKED_PATH_FAMILIES`（从 `src/services/hooks/pre-tool-code-gate.ts` import），或安全臂谓词。判定永远从策略常量重算，**从不**读 `.peaks/race/pilot-gate.json` 自己的 policy 块——否则削弱那个块就能洗白这道门。用五条真实的 2026-10-11 trace 播种，得到 `insufficient-evidence` 与两个缺口：**task 4 < 10、session 1 < 2**（core 3 与 safetyArm 1 达标）。 **车道相位从 markdown 搬进一个有语法的载体。** 相位此前是 `skills/peaks-audit/SKILL.md` 里的一句话加一个 HTML 注释标记；markdown 是自由文本，于是每一条"必须长得像 X"的守卫都能被一个人类仍读作相位声明的拼写变体绕开——**五轮修复产生了五种逃逸**（一行两个 token、一行两个 `phase=`、多一个空格、少一个空格、tab、NBSP、大写、缺前缀），没有一轮是最后一轮，而守卫已到 500 行帽的 495 行。`3b95e00a` 把它搬到 `.peaks/race/lane-phase.json`（`{ "phase": "name-only" }`），`src/services/race/lane-phase.ts` 是唯一读者：严格的 Zod 对象、恰好两个值的 enum、以及一个带标签的结果（ok / missing / invalid），**missing 拒绝而不是取默认**。**第一版没有做到这件事，记录如此**：JSON 的键可以用 unicode 转义书写，而 `JSON.parse` 会把转义解析回键名 `phase`，于是一个首条声明被转义的文件返回 ok 并采用**第二个**值——原始文本读者看到的是一个相位，守卫解析出的是另一个，而一条非法的首条声明被静默丢弃。修法是拒绝任何反斜杠。QA 对八条验收判据全部 PASS，含 80+ 条对抗输入（键与值里的 unicode 转义、任何位置的重复键、三个位置的 BOM、NUL、孤立代理、CRLF、NEL、一个 4 MB 的填充对象、载体路径上放目录与符号链接，以及为数组 / 字符串 / 数字 / null 的 root）。 `76830652` 把车道问题放到**每一次 peaks 工作流的入口**：一个以"端到端做这个"表述的诉求直达 peaks-code，所以住在 dispatcher 里的问题永远不会被问到。问题落在 peaks-audit 的契约处（任何 peaks-* 工作流的第一步），每个请求问一次；快车道是 pre-pilot，所以在 pilot 清关前它**只在用户点名时**可达。 ### 3. 提交边界上新增的三道门 CI 结构性地看不到这三样东西：artifact 住在 `.peaks/_runtime/`，那是 gitignored，所以**本地提交是它们唯一可见的边界**。 **artifact 契约在提交处被强制执行（`4a5d74b4`）。** 本仓此前对同一份工作有三种做法，按"artifact 的 state 值对该 role 是否合法"衡量：完整状态机（2026-09-10）、混合——33 条规范 state 行加 6 条手写、CLI 会拒绝的名字（2026-10-09）、以及完全没有（2026-10-11，零条 state 行）。**绕过的形式是模仿，不是拒绝。** 检查器早就存在（`peaks workflow verify-pipeline` 在 2026-10-11 那次会话上正确报 `complete:false / gateC:fail`），**只是没有任何东西运行它**。新增 `.husky/peaks-gate-pipeline.mjs`（pre-commit 腿）与 `.husky/pipeline/contract-verdict.mjs`（纯判定路径：无 fs、无 spawn、无时钟）。豁免是 `PEAKS_SKIP_PIPELINE_VERIFY=1` 且**大声**：它逐条列出跳过的 rid、说明读过的范围、并声明环境变量在 git 历史里不留痕——不像 `--allow-incomplete`，它的理由留在 artifact 里。**跑不起来的检查器一律拒绝**：一条崩溃的检查器不是"没有违规"。rid 枚举改按 **artifact** 键控而不是按 `rid-` 前缀，两个方向的错误在真实会话上量过：2026-10-11 是 8→4，2026-10-10 是 0→18。文件里也写明它**不是**完全强制：这条腿放行 `MUT_REPORT`，而它的 artifact 在这个构建里没有生产者。 **这条腿会验证一个有工作的会话，而不是它被绑定到的那个（`f9091db3`）。** 此前它解析 ACTIVE 会话并枚举该会话的 rid 载体；当 active 会话是新的、而工作属于另一个会话时，枚举为空，这条腿便以"no rid to verify … Nothing was refused"放行——那句话是真的，而检查从未运行。实测：job backlog-9x-drain 的最后一条切片从会话 `…-3cb9bc` 提交，而它全部六个 rid 载体住在 `…-2f9323` 下。**显然的修法（绑定会话为空而兄弟非空时拒绝）被量过后否决**：11 个会话目录里 6 个零 rid 载体，其中三个是当天建立的，拒绝会挡住那六个会话的每一次 docs / chore / memory 提交。落地的形状是验证**正确**的那个会话，而不是拒绝。`15def424` 收掉它留下的三条：平局判定从 `>=` 改成 `carrier mtime → session id` 的全序 `better()`（QA 把三个兄弟的所有六种排列都跑过，修复后收敛到**一个**目标，HEAD 下有**三个**）；不可读的兄弟从静默丢弃改为**被点名**（审计者量到：40 棵指向这条路径的树里，HEAD 在 15 棵上打印 "0 NOT verified" 而确实丢了一个会话）；注释里那串"87 + 47 + 19 + 18 + 14 rids"被删掉——它们是 request **文件**计数，真实枚举是 6 个载体会话上的 65 个 rid。 **staged 与 worktree 的分歧被抓住（`23d5de3d`）。** `git commit` 交付的是 INDEX，而本仓每一个测试、门和评审读的都是 WORKING TREE。两者分歧时"被验证的字节"和"被提交的字节"不是同一份，而没有东西说出来——一个会话里真实触发过两次：一轮修复编辑了受tracked 文件却没重新 `git add`，于是 STAGED 侧是修复前的弱守卫（22 例 / 16004 B）而 worktree 是 28 / 24168 B。比较**经过 git 的 filter**：staged 侧是 index blob，worktree 侧是 `git hash-object`。第一版直接比原始字节，在 `core.autocrlf=true`（本仓如此）下会把 git 判定为同步的文件拒绝，而且打印出的补救（`git add`）是可证明的空操作——**这是提交门唯一绝不能有的结局：它教人用 `--no-verify`**。不可比较的路径（gitlink、符号链接、未合并、不可读）一律拒绝。 **提交路径开始量 staged 文件尺寸（`8caa1901`）。** 在此之前 `node .husky/peaks-gate.mjs staged ` 对任何文件都打印 `NOTHING WAS COMPARED (staged) … every one of them is OUTSIDE the lint scope` 并 **exit 0**——337 行的测试文件和 600 行的一样，而 `peaks scan file-size` 与 transition 路径会拒绝同一个文件并给出 delta。新腿挂在门的 `all` scope 上而不是 lint-scoped 的 `files` 上，因为 `tests/**` 在 LINT scope 之外、却在 file-size 政策之内——挂在 `files` 上的腿会漏掉缺陷正是在其上被量到的那个文件；它跑在 empty-change-set 分支**之前**，因为那个分支正是本缺陷的签名。`scripts/lint/file-size-delta.ts` 调用 `scanFileSize`，与 `peaks scan file-size` 用的是**同一个**实现，新模块自己不含任何阈值、也没有"长大了"这个概念。**只有增长被拒绝**：已经超帽但没长大的文件保持绿，创建是另一个分支。 ### 4. 既有的几条判据被改成会失败 **尺寸判定按 delta 而不是绝对值（`435445dd`）。** `rd -> implemented` 的尺寸门扫描 `getChangedFiles` 并拒绝**任何**超帽的改动文件，而基线把 `fileSizeOverCap` **78** 当作可接受量棘轮着——同一个机制一边容忍 78 个超帽文件，一边不许任何切片碰其中一个。连续复现两次；第二次一个 767 行的文件因为改了 **2 行描述**被拒，两次会话都退回了 `--allow-incomplete`——那正是 artifact 契约存在来让它多余的旁路。状态机也开始强制它自己描述的顺序：`rd: draft -> handed-off` 此前能通过，而 `implemented` 与 `qa-handoff` 都被拒，于是一条切片可以越过每一道中间门宣称自己已交付。 **软通过的前提被真的报出来（`3059ac27`）。** 门为每一个缺失文件的 backCompat 前提构造一个 `warnings` 数组且不动 `missing`，于是 `ok` 保持 true——而调用方只在它自己的 `throw` 里读 `prerequisiteResult.warnings`。那个词在文件里只出现一次，就在那一行，所以成功路径上这个数组被构造、填满、一帧之后丢弃：一个软通过了两条前提的 transition 因此报 `warnings: []`，读者会断定每一条前提都通过了。实测：`data.prerequisiteWarnings: undefined` 与 `envelope.warnings: []` 变成了 **2 和 2**。顺带修掉一处"不会失败的门"——警告码是硬编码的字面量、指着 mut-report，却为**每一条** backCompat 前提发出，于是 third-party-review 前提被报在 mut-report 的码下面，而任何按那个码过滤 MUT_REPORT 问题的东西都会一并匹配到它。 **eslint 的行改成说出它们容忍什么（`d3684dbc`）。** `eslintFindings` 是一个**计数**的上界，而计数的上界意味着没有任何单条 finding 能迫使行动：ESM `require()` 家族的 16 个 error 级站点一直被报出来，却落在一个 1727 的计数里——约等于零。行现在是"包含 + 按量不增长"，建立在 census 既有的 per-file map 上：1270 个文件里 478 个容忍 finding、792 个为零，artifact 精确复现 ceiling（**行之和 = 1727 findings / 573 errors**）。**提交路径调用同一条规则**，于是新实例在贡献者遇到它的地方**按名字**变红： ``` count form: eslint findings (derived) 1 (ceiling 1) -> green, silent table form: src/tidy.ts went from 0 to 1 lint finding(s) (+1) -> exit 1 ``` 一条关键情形也成立：对受容忍文件的**无关改动**在提交路径上保持绿——因为会拦住无辜提交的门正是教人用 `--no-verify` 的那一扇。这个切片交了六条 finding，最该记的一条是它自己赖以成立的理由**是假的，且来自编排者**：声称 eslint-disable 注释点名的 `no-var-requires` "在 ESLint v8 里不存在"，实测 `@typescript-eslint/eslint-plugin` **8.66.0 定义了它**（`deprecatedSince` 8.0.0，`replacedBy` `no-require-imports`），而一条被弃用的规则**仍然会报**。真缺陷是"被抑制的规则"和"在报的规则"**不匹配**——一个更有意思的失败，被那个更弱的故事挤掉了。 **把每一个 `require()` 扫出源码，并防止它回来（`c3fe88b7`）。** 本仓每个 `package.json` 都声明 `"type": "module"`，所以 `require` 在运行时不存在。十六处分布在十四个文件里：十五处躲在函数体里当"惰性" require，只在各自的冷路径上抛；一处（`scripts/fix-dispatcher.js`）在顶层，让那个文件无法加载。**没有任何东西能在模式上失败，这正是它累积起来的原因**：tsc 接受 ESM 文件里的 require；没有测试走过那些路径；四处带着 `eslint-disable-next-line @typescript-eslint/no-var-requires`——一条**没有启用**的规则，而真正的拼写 `no-require-imports` 本来就在那些站点上报错，于是这些指令什么都没抑制。实测 before → after：`peaks loop run` 在干净会话上 `RUN_FAILED "require is not defined"` → exit 0 `RUN_OK`；`peaks security-audit run` 不带 `globalThis` shim 从 exit 1、只留一个 `.tmp` → exit 0、`.md` 落盘。新守卫 `tests/unit/standards/no-esm-require-mixing.test.ts` 目标为零、无 allowlist，其判别性对照是一个被转换文件**逐字的前修内容**——一条不可能失败的对照不是对照。 **一个名字可以给一行做键，不能判定一行（`e8e916e6`）。** 同一缺陷类的三个活实例，每一个都由测量而非检视确立：`pilot-gate-store` 拒绝任何不以 `rid-` 开头的 rid，而 `.peaks/_runtime/*/rd/requests/` 下 97 个不同 id 里有 **58 个**没有前缀——守卫在拒绝本仓实际铸造的多数 id；`type-sanity-service` 用 `/\b(?:tests?|…)\b/` 判断"这是不是测试文件"，而词边界可以被 `-` 满足，于是 `src/services/test-cache/test-cache-service.ts` 被判成测试（在 `git ls-files` 上重测：3064 条 tracked 路径，**恰好 29 条判定改变**，全部单向——18 条变 `source`、11 条变 `unknown`）；`context/collector` 把 `relative(root, full)`——在 win32 上以 `\` 分隔——喂给一个测试 `/__tests__/` 的分类器，于是那个分支在它被写成的平台上**永远不可能匹配**，而规范化的值就在四行之上已经算好了。 ### 5. 派发：提示词第一次被自己的 CLI 校验 编排者手写一份共享 brief 交给一个 campaign 里的每个子代理，**没有任何东西校验它**，而它在一次会话里三次携带关于本仓 CLI 自身的假陈述：一个错 flag、一条范围错误的必需项、一条挂在错 artifact 上的必需项。三条都是子代理读 artifact 时发现的，**没有一条是门发现的**——这是工作流里唯一没有测试读过的 artifact。 `9894eab0` 加了检查器：从提示里抽出 `peaks …` 调用，对**注册的命令树**解析，报出被解析出的命令或它的祖先没有声明的 flag。解析来自 CLI 自己，永不来自一份名单。它**警告而不拒绝**，决定的数字是真实语料上的假阳性计数：本会话 **147 条派发记录、1772 次调用、176 条未声明 flag**，其中**恰好一条**是假阳性——一份正确的 brief 在一个记录该缺陷的表格里**引用了**那条错误命令。`--rid` 是整个语料里唯一的未声明 flag：147 次出现在被注入的一行上，29 次出现在手写的一行上——**第二组是真的，这正是本片的意义**。审查者给的二次输入关闭了一个真缺陷：一次每匹配都走到文末的扫描在 `composeDispatchPrompt` 里对一份 3.5 MB 提示耗时 **109.9 s**，按 run 上限定界后同一输入是 **98.6 ms**。 `f9ecb6fd` 把被注入的那一行修对：`L1_WORKTREE_GOVERNANCE_BLOCK` 里的两条 worktree 命令**都跑不起来**——`peaks worktree auth grant --rid … --reason … --ttl <5m>` 三处都错（没有 `--rid` 这个 flag，它是可选的 `--request-id`；必需的 `--operation` 被省略；`--ttl` 的单位是毫秒，`<5m>` 不是合法值形式），逐一逐字运行两者都答 `error: required option … not specified`。修完的守卫是重点：第一版只查 flag 是否存在、必需项是否出现、拼写是否声明过——评审证明它**看不见它刚刚移除的缺陷**：把 `--ttl 5m` 重新加回全部五个表面，它 8/8 全绿，而 CLI 接受那一行并写下一份 **5 毫秒** TTL 的 grant。它现在是逐次出现的形状走查，把每个选项对回注册声明，断言块里点名的字面值是声明 enum 的成员，并把未被消费的 token 当作游离操作数。 `b7056cdb` 让生产者知道它将被按什么评判：前提表靠字面量字符串判定 artifact 是否存在，而派发提示从不点名它们——于是做了工作的生产者被一个它从未被展示过的谓词拒绝，唯一出路是事后编辑别人的证据。实测：四个有真实内容、判定正确、证据可量的 artifact 因四条违规被拒，**每一条都是缺失的字面标题而非缺失的事实**。块从表里**生成**，永不从表里**转录**：改表会移动这个块，移除 surfacing 会让套件点名那个缺失的标记而变红。 ### 6. artifact 按 rid 落盘，两条切片停止互相覆写 一个会话里两条同类型切片写同一个路径，第二条覆写第一条，**而两条 transition 都通过**——第二条切片被另一份 diff 的审查判定，artifact 和门里都没有任何东西说出来。本版把三类 artifact 改成按 rid： - `BUG_ANALYSIS`（`6a394084`）：`rd/bug-analysis.md` → 带 `` 占位符，`legacyRelativePath` 兜底，磁盘上已有的会话继续解析；`AUDIT_SECURITY` / `AUDIT_PERF` / `KARPATHY_REVIEW` 早已是这个形状。磁盘上实测：三个会话 95 份 request artifact 里，**每个会话恰好一份** `bug-analysis.md`。后果是**观察到的而不是推断的**：一个在修显然是 bugfix 的 RD 报称自己选了 `refactor`，因为那个文件"已经装着另一条切片的分析"——而声明一个自己不是的类型会选中**另一张**前提表，于是结构性碰撞转化为一条静默更轻的门。把表项回退，13 个用例里 9 个变红。 - `SECURITY_REVIEW`（`47863518`）：`rd/security-review.md` 是同一碰撞里**硬且静默**的那个实例，它不声明 `mustContain`。七处读者分布于五个服务，八份 `skills/**` 文档一并跟过来。两轮 QA 修复各有产出：第一轮证伪了一条证据表断言（`workflow-gates-and-types.md:109` 不在 diff 里却仍然断言那个性质），第二轮证伪了清扫自己的完备性断言——模式以 artifact **名字**和 token "rid" 为键，而真正要紧的 `v2-12-fanout-collapse.md:12/:15` 把 `audit/security.md` 与 `audit/perf.md` 当作当前的写目标呈现，其中 `rid` 出现 **0 次**。所以第二轮不再清扫，而是落地 `tests/unit/services/artifacts/legacy-path-doc-contract.test.ts`：从前提表**推导**被降级的词干（七个名字，没有喂给扫描的字面名单），它的红跑取在真实的修复前文本上，1 failed / 15 passed，恰好点名那三处。 - `final-review` 消费的 rid 作用域证据路径（`ebb07c61`）：门接受的 artifact 路径**其消费者从不读**——`peaks prepare-final-review` 从 `rd/code-review.md`、`rd/security-review.md` 拼装证据，而 transition 门与写侧统一在 `rd/code-review-.md` 与 `audit/security-.md`；写对了 rid 作用域路径的切片，其 no-new-bugs 维度仍然回到 `inconclusive`，评审报 `rd-code-review` ENOENT。 `0da35578` 把一条**写了却没人读**的声明变成会被读：`backCompatUntil` 落在两行前提上（`mut/mut-report.json` 在 v2.14.0、`rd/third-party-review.md` 在 v2.15.0）而没有任何东西读它，安装版本是 4.1.4，于是两个窗口都过期了约二十个 minor release，没有任何用户可见的输出把它们与按时的窗口区分开。软通过警告现在带一个附加的 `expiredWindow` 字段，拒绝打印机与成功打印机都渲染它。实测一次真实的 `rd -> qa-handoff`：两条软通过分别报 `v2.15.0 (installed 4.1.4)` 与 `v2.14.0 (installed 4.1.4)`，各带一句 "past expiry"。**它只观察**：一条 OPEN 窗口和一条**早于**窗口的构建都渲染不出这个从句，缺失前提仍然给 `ok: true`，`path`/`code`/`message` 逐字节不变。 `21016bbf` 让一条切片**声明它判定了什么**，而检查读那份声明（backlog 9.9 的第四次尝试）：三次尝试都被建起来又撤回，因为此前没有机器可读的"这条切片动了什么"，每个机制只能去**推断**，而每一种推断在本仓日常生成的输入上都是错的——从 git 状态推断会让干净树上的审计永久空转，从散文 `## Red-line scope` 解析会拒掉 15 份真实请求里的 14 份。现在 `security-audit run --judged ` 记录每条路径的内容哈希，`rd:qa-handoff` 重新哈希它们并拒绝，点名 artifact 与第一条移动的路径。 ### 7. 其余修复 - **`peaks workspace init` 把本仓自己的开发 hook 注册进下游项目（`09f8d043`）。** 模板用 `bash "${CLAUDE_PROJECT_DIR}/src/services/hooks/