peaks-loop 4.0.54 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 4.1.0 — 2026-10-03 (strict-remediation 战役收口: 门禁第一次开始看自己、判据换成"哪些代码是产品"、以及一次把自己推翻的探针)
+
+**版本级别**: 未发布区间 `v4.0.54..HEAD` 共 **167 个 commit**（49 refactor / 42 docs / 35 fix / 8 feat / 6 test / 15 chore / 1 style）。取 **minor** 而不是继续 patch，理由是这区间有**新增的用户可见 CLI 表面**（`peaks job add-slice`）以及若干会改变用户所见的修复（cron 超时、`pnpm lint` 的口径、空测试集从"绿"变"红"）；`^4.0.54` 的下游仍能匹配到本版。
+
+### 1. `peaks job` 不再自相矛盾（§2.38，本版本唯一"新增命令"）
+
+三条都是先在临时仓库里**跑出来**再修的：(a) `init` 之后没有任何办法给已有 job 追加 slice，`checkpoint` 回 `SLICE_NOT_FOUND`，于是"一片一片发现的 wave"只能谎报账本或一片开一个 job；(b) `checkpoint --commit-sha` 原先**只校验长度 ≥7**，一个 `git cat-file` 判定"不是有效对象"的 `c6de09a9` 被接受并写成 `lastCommitSha`；(c) `progress` 的 `currentSlice` 是 `slice-<done+1>` **合成出来的 id**，所以工具自己建议下一步、又自己拒绝那一步——第三条是第一条的成因。现在：`peaks job add-slice --slice-label` 幂等（重复 label 报知且 `state.json` 字节不变、空 label 拒绝）；sha 必须可解析才写入，拒绝时引用 git 原话且账本一字节不动；`describeNextSlice` 成为 `#N of M` 的**唯一**出口（原先三处各自算），并把"全部完成"从 `Next: slice #3 of 2 (no slice pending)` 改成 `no further slice is registered — add one with: peaks job add-slice …`，实测该分支下 `slice #` 出现 **0 次**。附带撤回 backlog 自己原先写的"checkpoint 应该记录未知 slice 而不是拒绝"——拒绝未声明的 id 正是账本唯一的防线。
+
+### 2. cron 的三处名实不符（用户可见行为）
+
+`EXEC_TIMEOUT_MS` 在名字叫"五分钟"的地方是**五小时**；超时不再收割任务子进程（孤儿活在大门之后）；daemon 与 run-once 两个写者对 `lastRunAt` 各有各的规则。现在同一 killed 规则覆盖两条路径，killed 记录带得出 killed 标记与非空 stderr，普通失败给不出这个形状。
+
+### 3. 假绿被系统性关掉（三处）
+
+包内测试集为空从"通过"变成"失败"并补上 CI 步骤；`emit` 检查改为**递归**，嵌套 emit 不能再不吭声地消失；stamp 写入改为原子，且守卫不再为自己验证不了的东西背书；build-integrity 的包集合与 gate 对齐（不一致就拒），空 stamp 记录直接拒。
+
+### 4. `pnpm lint` 与门禁终于量同一个集合
+
+原先 `peaks lint` 报的是 1259 而 `peaks-gate.mjs repo` 量 1298（少 80 条 finding 却仍打印"全部守住"）——因为 gate 里那份扩展名/目录正则是规则的**第二份写法**、没有任何测试观察它。现在只有一个列表、一处过滤，两边由 parity 测试互相钉住；`.peaks/lint/baseline.json` 也修成可移植路径，**waiver 真的在豁免**（此前它按绝对路径匹配，等于静默不豁免）。
+
+### 5. 判据换掉：严格检查属于"产品代码"，出界部分只测不闸
+
+owner 明确「只需要对 `src` 与 `packages/*/src` 这些目录下的文件做 eslint 严格检查、tscheck、prettier」，取代原先"四个目录"的口径。被排除的 552→575 个文件（`tests/`、`scripts/`、包内非 `src`）**不是删掉的债**——`eslintFindings 638`、`fileSizeExcessLines 13557` 仍每次测量并打印，只是不设 ceiling；`shadow` 块承担这笔账，并在上升时主动播报（实测今天连报 `638 → 639 → 641 → 648`，而受闸一侧同期 `2130 → 2128`）。配套把 `--rescope` 的触发条件从"数值变了"改成**"边界文本变了，或有文件离开了范围"**——纯长大免 flag 并打印 `scope grew: 950 -> 952 (7 entered, 0 left the scope)`，因为总体变大只会让计数上升，而任何上升都照旧被 `RAISED` 拒绝：**松的是仪式，不是 ratchet**。
+
+### 6. 门禁第一次开始看自己
+
+`.husky/` 原先不在任何行数口径里（`peaks-gate.mjs` 1019 行、3.3× 它自己 enforced 的 cap，而它贡献 0）。现在它有**自己的两行**且全程未动主口径（`fileSizeOverCap` 始终 162→126），四个 slice 把 gate 目录从 **4 文件 / 1,701 超实行降到 33+ 文件 / 0**；799 行的生成器与 1,019 行的入口都被拆开，每一次拆分都带**等价手臂**（拆分前后逐行多重集守恒 + 对 `git show` 钉 sha 的行为对照），因为"重构看起来没动"不等于"证明没动"。`silent-warning` 成为最后一条自择总体的腿，收口后它和其余腿共用同一份跟踪列表——顺带数出**17 处此前没有任何 ceiling 见过的静默吞异常**（16 处集中在 `packages/peaks-loop-mut/src/services/agent/ecc-cache-service.ts`，该文件同时欠 537 行）。
+
+### 7. 一条被自己的探针推翻的结论（保留为记录，不删）
+
+本版曾断言"全局 `npm i -g` 会静默跳过 `install-skills`，用户装到 CLI 却拿不到 skills"。一个 `mkprobe` 探针包（`postinstall` 写 marker 文件）在 **npm 11.19.0** 上两次都**执行了**脚本——该版本的 `install-scripts` 警告是告知性的，`ignore-scripts` 为 `false`；而"skills 目录 45 项未变"正是 `install-skills` **按内容 hash 幂等**的成功样子。教训写进 backlog §2.52a：**no-op 和 skip 给出同一份证据**，"工具 X 不肯做 Y"这种结论，先花一秒把 X 跑一遍。仍然成立的两点：npm 自己说这些脚本"尚未被覆盖"、翻默认在即（二手报道指 v12，本次未能取到一手来源），届时 `--allow-scripts=peaks-loop` 是唯一防线，故两版 README 的安装段落现在写明；以及本仓 `.npmrc` 携 pnpm 的 `onlyBuiltDependencies`（外加一个连字符重复项），npm 每次调用都报未知并声明下个大版本失效——**pnpm 侧有一条放行、npm 侧为空**。
+
+### 验证
+
+`gate repo` exit 0（943→952 文件、hooks 行 0/0）、`tsc -p tsconfig.json --noEmit` 0、`pnpm test:unit` **379 文件 / 3,915 passed / 3 skipped**、`npm run build` 0（`build-integrity: OK`，`dist-stamp: 907 source file(s)`）。战役过程与全部自我推翻记录在 `.peaks/docs/backlog.md` §2.25–§2.52a、`.peaks/docs/lint-gate.md` §4n–§4z。
+
 ## 4.0.54 — 2026-09-18 (Phase A 缺陷闭合十片: 9 片真改 + 3 次修复推翻自己 + 4.0.53 宣称闭合的 AC 里 2 个被证伪 — AC-6 是假 pin、AC-1 是空 pin)
 
 **Highlights**:

package/README-en.md

@@ -49,6 +49,21 @@ peaks-loop is a **Loop Engineering crystallization system**, not a workflow tool
 npm i -g peaks-loop
 ```
 
+> **On npm 11+, pass one flag.** npm prints an `install-scripts` warning for lifecycle scripts that are not
+> covered by its allowlist. **At the current version (npm 11.19) the scripts still run**, so the install works
+> as-is — but npm says that default is about to flip. To avoid silently ending up with "a CLI, no skills", write
+> it out fully:
+>
+> ```bash
+> npm i -g --allow-scripts=peaks-loop peaks-loop
+> ```
+>
+> If you suspect the skills did not land, **no CLI command reports that state today**
+> (`peaks skill search` queries the in-package skill pool, which says nothing about your IDE directory), so
+> look at the directory itself: `ls ~/.claude/skills | grep '^peaks-' | head` (or the IDE dir you actually
+> use). Empty means the CLI installed but the skills did not — the gap is recorded in
+> `.peaks/docs/backlog.md` §2.52a.
+
 Then, in the **Claude Code** or **Z Code** chat you already use, send an **explicit slash command** (the leading slash is what triggers peaks-loop — a plain sentence won't always route here):
 
 ```
@@ -140,7 +155,7 @@ Every lane opens with **one slash command**.
 
 | | |
 | --- | --- |
-| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.54 (2026-09-18) |
+| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.1.0 (2026-10-03) |
 | **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test` · `peaks-slice-decompose`) |
 | **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
 | **Test suite** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · **0 timeouts** · 14 BDD caller-binding edge cases |

package/README.md

@@ -49,6 +49,20 @@ peaks-loop 是一个 **Loop Engineering 结晶系统**,不是工作流工具 —
 npm i -g peaks-loop
 ```
 
+> **npm 11+ 请带一个 flag**:安装时 npm 会对"未经 allowlist 覆盖"的 install 脚本打一条 `install-scripts` 警告。**当前版本(npm 11.19)仍然会执行**这些脚本,所以装完就能用;但 npm 已明说这个默认值即将翻成"默认不执行"。为了不在那一天静默装到一个"有 CLI、没有 skills"的状态,请写全:
+>
+> ```bash
+> npm i -g --allow-scripts=peaks-loop peaks-loop
+> ```
+>
+> 装好后如果怀疑 skills 没落上,**目前没有一条 CLI 命令报告这个状态**(`peaks skill search` 查的是包内技能池,与 IDE 目录里装了没装无关),所以只能看目录本身:
+>
+> ```bash
+> ls ~/.claude/skills | grep '^peaks-' | head    # 或你实际在用的 IDE 目录
+> ```
+>
+> 空目录 = skills 没装上(CLI 本身仍可用)。这个"报告不出自己装了没装"的缺口记在 `.peaks/docs/backlog.md` §2.52a。
+
 装好之后,在你已经用的 **Claude Code** 或 **Z Code** 对话框里发一条**显式命令**(必须以斜杠开头,才会触发 peaks-loop):
 
 ```
@@ -140,7 +154,7 @@ npm i -g peaks-loop
 
 | | |
 | --- | --- |
-| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.54(2026-09-18) |
+| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.1.0(2026-10-03) |
 | **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测 / `peaks-slice-decompose` 切片) |
 | **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
 | **测试套件** | 1096 cases · 4 packages (peaks-loop 1015 / runtime 39 / mut 22 / shared-channel 20) · **CI 首次全绿**(ubuntu + windows) · 14 BDD caller-binding coverage |

package/config/eslint/.peaks-rules.cjs

@@ -36,7 +36,20 @@ module.exports = {
   parserOptions: {
     ecmaVersion: 2022,
     sourceType: 'module',
-    project: ['./tsconfig.json', './tsconfig.build.json'],
+    // 2026-09-19 rid-s1-lint-config-coverage: the root tsconfig.json includes
+    // only src/** and tests/**, so every file under scripts/** and
+    // packages/** belonged to NO project and eslint failed 71 of them with
+    // "The file was not found in any of the provided project(s)" BEFORE
+    // parsing them. That is not a lint result — it is a hole, and it also
+    // masked real syntax errors (a .mjs with a broken string literal was found
+    // by prettier only, because eslint never reached the parser). The
+    // ESLint-only project below covers those directories without changing what
+    // `tsc -p tsconfig.json` sees.
+    project: [
+      './tsconfig.json',
+      './tsconfig.build.json',
+      './config/eslint/tsconfig.lint.json'
+    ],
     // 2026-08-06 lint-dogfood cycle-3 follow-up: the runner now uses
     // `node node_modules/eslint/bin/eslint.js` from the repo root, so
     // tsconfigRootDir must be the repo root (one level above config/).
@@ -52,16 +65,34 @@ module.exports = {
     'plugin:@typescript-eslint/recommended-type-checked'
   ],
   settings: {},
+  // 2026-09-19 rid-s1-lint-config-coverage: every pattern here used to be a
+  // bare trailing-slash name. ESLint reads those the way .gitignore does — a
+  // trailing slash with no inner slash matches a directory of that name at ANY
+  // depth — so `'skills/'` also swallowed `src/services/skills/`, `src/skills/`
+  // and two test directories: 33 tracked files, production source among them,
+  // silently reported as "0 findings" without ever being parsed. A LEADING
+  // slash anchors a pattern to the config's base path (the repo root), which
+  // is what these were always meant to mean: the repo-root prose / artifact /
+  // tooling directories.
+  //
+  // A leading slash alone is not enough for generated output, though: a
+  // per-package `dist/`, `coverage/` or `node_modules/` must still stay out of
+  // a directory walk, so those three are kept at any depth explicitly.
+  // `**/node_modules/` in particular must be spelled out, not left to
+  // eslint's own default ignore of `/**/node_modules/*`: a config that sets
+  // `ignorePatterns` REPLACES that default rather than adding to it.
   ignorePatterns: [
-    'node_modules/',
-    'dist/',
-    'coverage/',
-    'output-styles/',
-    'skills/',
-    'agents/',
-    'bin/',
-    'scratch/',
-    'examples/'
+    '/dist/',
+    '/coverage/',
+    '/output-styles/',
+    '/skills/',
+    '/agents/',
+    '/bin/',
+    '/scratch/',
+    '/examples/',
+    '**/dist/',
+    '**/coverage/',
+    '**/node_modules/'
   ],
   rules: {
     // L1 (eslint built-in) — always on, no plugin package required.
@@ -113,9 +144,28 @@ module.exports = {
       { prefer: 'type-imports' }
     ],
     '@typescript-eslint/no-non-null-assertion': 'warn',
-    '@typescript-eslint/no-implicit-any': 'warn',
+    // 2026-09-19 rid-s1-lint-config-coverage: `@typescript-eslint/no-implicit-any`
+    // was REMOVED here, not renamed. It does not exist in
+    // @typescript-eslint/eslint-plugin@8.66.0 (134 rules; verified against the
+    // shipped plugin's rule index) — typescript-eslint dropped it in v6 — and
+    // eslint answered every parsed file with 2 severity-2
+    // "Definition for rule ... was not found" messages, 2390 across the repo.
+    // Besides inflating the count, that made "a NEW file must be lint- and
+    // commit-able" unsatisfiable, since no new file could avoid those two.
+    // Its intent is already covered twice over, so nothing needs to replace it:
+    //   - tsc: this repo builds with `strict: true` (root tsconfig.json), which
+    //     turns on noImplicitAny at the compiler level;
+    //   - eslint: `plugin:@typescript-eslint/recommended-type-checked` above
+    //     already enables the implicit-any surface (`no-unsafe-assignment`,
+    //     `-argument`, `-call`, `-member-access`, `-return`, …) plus
+    //     `no-explicit-any`, which is re-declared as `warn` just above.
     // G-lint-1 §二 enum → as const: warn-only (escape hatch preserved).
-    '@typescript-eslint/no-restricted-syntax': [
+    // NOTE: this must stay the CORE `no-restricted-syntax`. The selector below
+    // is an ESLint-core selector, and core is where the rule lives —
+    // `@typescript-eslint/no-restricted-syntax` does not exist in
+    // @typescript-eslint/eslint-plugin@8.66.0 and produced the same phantom
+    // "Definition for rule ... was not found" on every file.
+    'no-restricted-syntax': [
       'warn',
       {
         selector: 'TSEnumDeclaration',
@@ -127,7 +177,42 @@ module.exports = {
     // Use ESLint built-in `no-duplicate-imports` — `@typescript-eslint/no-duplicate-imports`
     // does NOT exist in @typescript-eslint/eslint-plugin@8.66.0 (broken ruleId, all 820
     // phantom entries were `Definition for rule ... was not found`). PRD-002b 2026-08-07.
-    'no-duplicate-imports': 'warn'
+    'no-duplicate-imports': 'warn',
+
+    // 2026-09-20 rid-s9-require-await-decision — DELIBERATE divergence, measured.
+    //
+    // INHERITED, not chosen. This rule arrives via
+    // `plugin:@typescript-eslint/recommended-type-checked` in `extends` above;
+    // nothing in this file ever turned it on. Its inherited default is `error`.
+    // An absent line here would therefore NOT be "we never enabled it" — it
+    // would keep firing at error severity, silently. That is why the override is
+    // written out explicitly rather than left out.
+    //
+    // WHY OFF. Measured over all 291 findings in this repo, classified 291/291
+    // by AST: 259 (89%) are the rule being wrong, not debt. `async` here is
+    // load-bearing in two ways the rule does not model —
+    //   (a) it is the mechanism that moves a `throw` out of the synchronous path
+    //       and into the rejection channel (19 src sites), and
+    //   (b) it IS the interface contract (`readonly execute: (ctx) => Promise<…>`,
+    //       with the implementation written `execute: async () => ({…})`).
+    // The rule also does NOT exempt an explicit `Promise<…>` annotation — the
+    // declared type is consulted only by its autofix suggestion, to rewrite
+    // `Promise<T>` → `T`. Acting on that suggestion is a tsc error (measured:
+    // stripping `async` from the 314 candidate sites produced 363 tsc errors),
+    // so "just remove them" was always an interface rewrite, not a cleanup.
+    // Driving the number to zero would mean 259 knowingly-false entries inside
+    // the one ratchet axis that is supposed to mean "lint debt".
+    //
+    // WHAT REPLACES IT. The residual signal — "a later `await` added at the top
+    // of this function would silently make everything below it asynchronous" —
+    // is carried by an AST + tsc-type-checker guard at
+    // `tests/unit/standards/gratuitous-async-guard.test.ts`, which runs with
+    // `pnpm test:unit` and is pinned to exactly 14 sites. The 18 genuinely
+    // gratuitous `it`/`test` `async` callbacks in `tests/` were removed.
+    //
+    // Full evidence, the probe table, and the "when to reconsider" triggers:
+    // `.peaks/docs/lint-rule-divergences.md` § `@typescript-eslint/require-await`.
+    '@typescript-eslint/require-await': 'off'
   },
   overrides: [
     {
@@ -138,6 +223,66 @@ module.exports = {
         'max-lines-per-function': 'off',
         '@typescript-eslint/no-explicit-any': 'off'
       }
+    },
+    // 2026-09-20 rid-s11-js-type-aware-exemption — a type-aware rule family
+    // applied to files the project deliberately refuses to type-check.
+    // DELIBERATE divergence, measured; not a blanket rule switch-off.
+    //
+    // THE CONTRADICTION. `config/eslint/tsconfig.lint.json` sets
+    // `allowJs: true` together with `checkJs: false`. Those two are one
+    // deliberate statement: a JS file is *parsed* (so it can be linted at all)
+    // and is deliberately NOT type-checked — no types are ever established for
+    // it. `no-unsafe-*` is a *type-aware* family; every finding it reports is
+    // the answer to "what type does this expression have?". Asking that of a
+    // property the configuration explicitly declines to establish is not
+    // strictness — it is a self-contradiction. Where there are no types, `any`
+    // is not a defect the author introduced; it is the only answer the compiler
+    // was ever allowed to give.
+    //
+    // MEASURED REACH (census by file extension, taken before this entry
+    // existed; 1273 files in the gate's scope, 1036 findings on JS). Exactly
+    // five ruleIds account for 956 of those 1036, on 23 files:
+    //   no-unsafe-member-access 389, no-unsafe-assignment 214,
+    //   no-unsafe-argument 156, no-unsafe-call 146, no-unsafe-return 51.
+    // No other `no-unsafe-*` rule fires on JS anywhere in the repo. The globs
+    // below are the four JS extensions: 31 `.mjs` + 1 `.js` exist today, 0
+    // `.cjs` and 0 `.jsx`; the latter two are carried so a new file cannot
+    // reopen this hole by being written with a different extension.
+    //
+    // WHAT IS *NOT* SWITCHED OFF — the reach of this entry is the whole point:
+    //   - `.ts`/`.tsx`/`.mts`/`.cts` are not matched. The 538 type-aware
+    //     findings there are real: the root tsconfig.json runs `strict: true`,
+    //     so a type question has a genuine answer to reject. TS counts must not
+    //     move by one.
+    //   - `no-unsafe-finally` is deliberately ABSENT from the list. It is the
+    //     ESLint *core* rule of that name (control flow out of a `finally`
+    //     block) — NOT `@typescript-eslint/no-unsafe-finally` — and it needs no
+    //     type information. It fires twice on JS here, and both are genuine.
+    //   - every rule that is not type-aware keeps firing on JS (74 findings):
+    //     no-magic-numbers, complexity, max-lines-per-function, max-lines,
+    //     no-unused-vars, no-duplicate-imports, prefer-const,
+    //     no-inner-declarations, no-require-imports.
+    //   - the type-aware rules OUTSIDE this family also keep firing (6
+    //     findings): only-throw-error, restrict-plus-operands,
+    //     no-floating-promises, prefer-promise-reject-errors. They are
+    //     type-aware but not `no-unsafe-*`, so this authorisation does not reach
+    //     them. Widening these globs to cover them is a different decision that
+    //     needs its own evidence.
+    //   - `no-explicit-any` does NOT fire on JS (0 findings, measured — it does
+    //     not appear in the JS census at all). JS has no type annotations, so
+    //     there is no place to write `any` and nothing for the rule to match.
+    //
+    // Reasoning, the census, and the "when to reconsider" triggers:
+    // `.peaks/docs/lint-rule-divergences.md`
+    {
+      files: ['**/*.js', '**/*.jsx', '**/*.cjs', '**/*.mjs'],
+      rules: {
+        '@typescript-eslint/no-unsafe-argument': 'off',
+        '@typescript-eslint/no-unsafe-assignment': 'off',
+        '@typescript-eslint/no-unsafe-call': 'off',
+        '@typescript-eslint/no-unsafe-member-access': 'off',
+        '@typescript-eslint/no-unsafe-return': 'off'
+      }
     }
   ]
 };

package/config/eslint/tsconfig.lint.json

@@ -0,0 +1,47 @@
+// ESLint-ONLY tsconfig — see config/eslint/.peaks-rules.cjs. Never run tsc on
+// this file; it exists purely so parserOptions.project can see every file eslint
+// is asked to lint. The root tsconfig.json intentionally includes only src/**
+// and tests/**, so scripts/** and packages/** belonged to NO project at all:
+// eslint failed 71 of those files with "The file was not found in any of the
+// provided project(s)" BEFORE parsing them, which is not a lint result but a
+// hole — and one that also masked real syntax errors (a .mjs with a broken
+// string literal was ever only caught by prettier, because eslint never reached
+// the parser).
+//
+// allowJs is what lets the .mjs/.js tools under scripts/ into the program.
+//
+// The explicit `files` list below is NOT redundant. TypeScript's
+// extension-priority pass groups extensions as
+//   [[.ts,.tsx,.d.ts,.js,.jsx], [.cts,.d.cts,.cjs], [.mts,.d.mts,.mjs]]
+// and drops a file when a HIGHER-priority sibling exists; it carves out
+// .js/.jsx shadowed by .d.ts, but NOT .mjs shadowed by .d.mts. So a wildcard
+// include silently loses these four. Files named literally bypass that pass.
+// Any new <name>.mjs + <name>.d.mts pair under scripts/ must be added here —
+// tests/unit/lint/eslint-rules-config-coverage.test.ts asserts this program
+// contains every tracked in-scope file, so an omission fails a test instead of
+// silently reopening the coverage hole.
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "noEmit": true
+  },
+  "files": [
+    "../../scripts/_release-shared.mjs",
+    "../../scripts/release-pack.mjs",
+    "../../scripts/dist-freshness.mjs",
+    "../../scripts/install-skills.mjs",
+    "../../scripts/packages-build-prerequisite.mjs",
+    "../../scripts/verify-version-parity.mjs"
+  ],
+  "include": [
+    "../../src/**/*",
+    "../../tests/**/*",
+    "../../scripts/**/*",
+    "../../packages/*/src/**/*",
+    "../../packages/*/tests/**/*",
+    "../../packages/*/vitest.config.ts"
+  ],
+  "exclude": ["../../dist", "../../node_modules", "../../tests/fixtures/bdd-reporter-tmp"]
+}

package/dist/cli/cli-envelope.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The runtime shape of the JSON envelope `peaks … --json` writes to stdout.
+ *
+ * WHY THIS EXISTS (S12, 2026-09-20). The CLI envelope was the single largest
+ * cluster of unvalidated `JSON.parse` in the repo: 21 test files do
+ * `JSON.parse(<spawn result>.stdout)` and then read `out.ok` / `out.code` /
+ * `out.data.*`. Because `JSON.parse` returns `any`, none of those reads was
+ * checked against anything, and each one is a `no-unsafe-*` finding. Measured
+ * at the S12 census: ~196 of the ~448 findings in the R1 root.
+ *
+ * WHAT IS VALIDATED, AND WHAT IS NOT — stated plainly, because the difference
+ * is the whole point. The envelope HEAD is always validated: `ok` must be a
+ * boolean; `warnings` / `nextActions`, when present, arrays of strings; `code`
+ * / `message` / `errorId`, when present, strings. The PAYLOAD (`data`) is
+ * validated only as "a JSON object with string keys" — there is no single
+ * payload schema, because `data` is `T` in `ResultEnvelope<T>` and every
+ * command has its own shape. That is a measured finding of S12, not an
+ * oversight: R1 does not collapse onto one schema.
+ *
+ * A caller that reads `data.<field>` at depth >= 2 therefore names the payload
+ * shape itself, through the same validating primitive:
+ *
+ *     parseCliEnvelopeWith(raw, EvolutionStatusPayload)
+ *
+ * The alternative — one generic helper with a type parameter and no schema —
+ * is the `as T` costume S12 forbids. Here the type parameter is a SCHEMA, so
+ * the returned type is derived from a check that actually ran.
+ */
+import { z } from 'zod';
+declare const baseEnvelopeSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    command: z.ZodOptional<z.ZodString>;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    nextActions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    code: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    errorId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * Build the envelope schema with a payload schema — for the callers that read
+ * `data.<field>` at depth >= 2 and can say what they expect there.
+ */
+export declare function cliEnvelopeSchema<S extends z.ZodType>(payload: S): z.ZodObject<{
+    ok: z.ZodBoolean;
+    command: z.ZodOptional<z.ZodString>;
+    data: S;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    nextActions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    code: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    errorId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * `ok` + `data` (any JSON object) + the optional head fields.
+ */
+export type CliEnvelope = z.infer<typeof baseEnvelopeSchema>;
+/**
+ * Parse a CLI stdout envelope, validating the head. Throws when the text is
+ * not JSON, or is JSON that is not an envelope — a caller that fed this
+ * something else wants to know, not to read `undefined.ok` further down.
+ */
+export declare function parseCliEnvelope(raw: string): CliEnvelope;
+/**
+ * Parse a CLI stdout envelope for a caller that reads `data.<field>` at depth
+ * >= 2, validating that field's own shape as well. The caller names the shape;
+ * nothing is asserted on its behalf.
+ */
+export declare function parseCliEnvelopeWith<S extends z.ZodType>(raw: string, payload: S): ({
+    ok: z.ZodBoolean;
+    command: z.ZodOptional<z.ZodString>;
+    data: S;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    nextActions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    code: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    errorId: z.ZodOptional<z.ZodString>;
+} extends infer T_1 extends z.core.$ZodLooseShape ? { -readonly [k in keyof T_1 as {
+    ok: z.ZodBoolean;
+    command: z.ZodOptional<z.ZodString>;
+    data: S;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    nextActions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    code: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    errorId: z.ZodOptional<z.ZodString>;
+}[k] extends {
+    _zod: {
+        optout: "optional";
+    };
+} ? never : k]: T_1[k]["_zod"]["output"]; } : never) & ({
+    ok: z.ZodBoolean;
+    command: z.ZodOptional<z.ZodString>;
+    data: S;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    nextActions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    code: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    errorId: z.ZodOptional<z.ZodString>;
+} extends infer T_2 extends z.core.$ZodLooseShape ? { -readonly [k_1 in keyof T_2 as {
+    ok: z.ZodBoolean;
+    command: z.ZodOptional<z.ZodString>;
+    data: S;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    nextActions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    code: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    errorId: z.ZodOptional<z.ZodString>;
+}[k_1] extends {
+    _zod: {
+        optout: "optional";
+    };
+} ? k_1 : never]?: T_2[k_1]["_zod"]["output"]; } : never) & Record<string, unknown> extends infer T ? { [K in keyof T]: T[K]; } : never;
+export {};

package/dist/cli/cli-envelope.js

@@ -0,0 +1,85 @@
+/**
+ * The runtime shape of the JSON envelope `peaks … --json` writes to stdout.
+ *
+ * WHY THIS EXISTS (S12, 2026-09-20). The CLI envelope was the single largest
+ * cluster of unvalidated `JSON.parse` in the repo: 21 test files do
+ * `JSON.parse(<spawn result>.stdout)` and then read `out.ok` / `out.code` /
+ * `out.data.*`. Because `JSON.parse` returns `any`, none of those reads was
+ * checked against anything, and each one is a `no-unsafe-*` finding. Measured
+ * at the S12 census: ~196 of the ~448 findings in the R1 root.
+ *
+ * WHAT IS VALIDATED, AND WHAT IS NOT — stated plainly, because the difference
+ * is the whole point. The envelope HEAD is always validated: `ok` must be a
+ * boolean; `warnings` / `nextActions`, when present, arrays of strings; `code`
+ * / `message` / `errorId`, when present, strings. The PAYLOAD (`data`) is
+ * validated only as "a JSON object with string keys" — there is no single
+ * payload schema, because `data` is `T` in `ResultEnvelope<T>` and every
+ * command has its own shape. That is a measured finding of S12, not an
+ * oversight: R1 does not collapse onto one schema.
+ *
+ * A caller that reads `data.<field>` at depth >= 2 therefore names the payload
+ * shape itself, through the same validating primitive:
+ *
+ *     parseCliEnvelopeWith(raw, EvolutionStatusPayload)
+ *
+ * The alternative — one generic helper with a type parameter and no schema —
+ * is the `as T` costume S12 forbids. Here the type parameter is a SCHEMA, so
+ * the returned type is derived from a check that actually ran.
+ */
+import { z } from 'zod';
+import { parseJson } from '../shared/json-parse.js';
+const anyJsonObject = z.record(z.string(), z.unknown());
+/** The head of the envelope, with `data` checked by whichever schema is passed. */
+function envelopeWith(data) {
+    // `looseObject` keeps every key the schema does not name, matching
+    // `JSON.parse`'s old behaviour of handing back every key: validation is not
+    // licence to silently drop fields.
+    return z.looseObject({
+        ok: z.boolean(),
+        // `command` is the one head field that is genuinely optional: the
+        // `printCliEnvelope` shim (`src/cli/cli-helpers.ts`, used only by
+        // `sediment-commands.ts`) writes `{ ok, data }` / `{ ok, error }`, and
+        // `_super.ts` writes `{ ok, data, warnings, nextActions }`.
+        command: z.string().optional(),
+        data,
+        // `warnings` / `nextActions` are OPTIONAL, and that is a MEASURED fact,
+        // not a convenience. S12 first made them required on the theory that
+        // "every emitter writes them" — then the integration suite proved the
+        // theory false: `peaks workspace clean --json`
+        // (`src/cli/commands/workspace/clean-command.ts`) writes `{ ok, data }`
+        // and nothing else. So the premise this slice inherited — "the CLI stdout
+        // envelope has a fixed shape `{ ok, command, data, warnings, nextActions }`"
+        // — is wrong as stated; `ok` and `data` are the only universal members.
+        // A caller that needs `nextActions` must say so — `program.test.ts` names
+        // it in a schema rather than looping over a possibly-absent array.
+        warnings: z.array(z.string()).optional(),
+        nextActions: z.array(z.string()).optional(),
+        code: z.string().optional(),
+        message: z.string().optional(),
+        errorId: z.string().optional()
+    });
+}
+const baseEnvelopeSchema = envelopeWith(anyJsonObject);
+/**
+ * Build the envelope schema with a payload schema — for the callers that read
+ * `data.<field>` at depth >= 2 and can say what they expect there.
+ */
+export function cliEnvelopeSchema(payload) {
+    return envelopeWith(payload);
+}
+/**
+ * Parse a CLI stdout envelope, validating the head. Throws when the text is
+ * not JSON, or is JSON that is not an envelope — a caller that fed this
+ * something else wants to know, not to read `undefined.ok` further down.
+ */
+export function parseCliEnvelope(raw) {
+    return parseJson(raw, baseEnvelopeSchema);
+}
+/**
+ * Parse a CLI stdout envelope for a caller that reads `data.<field>` at depth
+ * >= 2, validating that field's own shape as well. The caller names the shape;
+ * nothing is asserted on its behalf.
+ */
+export function parseCliEnvelopeWith(raw, payload) {
+    return parseJson(raw, cliEnvelopeSchema(payload));
+}

package/dist/cli/cli-helpers.d.ts

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { getErrorMessage, ok, redactSensitiveErrorMessage, type ResultEnvelope } from 'peaks-loop-shared/result';
 import type { ArtifactProvider, GuidedArtifactSetup } from '../services/artifacts/artifact-service.js';
 import type { ConfigLayer } from '../services/config/config-service.js';

package/dist/cli/cli-helpers.js

@@ -44,7 +44,9 @@ export function addJsonOption(command) {
     return command.option('--json', 'print machine-readable JSON envelope');
 }
 export function failUnsupportedNonDryRun(io, command, asJson) {
-    printResult(io, fail(command, 'UNSUPPORTED_NON_DRY_RUN', 'Only dry-run planning is supported', {}, ['Rerun with --dry-run or omit --no-dry-run']), asJson);
+    printResult(io, fail(command, 'UNSUPPORTED_NON_DRY_RUN', 'Only dry-run planning is supported', {}, [
+        'Rerun with --dry-run or omit --no-dry-run'
+    ]), asJson);
     process.exitCode = 1;
 }
 export function printCliEnvelope(io, r) {
@@ -152,10 +154,10 @@ export function isArtifactProvider(value) {
     return value === 'github' || value === 'gitlab';
 }
 export function isArtifactSetupStep(value) {
-    return value === 'detect' || value === 'configure' || value === 'validate' || value === 'complete';
+    return (value === 'detect' || value === 'configure' || value === 'validate' || value === 'complete');
 }
 export function isArtifactRepoSegment(value) {
-    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !value.includes('..') && !value.endsWith('.');
+    return (/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !value.includes('..') && !value.endsWith('.'));
 }
 export function parseConfigLayer(value) {
     if (value === undefined) {
@@ -164,7 +166,9 @@ export function parseConfigLayer(value) {
     return value === 'user' || value === 'project' ? value : null;
 }
 export function printInvalidConfigLayer(io, command, asJson) {
-    printResult(io, fail(command, 'INVALID_CONFIG_LAYER', 'Config layer must be user or project', {}, ['Use --layer user or --layer project']), asJson);
+    printResult(io, fail(command, 'INVALID_CONFIG_LAYER', 'Config layer must be user or project', {}, [
+        'Use --layer user or --layer project'
+    ]), asJson);
     process.exitCode = 1;
 }
 export function multipleOption(value, previous) {

package/dist/cli/commands/_cli-error-envelope.js

@@ -40,7 +40,7 @@ export function mapServiceError(error) {
     if (error instanceof ProviderNotConfiguredError) {
         return {
             code: 'INVALID_PROVIDERS',
-            nextActions: ['Configure provider model: peaks config provider <id> set --model <id>'],
+            nextActions: ['Configure provider model: peaks config provider <id> set --model <id>']
         };
     }
     if (error instanceof Error && GOAL_VALIDATION_MESSAGE_RE.test(error.message)) {