peaks-loop 4.1.1 → 4.1.3

package/.claude-plugin/marketplace.json

@@ -1,106 +1,195 @@
 {
   "metadata": {
     "pluginRoot": ".",
-    "version": "2.0.3"
+    "version": "4.1.3"
   },
   "plugins": [
     {
       "name": "peaks-loop",
-      "description": "Cross-AI-IDE workflow-gating CLI + 11-skill family. Turns LLM improvisation into auditable engineering process. Skills cover PRD / R&D / UI / QA / change-control / context / SOP definition / orchestration. Soft-fail gates block irreversible actions mid-conversation (even under --dangerously-skip-permissions).",
-      "version": "2.0.3",
+      "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
+      "version": "4.1.3",
       "author": {
         "name": "SquabbyZ"
       },
       "homepage": "https://github.com/SquabbyZ/peaks-loop",
       "repository": "https://github.com/SquabbyZ/peaks-loop",
       "license": "MIT",
-      "tags": [
-        "workflow",
-        "gating",
+      "keywords": [
+        "peaks-loop",
+        "loop-engineering",
+        "ai-orchestration",
+        "ai-coding-agent",
+        "ai-programmer",
+        "multi-agent",
+        "claude-code",
+        "codex",
+        "z-code",
+        "cursor",
+        "trae",
+        "tongyi-lingma",
+        "agent-harness",
+        "agentic-engineering",
+        "autonomous-workflow",
+        "workflow-orchestration",
+        "llm-workflow",
+        "long-running-task",
+        "sub-agent-dispatch",
+        "dag-orchestration",
+        "slice-decomposition",
         "sop",
+        "openspec",
+        "karpathy",
+        "darwin",
+        "anti-drift",
+        "evolution-evaluation",
+        "ci-cd",
+        "github-actions",
+        "trusted-publishing",
+        "oidc",
+        "monorepo",
+        "pnpm",
+        "vitest",
         "code-review",
-        "agent-team",
-        "cross-ide",
-        "claude-code",
-        "memory",
-        "second-opinion"
-      ],
-      "keywords": [
-        "AI IDE",
-        "agent guardrails",
-        "SOP engine",
-        "cross-IDE",
-        "developer workflow",
-        "irreversible-action gates"
+        "tdd",
+        "security-scan",
+        "lint",
+        "typecheck",
+        "devtool",
+        "cli",
+        "developer-tools"
       ],
+      "mcpServers": {
+        "peaks": {
+          "command": "peaks",
+          "args": [
+            "mcp",
+            "serve"
+          ]
+        }
+      },
       "skills": [
         {
-          "name": "peaks-solo",
-          "path": "./skills/peaks-solo",
-          "description": "Dispatcher (分诊员) — natural-language front door for the Peaks-Loop skill family. Use when the user describes a task in NL and does not know which peaks-* skill fits. NOT for code/content/doctor/issue-fix-orchestrator/SOP work (use the specific skill)."
+          "name": "peaks-audit",
+          "path": "./skills/peaks-audit",
+          "description": "Gate autonomous LLM work on a 6-dimension audit + user-accepted goal. Use IMMEDIATELY after a need is expressed, BEFORE any PRD/RD/QA work starts."
         },
         {
           "name": "peaks-code",
           "path": "./skills/peaks-code",
-          "description": "Full-auto orchestration facade for the Peaks-Loop skill family. Use when the user asks Peaks-Loop to handle a project workflow end-to-end."
+          "description": "Code-domain loop engineering orchestrator for the Peaks-Loop skill family. Use when the user asks Peaks-Loop to handle a code-repo workflow end-to-end (端到端/全流程/需求开发), especially from a product document (PRD/飞书文档/Feishu doc) through implementation and validation. Coordinates peaks-prd, peaks-rd, peaks-qa, peaks-ui, peaks-sc, and peaks-txt while preserving user confirmation gates. Triggers on `/peaks-code`, \"peaks code\", \"全流程开发\", \"端到端迭代\". General primitives (peaks-resume / peaks-status / peaks-test) are sibling skills, not children."
         },
         {
-          "name": "peaks-resume",
-          "path": "./skills/peaks-resume",
-          "description": "Resume an in-flight peaks-code slice in the current session."
+          "name": "peaks-content",
+          "path": "./skills/peaks-content",
+          "description": "Non-code orchestrator for content workflows (draft / edit / publish / archive). Use when a user wants to drive an end-to-end content-production loop (blog post, newsletter, marketing copy, social thread, doc page) where the LLM must coordinate draft / edit / tone / publish / archive stages with explicit gates between them, and where the user only wants to speak natural language and pick options. NOT for free-form chatting; NOT for code review. Reuses the peaks-loop Loop Engineering primitives (Loop Engineering Asset, Bee Asset, Workflow Trace, Evolution Evaluation) but does NOT import peaks-code internals. Triggers on `/peaks-content`, \"peaks content\", \"content workflow\", \"publish this to <channel>\", \"edit the draft\", \"archive the previous version\"."
         },
         {
-          "name": "peaks-status",
-          "path": "./skills/peaks-status",
-          "description": "Show the current state of the peaks-code orchestrator in a compact summary."
+          "name": "peaks-doctor",
+          "path": "./skills/peaks-doctor",
+          "description": "Orchestrate peaks-loop's L3 doctor (peaks audit + peaks doctor + peaks openspec from-doctor) for project health. Use when the user asks for a project health check, doctor report, audit, or wants to convert doctor findings into OpenSpec change records. Coordinates the L2 audit framework + the L3.2 doctor + the L3.3 from-doctor proposal generator. Triggers on `/peaks-doctor`, \"peaks doctor\", \"项目健康\", \"doctor report\", \"health check\", \"check the project\", \"audit my repo\".",
+          "userInvocable": false
         },
         {
-          "name": "peaks-test",
-          "path": "./skills/peaks-test",
-          "description": "Run the project's test suite on the current repo and report results."
+          "name": "peaks-final-review",
+          "path": "./skills/peaks-final-review",
+          "description": "Final-review skill for Peaks. Use when a workflow needs to assemble 4-dimension business-review evidence (functional-completeness, problem-resolution, no-new-bugs, existing-functionality-intact) for human acceptance at the end of an autonomous slice. Triggers on \"/peaks-final-review\", \"prepare final review\", \"4-dim review\", or peaks-code end-of-workflow handoff."
+        },
+        {
+          "name": "peaks-ide",
+          "path": "./skills/peaks-ide",
+          "description": "Orchestrate peaks-loop's IDE-aware behavior (hooks + statusline + handle) for a user's specific IDE. Detects the current state (which IDE the user is on, what peaks has already installed), plans the install / switch / status / uninstall actions, and invokes the existing peaks CLI primitives. Triggers on `/peaks-ide`, \"set up peaks for my IDE\", \"switch peaks to Trae\", \"what did peaks install\", \"uninstall peaks hooks\". Sits between the user and `peaks hooks install` / `peaks statusline install` / `peaks hook handle` — those are the CLI primitives; this skill is the user-facing surface.",
+          "userInvocable": false
+        },
+        {
+          "name": "peaks-issue-fix-orchestrator",
+          "path": "./skills/peaks-issue-fix-orchestrator",
+          "description": "End-to-end orchestrator that surveys open issues in a target repo, classifies them by difficulty, mines reference merged-PRs, fixes each issue with real commits (with Repository + AI-modified declaration), writes normalized PR description files, and emits a one-line submit script. Use when the user wants to drive a \"fix N open issues and prepare PRs\" run on an upstream repo (any language; primarily Python + TypeScript). Reuses Loop Engineering primitives: 4-layer asset model, Darwin ratchet, karpathy-engineered red lines, Human-NL-Choice-Only. Triggers on `/peaks-issue-fix-orchestrator`, \"fix 30 issues\", \"dogfood on <repo>\", \"open-issue sweep on <repo>\"."
+        },
+        {
+          "name": "peaks-perf-audit",
+          "path": "./skills/bee/peaks-perf-audit",
+          "description": "Independent performance audit skill. Reads the immutable peaks-prd handoff + the project-level perf-template.md, performs a 6-dimension perf audit, and writes a structured envelope to `.peaks/_runtime/<sessionId>/audit/perf-<rid>.md`. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 3). Use when the slice introduces CPU-bound hot loops, I/O throughput changes, memory allocation patterns, concurrency model changes, bundle size deltas, or cold-start costs.",
+          "userInvocable": false
         },
         {
           "name": "peaks-prd",
           "path": "./skills/bee/peaks-prd",
-          "description": "Product and requirement skill for Peaks. Use when a workflow needs PRD, refactor goals, non-goals, behavior preservation, acceptance criteria, product change proposals, or user-confirmable product artifacts.",
+          "description": "Product and requirement role for Peaks-Loop (LLM-only internal role; not user-invocable.\nTriggered by peaks-code via `peaks sub-agent dispatch --role prd`.)\nUse when a workflow needs PRD, refactor goals, non-goals, behavior preservation,\nacceptance criteria, product change proposals, or user-confirmable product artifacts.",
+          "userInvocable": false
+        },
+        {
+          "name": "peaks-qa",
+          "path": "./skills/bee/peaks-qa",
+          "description": "QA and verification role for Peaks-Loop (LLM-only internal role; not user-invocable.\nTriggered by peaks-code via `peaks sub-agent dispatch --role qa`.)\nUse when a workflow needs unit-test coverage evidence, regression matrices,\nbaseline reports, validation reports, acceptance checks, or refactor verification gates.",
           "userInvocable": false
         },
         {
           "name": "peaks-rd",
           "path": "./skills/bee/peaks-rd",
-          "description": "Research and development skill for Peaks. Use for engineering analysis, refactor planning, project scanning, code standards, unit-test coverage gates, implementation contracts, task graphs, and RD handoffs. Always use this for Peaks-Loop refactor workflows.",
+          "description": "Research and development role for Peaks-Loop (LLM-only internal role; not user-invocable.\nTriggered by peaks-code via `peaks sub-agent dispatch --role rd`.)\nUse for engineering analysis, refactor planning, project scanning, code standards,\nunit-test coverage gates, implementation contracts, task graphs, and RD handoffs.\nAlways use this for Peaks-Loop refactor workflows.",
           "userInvocable": false
         },
         {
-          "name": "peaks-qa",
-          "path": "./skills/bee/peaks-qa",
-          "description": "QA and verification skill for Peaks. Use when a workflow needs unit-test coverage evidence, regression matrices, baseline reports, validation reports, acceptance checks, or refactor verification gates.",
-          "userInvocable": false
+          "name": "peaks-resume",
+          "path": "./skills/peaks-resume",
+          "description": "Universal resume primitive for any in-flight Peaks-Loop workflow (orchestrator-agnostic). Detects the current session's deepest completed gate and surfaces a resume option via AskUserQuestion. Use when ANY bee (peaks-code, future peaks-research, future peaks-content, …) needs to recover from /compact or session interruption. Triggers on \"/peaks-resume\", \"continue the unfinished work\", \"继续完成\", \"把刚才没做完的收尾\". (Replaces peaks-resume as a top-level primitive.)"
         },
         {
-          "name": "peaks-ui",
-          "path": "./skills/bee/peaks-ui",
-          "description": "UI and experience skill for Peaks. Use when a workflow touches UI/UX, interaction design, visual direction, design systems, frontend page behavior, high-fidelity HTML prototypes, or UI regression seeds.",
+          "name": "peaks-reviewer",
+          "path": "./skills/bee/peaks-reviewer",
+          "description": "Third-party independent code-review skill for Peaks. Use as a parallel reviewer to karpathy-reviewer when a workflow needs an out-of-band (non-RD-model) review pass to mitigate single-LLM self-dogfood blind spots. Emits a schema-validated ReviewerEnvelope (no free-form LLM JSON). v2.14.0 G4.",
           "userInvocable": false
         },
         {
           "name": "peaks-sc",
           "path": "./skills/bee/peaks-sc",
-          "description": "Source control, sync, and change-control skill for Peaks. Use when a workflow needs change impact, artifact retention, commit boundaries, GitHub artifact repository pointers, sync state, or rollback evidence.",
+          "description": "Source control, sync, and change-control role for Peaks-Loop (LLM-only internal role;\nnot user-invocable. Triggered by peaks-code via `peaks sub-agent dispatch --role sc`.)\nUse when a workflow needs change impact, artifact retention, commit boundaries,\nGitHub artifact repository pointers, sync state, or rollback evidence.",
           "userInvocable": false
         },
         {
-          "name": "peaks-txt",
-          "path": "./skills/bee/peaks-txt",
-          "description": "Context and knowledge skill for Peaks. Use when a workflow needs context capsules, role-specific context slices, decision records, assumptions, discarded options, staleness checks, lessons, or reusable project memory.",
+          "name": "peaks-security-audit",
+          "path": "./skills/bee/peaks-security-audit",
+          "description": "Independent security audit skill. Reads the immutable peaks-prd handoff + the project-level security-template.md, performs an OWASP Top-10 + 8-dimension threat model audit, and writes a structured envelope to `.peaks/_runtime/<sessionId>/audit/security-<rid>.md`. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 2). Use when the slice introduces authn/authz, secrets, input validation, path/filesystem trust, SQL/NoSQL injection, XSS/content injection, dependency supply chain, or external API surface changes.",
           "userInvocable": false
         },
+        {
+          "name": "peaks-slice-decompose",
+          "path": "./skills/peaks-slice-decompose",
+          "description": "Run multi-pass slice decomposition on a PRD-ready request and emit a v2 envelope with passes, cross-pass edges, and an LLM-arbitration trace. Use when a PRD is ready and the caller needs service-level and/or file-level cuts in one artifact."
+        },
+        {
+          "name": "peaks-solo",
+          "path": "./skills/peaks-solo",
+          "description": "Dispatcher (分诊员) for the Peaks-Loop skill family. Use when the user describes a task in natural language and does NOT know which peaks-* skill fits. peaks-solo reads the live skill pool via `peaks skill search`, dispatches to a matching leaf (peaks-code / peaks-content / peaks-doctor / peaks-issue-fix-orchestrator / etc.) or falls back to self-planned execution (deep-search / WebSearch / Bash / Edit markdown) if no leaf matches, and then asks the user whether to sediment the result.\n\nTriggers: 自然语言描述诉求且无明确 peaks-* skill 选择 / \"帮我处理这个\" / \"我不知道该用哪个\" / \"随便都行\".\n\nNOT for: code-specific work (use /peaks-code) / content-specific work (use /peaks-content) / project health check (use /peaks-doctor) / issue sweep (use /peaks-issue-fix-orchestrator) / SOP authoring (use /peaks-sop)."
+        },
         {
           "name": "peaks-sop",
           "path": "./skills/peaks-sop",
-          "description": "Authoring skill for user-defined SOPs in Peaks. Use when a user wants to create, edit, debug, or register their own gated workflow."
+          "description": "Authoring skill for user-defined SOPs (standard operating procedures) in Peaks. Use when a user wants to create, edit, debug, or register their own gated workflow — ordered phases plus gates that block advancement until conditions are met — by describing it in natural language instead of hand-writing JSON or memorizing CLI commands. DOMAIN-AGNOSTIC: not just software/release flows — equally for content publishing, compliance and approval checklists, data pipelines, onboarding, ops runbooks, or any personal repeatable procedure, wherever \"don''t enter the next stage until X is true\" applies and X is checkable via a file, file content, or a command."
+        },
+        {
+          "name": "peaks-status",
+          "path": "./skills/peaks-status",
+          "description": "Universal status primitive for any in-flight Peaks-Loop workflow (orchestrator-agnostic). Reads the existing CLI primitives (peaks skill presence, peaks session list, peaks project dashboard, peaks request show) and renders a 1-screen status table. Use when the user asks \"where are we\", \"现在到哪了\", \"what's the current state\" for ANY bee (peaks-code, future peaks-research, …). Triggers on \"/peaks-status\", \"现在到哪了\", \"what is the current state\", \"show me the dashboard\". (Replaces peaks-status as a top-level primitive.)"
+        },
+        {
+          "name": "peaks-test",
+          "path": "./skills/peaks-test",
+          "description": "Universal test-runner primitive for any in-flight Peaks-Loop workflow (orchestrator-agnostic). Runs the project's test suite on the current repo and reports results. Use when the user asks \"run the tests\", \"跑一下 test\", \"跑测试\" for ANY bee (peaks-code, future peaks-research, …). Triggers on \"/peaks-test\", \"跑一下 test\", \"跑测试\", \"run the tests\", \"test now\". (Replaces peaks-test as a top-level primitive.)"
+        },
+        {
+          "name": "peaks-txt",
+          "path": "./skills/bee/peaks-txt",
+          "description": "Context and knowledge role for Peaks-Loop (LLM-only internal role; not user-invocable.\nTriggered by peaks-code via `peaks sub-agent dispatch --role txt`.)\nUse when a workflow needs context capsules, role-specific context slices, decision records,\nassumptions, discarded options, staleness checks, lessons, or reusable project memory.",
+          "userInvocable": false
+        },
+        {
+          "name": "peaks-ui",
+          "path": "./skills/bee/peaks-ui",
+          "description": "UI and experience role for Peaks-Loop (LLM-only internal role; not user-invocable.\nTriggered by peaks-code via `peaks sub-agent dispatch --role ui`.)\nUse when a workflow touches UI/UX, interaction design, visual direction, design systems,\nfrontend page behavior, high-fidelity HTML prototypes, or UI regression seeds.",
+          "userInvocable": false
         }
       ]
     }
   ]
-}
+}

package/CHANGELOG.md

@@ -1,5 +1,111 @@
 # Changelog
 
+## 4.1.3 — 2026-10-09 (只读 MCP 能力面首次发布：把"只读"做成可证伪的东西；两处"工具在说假话"的修复；三批尺寸债，以及门禁自己被加固)
+
+**版本级别**: 未发布区间 `v4.1.2..HEAD` 共 **20 个 commit**（2 feat / 3 fix / 4 refactor / 2 chore(gate) / 2 merge / 其余 docs+memory）。取 **patch**，依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。
+
+**但此处必须如实记一笔**：本版**确实新增了命令族**（`peaks mcp serve|install|uninstall`）。4.1.2 那条写的是"取 patch：本版不新增命令"，本版**不适用那句**——取 patch 是常设规则的默认，不是"没有新增命令"。按严格语义化版本，新增用户可见命令应当取 minor。4 个 workspace 包各 +1 patch（shared 0.0.91→0.0.92、internal-runtime 0.0.42→0.0.43、mut 0.1.56→0.1.57、shared-channel 0.0.59→0.0.60），`CLI_VERSION` 与 `RUNTIME_VERSION` 由 `scripts/sync-version.mjs` 同步（`bump-version.mjs` 只管清单，两者都在 tag 之前，否则 publish.yml 的 `gate-cli-version` 会在 `npm publish` 前中止）。
+
+### 1. 只读 MCP 能力面（2 feat）——核心不是"能调用"，而是"只读这件事被证明过"
+
+`peaks mcp serve` 把既有的非 gate 能力以 MCP stdio 暴露给 AI Harness；`peaks mcp install|uninstall` 把它注册进 harness。**CLI 不删**，MCP 是并列的一条调用路径。
+
+**"只读"不是一句声明，是一条可证伪的断言。** 分类键是**完整 argv**（含 flag），不是命令名——13 个命令族全部读写成对存在，有些**默认就是写**，只看命令名会把写当成读。白名单是手写真源（`contracts/readonly-surface.json`）+ 生成物（`contracts/readonly-argv-whitelist.json`），生成物才是运行时读的那个。
+
+证明分三层：(A) 文件系统 + state-store 快照差分；(B) 进程内对 `child_process` / `fetch` / `http(s).request` 的测试替身拦截；(C) CI-only 的无网络只读挂载沙箱。执行面分 L1–L4 四层，其中 L3 是 PreToolUse matcher 覆盖，**MCP 分支 fail-closed**（与 Bash 分支的 fail-open 相反）——这条分支被刻意放在强制链最前面，因为 MCP 工具名既不匹配 Bash matcher 也不是 worktree 工具，放在后面会被直接放行。
+
+**客户端那一跳已实测**：真 Claude Code 2.1.295 上 `claude mcp add … peaks -- <node> <bin/peaks.js> mcp serve` 被原样接受，`claude mcp list` 报 `✔ Connected`，即 harness 真的 spawn 了 server 并完成握手。这是本能力**唯一无法在离线环境推断**的一步，也是这一版敢发出来的理由。
+
+**注意**：`peaks mcp install` 会**写用户的 `~/.claude.json`**（user scope），卸载会扫掉全部已声明 scope。这是本仓第一次发出去会改用户环境的命令。
+
+### 2. 两处"工具在说假话"（2 fix + 1 fix(baseline)）
+
+**`peaks mcp uninstall` 在删不掉时返回 `ok: true` 并断言"no registration was present"。** 实测：注册项仍在（`claude mcp get peaks` 仍 `✔ Connected`），harness 配置前后逐字节相同，而移除命令**超时被杀**。根因是 `runMcpUninstallPlan` 把**任何**失败的移除都归入 `absent`，然后无条件 `ok: true`。安装侧容忍失败的移除是对的（紧接着就要写，旧项在不在无关紧要），卸载侧不成立——移除**就是**那个操作。修法只划一条**不需要读 harness 输出**的界（读它的英文是 vendor-specific，本仓禁止）：`exit 0` → 已移除；`exit ≠ 0` → 它**表了态**（absent，不变）；**超时/未启动 → 它从未给出裁决**（`unknown`，`ok: false`）。`detail` 从此只在所有 scope 都表了态且都没找到时才说"没有注册项"。
+
+**同一分支还漏了信息**：失败信封的 `data` 只带 `{ ide }`，整份 report 被丢掉——而这条分支在本次改动之前**不可达**（卸载恒为 `ok:true`），所以这个信息丢失是本版引入并本版修掉的。R3 场景（一个 scope 移除成功、另一个从未答复）下，`--json` 的消费者现在看得见 `removed`。
+
+**`npx` / `npm` 解析器差一级目录。** `locateNpmCliScript` 在 win32 上从 `process.execPath` 往上找**两级**，而标准 Windows 布局（MSI、zip、nvm-for-windows）都是**一级**。在第 3 个硬编码候选（`C:/Program Files/nodejs`）也不存在的机器上，它找不到 `npm-cli.js` / `npx-cli.js`，**静默回退到裸名 `npx`/`npm`**——正是这个模块被写出来专门要绕开的那个 `.cmd` shim。长期不可见是因为那个硬编码候选恰好命中默认安装与 CI 的 `windows-latest`。
+
+### 3. 门禁自己被加固（2 chore(gate)）
+
+**两条不会失败的门被修成会失败。** `peaks-gate staged`（无参）曾打印 `EMPTY CHANGE SET — NOTHING WAS CHECKED` 却 **exit 0**；`format:check` 与 pre-commit 的范围本就不一致而 CI 根本没跑它。后者接进 CI 时被写成**集合包含**棘轮而非计数棘轮——一个计数看不见**替换**（删一个、加一个，计数不变）。
+
+**单调守卫的第一个、也是唯一一个例外**：`fileSizeOverCap`（文件数）与 `fileSizeExcessLines`（超出行数）各自独立棘轮，而规则是"任一 key 高于基线即拒"。于是把 1125 行拆成 2 份、每份仍 >300 时 `overCap 1→2` 被拒——一个**把超出行数降下来的改动**被挡住。新政策：`overCap` 允许上涨，**仅当**同一次变更中 `excess` 严格下降；双升则拒。
+
+**基线生成器在本版拒绝过两次，两次都是改源码而不是抬 ceiling**：一次 `commentNarrativeLines: 22 → 24`（新模块头注释写了切片名，而 `rid-id` 是 8 个 NARRATIVE_MARKER 之一），一次 `comment narrative: 63 > ceiling 22 (+41)`。这条拒绝路径在本版内**真的被执行过**，不是事后补的说辞。
+
+### 4. 三批尺寸债（4 refactor）——能降 ceiling 的只有 `src/`
+
+`src/cli/commands` 从 10 个最严重的文件拆成 110 个模块（三批），`scripts/` 4 个文件拆成 16 个模块。**四个 ceiling 全部下降，无一上升**：
+
+```
+eslintFindings     2055 -> 1951      fileSizeOverCap      122 -> 112
+eslintErrors        770 ->  709      fileSizeExcessLines 35536 -> 30352
+```
+
+**配方是"拆分与压函数必须在同一次交付里完成"**，这条是血换来的：第一批只拆，`eslintFindings`/`eslintErrors` 被**推高** +23/+19（把一个长函数切成 helper 之后，原函数在压缩前必然仍超 50 行），被拒后第二遍才把 51 个函数压到 0；第二、三批一次做完，分别 −61 和 −43。
+
+**`scripts/**` 与 `tests/**` 是 shadow 人口，不受任何 file-size ceiling 约束**（`gate/legs.mjs` 只 check `partition.gated`）。拆它们**不移动任何 ceiling**——实测前后均为 `117 / 32979`，移动的只有 census 与 shadow 块。它们是被 owner（2026-10-03）刻意排除在 ceiling 之外的，本版如实记录这一点，而不是把"拆了 4 个文件"说成还了 ceiling 的债。
+
+### 5. 未验证（记录而非隐瞒）
+
+- **C 层沙箱从未实跑**（CI-only，本仓无 runner）；`format:check` job 同样**从未在 runner 上跑过**。
+- **L3 端到端未验**：PATH 上的 `peaks` 是已安装构建而非工作树。
+- **S1 政策例外的端到端触发未验**：机制只在纯函数层被测，"允许涨" ≠ "已经涨过"。
+- **MCP 只读证明的白名单覆盖面**：分类键是完整 argv，但白名单是手写枚举；一条新命令若忘记分类会落到默认分支。`_no-mcp-source-import-scan` 守着"服务层不得 import MCP"这条不变量，但**不守**白名单本身的完备性。
+- **`scripts/**` 的债是自愿还的**，没有任何门会因为不还而变红（见 §4）。
+- **发布路径的一处结构性冲突（过程，非产品）**：`git push origin <tag>` 单独推送**永远过不了本仓 pre-push 门**——只推 tag 时 `origin/main...HEAD` 为空，而门在空变更集上按设计拒绝（"nothing to compare ≠ compared and clean"）。也就是说**每一次发布都必须靠一次 `--no-verify`**，恰是本仓钩子注释里警告过的形状。本版未修（属门机器，须单独立项）。
+
+## 4.1.2 — 2026-10-08 (资产真源落地: 升级不再静默冻结入口; codegraph 换上 1.6.2 的包模型, 顺带照出一条从未响过的失败路径)
+
+**版本级别**: 未发布区间 `v4.1.1..HEAD` 共 **14 个 commit**（6 feat / 3 fix / 1 refactor / 1 test / 3 docs）。取 **patch**：本版不新增命令，不改变任何既有命令的输入输出形状 —— 两件主要工作都是"让已经承诺的行为真的发生"。4 个 workspace 包各 +1 patch（shared 0.0.90→0.0.91、internal-runtime 0.0.41→0.0.42、mut 0.1.55→0.1.56、shared-channel 0.0.58→0.0.59），与 `scripts/bump-version.mjs` 的 lockstep 规则（每个可发布包跟随根版本 +1 patch）一致；实测子包自身的 `version` 字段**不进** `pnpm-lock.yaml`（workspace 依赖在 lock 里是 `link:` 形态、importer 条目为 `packages/peaks-loop-shared: {}`，无版本行），故本版**不需要**改 lockfile。
+
+### 1. 资产真源：升级不再静默冻结入口（4 feat + 1 refactor + 1 test）
+
+原先三个安装器（`installBundledSkills` / `installBundledAgents` / `installBundledOutputStyles`）把归属判断写成 `resolve(marker.sourcePath) === resolve(sourcePath)`，比对的原件是**装它的那个版本**的包路径。实测这条路径里带 node 版本号（`…\nvm\v24.21.0\node_modules\…`），于是这个判断本身就是一个"版本内有效"的事实：一次 node 升级之后的第一次 `npm i -g peaks-loop@latest`，此后每一次运行都会**跳过**该条目 —— 既不更新，也不报错。而唯一的修复路径 `reconcileJunctions` postinstall 从不传入，其余所有情况都落到一个**无声的** `skipped`：升级既不修旧链，也不说没修。本机实测：8 个 IDE 目录 × 44 个 `peaks-*` 条目，全部解析进同一个包路径。
+
+现在三族都走真源（skills 原本已走，agents / output-styles 在 `4e1bd85a` 补齐）：`~/.peaks/{skills,agents,output-styles}/<name>` 放真副本，IDE 侧入口指向它 —— 升级变成**重写一份副本，而不是重指 176 条链**。归属由 `.peaks-managed` 边车 + 两侧 `realpath` 决定，**绝不用字符串相等**（Windows junction 的 `readlinkSync` 拼写不保证，这正是旧安装器里那处脆弱点，新模块不许抄它）；旧的 JSON 边车按两条臂之一收养 —— 记录的包路径已不再解析（更早一次安装），或那个路径**就是**正在安装的这个包（原地升级）；记录的路径解析到**另一个活的包**则原样不动 —— 那是第二份安装，不是陈旧的。
+
+Windows 不给**文件**符号链接（没有开发者模式或管理员时），而 skills 用的 junction 从不需要这个权限。宿主拒绝时写实体副本（保留"每次运行都保持最新"的语义），并在返回值与 stderr 上说明这次拒绝 —— `copied` 与 `skipped` 现在各自说得出自己是哪一个；一次不带理由的降级与一次成功无法区分。
+
+`dbf91c25` 把真源根从 `~/.agents` 改成 `~/.peaks`（owner 在本次 job 内改的决定）：`~/.agents` 是**共享命名空间**（`npx skills`、agentrecall、agentlink 都往那里写），而 `~/.peaks` 是 peaks-loop 自己的家且**已在使用**（实测 `~/.peaks/agents/` 存在并持有 `ecc`）；共享约定唯一的好处（给原生读它的工具省一条软链）本次**没有任何测量**证明过。环境变量复用 `PEAKS_HOME`（`peaksHome()`，`src/services/sop/sop-paths.ts:29`）而非新造一个 —— 一个目录两个旋钮就是一对可以互相矛盾的值。
+
+`e08dc4af` 补上最后一块：安装器此前**只会加**。把某个 skill 从包里删掉，它的真源副本、各 IDE 目录里的链、`.peaks-managed` 边车会永远留在用户机器上 —— 这与"更新"的含义不符。新的 `canonical-store-prune.mjs` 删真源条目 / IDE 链 / 边车，凡是 `isManagedEntry` **证明不了**是自己的一律保留；顺带把 `ensureCanonicalCopy` 原先无条件的 `rmSync` 换成 `action: 'unmanaged'`（→ `skipped`）—— 那正是根目录搬迁时记下的隐患：`~/.peaks/agents/` 真的有一个 peaks-loop 自己建的 69 条目 `ecc/`，一个同名捆绑资产本会把它静默删掉。**负控是本片重点**：用户自建的真目录 `peaks-gamma`（无边车）同时放进真源与 IDE 目录，`pruned: []`，两者逐字节存活；把 `isManagedEntry` 强制成 `return true` 则三臂转红。端到端实测（一次性 HOME / USERPROFILE / PEAKS_HOME）：装 alpha 与 beta、从包里去掉 alpha、重跑 —— `pruned: ["skills/peaks-alpha", "…\.claude\skills/peaks-alpha"]`，四件产物全消失，beta 未动。
+
+**发布白名单是本版反复咬人的一处。** `package.json#files` 是 npm 发布白名单，而仓库里**没有任何东西读它** —— 一个不在里面的模块会让每一个已发布包的用户在 `ERR_MODULE_NOT_FOUND` 上崩掉，而整个测试套件保持全绿。本分支三次踩到（`canonical-store.mjs`、`canonical-store-prune.mjs`、`canonical-store-link.mjs`）：slice 1 加文件时无人导入，`npm pack --dry-run` 给出 `canonical-store shipped: false`，直到 slice 2 接上 import 才暴露。`87d2b86b` 把一条"枚举两个模块名"的守卫（第三个模块出现就会放行）换成 `install-skills-published-modules.test.ts` —— 从安装器自己的相对 import 里**读出规则**，没有表要维护；解析器先断言解析结果非空，再用同一份解析器跑 fixture 文本，于是"解析器退化成空转"会被它自己的读法抓住，而不是被它恰好指向的文件抓住。
+
+**本版未测（记录而非隐瞒）**：trae / codex / cursor 是否跟随文件符号链接（只探过 Claude Code 2.1.292）；以及一次自然发生的、无开发者模式下的 EPERM。**记录未修**：手工删掉一条链会让对应 IDE 边车变成孤儿，prune 不扫这种情况（有意的范围限制）；nvm 用户保留旧 node 版本时那条包路径仍可解析，条目会两条收养臂都不落，现在报在 stderr 上（此前无声）。
+
+### 2. codegraph 升到 1.6.2：包模型换了骨，配置轴反了向（2 feat + 1 fix）
+
+`0.7.10` → `1.6.2` 的升级**不是**表面工作。在 Node v24.21.0（ABI 137）上 `better-sqlite3@11.10.0` 没有预编译二进制，0.7.10 的原生后端在本机根本建不起来，`prebuild-install` 落到 `node-gyp`（需要 Visual Studio），于是退到 `node-sqlite3-wasm` —— 而它打不开 WAL 模式的数据库（带对照实测：DELETE 模式打开、WAL 模式报 `unable to open database file`）。也就是说 codegraph 在这台机器上**已经死了好几天**，每一次 RD 派发都在静默降级。1.6.2 是自包含的，直接用 Node 内建的 `node:sqlite`，完整 WAL。
+
+**包模型**：1.6.2 的主包 `dist/` 下**没有可执行 JavaScript**（只有 `.d.ts`）加两个 shim，代码在一个自带 `node.exe` 的平台子包里。于是 `dist/types.js`、`dist/extraction/grammars.js`、`dist/bin/codegraph.js` 全是 MODULE_NOT_FOUND —— 正是 peaks-loop 全部的 spawn 目标。新的 `codegraph-upstream-layout.ts` 是这四个触点的**唯一**定位器：先探 `<平台包>/lib/dist/bin/codegraph.js`（1.6.x），再退回 `<主包>/dist/...`（0.7.x）；必须经 `createRequire(<主包>/package.json)` 解析，因为平台包只链在主包自己的 `node_modules/` 里。
+
+**配置轴是一个陷阱**：1.6.2 不只是把配置文件从 `.codegraph/config.json` 搬到 `<root>/codegraph.json`，它把 `include` 的**语义反了**。0.7.x 里 `include` 是白名单；1.6.x 里它的意思是"即使被 .gitignore 丢掉也强行纳入索引"，准入模型是 `force-include`。只换路径的改法会把**每一个**受支持的 tracked 文件报成缺口 —— 一个看起来像绿的、方向相反的失败。新的 `codegraph-project-config.ts` 通过探测上游同时定出**源**与**模型**，两条臂都对着真实的 0.7.10 与 1.6.2 安装测过。
+
+两个 reconciler 的处置都写明而不是暗示：`codegraph-include-reconciler.ts` **删除** —— 它的前提是上游那份 32 条默认模板（1.6.2 已无），它的动作是往 `include` 追加 78 条 `**/*.ext`，在 1.6.x 下会把 gitignore 掉的源码**强行塞进**索引；只重定向读会留下这条写路径仍是活的，那是更坏的结果。`codegraph-exclude-reconciler.ts` **保留、但把范围收窄**到项目自撰的 `exclude`，读写两端都搬到真实源。**顺带修掉一条活的缺陷**：exclude reconciler 原先用 `include` 做预过滤，而 1.6.x 下 `include` 什么都不准入，于是这道闸**从来不会触发** —— 在那种组合存在多久，它就无声了多久。
+
+`e60948bf` 明确**推迟**验收判据 1（`peaks codegraph status` 在 1.6.2 下退出 76，因为完整性轴读 `.codegraph/config.json`，那是 1.6.2 从不写的文件；在**新初始化的真实 git 仓库**上复现：`init` 退出 0，`status` 退出 76 并报 `ENOENT`），`c61bf331` 把它关掉：现在退出 0，且该轴是**真的被求值**而不是被跳过 —— 一个全新的 1.6.2 git 仓库上 `--peaks-json` 给出 `indexIntegrityVerdict: "clean"`、`admissionModel: "force-include"`、`trackedSourceCount: 2`、`admittedTrackedCount: 2`、`indexedFileCount: 2`、`gap: false`、`includeGap: []`、`deadRows: []`，这些数字与那个仓库里的两个文件相符，是量出来的而不是默认值。
+
+**一条因为上游而非并发而闪的臂**：1.6.2 自己会在约 **1.3%** 的 `init` 调用上以 `0xC0000005` 中止进程，而且是**串行**的 —— 一个只做单次 spawn、不用 vitest 的最小工装实测 458 次里 6 次中止，stdout 每次都停在同一字节，那里 `extraction/index.js` 正在建一个 8 线程的 `ParseWorkerPool`；`status`（该臂真正的主语）从不中止（0/80）。上游的 `--liftoff-only` 启动器形态修不了它（1/318，Fisher p≈0.13），所以**不许**在生产调用里粉饰。修复只落在测试里：**只**重试 setup 那次 spawn、只认那一个退出码、上限三次、每次换新项目目录；`status` 永远只 spawn 一次；每条漂移断言逐字节未动；另有一条对照臂钉住"只有一个退出码可重试"。残余 ≈ 2.2e-6 每次运行。**仍然敞开并记录在案**：生产有同样的 ~1.3% `init` 暴露面（每一个消费者的 `peaks codegraph init` 都会以那个频率中止），真正的修复属于 `src/services/codegraph/`，本片被划在范围之外。
+
+**失败原因进入 dispatch（`33fdefdf`）**：RD 派发块读的是 `preflight.available ? preflight.block : null`，于是 codegraph 一旦失败，preflight 的 `note`（上游原因的唯一载体）就被丢掉，提示词退回一句常量"codegraph unavailable — proceeding on project-scan only"。失败分支因此渲染出一段**读起来与正常状态一模一样**的块，每个 dispatch 记录里，坏索引与健康索引无法区分 —— codegraph 在这台机器上坏了这么久没被注意到，就是这么来的：上游一直在说 `Failed to index: unable to open database file`，而派发路径上没有任何东西复述它。新的 `codegraph-unavailable-block.ts` 负责渲染原因，退回常量改成"没拿到原因"而不是暗示"没有原因"；手臂同时判别**有**与**无**（一条断言该块**不**包含裸露的上游行），所以"渲染了某个 note"不能满足它们。修复前把四个源文件回退到 HEAD、只留新模块，观察到的是一次断言失败而非加载错误：6 failed / 4 passed。
+
+### 3. 两次"新文件对门禁不可见"（2 fix）
+
+`.husky/` 的 census 腿走的是 `git ls-files`，所以新文件在未 track 时**门禁看不见** —— 本分支两次踩到（`f8073e1f` 对 slice 1 的四个新文件，`b88c4056` 对 tripwire 的三个）。两次都发生在 RD 报告与全量套件都跑了、都报绿的状态下；是 commit 让文件可见，下一次运行就有三个失败。第二次发生在这条教训**已经写进** `sediment-backlog.md` 一小时之后，所以它被记成"必须改的做法"而不是一条事实：一片的验收运行必须在文件已提交的状态下取，或者那次运行必须自己声明是未 track 时取的。`b88c4056` 用 `node .husky/peaks-gate-baseline.mjs` 重生成基线（该生成器只在有人要求抬高上限时拒绝）。
+
+`f8073e1f` 还含一行不显眼的配置：`config/eslint/tsconfig.lint.json` 加上 `../../scripts/canonical-store.mjs`。这不是装饰 —— `.mjs` 会被同名的 `.d.mts` 在 TypeScript 的扩展名优先级组 `[.mts, .d.mts, .mjs]` 里遮蔽，`include` glob 于是**静默丢掉**那个 `.mjs`；`.js` 被 `.d.ts` 遮蔽有豁免，`.mjs` 没有。
+
+### 4. 文档与记忆（3 docs）
+
+`2a70a651` 补上 `.peaks/docs/canonical-store.md`（真源模型、升级会发生什么、怎么验证与回退，含 4.1.1 升级 runbook）—— 一个跨四个 slice 落地的机制此前没有一页描述它，而它引入的两条行为是用户会**不被告知**就遇上的；README 加上短版与指针。`backlog.md` §2.56 记录缺陷：边车用字符串比较安装版本的包路径来判定归属，那是一条带 node 版本号的路径，所以这个判断是"版本内有效"的事实。页面里每一条行为断言都带代码引用，共 17 处，逐条对着它点名的行核过。`594be46f` 沉淀三条教训（后端被换掉之后要查能力而不是查标签；census 守卫看不见未 track 的文件，所以 pre-commit 绿不是绿；不带理由的降级与成功无法区分），索引到 448 files / 106 lessons。`17c7e2a8` 沉淀"守卫点了规则的名、却只查了名单"这一次：规则读取型守卫需要两条防御 —— 先断言解析非空（否则"什么都没找到"会以"对零个元素循环"的形式通过），以及把同一份解析器喂给 fixture 文本。
+
+### 5. 本版验证
+
+`tsc --noEmit -p tsconfig.json` 退出 0；`pnpm build` 退出 0；`pnpm test:unit` 退出 0 —— **406 files / 4238 passed / 3 skipped / 0 failed**（与改动前逐字相同）；版本 parity `shared-dist`（`OK (via import) CLI_VERSION=4.1.2`）与 `runtime-src`（`OK (via extract) RUNTIME_VERSION=4.1.2`）双双退出 0；`peaks changeset check --project . --json` 返回 `ok: true`（`state: staged-empty`），`.changeset/` 仍**只有** `config.json`；`peaks baseline diff --project . --json` 退出 0（15 行）；**`peaks baseline audit --project . --json` verdict 为 `consistent`**（15/15 journey，crossCheck `guardVsAudit: agree`，`findings: []`）。README 两版的**版本徽章行**更新到 `4.1.2(2026-10-08)` / `4.1.2 (2026-10-08)`，而 `README.md:107` 正文那句"从 4.1.1 升级时会发生什么"是**有意保留的历史陈述，未改动**。
+
 ## 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。

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.1 (2026-10-05) |
+| **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.3 (2026-10-09) |
 | **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 |
@@ -292,10 +292,10 @@ It changes, but **the gates hold**. Audit fails = nothing ships. QA fails = noth
 
 If you maintain a project that depends on `peaks-loop` (or that runs `npm install peaks-loop` as part of CI / contributor onboarding), three behaviors are worth pinning in your head:
 
-- **`codegraph` is a transitive dependency.** `peaks-loop` pins `@colbymchenry/codegraph@0.7.10` in its `dependencies`, so `npm install` / `pnpm install` will pull it automatically. The CLI command group `peaks codegraph …` (status / init / index / query / files / context / affected) is shipped inside `dist/services/codegraph/`. No extra install step required.
+- **`codegraph` is a transitive dependency.** `peaks-loop` pins `@colbymchenry/codegraph@1.6.2` in its `dependencies`, so `npm install` / `pnpm install` will pull it automatically. The CLI command group `peaks codegraph …` (status / init / index / query / files / context / affected) is shipped inside `dist/services/codegraph/`. No extra install step required.
 - **`.codegraph/` directory ownership is shared.** Tools like aider, cody, and similar agents also create a top-level `.codegraph/`. `peaks codegraph init` will refuse to overwrite a foreign schema and exits with code 73 + a `CODEGRAPH_INIT_CONFLICT` envelope. If your project already has a `.codegraph/` from another tool, move / rename it (or remove it if you no longer need it) before running `peaks codegraph init`.
 - **Session binding lives under `.peaks/_runtime/<sessionId>/`.** Codegraph orchestration context (and other per-session evidence) is written there by RD / QA slices. Add `.peaks/_runtime/` to your project's `.gitignore` to avoid committing local session state. A missing / unbound session produces a graceful skip-with-warning, never a crash.
-- **Doctor fallback for yarn-pnp / pnpm-strict.** `peaks doctor` falls back to a filesystem walk when `require.resolve('@colbymchenry/codegraph/package.json')` throws, so downstream installs under strict resolution modes still get a green check (or a `severity: 'warning'` if the version drifted from the pinned `0.7.10`).
+- **Doctor fallback for yarn-pnp / pnpm-strict.** `peaks doctor` falls back to a filesystem walk when `require.resolve('@colbymchenry/codegraph/package.json')` throws, so downstream installs under strict resolution modes still get a green check (or a `severity: 'warning'` if the version drifted from the pinned `1.6.2`).
 - **Tarball size / verify.** Each release ships the codegraph service under `dist/services/codegraph/`. Per-release verification lives at `scripts/verify-codegraph-tarball.mjs` (run `node scripts/verify-codegraph-tarball.mjs` locally before tagging a release). Exit 0 means the whitelist is intact; exit 1 means the tarball is missing the codegraph service files.
 
 Install snippet (typical consumer):
@@ -315,7 +315,7 @@ npx peaks doctor --project .
 Three common pitfalls:
 
 1. **`peaks codegraph init` exits 73** — your project has a pre-existing `.codegraph/` from another tool. Move it out of the way (or remove it), then re-run.
-2. **`peaks doctor` warns about codegraph version drift** — your lockfile resolved a different `@colbymchenry/codegraph` version than the pinned `0.7.10`. Pin to `0.7.10` in your lockfile; the warning does not flip the doctor exit code.
+2. **`peaks doctor` warns about codegraph version drift** — your lockfile resolved a different `@colbymchenry/codegraph` version than the pinned `1.6.2`. Pin to `1.6.2` in your lockfile; the warning does not flip the doctor exit code.
 3. **Session-bound artifacts under `.peaks/_runtime/` are noisy in `git status`** — add the path to your project's `.gitignore`. The `peaks-loop` repo already does this; consumers should mirror the rule.
 
 ---

package/README.md

@@ -88,6 +88,27 @@ npm i -g peaks-loop
 
 ---
 
+## 装上以后，文件放在哪
+
+`npm i -g` 之后，三类资产（**skills / agents / output-styles**）的**实体只存一份**，放在你自己 home 下的
+`~/.peaks/{skills,agents,output-styles}`；每个 IDE 目录里（`~/.claude/…`、`~/.trae/…` 等）的条目都是**指向它的链接**
+（目录用 junction，单个 `.md` 文件用符号链接）。所以升级 `peaks-loop` 时链接目标不变、不需要重建，也不会因为
+包路径（里面嵌着 node 版本号）变化而静默断裂。
+
+两件会直接影响你的事：
+
+- **受管入口会在升级时被覆盖。** 由 peaks-loop 装进去的入口（比如 `~/.claude/agents/karpathy-reviewer.md`）旁边有一份
+  `.peaks-managed` 边车标记归属，升级时内容会被更新。**想换成你自己的版本，删掉那份额边车即可** —— 没有标记的入口
+  一律视为你自己建的，**永不被替换、也永不被删除**。
+- **有些 Windows 机器上会退化成实体副本。** 没有开发者模式、也不是管理员时，建不出**文件**符号链接（目录用的 junction
+  不受影响），安装器会写实体副本并在 stderr 明说 `installed as REAL COPIES because this host refused a symlink`。
+  内容照样跟着升级走，只是不再与真源共享同一份。
+
+真源根可用环境变量 `PEAKS_HOME` 重定向。完整的模型、从 4.1.1 升级时会发生什么、怎么验证与回退 →
+[`.peaks/docs/canonical-store.md`](./.peaks/docs/canonical-store.md)。
+
+---
+
 ## 它能为你做什么
 
 代码、内容、项目健康、issue 修复、自定义工作流 —— **4.x 已经覆盖五条域**,每条域都有专门编排器,按"门禁不通过就停"的纪律一条一条跑。
@@ -154,7 +175,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.1(2026-10-05) |
+| **最新版本** | [![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.3(2026-10-09) |
 | **覆盖域** | 代码(`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 |
@@ -292,10 +313,10 @@ winget install Python.Python.3.12
 
 如果你的项目依赖 `peaks-loop`(或者把 `npm install peaks-loop` 写进 CI / 协作者 onboarding),有三件事需要先记清:
 
-- **`codegraph` 是传递依赖。** `peaks-loop` 在 `dependencies` 里硬钉 `@colbymchenry/codegraph@0.7.10`,所以 `npm install` / `pnpm install` 会自动拉取。CLI 命令组 `peaks codegraph …`(status / init / index / query / files / context / affected)打包在 `dist/services/codegraph/`,无需额外安装步骤。
+- **`codegraph` 是传递依赖。** `peaks-loop` 在 `dependencies` 里硬钉 `@colbymchenry/codegraph@1.6.2`,所以 `npm install` / `pnpm install` 会自动拉取。CLI 命令组 `peaks codegraph …`(status / init / index / query / files / context / affected)打包在 `dist/services/codegraph/`,无需额外安装步骤。
 - **`.codegraph/` 目录归属是共享的。** aider / cody 等类似工具也会在项目根创建 `.codegraph/`。`peaks codegraph init` 拒绝覆盖外源 schema,以 exit code 73 + `CODEGRAPH_INIT_CONFLICT` 凭据退出。如果你的项目里已经有其他工具建的 `.codegraph/`,跑 `peaks codegraph init` 之前先移走 / 改名(或确认不再需要后删除)。
 - **session 绑定落在 `.peaks/_runtime/<sessionId>/`。** codegraph 编排上下文(以及其他 session 级证据)由 RD / QA 切片写入。把 `.peaks/_runtime/` 加进项目的 `.gitignore`,避免误提交本地 session 状态。session 缺失 / 未绑定时优雅降级为「跳过 + 警告」,绝不 crash。
-- **yarn-pnp / pnpm-strict 的 doctor 兜底。** `peaks doctor` 在 `require.resolve('@colbymchenry/codegraph/package.json')` 抛错时回退到文件系统遍历,因此严格解析模式下的下游安装也能拿到绿色 check(若版本偏离钉死的 `0.7.10` 则降级为 `severity: 'warning'`)。
+- **yarn-pnp / pnpm-strict 的 doctor 兜底。** `peaks doctor` 在 `require.resolve('@colbymchenry/codegraph/package.json')` 抛错时回退到文件系统遍历,因此严格解析模式下的下游安装也能拿到绿色 check(若版本偏离钉死的 `1.6.2` 则降级为 `severity: 'warning'`)。
 - **tarball 大小 / 自检。** 每次发布都把 codegraph service 打进 `dist/services/codegraph/`。逐版本自检脚本见 `scripts/verify-codegraph-tarball.mjs`(发布前本地跑 `node scripts/verify-codegraph-tarball.mjs`)。exit 0 表示 whitelist 完好,exit 1 表示 tarball 漏了 codegraph service 文件。
 
 典型下游安装片段:
@@ -314,7 +335,7 @@ npx peaks doctor --project .
 三个常见坑:
 
 1. **`peaks codegraph init` 退出码 73** —— 项目里已有外源 `.codegraph/`(aider / cody 等)。把它挪开(或删掉)再重跑。
-2. **`peaks doctor` 报 codegraph 版本漂移** —— 你的 lockfile 解到了一个跟钉死 `0.7.10` 不同的版本。在 lockfile 里钉到 `0.7.10`;这条 warning 不会让 doctor 退出码翻红。
+2. **`peaks doctor` 报 codegraph 版本漂移** —— 你的 lockfile 解到了一个跟钉死 `1.6.2` 不同的版本。在 lockfile 里钉到 `1.6.2`;这条 warning 不会让 doctor 退出码翻红。
 3. **`.peaks/_runtime/` 下的 session 产物在 `git status` 里嘈杂** —— 把这条路径加进项目的 `.gitignore`。`peaks-loop` 仓库已经这样做;下游消费者应当镜像这条规则。
 
 ---

package/bin/node-floor.mjs

@@ -0,0 +1,59 @@
+/**
+ * The Node version floor, checked by `bin/peaks.js` before it imports the app.
+ *
+ * WHY THIS FILE IS NEXT TO THE SHIM AND NOT IN `src/`. Every store now imports
+ * `node:sqlite`, so on a Node that predates that builtin the failure is raised while
+ * resolving the import graph — `ERR_UNKNOWN_BUILTIN_MODULE`, before one line of our code
+ * runs. A check inside the CLI would be compiled into the very graph that cannot load.
+ * `bin/peaks.js` is already the place that translates pre-app Node failures (a stale
+ * `dist/`) into sentences, so the floor lives with it.
+ *
+ * WHY 24. `node:sqlite` exists in 22.5+ but not as something this code can import
+ * unconditionally; 24 is the line measured on the developer host that started this change,
+ * where `import { DatabaseSync } from 'node:sqlite'` works with no flag and no warning.
+ * The number is asserted against `package.json#engines.node` by
+ * `tests/unit/cli/node-floor.test.ts`, because two spellings of one boundary is this
+ * repository's oldest defect class.
+ *
+ * WHAT IT REFUSES TO GUESS. An empty version string is not evidence of an old Node, so it
+ * does not block anyone; a NON-empty string that cannot be parsed fails loudly instead,
+ * because a wrong "you're fine" costs a crash two commands later and a wrong "too old"
+ * costs one confusing message.
+ */
+
+/** The major version at which `node:sqlite` is importable with no flag. */
+export const MIN_NODE_MAJOR = 24;
+
+/**
+ * A short reason string when `version` is below the floor, undefined when it is not.
+ *
+ * Returns the reason rather than printing it so the caller decides the stream and the exit
+ * code, and so the predicate is testable at every version without spawning a Node per case.
+ */
+export function nodeFloorProblem(version) {
+  if (typeof version !== 'string' || version.length === 0) return undefined;
+  const major = Number.parseInt(version.replace(/^v/, ''), 10);
+  if (!Number.isFinite(major)) {
+    return `the running Node version could not read as a version: "${version}"`;
+  }
+  if (major >= MIN_NODE_MAJOR) return undefined;
+  return `Node ${version} predates the builtin SQLite module`;
+}
+
+/** The full operator-facing message: what is wrong, and what to do about it. */
+export function nodeFloorSentence(version) {
+  return (
+    `peaks-loop requires Node >=${String(MIN_NODE_MAJOR)}.0.0 — found ${version || 'unknown'}.\n` +
+    '  why:    the stores read and write through `node:sqlite`, a Node builtin. It replaced\n' +
+    '          a native SQLite addon so that installing this CLI needs no C++ toolchain and\n' +
+    '          no prebuilt binary matching your Node ABI.\n' +
+    '  fix:    switch to Node ' +
+    String(MIN_NODE_MAJOR) +
+    '.x (nvm install ' +
+    String(MIN_NODE_MAJOR) +
+    ' && nvm use ' +
+    String(MIN_NODE_MAJOR) +
+    '),\n' +
+    '          then re-run the same command.\n'
+  );
+}

package/bin/peaks.js

@@ -20,6 +20,19 @@
  */
 import { fileURLToPath } from 'node:url';
 
+import { nodeFloorProblem, nodeFloorSentence } from './node-floor.mjs';
+
+/**
+ * Checked before the app is imported, because the thing it checks is an import: the stores
+ * load `node:sqlite` at module scope, so below the floor the process dies resolving the
+ * graph and never reaches a check written inside the CLI.
+ */
+const floorProblem = nodeFloorProblem(process.versions.node);
+if (floorProblem !== undefined) {
+  process.stderr.write(nodeFloorSentence(process.versions.node));
+  process.exit(1);
+}
+
 const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
 
 /** Workspace-internal packages whose absence always means "stale build". */

package/config/eslint/tsconfig.lint.json

@@ -33,7 +33,8 @@
     "../../scripts/dist-freshness.mjs",
     "../../scripts/install-skills.mjs",
     "../../scripts/packages-build-prerequisite.mjs",
-    "../../scripts/verify-version-parity.mjs"
+    "../../scripts/verify-version-parity.mjs",
+    "../../scripts/canonical-store.mjs"
   ],
   "include": [
     "../../src/**/*",