peaks-loop 4.1.0 → 4.1.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 4.1.1 — 2026-10-05 (一次"闸自己坏了整整一个版本"、注释债第一次进棘轮、以及五个从真实使用里捞出来的缺陷)
+
+**版本级别**: 未发布区间 `v4.1.0..HEAD` 共 **14 个 commit**（6 fix / 4 feat / 1 test / 1 refactor / 1 docs / 1 chore）。**取 patch，而不是按 4.1.0 自己写下的判据取 minor** —— 这条判据不是被推翻，而是被有意收窄：本版新增的两条命令（`peaks comments audit` / `peaks comments prune`）是**仓库自己的维护表面**，只读或只动本仓注释，不改变任何既有命令的输入输出，也不要求下游做任何事；对外承诺的内容全是修复（其中一条是门禁崩溃）。`^4.1.0` 的下游直接匹配本版。4 个 workspace 包各 +1 patch（internal-runtime 0.0.40→0.0.41、mut 0.1.54→0.1.55、shared 0.0.89→0.0.90、shared-channel 0.0.57→0.0.58），顺带把"本地 manifest 比 registry 新"（mut 的 0.1.54 从未发布）这个坑一次清掉：`scripts/release-pack.mjs` 按拓扑序把 5 个包在同一次 CI 运行里一起发出去，`pnpm pack` 把 `workspace:*` 重写成精确 pin，实测 tarball 内 `CLI_VERSION` 为 4.1.1。
+
+### 1. 门禁自己坏了一个版本（`78cb982f`，用户可见）
+
+`node .husky/peaks-gate.mjs file-size` 从 `28b5145f` 起**每次都崩**：那次提交把 comment 腿从 `.husky/gate/legs.mjs` 搬出去时，连带删掉了紧贴它的两段 import（`./context.mjs` 与 `peaks-gate-file-size.mjs`），而 file-size 腿的函数体留在原地 —— `ReferenceError: refuseScopedSubset is not defined`。没有一条臂跑过整条 file-size 模式，所以它活着进了主干；恢复 import 后 `file-size-gate-leg` / `-excess-` / `-hooks-` 三家 21 条臂当场转绿。同一批 78 条臂红的第二个成因是工装：`.husky/file-size/measure.mjs` 与 `.husky/peaks-gate-comment-hygiene.mjs` 都通过 `node_modules/tsx/dist/cli.mjs`  spawn 工具，而四个 fixture builder 把这个 tsx 替身写死成"任何调用都回 census 信封"。census 曾是唯一的 tsx 调用方，所以这写法无害了三个版本；comment 腿上线后它收到 census JSON、在里面找不到 `deadReferences`，于是拒绝 seed —— 现在是一份按请求工具分派的替身，顺带把四份逐字复制的 census 信封合成一份。
+
+### 2. 注释债第一次进棘轮（4 feat）
+
+`peaks comments audit` 出只读清单（dead-reference / narrative 两类，带归属文件），`peaks comments prune` 是执行器，它的**交付物是证明而不是删除**：在真树副本上计划 1677 处、覆盖 484 文件、拒绝 7 处，注释-only 证明 0 问题，残余计数 4+3 恰好等于拒绝数 —— 证明方式是重读改前改后文本、逐行比对非注释行与代码 token，任何一条代码文本变动都拒绝写入。两行 ceiling `commentDeadReferences` / `commentNarrativeLines` 入闸，seed 于**强制范围内实测**的 25 / 1515（952 个 tracked 文件，与 eslint / prettier / tsc / silent-warning / file-size 读同一份清单）。分类器是**先校准再入闸**的：188 → 65（把 standards 守卫的 5 条候选排除规则搬过来）→ 28（邻居解析改为 sibling-only，实测每一次祖先上溯带来 16 次误报）→ 25（再加"句子在推理路径"与包内相对根两条规则）。分类器与守卫的排除规则由一条 parity 臂钉住（读守卫源码里的字面量比对，不抄表）。
+
+### 3. 五个从真实使用里捞出来的缺陷（`c08bf736` / `23af9c1d` / `2e323344`）
+
+1.x→2.0 的升级路径整条删除（含 gate step），不再让一个已经退役的迁移分支继续决定今天的状态；`frontendOnly` 对隐藏目录 / 非 Node 后端的**漏判**修掉（有后端却报 true，用户据此关掉了一整条后端保护）；ECC 从 GitHub tarball 拉取改为读 `ecc-universal` npm 依赖， acquisition 层删除，`ecc status` 从此只报告它能不吞异常说出的东西；`peaks memory extract` 的凭证拒绝变成**可诊断**（原先只说"有凭证"，且误杀形状过宽），并收紧了两类假阳性；PRD 交接的 frontmatter / `gateEvidence` 字段由文档断言变成代码真产 —— 这是本仓最主的一类缺陷：prose 声称的字段实现里没有。
+
+### 4. 一个钉在历史 commit 上的等价守卫，收窄而不是退役（owner 决定 2026-10-05）
+
+`baseline-split-equivalence.test.ts` 把拆分前的 799 行 monolith 钉在 `77b711ff`，与今天的 11 模块版逐字节对比。两行新 ceiling 落在**两侧共享**的 `keys.mjs` 里，于是旧程序被要求核准它自己没有腿去量的行 —— 它诚实地拒绝了（`NOT THE CANONICAL CEILING SET`）。逐字节等价在"行集会增长"的棘轮上不可能再次成立，可选的只有收窄与退役，选了前者：参考侧现在读**自己那个时代**的 `keys.mjs`（一个被交给今天的清单的钉死程序，已经不是那个程序了），投影只允许吞掉"锚点之后 `CEILING_KEYS` 新增的行"，而这个集合由两份真实清单求差得出（`ceilingKeysInText` 读 git blob 与工作树），没有任何字面量；`_split-anchor-era.ts` 持有唯一的 sha，`baseline-split-anchor.test.ts` 证明 harness 不留第二份。`rescope-projection-bounded.test.ts` 加 4 条臂：种一条**不属于 era** 的 moved-row，它的 bullet、header、计数与差异全部保留；note 下的 bullet 若全是 era 行则整条随计数一同消退；comment 腿的两行 stderr 必须由其**自己的 emitter** 或源码字面量证明真的会打印；`projectArtifact` 只掉它被交出去的键，其余照旧逐字节比。
+
+### 5. 本版验证
+
+tsc 0；`pnpm build` 0；全量 unit **388 files / 4082 passed / 3 skipped**；`node .husky/peaks-gate.mjs repo` exit 0，19 行 ceiling 全部 held（`eslint 2098/803`、`comment dead-ref 25 / narrative 1515`、`silent-warn 44/62`、`file-size 127 / 40137`、`hooks 0/0`）；`peaks release precheck --strict` 0；版本 parity `shared-dist` / `runtime-src` 双 OK；`PEAKS_DRY_RUN=1 scripts/release-pack.mjs` 5 个 tarball 全部通过 registry 校验（无 `workspace:*` 残留）。artifacts 侧：baseline 只重写了**报告用**的 shadow 块（588 files / 643 findings / 160 errors / 36 over-cap / 13349 excess，增量是那个新进的 era helper 文件），没有任何 ceiling 移动。
+
+
 ## 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` 的下游仍能匹配到本版。

package/README-en.md

@@ -155,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.1.0 (2026-10-03) |
+| **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.1 (2026-10-05) |
 | **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

@@ -154,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.1.0(2026-10-03) |
+| **最新版本** | [![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.1(2026-10-05) |
 | **覆盖域** | 代码(`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/dist/cli/commands/_register.js

@@ -10,6 +10,7 @@ import { registerCodeCommands } from './code-commands.js';
 import { registerCodeGateCommand } from './code-gate-command.js';
 import { registerDashboardCommands } from './dashboard-commands.js';
 import { registerCodeReviewCommands } from './code-review-commands.js';
+import { registerCommentsCommands } from './comments-commands.js';
 import { registerCodegraphCommands } from './codegraph-commands.js';
 import { registerCompactCommands } from './compact-command.js';
 import { registerComplexityCommands } from './complexity-commands.js';
@@ -79,7 +80,6 @@ import { registerSubAgentShutdownCommands } from './sub-agent-shutdown-commands.
 import { registerSubAgentDispatchGuard } from './sub-agent-dispatch-guard.js';
 import { registerTestCommands } from './test-commands.js';
 import { registerVendorDetectCommand } from './vendor-detect.js';
-import { registerUpgradeCommands } from './upgrade-commands.js';
 import { registerUserTouchpointCommands } from './user-touchpoint-commands.js';
 import { registerVerdictAggregateCommands } from './verdict-aggregate-command.js';
 import { registerWebCommands } from './web-commands.js';
@@ -158,8 +158,8 @@ const REGISTRATIONS = [
     ['bee-commands', registerBeeCommands],
     ['ecc-commands', registerEccCommands],
     ['baseline-commands', registerBaselineCommands],
-    ['upgrade-commands', registerUpgradeCommands],
     ['code-review-commands', registerCodeReviewCommands],
+    ['comments-commands', registerCommentsCommands],
     ['security-audit-commands', registerSecurityAuditCommands],
     ['perf-audit-commands', registerPerfAuditCommands],
     ['verdict-aggregate-command', registerVerdictAggregateCommands],

package/dist/cli/commands/code-mode-gate-should-pause-command.js

@@ -67,7 +67,7 @@ function validateModeAndStep(opts) {
     if (!GATED_STEPS.includes(opts.step)) {
         return {
             ok: false,
-            envelope: fail('code.should-pause', 'INVALID_STEP', `step must be one of the 14 GATED_STEPS (got "${opts.step}")`, { provided: opts.step, allowed: [...GATED_STEPS] }, ['Pass --step <one of the 14 GATED_STEPS>'])
+            envelope: fail('code.should-pause', 'INVALID_STEP', `step must be one of the ${GATED_STEPS.length} GATED_STEPS (got "${opts.step}")`, { provided: opts.step, allowed: [...GATED_STEPS] }, [`Pass --step <one of the ${GATED_STEPS.length} GATED_STEPS>`])
         };
     }
     return { ok: true, mode, step: opts.step };

package/dist/cli/commands/comments-commands.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `peaks comments` — the read side of comment hygiene.
+ *
+ * `peaks comments audit` reports which comments in the product scope assert
+ * something the repository no longer supports, and which are development
+ * narrative rather than documentation. It is read-only on purpose: the number it
+ * prints is the number a later ratchet would be seeded from, and a ceiling is
+ * only trustworthy once a human has read a list of what the rule flags.
+ *
+ * Remediation is the next slice's job, not this command's.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCommentsCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/comments-commands.js

@@ -0,0 +1,96 @@
+/**
+ * `peaks comments` — the read side of comment hygiene.
+ *
+ * `peaks comments audit` reports which comments in the product scope assert
+ * something the repository no longer supports, and which are development
+ * narrative rather than documentation. It is read-only on purpose: the number it
+ * prints is the number a later ratchet would be seeded from, and a ceiling is
+ * only trustworthy once a human has read a list of what the rule flags.
+ *
+ * Remediation is the next slice's job, not this command's.
+ */
+import { auditComments } from '../../services/comments/comment-audit.js';
+import { pruneComments } from '../../services/comments/comment-prune.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+const KINDS = ['dead-reference', 'narrative'];
+function parseKind(value) {
+    return KINDS.find((kind) => kind === value);
+}
+function nextActions(result) {
+    const lines = [
+        `dead-reference: ${result.deadReferences} comment line(s) cite a path that resolves nowhere.`,
+        `narrative: ${result.narrative} comment line(s) are about the work, not the code.`
+    ];
+    if (result.deadReferences > 0) {
+        lines.push('Fix the citation or delete the claim — a comment that names a deleted file is an instruction to go look for it.');
+    }
+    lines.push('Worst files first: --json carries per-line records with the matched rule.');
+    return lines;
+}
+/** The `prune` action: plan, prove, and only then write. */
+function runPrune(io, options) {
+    const kind = parseKind(options.kind);
+    if (options.kind !== undefined && kind === undefined) {
+        printResult(io, fail('comments.prune', 'INVALID_KIND', `--kind must be one of: ${KINDS.join(', ')}`, { provided: options.kind }, ['Re-run with a supported --kind, or omit it for both categories.']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const result = pruneComments({
+        projectRoot: options.project ?? process.cwd(),
+        ...(kind === undefined ? {} : { kinds: [kind] }),
+        ...(options.file === undefined ? {} : { onlyFile: options.file }),
+        ...(options.apply === true ? { apply: true } : {})
+    });
+    const actions = [
+        result.applied
+            ? `Ledger: ${result.ledgerPath} records every line removed and every refusal.`
+            : 'Dry run: nothing was written. Pass --apply to write, after reading the plan.',
+        result.skipped > 0 ? `${result.skipped} finding(s) refused — see skipped reasons.` : undefined,
+        result.notWritten.length > 0 ? `Files not written: ${result.notWritten.join(', ')}` : undefined
+    ].filter((line) => line !== undefined);
+    printResult(io, ok('comments.prune', result, [], actions), options.json === true);
+}
+/** The `audit` action, named so the registration above stays a registration. */
+function runAudit(io, options) {
+    const projectRoot = options.project ?? process.cwd();
+    const kind = parseKind(options.kind);
+    if (options.kind !== undefined && kind === undefined) {
+        printResult(io, fail('comments.audit', 'INVALID_KIND', `--kind must be one of: ${KINDS.join(', ')}`, { provided: options.kind }, ['Re-run with a supported --kind, or omit it to scan both.']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const limit = options.limit === undefined ? undefined : Number.parseInt(options.limit, 10);
+        const result = auditComments({
+            projectRoot,
+            ...(kind === undefined ? {} : { kind }),
+            ...(limit === undefined || Number.isNaN(limit) ? {} : { limit })
+        });
+        printResult(io, ok('comments.audit', result, [], nextActions(result)), options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('comments.audit', 'COMMENTS_AUDIT_FAILED', getErrorMessage(error), {}, [
+            'Check --project points at a repository root.'
+        ]), options.json === true);
+        process.exitCode = 1;
+    }
+}
+export function registerCommentsCommands(program, io) {
+    const comments = program
+        .command('comments')
+        .description('Measure comment debt in product code: stale references and process narrative.');
+    addJsonOption(comments
+        .command('audit')
+        .description('Read-only scan of src/** and packages/*/src/** comments.')
+        .option('--project <path>', 'project root to scan (default: cwd)')
+        .option('--kind <kind>', `one of: ${KINDS.join(', ')}`)
+        .option('--limit <n>', 'cap the per-line findings printed (totals are never capped)')).action((options) => runAudit(io, options));
+    addJsonOption(comments
+        .command('prune')
+        .description('Remove the comment lines the scan named, and prove the diff is comment-only first. Dry run unless --apply.')
+        .option('--project <path>', 'project root to prune (default: cwd)')
+        .option('--kind <kind>', `one of: ${KINDS.join(', ')}`)
+        .option('--file <path>', 'one repo-relative file, for a narrow first run')
+        .option('--apply', 'write the files (default: plan and prove only)')).action((options) => runPrune(io, options));
+}

package/dist/cli/commands/core/memory-command.js

@@ -217,5 +217,15 @@ function memoryExtractNextActions(refusal) {
             'Retitle the memory so it is not named after a credential term, then re-run memory extract'
         ];
     }
+    if (refusal.check === SENSITIVE_MEMORY_CHECKS.content) {
+        // Name the rule, not just the family. `matchedTerm` is a closed id
+        // (`credential-assignment`, `bearer-value`, `pem-private-key`, …), so the
+        // reader can tell a credential in the text from a sentence that merely has
+        // the shape of one — which is the difference between removing a value and
+        // rewording prose.
+        return [
+            `Remove the credential value the "${refusal.matchedTerm}" pattern matched, then re-run memory extract`
+        ];
+    }
     return ['Remove the credential value from the memory content, then re-run memory extract'];
 }

package/dist/cli/commands/core/skill-command.js

@@ -136,7 +136,7 @@ function generatedConfigNotice(projectRoot) {
         warnings: [
             `Generated config at '${projectRoot}' was produced by peaks-loop ${onDiskVersion} ` +
                 `but ${staleness.expected.packageVersion} is installed (${staleness.reasons.join(', ')}). ` +
-                `Re-run \`peaks workspace init\` (or the idempotent \`peaks upgrade --apply-init\`) ` +
+                `Re-run \`peaks workspace init\` ` +
                 `to regenerate .claude/settings.local.json and the offline template copy.`
         ]
     };

package/dist/cli/commands/core/standards-command.js

@@ -145,7 +145,7 @@ export function registerStandardsCommand(program, io) {
         .description('Rewrite a consumer project CLAUDE.md to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write. With --from-claude-rules, thins the 1.x .claude/rules/ tree to 2-line pointers and scaffolds .peaks/standards/ (slice 2026-06-12-standards-migrate-claude-rules).')
         .option('--project <path>', 'target project root')
         .option('--apply', 'rewrite the legacy block in place; default is dry-run')
-        .option('--from-claude-rules', 'thin .claude/rules/ to pointers and scaffold .peaks/standards/ (used by `peaks upgrade --to 2.0`)')).action((options) => {
+        .option('--from-claude-rules', 'thin .claude/rules/ to pointers and scaffold .peaks/standards/')).action((options) => {
         const projectRoot = options.project ?? process.cwd();
         if (options.fromClaudeRules === true) {
             try {

package/dist/cli/commands/ecc-commands.d.ts

@@ -1,29 +1,24 @@
 /**
- * `peaks ecc install|status|ls|show` — Slice 3 of 4.0.0-beta.11.
+ * `peaks ecc install|status|ls|show` — the ECC read layer.
  *
- * Drop-in replacement for the deleted `peaks agent run|list`
- * surface. The pre-Slice-3 implementation shelled out to
- * `npx ecc agent run ...`, but the upstream `affaan-m/everything-claude-code`
- * v2.0.0 release has NO `ecc` binary — the repo is `agents/*.md`
- * flat files plus SKILL.md descriptors.
+ * ECC's agent definitions come from the `ecc-universal` npm dependency of
+ * `peaks-loop-mut`. `install` copies `<package>/agents/*.md` into the
+ * plugin-free dir the LLM reads (`~/.peaks/agents/ecc/`); `status`, `ls` and
+ * `show` read that copy. There is no download anywhere in this file: the
+ * previous design fetched a GitHub release tarball on the premise that the
+ * project was not on npm, and that premise was false (`ecc-universal`
+ * `repository.url` is `git+https://github.com/affaan-m/ECC.git`).
  *
- * The new flow:
- *   - `peaks ecc install [--ref <tag>]` downloads the ECC tarball
- *     into `~/.peaks/cache/ecc-<sha>/agents/` (selective extract,
- *     agents/*.md only).
- *   - `peaks ecc status` reports the cache manifest state.
- *   - `peaks ecc ls` lists cached agents from `<cache>/agents/*.md`,
- *     parsing YAML frontmatter (with D-009 fallback to filename +
- *     first body line when frontmatter is malformed).
- *   - `peaks ecc show <name> [--section H] [--max-lines N]` prints
- *     the SKILL.md body to stdout — this is the Skill-first path
- *     the LLM consumes directly.
+ *   - `peaks ecc install` — land/refresh the copy. Idempotent; prunes agents the
+ *     installed package no longer ships.
+ *   - `peaks ecc status` — package version + what landed and when.
+ *   - `peaks ecc ls` — the roster with declared name + description (D-009
+ *     fallback to filename + first body line when frontmatter is malformed).
+ *   - `peaks ecc show <name> [--section H] [--max-lines N]` — the agent body;
+ *     this is the Skill-first path the LLM consumes directly.
  *
- * The `--section` filter extracts a single H1 (`# heading`)
- * through the next H1 — useful when the SKILL.md is large.
- *
- * Per the "Enhancement, not new AI CLI" tenet: this command is a
- * download + read-only access layer. There is no `peaks ecc run`.
+ * Per the "Enhancement, not new AI CLI" tenet: read-only access plus a local
+ * copy. There is no `peaks ecc run`, and no ECC subprocess is spawned.
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';

package/dist/cli/commands/ecc-commands.js

@@ -1,53 +1,65 @@
-import { downloadToCache, listCachedAgents, readAgentSkill, readCacheManifest } from 'peaks-loop-mut';
+import { EccSourceError, installEccAgents, listEccAgents, readEccMaterializeManifest, readMaterializedAgent } from 'peaks-loop-mut';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 export function registerEccCommands(program, io) {
     const ecc = program
         .command('ecc')
-        .description('affaan-m/ECC cache: download + read-only access for the LLM (no subprocess; no peaks agent run).');
+        .description('ECC agents from the bundled `ecc-universal` dependency: copy + read-only access for the LLM (no subprocess; no peaks agent run).');
     addJsonOption(ecc
         .command('install')
-        .description('Download affaan-m/ECC to ~/.peaks/cache/ecc-<sha>/ (selective extract: agents/ subtree only).')
-        .option('--ref <tag>', 'release tag (default: latest)')).action(async (options) => {
-        const asJson = options.json === true;
+        .description('Copy <node_modules>/ecc-universal/agents/*.md into ~/.peaks/agents/ecc/ (idempotent).')).action((_options) => {
+        const asJson = _options.json === true;
         try {
-            const result = await downloadToCache(options.ref !== undefined && options.ref.length > 0 ? { ref: options.ref } : {});
+            const result = installEccAgents();
             const envelope = ok('ecc.install', result, [], [
-                `Cache landed at ~/.peaks/cache/ecc-${result.sha}/agents/`,
-                `Plugin-free copy materialized at ~/.peaks/agents/ecc/ (read it directly when the ECC plugin is absent)`,
-                `Inspect with: peaks ecc ls`,
-                `Consume one agent with: peaks ecc show <name>`
+                `Materialized ${result.materialized.length} ECC agent(s) at ${result.targetDir}`,
+                `Source: ecc-universal@${result.packageVersion}`,
+                'Inspect with: peaks ecc ls',
+                'Consume one agent with: peaks ecc show <name>'
             ]);
             printResult(io, envelope, asJson);
         }
         catch (error) {
-            const message = getErrorMessage(error);
-            printResult(io, fail('ecc.install', 'FETCH_FAILED', message, { ref: options.ref ?? 'latest' }, [
-                'Network failure during ECC download. Manual fallback:',
-                '  git clone https://github.com/affaan-m/ECC.git',
-                '  Copy <repo>/agents/*.md into ~/.peaks/cache/ecc-<sha>/agents/.',
-                '  Drop a minimal ecc-installed.json manifest into ~/.peaks/cache/.'
-            ]), asJson);
+            const missing = error instanceof EccSourceError;
+            printResult(io, fail('ecc.install', missing ? 'ECC_PACKAGE_MISSING' : 'ECC_INSTALL_FAILED', getErrorMessage(error), { source: missing ? error.failure : 'copy-failed' }, missing
+                ? [
+                    'The `ecc-universal` dependency is not resolvable from this installation.',
+                    'Reinstall peaks-loop (`npm i -g peaks-loop@latest`) — the ECC agents ship inside that dependency.',
+                    'A partial or `--ignore-scripts` install can leave the dependency tree incomplete.'
+                ]
+                : ['Check that ~/.peaks is writable, then re-run `peaks ecc install`.']), asJson);
             process.exitCode = 1;
         }
     });
     addJsonOption(ecc
         .command('status')
-        .description('Show ECC cache state (version, sha, fetchedAt, agent count).')).action((options) => {
+        .description('Show the materialized ECC copy: source version, agent list, when it landed.')).action((options) => {
         const asJson = options.json === true;
-        const manifest = readCacheManifest();
+        const manifest = readEccMaterializeManifest();
         if (manifest === null) {
-            printResult(io, fail('ecc.status', 'NO_CACHE', 'No ECC cache found. Run `peaks ecc install` first.', { installed: false }, ['Run `peaks ecc install [--ref <tag>]` to populate ~/.peaks/cache/ecc-<sha>/agents/.']), asJson);
+            printResult(io, fail('ecc.status', 'NOT_INSTALLED', 'No materialized ECC agents found. Run `peaks ecc install` first.', { installed: false }, [
+                'Run `peaks ecc install` to copy the bundled ecc-universal agents into ~/.peaks/agents/ecc/.'
+            ]), asJson);
             process.exitCode = 1;
             return;
         }
-        printResult(io, ok('ecc.status', manifest, [], [`Inspect agents with: peaks ecc ls`, `Print one agent with: peaks ecc show <name>`]), asJson);
+        // `status` reads the copy and reports it. It does not re-probe the package:
+        // `manifest.packageVersion` already records which version landed the agents,
+        // and probing again would need either a throw that hides the answer or a
+        // swallowed error — the second is the class the repository's silent-catch
+        // ratchet counts, the first would turn "here is what the LLM can read" into a
+        // failure just because a dependency moved.
+        printResult(io, ok('ecc.status', manifest, [], [
+            `Materialized from ecc-universal@${manifest.packageVersion}.`,
+            'Inspect agents with: peaks ecc ls',
+            'Print one agent with: peaks ecc show <name>'
+        ]), asJson);
     });
     addJsonOption(ecc
         .command('ls')
-        .description('List cached agents from <cache>/agents/*.md with parsed frontmatter.')).action((options) => {
+        .description('List materialized agents from ~/.peaks/agents/ecc/*.md with parsed frontmatter.')).action((options) => {
         const asJson = options.json === true;
-        const agents = listCachedAgents();
+        const agents = listEccAgents();
         printResult(io, ok('ecc.ls', { agents }, [], ['Print one with: `peaks ecc show <name>`']), asJson);
     });
     addJsonOption(ecc
@@ -61,11 +73,11 @@ export function registerEccCommands(program, io) {
             process.exitCode = 1;
             return;
         }
-        const body = readAgentSkill(name);
+        const body = readMaterializedAgent(name);
         if (body === null) {
-            printResult(io, fail('ecc.show', 'NOT_FOUND', `agent "${name}" is not in the cache`, { name }, [
+            printResult(io, fail('ecc.show', 'NOT_FOUND', `agent "${name}" is not in the materialized copy`, { name }, [
                 'Run `peaks ecc ls` to see available agents.',
-                'Or run `peaks ecc install` to (re-)populate the cache.'
+                'Or run `peaks ecc install` to (re-)copy the bundled agents into ~/.peaks/agents/ecc/.'
             ]), asJson);
             process.exitCode = 1;
             return;

package/dist/cli/commands/prd-commands.js

@@ -94,7 +94,12 @@ export function registerPrdCommands(program, io) {
                     bodyBytes: Buffer.byteLength(body, 'utf8'),
                     goals: handoff.frontmatter.goals,
                     acceptanceCriteria: handoff.frontmatter.acceptanceCriteria,
-                    preservedBehavior: handoff.frontmatter.preservedBehavior
+                    preservedBehavior: handoff.frontmatter.preservedBehavior,
+                    // The derived declaration is printed, not just written. A reader
+                    // deciding whether to `--apply` must be able to see which gate
+                    // keys this slice declares and at what paths; before this, the
+                    // only way to learn the five key names was to read the source.
+                    gateEvidence: handoff.frontmatter.gateEvidence ?? null
                 }), options.json);
                 return;
             }
@@ -104,7 +109,8 @@ export function registerPrdCommands(program, io) {
                 path: written.path,
                 hash: written.hash,
                 requestId: handoff.frontmatter.requestId,
-                sessionId: handoff.frontmatter.sessionId
+                sessionId: handoff.frontmatter.sessionId,
+                gateEvidence: handoff.frontmatter.gateEvidence ?? null
             }), options.json);
         }
         catch (error) {

package/dist/cli/program.js

@@ -18,7 +18,7 @@ import { registerSopCommands } from './commands/sop-commands.js';
 import { registerSkillVisibilityCommand } from './commands/skill-visibility.js';
 import { registerPrimerCommand } from './commands/primer-command.js';
 import { registerReinjectCommand } from './commands/reinject-command.js';
-import { applyRetention, cleanupEccCache } from '../services/log/retention.js';
+import { applyRetention } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
 import { printSuperCommandCatalog } from './cli-helpers.js';
 export { printErrorEnvelope, printResult } from './cli-helpers.js';
@@ -57,14 +57,9 @@ function bootstrapLogger(verbose) {
         // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         /* best-effort retention sweep; never block the CLI */
     }
-    // Slice 3 (on-demand-ecc): 7-day TTL sweep over ecc-<sha>/ cache dirs.
-    try {
-        cleanupEccCache({ retentionDays: 7, nowMs: Date.now() });
-    }
-    catch {
-        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        /* best-effort ECC retention sweep; never block the CLI */
-    }
+    // The ECC cache sweep that used to sit here is gone with the cache: ECC comes
+    // from the `ecc-universal` dependency, whose files expire when npm removes the
+    // package, not on a peaks-loop TTL.
     const dateOverride = process.env.PEAKS_LOG_DATE_OVERRIDE;
     const entry = {
         ts: new Date().toISOString(),

package/dist/services/code/mode-gate-types.d.ts

@@ -21,7 +21,7 @@ export declare const CODE_MODES: readonly CodeMode[];
  * "Inventory of unconditional confirmation gates" table. Each row
  * is the bare minimum needed to gate it through `shouldPauseAtGate`.
  */
-export type GatedStepId = 'step-0.5-openspec-opt-in' | 'step-0.6-audit-goal' | 'step-0.7-resume-detection' | 'step-0.55-1x-upgrade' | 'step-1-mode-select' | 'step-2.5-session-title' | 'phase-2-prd-confirm' | 'phase-3-swarm-gate-b' | 'phase-6-qa-gate-d' | 'phase-10-txt-memory-extract' | 'step-n+1-final-review' | 'frontend-only-mismatch' | 'step-0.75-checkpoint-resume' | 'standards-preflight';
+export type GatedStepId = 'step-0.5-openspec-opt-in' | 'step-0.6-audit-goal' | 'step-0.7-resume-detection' | 'step-1-mode-select' | 'step-2.5-session-title' | 'phase-2-prd-confirm' | 'phase-3-swarm-gate-b' | 'phase-6-qa-gate-d' | 'phase-10-txt-memory-extract' | 'step-n+1-final-review' | 'frontend-only-mismatch' | 'step-0.75-checkpoint-resume' | 'standards-preflight';
 export declare const GATED_STEPS: readonly GatedStepId[];
 /**
  * v2.15.0 slice 002 AC-4: the 5 action identifiers that qualify as

package/dist/services/code/mode-gate-types.js

@@ -18,7 +18,6 @@ export const GATED_STEPS = [
     'step-0.5-openspec-opt-in',
     'step-0.6-audit-goal',
     'step-0.7-resume-detection',
-    'step-0.55-1x-upgrade',
     'step-1-mode-select',
     'step-2.5-session-title',
     'phase-2-prd-confirm',

package/dist/services/code/mode-gate.js

@@ -74,19 +74,11 @@ export function shouldAutoProceed(mode) {
  * without user consent (defect #1: new Code session skipped Step 1
  * AskUserQuestion because `full-auto` mode triggered `shouldAutoProceed`
  * on `step-1-mode-select` itself).
- *
- * v2.18.4 slice 002-fix-first-run-step-gates: added
- * `step-0.55-1x-upgrade`. The 1.x → 2.0 upgrade is an irreversible
- * external side effect (migration rewrites config files and the
- * on-disk cache shape) — it must always pause, even in full-auto.
- * Without this, `full-auto` mode auto-proceeds and silently
- * downgrades a 1.x install to 2.0 without user consent.
  */
 const HARD_PAUSE_STEPS = new Set([
     'step-1-mode-select',
     'step-0.5-openspec-opt-in',
-    'step-0.7-resume-detection',
-    'step-0.55-1x-upgrade'
+    'step-0.7-resume-detection'
 ]);
 export function shouldPauseAtGate(opts) {
     if (opts.hardFloorCategory !== undefined && isHardFloorCategory(opts.hardFloorCategory)) {

package/dist/services/code/user-touchpoint-classifier.js

@@ -42,13 +42,6 @@ const RAW_CLASSIFICATION = [
         fullAutoCanProceed: false,
         userShouldReview: 'always'
     },
-    {
-        step: 'step-0.55-1x-upgrade',
-        kind: 'commit-floor',
-        description: '1.x → 2.0 升级检测。不可逆外部副作用(改写 config + cache schema),所有 mode 都必须 AskUserQuestion。full-auto 也暂停。',
-        fullAutoCanProceed: false,
-        userShouldReview: 'always'
-    },
     {
         step: 'step-0.75-checkpoint-resume',
         kind: 'tech',

package/dist/services/code-review/ecc-bridge.d.ts

@@ -21,12 +21,12 @@
  *
  * === Why no `peaksConfig.ecc.*` block ===
  *
- * ECC is shipped via the `everything-claude-code` plugin, not as a
- * separate npm package. The user installs the plugin (a one-time
- * marketplace step); peaks-loop does not write or read any LLM
- * endpoint config for ECC. If a future ECC release needs user-
- * managed config (URL / token / model), add a `peaksConfig.ecc.*`
- * block then — not speculatively now.
+ * ECC ships as the `ecc-universal` npm package — the same repository as
+ * github.com/affaan-m/ECC — and peaks-loop depends on it, so the agents are read
+ * from that dependency, not downloaded. ECC may ALSO be present as the
+ * `everything-claude-code` Claude Code plugin, the native path `detectEcc`
+ * prefers. Either way peaks-loop writes and reads no LLM endpoint config for ECC;
+ * add a `peaksConfig.ecc.*` block only when a release actually needs one.
  *
  * === Source: peaks-rd/references/parallel-review-fanout.md ===
  *