peaks-loop 3.0.0 → 3.0.2

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "plugins": [
     {
-      "name": "peaks-cli",
+      "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",
       "author": {
         "name": "SquabbyZ"
       },
-      "homepage": "https://github.com/SquabbyZ/peaks-cli",
-      "repository": "https://github.com/SquabbyZ/peaks-cli",
+      "homepage": "https://github.com/SquabbyZ/peaks-loop",
+      "repository": "https://github.com/SquabbyZ/peaks-loop",
       "license": "MIT",
       "tags": [
         "workflow",

package/CHANGELOG.md

@@ -1,8 +1,12 @@
 # Changelog
 
-## [Unreleased] — 2026-06-29 — change-id shim (cleanup post v2.17.0 hard-kill)
+## [3.0.2] — 2026-07-02 — change-id shim retirement (v2.19.0) + Understand Anything hybrid context (3.0.2)
 
-**MINOR bump target: v2.19.0**. Full removal of the peaks-cli change-id axis (filesystem axis, code shim, envelope JSON slug, CLI flags). OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched. One cleanup slice that retires the v2.17.0 shim half-life.
+**PATCH bump from 3.0.1**. Two independent slices bundled into one release:
+- **v2.19.0 change-id shim retirement** — full removal of the peaks-loop change-id axis (filesystem axis, code shim, envelope JSON slug, CLI flags). The change-id was a no-op post-v2.17.0 hard-kill; this slice retires the v2.17.0 shim half-life. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched.
+- **3.0.2 Understand Anything hybrid context** — new `peaks understand context` subcommand that encapsulates the UA-first / codegraph-fallback / hybrid-union routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture). Consumers no longer pick one or the other at the LLM level.
+
+The v2.19.0 work shipped as code commits (`f91d71c`, `5186d3d`, `b598612`, `ced835e`, `7ee9d8f`, plus follow-up tests) but was never formally released. v2.19.0 is therefore *not* a separate release line — its changes are rolled forward into 3.0.2. Future releases resume numeric sequence from 3.0.3.
 
 ### Removed — change-id shim (cleanup post v2.17.0 hard-kill)
 
@@ -70,7 +74,38 @@
 - Existing RD/QA artifacts in `.peaks/_runtime/<sid>/<role>/` remain readable; the planner no longer requires a change-id, and the change-id (if any) is embedded only as a filename slug.
 - The 2.8.3 hard-ban on `.peaks/_runtime/<YYYY-MM-DD-*>/` sibling directories is still enforced via the rewritten guard test and the inline `lstatSync` in `initWorkspace`.
 
-## [2.18.4] — 2026-06-29 — peaks-solo first-run step gates: hard-pause 1.x→2.0 upgrade + make `--mode` optional on Step 1
+## [3.0.2] — 2026-07-02 — change-id shim retirement (v2.19.0) + Understand Anything hybrid context (3.0.2)
+
+**PATCH bump from 3.0.1**. Two independent slices bundled into one release:
+- **v2.19.0 change-id shim retirement** — full removal of the peaks-loop change-id axis (filesystem axis, code shim, envelope JSON slug, CLI flags). The change-id was a no-op post-v2.17.0 hard-kill; this slice retires the v2.17.0 shim half-life. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched.
+- **3.0.2 Understand Anything hybrid context** — new `peaks understand context` subcommand that encapsulates the UA-first / codegraph-fallback / hybrid-union routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture). Consumers no longer pick one or the other at the LLM level.
+
+The v2.19.0 work shipped as code commits (`f91d71c`, `5186d3d`, `b598612`, `ced835e`, `7ee9d8f`, plus follow-up tests) but was never formally released. v2.19.0 is therefore *not* a separate release line — its changes are rolled forward into 3.0.2. Future releases resume numeric sequence from 3.0.3.
+
+### Added — `peaks understand context` (3.0.2 user-facing feature)
+
+The Understand Anything (UA) Claude Code plugin and `@colbymchenry/codegraph` are both complementary project-analysis tools. UA provides a high-level knowledge graph (tours, layers, expert prompts); codegraph provides low-level affected-file analysis. Until 3.0.2, peaks-loop consumers had to choose one or the other at the LLM level — there was no service-layer enforcement of either.
+
+This slice adds a single `peaks understand context` subcommand that encapsulates the routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture — see `peaks-solo` SKILL.md). The envelope carries a `source` tag so downstream consumers can audit which evidence contributed to the context.
+
+**Source routing** (deterministic, decided in `buildUnderstandContext`):
+- `ua-only` — UA knowledge graph present, no codegraph
+- `ua-missing-fallback-codegraph` — UA absent, codegraph produced evidence
+- `ua-and-codegraph-hybrid` — both present, both contribute (parallel `Promise.all`)
+- `both-missing` — neither produced evidence, exit code 2
+
+**Added files (5):**
+- `src/services/understand/understand-hybrid-service.ts` (133L, new): `buildUnderstandContext({projectRoot, files?, sampleSize?, artifactDir?, codegraphRunner?})` uses `Promise.all` to run UA scan and codegraph affected in parallel; total wall-clock = `max(uaMs, codegraphMs)`, not sum. Failures are caught into `warnings[]` (best-effort); the main envelope is always returned so consumers can audit missing evidence.
+- `src/services/understand/hybrid-types.ts` (39L, new): `UnderstandContextResult` envelope + 4-value source enum + `CodegraphContextBlock`.
+- `src/cli/commands/understand-commands.ts` (208L, +51L net): new `peaks understand context` subcommand at base path `admin/audit-logs` (the only 3rd CLI surface in the understand module family). The subcommand accepts `--project --files --sample --artifact-dir` and emits the envelope as JSON or human-readable summary.
+- `tests/unit/understand-hybrid-service.test.ts` (110L, 4 cases): `ua-only` / `fallback` / `hybrid` / `both-missing`.
+- `tests/integration/understand-hybrid-cli.test.ts` (85L, 3 cases): end-to-end CLI both-missing / ua-only / envelope-shape-stability.
+
+**Test evidence:** 7/7 vitest (4 unit + 3 integration), `tsc --noEmit` clean.
+
+The peak-loop skill-external-invocation audit pattern (capability discovery + references only + do-not-execute + Peaks authoritative) is preserved: codegraph is consumed via the existing `executeCodegraphInvocation` (no upstream installer calls); UA installation is a text `INSTALL_HINT` only.
+
+### Removed — change-id shim (cleanup post v2.17.0 hard-kill, rolled up from v2.19.0)
 
 **PATCH bump from 2.18.3**. Resolves the user-reported "新项目第一次使用 peaks-solo 时初始化完不按流程走、开发效果差、再开 session 后才正常" defect. Two surgical fixes to the first-run Solo gates (3 source files, 1 new test file, 2 test-regression updates; no schema change, no new dependencies, no public API change).
 
@@ -246,7 +281,7 @@ Each original file gets a sibling `import { ... } from './X-helpers.js'` + `expo
 
 ## [2.18.1] — 2026-06-29 — verify-pipeline path-axis + prd check-blocks ESM fix (2 P0 toolchain bugs)
 
-**PATCH bump from 2.18.0**. Resolves 2 P0 peaks-cli toolchain bugs deferred from the v2.18.0 release (CHANGELOG §"Out of scope (deferred)" #5 and #6). No CLI surface change, no new commands, no schema change. Both fixes are surgical: under 10 lines of production-code change each, no refactors.
+**PATCH bump from 2.18.0**. Resolves 2 P0 peaks-loop toolchain bugs deferred from the v2.18.0 release (CHANGELOG §"Out of scope (deferred)" #5 and #6). No CLI surface change, no new commands, no schema change. Both fixes are surgical: under 10 lines of production-code change each, no refactors.
 
 ### Feature — `peaks workflow verify-pipeline` session-axis fix (P0 audit #5)
 
@@ -380,8 +415,8 @@ Each original file gets a sibling `import { ... } from './X-helpers.js'` + `expo
 
 - **#1** Legacy v2.16.0 binding callerId rewrite — defer to `peaks doctor --rebuild-binding` slice. v2.18.0 read path is forward-compatible; active rewrite would create write-amplification loops.
 - **#2** `peaks binding status` CLI (PRD §3.4 nice-to-have) — defer to v2.19 RD.
-- **#5** `peaks workflow verify-pipeline` CLI bug (looks for v2.16.0-era change axis) — defer to peaks-cli toolchain fix slice, NOT a v2.18.0 regression.
-- **#6** `peaks prd check-blocks` CLI bug (`require is not defined`, ESM/CJS mix) — defer to peaks-cli toolchain fix slice, NOT a v2.18.0 regression.
+- **#5** `peaks workflow verify-pipeline` CLI bug (looks for v2.16.0-era change axis) — defer to peaks-loop toolchain fix slice, NOT a v2.18.0 regression.
+- **#6** `peaks prd check-blocks` CLI bug (`require is not defined`, ESM/CJS mix) — defer to peaks-loop toolchain fix slice, NOT a v2.18.0 regression.
 - **#7** 4 high-pressure near-cap files (`request-artifact-service.ts` 783 / `slice-decompose-service.ts` 775 / `workflow-autonomous-service.ts` 774 / `workspace-service.ts` 742) — out of v2.18.0 scope; backlog unchanged from v2.15.x.
 
 ### Redo additions (v2.18.0 REDO)
@@ -426,7 +461,7 @@ The first v2.18.0 release deferred two open items to a redo slice; both are now
 - `src/shared/change-id.ts`: 470 → ~210 lines. The substantive logic (change-id validation + path builders + symlink/file binding + LegacyChangeIdBindingError) is **retained as shims** that match the old contract; only the filesystem scope semantics changed.
 - `--change-id` option is preserved on 13 CLI commands as a metadata-only slug (does not affect CLI behavior).
 - `tests/unit/change-id.test.ts` (270 lines) and `tests/unit/workspace/workspace-init-change-id-redirect.test.ts` (441 lines) deleted.
-- 12 change-id-related memories archived under `.peaks/memory/archived/` (recoverable; documented in `peaks-cli-archive` policy).
+- 12 change-id-related memories archived under `.peaks/memory/archived/` (recoverable; documented in `peaks-loop-archive` policy).
 
 ### Behavior changes (user-visible)
 
@@ -467,7 +502,7 @@ Recommended scenarios before next release (see `peaks/_runtime/2026-06-29-sessio
 
 ## [2.15.1] — 2026-06-28 — 12 Gaps CLI 全套落地 + ice-cola dogfood 验证
 
-**PATCH bump from 2.15.0**. Follow-up ship for the 12 Gaps positioning memory (peaks-cli 真实定位 + 全套 15 个 Gap CLI 落地). No breaking changes. All new commands are additive top-level (no conflict with existing `peaks solo` / `peaks qa` / `peaks slice` role commands).
+**PATCH bump from 2.15.0**. Follow-up ship for the 12 Gaps positioning memory (peaks-loop 真实定位 + 全套 15 个 Gap CLI 落地). No breaking changes. All new commands are additive top-level (no conflict with existing `peaks solo` / `peaks qa` / `peaks slice` role commands).
 
 ### Feature — slice DAG layered parallelism + foundation/upstreamSync/complexity 字段
 
@@ -499,7 +534,7 @@ Recommended scenarios before next release (see `peaks/_runtime/2026-06-29-sessio
 
 ### Documentation
 
-- 6 new memory files: `peaks-cli-24h-ai-programmer-positioning` / `user-role-and-tech-decision` / `prd-template-design` / `slice-review-and-qa-perspective` / `fork-sync-and-layered-parallel` / `fast-iteration-quality-loop`
+- 6 new memory files: `peaks-loop-24h-ai-programmer-positioning` / `user-role-and-tech-decision` / `prd-template-design` / `slice-review-and-qa-perspective` / `fork-sync-and-layered-parallel` / `fast-iteration-quality-loop`
 - 4 SKILL.md 校准注: peaks-solo / peaks-prd / peaks-rd / peaks-qa 加 2026-06-28 校准 anchor
 - 12 Gaps 完整定位: 24h 程序员场景 / 唯一蜂群 / 反伪选择 / 业务审阅 / 轻量回归 / 上线观察期等
 
@@ -531,7 +566,7 @@ Recommended scenarios before next release (see `peaks/_runtime/2026-06-29-sessio
 - 真实 k8s rollout / LB config / 监控集成(G15)
 - 2 个 pre-existing 全量并发 race test 留后续
 
-## [2.15.0] — 2026-06-28 — Sticky-mode forced re-ask + user-feedback → peaks-cli enforcement (slice 002)
+## [2.15.0] — 2026-06-28 — Sticky-mode forced re-ask + user-feedback → peaks-loop enforcement (slice 002)
 
 **MINOR bump from 2.14.2** (slice `2026-06-28-sticky-mode-and-feedback-promotion`). Closes defect A (sticky-mode) and defect B (advisory-only feedback) from PRD-002. Two system-level fixes ship together because both are triggered by the same root cause: user-given rules were not machine-enforced.
 
@@ -547,7 +582,7 @@ Recommended scenarios before next release (see `peaks/_runtime/2026-06-29-sessio
 - **`skills/peaks-solo/references/mode-selection-with-stale-presence.md`** (NEW) — Detection protocol + worked example (88b27d defect) + ACL.
 - **`src/services/skills/skill-presence-service.ts`** — New exports: `checkStalePresence`, `clearStalePresenceOnRotation`, types `StalenessCheck`, `StaleReason`.
 
-### Feature — User-feedback → peaks-cli enforcement (defect B fix)
+### Feature — User-feedback → peaks-loop enforcement (defect B fix)
 
 - **`sops/feedback-promotion-sop.md`** (NEW) — SOP that requires every feedback memory (`.peaks/memory/<name>.md` with `metadata.type === 'feedback'`) to be promoted to at least one enforcement layer: A (peaks-sop gate), B (peaks-hooks PreToolUse), or C (mode-gate hardFloorCategory). When a rule spans multiple layers, promote to ALL of them.
 - **`peaks feedback promote <memory-file> [--layer A|B|C] [--dry-run]`** (NEW) — Reads the feedback memory, generates a code stub for the chosen layer, writes the promotion marker (HTML comment + `.promotion.json` sidecar), and writes the envelope at `.peaks/_runtime/<sid>/rd/feedback-promote-<name>.json`.
@@ -683,16 +718,16 @@ slice-2026-06-28-layered-dag PRD: 大需求(1 周内做不完)= 基础先行 +
 - peaks role add senior-fe --preset senior-fe + role list + role check (granted/not)
 - peaks complexity-estimate (auth files → complex, 41 lines + hasAsync)
 - peaks doc changelog-suggest (12 commits parsed into [Unreleased])
-- peaks doc generate-skill (peaks-cli 自己 75+ commands 扫到)
+- peaks doc generate-skill (peaks-loop 自己 75+ commands 扫到)
 - peaks slice-integrate (no contracts → graceful empty, 正确路径)
 
 **不触动:** transition gates / hard contracts / Karpathy 4 / sub-agent 协议。**新增 10 个新文件**(5 services + 5 CLIs + 5 tests)。
 
-### Documentation — peaks-cli 真实定位 + 12 Gaps 沉淀 (2026-06-28 follow-up)
+### Documentation — peaks-loop 真实定位 + 12 Gaps 沉淀 (2026-06-28 follow-up)
 
 会话期间从资深前端 + 后端半盲 + 极致工期 + 24h AI 程序员 + 存量无 UT 的真实场景,沉淀 6 个 memory 文件 + 索引 + 4 个 SKILL.md 校准注。**核心叙事:** `90% 效率 + 80% 质量` > `80% 效率 + 90% 质量`;user 在循环里 = 业务/产品审阅者不参与技术决策;主路径 = 唯一蜂群模式;prd 质量前置 = 4 必填块;QA = 业务视角 + 轻量回归 + 上线观察期。
 
-- **6 new memory files** — `.peaks/memory/peaks-cli-{24h-ai-programmer-positioning, user-role-and-tech-decision, prd-template-design, slice-review-and-qa-perspective, fork-sync-and-layered-parallel, fast-iteration-quality-loop}.md` (warm.project index 18 → 24)
+- **6 new memory files** — `.peaks/memory/peaks-loop-{24h-ai-programmer-positioning, user-role-and-tech-decision, prd-template-design, slice-review-and-qa-perspective, fork-sync-and-layered-parallel, fast-iteration-quality-loop}.md` (warm.project index 18 → 24)
 - **4 SKILL.md 校准注** — peaks-solo / peaks-prd / peaks-rd / peaks-qa 各加精简 anchor(均通过 25KB cap,只引用 memory 不重复内容)
 - **不触动** transition gates / hard contracts / Karpathy 4 / 模式枚举 / mode-gate.ts / sub-agent 协议
 
@@ -750,7 +785,7 @@ slice-2026-06-28-layered-dag PRD: 大需求(1 周内做不完)= 基础先行 +
 
 ---
 
-All notable changes to peaks-cli are documented here.
+All notable changes to peaks-loop are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
@@ -1075,14 +1110,14 @@ peaks-solo previously received 5 heterogeneous signals (security-audit, perf-aud
 
 ---
 
-## [2.13.0] — 2026-06-27 — Zero-human-intervention auto-compact (peaks-cli drives context compression on any AI CLI)
+## [2.13.0] — 2026-06-27 — Zero-human-intervention auto-compact (peaks-loop drives context compression on any AI CLI)
 
 **MINOR bump from 2.12.0** (slice `v2-13-0-auto-compact-protocol`, 5-sub-task plan AC-1..AC-5, red-line scope ~6 source files + 2 IDE adapter fields).
 
 peaks-solo now autonomously drives context compaction so the LLM-runner stays alive with context < 95% on **any AI CLI**, with **zero human / zero LLM intervention**. Two-tier threshold model:
 
-- **85% pre-compact zone** — peaks-cli writes a pre-compact checkpoint + convergence plan + auto-decisions log + IDE-side compact dispatch (async-friendly).
-- **95% RED LINE** — peaks-cli refuses sub-agent dispatch and forces synchronous IDE compact; mandatory, LLM cannot opt out.
+- **85% pre-compact zone** — peaks-loop writes a pre-compact checkpoint + convergence plan + auto-decisions log + IDE-side compact dispatch (async-friendly).
+- **95% RED LINE** — peaks-loop refuses sub-agent dispatch and forces synchronous IDE compact; mandatory, LLM cannot opt out.
 
 Adapter-driven protocol (no hard-coded IDE names): `IdeAdapter.compact?: IdeCompactProfile` is a 4-field per-IDE profile (`envVarForContextPercent` + `compactCommand` + `compactPathway` + `postCompactDetectCommand`). Claude Code is the MVP fill; trae / codex / cursor / qoder / tongyi-lingma / hermes / openclaw ship without `compact` and fall through to the conservative-zero probe (no auto-fire on missing signal).
 
@@ -1636,7 +1671,7 @@ are unchanged by this release), `pnpm build` clean.
   Rationale: `cc-connect@1.3.1`'s postinstall script runs
   `node scripts/install.js` which downloads a Go binary from
   `github.com/alibaba/open-code-review/releases` via HTTPS. This was
-  the dominant cause of slow `npm i -g peaks-cli` installs in
+  the dominant cause of slow `npm i -g peaks-loop` installs in
   restricted/proxied environments; `peaks companion` itself is also
   low-traffic (no Claude Code / Trae workflows depend on it). The
   `peaks-companion` skill directory remains in `skills/` for users
@@ -1658,7 +1693,7 @@ are unchanged by this release), `pnpm build` clean.
   `npm i -g @alibaba-group/open-code-review`. Install hint copy in
   `ocr-service.ts` and `code-review-commands.ts` updated to reflect
   the peer-dependency status. `pnpm.onlyBuiltDependencies` is now an
-  empty array (no peaks-cli dep needs postinstall approval).
+  empty array (no peaks-loop dep needs postinstall approval).
 - **Refreshed stale JSDoc** on `src/services/config/config-service.ts#hasLegacyGlobalFields` to describe the current 2.0 schema (`version` + `ocr`) — the old comment still described the deleted `companion` block from slice 2026-06-14-cc-connect-weixin.
 - **Removed dead `commander.invalidArgument` channel-not-supported block** in `src/cli/index.ts` — the only path that raised this exact error was the now-deleted `peaks companion` command.
 
@@ -1728,7 +1763,7 @@ are unchanged by this release), `pnpm build` clean.
 ### Added
 
 - **Slice DAG dependency analysis + parallel sub-agent dispatch (slice 1.2)** —
-  the `peaks-cli` repo now ships a typed DAG model for slicing work across
+  the `peaks-loop` repo now ships a typed DAG model for slicing work across
   parallel sub-agents. `src/services/dispatch/slice-dag.ts` exports
   `validateDag` (cycle detection with path-in-error-message),
   `topologicalLevels` (linear / diamond / parallel DAGs), and
@@ -1866,7 +1901,7 @@ are unchanged by this release), `pnpm build` clean.
 ### Added
 
 - **Multi-IDE agent install (Slice 2.6.1.E)** — the `karpathy-reviewer`
-  sub-agent now auto-installs on `npm i -g peaks-cli@latest` to **5
+  sub-agent now auto-installs on `npm i -g peaks-loop@latest` to **5
   platforms** instead of 1. Previously only `~/.claude/agents/`
   (claude-code) was populated; 2.6.1 extends to `~/.trae/agents/`,
   `~/.trae-cn/agents/`, `~/.codex/agents/`, and `~/.cursor/agents/`.
@@ -1882,7 +1917,7 @@ are unchanged by this release), `pnpm build` clean.
 
 - **orphan-service false-positive reductions (Slice 2.6.1.A)** —
   `peaks scan orphan` had been reporting 77 `cliSubcommandOrphans` for
-  the peaks-cli repo. Four surgical fixes bring this down to 35
+  the peaks-loop repo. Four surgical fixes bring this down to 35
   (54% reduction):
   1. The `usageCount` algorithm now excludes the declaration file
      itself, so the threshold is "wired iff referenced in any other
@@ -2013,10 +2048,10 @@ are unchanged by this release), `pnpm build` clean.
   (`passed` / `violations[]` / `gateAction`), file-write contract
   (title-case `## Karpathy-Gate` + 4 guideline sections), 8 hard
   prohibitions, 5 anti-patterns. Project-internal 2-line pointer at
-  `skills/peaks-rd/references/karpathy-reviewer-prompt.md` (peaks-cli
+  `skills/peaks-rd/references/karpathy-reviewer-prompt.md` (peaks-loop
   2.0 rules convention).
-- **Auto-install on `npm i -g peaks-cli@latest`** (slice 7) — the
-  `peaks-cli` postinstall (`scripts/install-skills.mjs`) now copies
+- **Auto-install on `npm i -g peaks-loop@latest`** (slice 7) — the
+  `peaks-loop` postinstall (`scripts/install-skills.mjs`) now copies
   bundled agents from the tarball to `~/.claude/agents/` with
   content-hash drift detection (`.peaks-managed` marker + SHA-256).
   Mirrors the existing `output-styles` install contract. New function
@@ -2084,7 +2119,7 @@ are unchanged by this release), `pnpm build` clean.
 - **L2-install test for Slice 7** — the auto-install path is
   L1-verified (vitest + end-to-end postinstall against a temp HOME)
   but not yet L2-verified on a real consumer machine. A real
-  `npm i -g peaks-cli@2.6.0` + postinstall + content-hash drift
+  `npm i -g peaks-loop@2.6.0` + postinstall + content-hash drift
   check + uninstall + reinstall cycle is the next L2 step (Slice 8
   follow-up if issues surface).
 - **Trae / Codex / Cursor / Qoder / Tongyi Lingma / Hermes /
@@ -2108,8 +2143,8 @@ are unchanged by this release), `pnpm build` clean.
   011 added `peaks session checkpoint` / `peaks session resume` CLIs plus
   `references/checkpoint-resume.md` + `references/periodic-checkpoint.md`, but
   SKILL.md body only mentioned them in a single line. New Claude Code sessions
-  that load SKILL.md never learned the optimization existed. `### Peaks-Cli
-  Step 0.75: Resume from checkpoint` and `### Peaks-Cli Step N: Periodic
+  that load SKILL.md never learned the optimization existed. `### Peaks-Loop
+  Step 0.75: Resume from checkpoint` and `### Peaks-Loop Step N: Periodic
   checkpoint` headings are now in the body (≥ 5 lines each), with explicit
   `peaks session checkpoint` / `peaks session resume` CLI mentions and
   reference-doc pointers. Byte cap bumped 22K → 24K (precedent: 18K → 20K → 22K).
@@ -2242,7 +2277,7 @@ are unchanged by this release), `pnpm build` clean.
   artifacts under `.peaks/_runtime/<change-id>/...` (per-change layout) but this
   session writes under `.peaks/_runtime/<session-id>/...` (per-session
   runtime layout). The pipeline may report `gateC: fail` despite a
-  PASS verdict; reconcile in a future slice (peaks-cli tooling fix,
+  PASS verdict; reconcile in a future slice (peaks-loop tooling fix,
   not a 2.4.0 blocker).
 
 ---
@@ -2473,7 +2508,7 @@ Full suite: **2957 passed, 12 skipped, 0 failed**.
   now derive from `parallelBatches` (with legacy `--type` lookup as
   the fallback path).
 
-- **Extended `peaks-solo/SKILL.md`** — adds "Peaks-Cli Slice
+- **Extended `peaks-solo/SKILL.md`** — adds "Peaks-Loop Slice
   Decomposition (Step 0.6 — pre-mode-selection)" section.
 
 - **Extended `runbook.md`** — adds "Step 2.5: Slice Decomposition"
@@ -2530,13 +2565,13 @@ Full suite: **2957 passed, 12 skipped, 0 failed**.
   (baseline 229/2894 -> delta +3 files / +45 tests).
 - `npx tsc --noEmit` clean.
 - `npm run build` clean.
-- End-to-end CLI smoke test on peaks-cli repo:
+- End-to-end CLI smoke test on peaks-loop repo:
   `peaks slice decompose 2026-06-13-slice-decompose-impl --json` returns
   `ok: true`, writes 9 work units, 1 dep edge, p50=247.5 within the
   expected [202, 248] range (8-WU 2.1.0 dry-run p50=225 +-10%).
 - `peaks doctor` clean (no L3 regressions from the new path).
 - QA verdict: pass (10 of 10 ACs pass; AC10 has 1 partial
-  regarding peaks-cli's existing `review-fanout` path mapping, but
+  regarding peaks-loop's existing `review-fanout` path mapping, but
   the partial is a pre-existing architecture issue, NOT a regression
   from this slice).
 
@@ -2803,9 +2838,9 @@ Full suite: **2957 passed, 12 skipped, 0 failed**.
   (was promoted to a hard `dependency` in 2.0.1 and carried through
   2.0.2). The ocr npm package's `postinstall` downloads a Go binary
   via HTTPS, which fails in restricted/proxied environments and was
-  aborting the whole `npm i -g peaks-cli` flow. The 5-state detector
+  aborting the whole `npm i -g peaks-loop` flow. The 5-state detector
   (`ready` / `package-missing` / `binary-missing` / `config-missing` /
-  `detection-failed`) and the soft-fail policy are unchanged — peaks-cli
+  `detection-failed`) and the soft-fail policy are unchanged — peaks-loop
   never blocks on ocr being installed; it just no longer forces the
   install. Users who want the second-opinion review run
   `npm i -g @alibaba-group/open-code-review` explicitly. Under pnpm
@@ -2819,7 +2854,7 @@ Full suite: **2957 passed, 12 skipped, 0 failed**.
 
 ### 🎯 Headline
 
-**One-key 1.x → 2.0 upgrade.** `npm i -g peaks-cli@2.0` runs the full
+**One-key 1.x → 2.0 upgrade.** `npm i -g peaks-loop@2.0` runs the full
 upgrade umbrella in the consuming project automatically (gated by the
 1.x detector). The manual fallback is `peaks upgrade --to 2.0 --auto`.
 
@@ -2839,11 +2874,11 @@ a slice. New CLI: `peaks code-review detect-ocr` / `run-ocr`. See
 
 > **Note:** This `optionalDependency` classification was briefly
 > promoted to a hard `dependency` in 2.0.1 (alongside the source-of-truth
-> refactor) because the user feedback was "peaks-cli should not leave
+> refactor) because the user feedback was "peaks-loop should not leave
 > install to the user". 2.0.3 reverts just the classification — the
 > source-of-truth refactor stays — because the ocr postinstall
 > downloads a Go binary via HTTPS, which fails in restricted/proxied
-> environments and was aborting `npm i -g peaks-cli`. See the 2.0.3
+> environments and was aborting `npm i -g peaks-loop`. See the 2.0.3
 > entry above for the full rationale.
 
 ### Breaking Changes
@@ -2864,27 +2899,27 @@ a slice. New CLI: `peaks code-review detect-ocr` / `run-ocr`. See
   `economyMode`, `swarmMode`, headroom settings, etc. are now per-project.
   The upgrade umbrella runs `peaks config migrate --apply` automatically.
 
-- **Postinstall behavior changed.** `npm i -g peaks-cli@2.0` now:
+- **Postinstall behavior changed.** `npm i -g peaks-loop@2.0` now:
   1. Symlinks bundled skills to **all 8 supported IDE platforms**
      (Claude Code, Trae, Cursor, Qoder, Codex, Tongyi Lingma, Aider, Roo Code),
      not just the auto-detected one. Per real Trae user feedback 2026-06-11.
   2. Installs bundled output styles.
-  3. If `cwd` contains a 1.x peaks-cli project, fire-and-forgets
+  3. If `cwd` contains a 1.x peaks-loop project, fire-and-forgets
      `peaks upgrade --to 2.0 --auto`. Opt out with `PEAKS_SKIP_AUTO_UPGRADE=1`.
 
-### Changed — ocr source-of-truth moved into peaks-cli's config
+### Changed — ocr source-of-truth moved into peaks-loop's config
 
 Following the same-release user feedback that the original 2.0.0 ocr
 config lived in `~/.opencodereview/config.json` (a file outside
-peaks-cli's reach) and was set via the `ocr config set` CLI from the
+peaks-loop's reach) and was set via the `ocr config set` CLI from the
 upstream package, the ocr LLM endpoint config now lives under
 `peaksConfig.ocr.llm` in `~/.peaks/config.json`. This makes the
-user-managed LLM endpoint discoverable from a single, peaks-cli-owned
+user-managed LLM endpoint discoverable from a single, peaks-loop-owned
 config surface.
 
 - **`@alibaba-group/open-code-review` is now a hard `dependency`** (was
   `optionalDependency`). The user no longer has to remember to install
-  it; `npm i -g peaks-cli` pulls it. Network-blocked installs that fail
+  it; `npm i -g peaks-loop` pulls it. Network-blocked installs that fail
   to download the platform binary still soft-fail at runtime
   (`binary-missing` state) — the install-time failure risk is the
   trade-off.
@@ -2892,7 +2927,7 @@ config surface.
   > **Reverted in 2.0.3.** The install-time failure risk turned out
   > to bite too many real-world installs (corporate proxies, region
   > firewalls, sandboxed dev environments all abort the whole
-  > `npm i -g peaks-cli`). 2.0.3 puts ocr back under
+  > `npm i -g peaks-loop`). 2.0.3 puts ocr back under
   > `optionalDependencies`; everything else in this section
   > (env-var injection, `config-template` CLI, `missingKeys`,
   > source-of-truth under `peaksConfig.ocr.llm`) is unchanged.
@@ -2905,17 +2940,17 @@ config surface.
   `OCR_LLM_URL` / `OCR_LLM_TOKEN` / `OCR_LLM_MODEL` /
   `OCR_USE_ANTHROPIC` / `OCR_LLM_AUTH_HEADER` from `peaksConfig.ocr.llm`
   when spawning the ocr subprocess — the ocr package's highest-priority
-  config path. peaks-cli never has to materialise
+  config path. peaks-loop never has to materialise
   `~/.opencodereview/config.json`, and does NOT auto-configure the
   endpoint — the user is the only party that touches the LLM
   token / URL.
 - **New CLI: `peaks code-review config-template`.** Prints the JSON
   snippet the user pastes into `~/.peaks/config.json`. It does NOT
   write anything. No `peaks ocr config set`, no `ocr config set` — just
-  edit peaks-cli's config.json (or use
+  edit peaks-loop's config.json (or use
   `peaks config set --key ocr.llm.url --value '...'` if preferred).
 - **JSON envelope contract change:** `OcrDetectResult.configPath` now
-  points at the peaks-cli config (e.g. `~/.peaks/config.json`) instead
+  points at the peaks-loop config (e.g. `~/.peaks/config.json`) instead
   of the OCR package's legacy file. A new `missingKeys` field lists the
   required `ocr.llm.*` keys the user has not yet populated. The
   five-state contract and the soft-fail policy are unchanged.
@@ -2928,14 +2963,14 @@ soft-optional 2.0.0 release should:
 1. Run `peaks code-review config-template --json` to see the JSON
    snippet.
 2. Paste the equivalent values into `~/.peaks/config.json` under
-   `ocr.llm` (peaks-cli handles the camelCase conversion; the
+   `ocr.llm` (peaks-loop handles the camelCase conversion; the
    template shows the canonical shape).
 3. Re-run `peaks code-review detect-ocr --json` to verify
    `state == "ready"`.
 
 The old `~/.opencodereview/config.json` is no longer consulted by
-peaks-cli. The user may delete it at their discretion (the ocr
-subprocess ignores it when peaks-cli's env vars are present).
+peaks-loop. The user may delete it at their discretion (the ocr
+subprocess ignores it when peaks-loop's env vars are present).
 
 ### Added
 
@@ -2961,7 +2996,7 @@ subprocess ignores it when peaks-cli's env vars are present).
 
 - **`peaks agent run`** — ECC 64 agents soft-optional integration
   (spec §7.2). When the L3 stack is installed, peaks delegates to it;
-  otherwise degrades to peaks-cli's own core diagnostics.
+  otherwise degrades to peaks-loop's own core diagnostics.
 
 - **`peaks memory search` / `peaks retrospective search`** — new search
   subcommands for the durable memory / retrospective stores.
@@ -2972,7 +3007,7 @@ subprocess ignores it when peaks-cli's env vars are present).
 - **`peaks preferences set / get / reset`** — per-project preferences
   read/write CLI.
 
-- **Two paired tenets** captured in `.peaks/memory/peaks-cli-tenet-one-key-completion.md`:
+- **Two paired tenets** captured in `.peaks/memory/peaks-loop-tenet-one-key-completion.md`:
   - **One-key completion** — actions that can be done in one step
     should not be designed as two-step operations.
   - **Minimal user operation** — features can be powerful, but the
@@ -3083,7 +3118,7 @@ is skipped (`PEAKS_SKIP_AUTO_UPGRADE=1` or `npm i --ignore-scripts`).
      `economyMode` / `swarmMode` with a pointer to
      `<project>/.peaks/preferences.json` (do not silently migrate).
 
-  The net effect: a freshly-installed peaks-cli writes a 2-key
+  The net effect: a freshly-installed peaks-loop writes a 2-key
   `~/.peaks/config.json`; legacy 1.x files migrate to the same
   2-key form; the ocr second-opinion config is now the only
   discoverable surface the user needs to populate to make
@@ -3112,9 +3147,9 @@ same animations, same anchor links); only the tagline and
 call-to-action text differ.
 
 - `README.md` updated to the new layout (typing animation uses the
-  Chinese tagline: `peaks-cli: 跨 AI IDE 的工程门禁与编排`).
+  Chinese tagline: `peaks-loop: 跨 AI IDE 的工程门禁与编排`).
 - `README-en.md` synced to mirror the new layout (typing animation
-  uses the English tagline: `peaks-cli: cross-AI-IDE engineering
+  uses the English tagline: `peaks-loop: cross-AI-IDE engineering
   gates & orchestration`).
 - Card anchors renamed to ASCII-friendly slugs on the English file
   (`30-seconds-to-running`, `5-minute-onboarding`, `11-skills-in-the-family`,
@@ -3131,6 +3166,6 @@ No code, CLI, or schema changes. The CLI still reports
 
 Last 1.x release. See git history pre-2.0.0 for details.
 
-[2.0.2]: https://github.com/SquabbyZ/peaks-cli/releases/tag/v2.0.2
-[2.0.1]: https://github.com/SquabbyZ/peaks-cli/releases/tag/v2.0.1
-[2.0.0]: https://github.com/SquabbyZ/peaks-cli/releases/tag/v2.0.0
+[2.0.2]: https://github.com/SquabbyZ/peaks-loop/releases/tag/v2.0.2
+[2.0.1]: https://github.com/SquabbyZ/peaks-loop/releases/tag/v2.0.1
+[2.0.0]: https://github.com/SquabbyZ/peaks-loop/releases/tag/v2.0.0

package/README-en.md

@@ -262,10 +262,10 @@ See [`CHANGELOG.md`](./CHANGELOG.md) and [`docs/`](./docs/) for details.
 
 ## 💬 Join the WeChat community
 
-Got usage questions, feature requests, or want to chat with the team and other peaks-loop users? Scan to join the **Peaks-Cli** WeChat group:
+Got usage questions, feature requests, or want to chat with the team and other peaks-loop users? Scan to join the **Peaks-Loop** WeChat group:
 
 <div align="center">
-  <img src="./docs/images/wechat-group-qr.png" alt="Peaks-Cli WeChat group QR code" width="240" />
+  <img src="./docs/images/wechat-group-qr.png" alt="Peaks-Loop WeChat group QR code" width="240" />
 </div>
 
 > When the QR code expires, feel free to open a GitHub Issue / Discussion instead.

package/README.md

@@ -346,10 +346,10 @@ peaks gate bypass --sop <id> --phase <phase> --reason "<why>"
 
 ## 💬 加入微信交流群
 
-遇到使用问题、功能建议、或者想和other peaks-loop users直接交流？扫码加入 **Peaks-Cli** 微信群：
+遇到使用问题、功能建议、或者想和other peaks-loop users直接交流？扫码加入 **Peaks-Loop** 微信群：
 
 <div align="center">
-  <img src="./docs/images/wechat-group-qr.png" alt="Peaks-Cli 微信群二维码" width="240" />
+  <img src="./docs/images/wechat-group-qr.png" alt="Peaks-Loop 微信群二维码" width="240" />
 </div>
 
 > 二维码图片过期后，欢迎在 GitHub Issues / Discussions 提反馈。

package/agents/karpathy-reviewer.md

@@ -7,9 +7,9 @@ model: sonnet
 
 # Karpathy Reviewer (peaks-rd 5-way fanout — Slice 5/6 + Slice 6/6 + Slice 7/7 LLM prompt)
 
-> **Shipped source** (Slice 7/7): this file is the canonical source for the karpathy-reviewer sub-agent prompt. The `peaks-cli` postinstall (`scripts/install-skills.mjs#installBundledAgents`) copies this file to `~/.claude/agents/karpathy-reviewer.md` on every `npm i -g peaks-cli@latest` invocation, with content-hash drift detection (a `.peaks-managed` marker + SHA-256 compare). Edit here; do not edit the copy in `~/.claude/agents/` (it will be overwritten on the next upgrade).
+> **Shipped source** (Slice 7/7): this file is the canonical source for the karpathy-reviewer sub-agent prompt. The `peaks-loop` postinstall (`scripts/install-skills.mjs#installBundledAgents`) copies this file to `~/.claude/agents/karpathy-reviewer.md` on every `npm i -g peaks-loop@latest` invocation, with content-hash drift detection (a `.peaks-managed` marker + SHA-256 compare). Edit here; do not edit the copy in `~/.claude/agents/` (it will be overwritten on the next upgrade).
 >
-> **Project-internal pointer**: `skills/peaks-rd/references/karpathy-reviewer-prompt.md` is a 2-line pointer to this file (peaks-cli 2.0 rules convention).
+> **Project-internal pointer**: `skills/peaks-rd/references/karpathy-reviewer-prompt.md` is a 2-line pointer to this file (peaks-loop 2.0 rules convention).
 
 You are a **Karpathy-guidelines enforcement reviewer** for peaks-rd. You inspect a slice's RD outputs against the 4 Karpathy guidelines and emit a compact JSON envelope that blocks the `rd → qa-handoff` transition if any guideline fails. You do **not** review style, performance, security, or code quality — those are owned by the parallel 4 sub-agents.
 

package/dist/src/cli/commands/agent-commands.js

@@ -4,7 +4,7 @@ import { fail, ok } from '../../shared/result.js';
 export function registerAgentCommands(program, io) {
     const agent = program
         .command('agent')
-        .description('Run an ECC agent (soft-optional per spec §7.2). 64 agents are npm-installable via npx ecc; peaks-cli shells out when ECC is installed and soft-fails with a 4-option install prompt when it is not. Native peaks-cli diagnostics still run via `peaks doctor scan`.');
+        .description('Run an ECC agent (soft-optional per spec §7.2). 64 agents are npm-installable via npx ecc; peaks-loop shells out when ECC is installed and soft-fails with a 4-option install prompt when it is not. Native peaks-loop diagnostics still run via `peaks doctor scan`.');
     addJsonOption(agent
         .command('run <name>')
         .description(`Run an ECC agent by name (e.g. 'security-reviewer', 'code-reviewer'). The canonical subprocess is \`npx ecc agent run <name> --target <path> --json\`.`)
@@ -28,7 +28,7 @@ export function registerAgentCommands(program, io) {
             const data = { ...result, projectRoot };
             const nextActions = [];
             if (result.reason === 'flag-enabled-but-ecc-missing') {
-                nextActions.push('ECC not installed. Pick one of the four options below:', '  a) Install: run `npx ecc --help` to install, then re-run `peaks agent run`.', '  b) Skip this run: use the peaks-cli native diagnostic via `peaks doctor scan`.', '  c) Skip forever: run `peaks preferences set agentShieldEnabled false`.', '  d) Learn more: see docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §7.2.');
+                nextActions.push('ECC not installed. Pick one of the four options below:', '  a) Install: run `npx ecc --help` to install, then re-run `peaks agent run`.', '  b) Skip this run: use the peaks-loop native diagnostic via `peaks doctor scan`.', '  c) Skip forever: run `peaks preferences set agentShieldEnabled false`.', '  d) Learn more: see docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §7.2.');
             }
             const envelope = ok('agent.run', data, [...result.warnings], nextActions);
             printResult(io, envelope, options.json);
@@ -41,7 +41,7 @@ export function registerAgentCommands(program, io) {
     });
     addJsonOption(agent
         .command('list')
-        .description(`List the 12 canonical ECC agents (peaks-cli ships a static subset; the full 64 are ECC-discovered).`)).action((options) => {
+        .description(`List the 12 canonical ECC agents (peaks-loop ships a static subset; the full 64 are ECC-discovered).`)).action((options) => {
         const envelope = ok('agent.list', { agents: CANONICAL_ECC_AGENTS.map((a) => ({ name: a.name, description: a.description })) }, [], ['Run any agent with: `peaks agent run <name> --target <path>`']);
         printResult(io, envelope, options.json);
     });

package/dist/src/cli/commands/audit-commands.d.ts

@@ -3,7 +3,7 @@
  *
  * Registers the new `peaks audit` top-level command with the
  * `red-lines` (L2.1) and `static` (L2.3 P2-a) subcommands.
- * Per `peaks-cli-when-adding-a-new-subcommand-check-for-existing-top-level-first.md`
+ * Per `peaks-loop-when-adding-a-new-subcommand-check-for-existing-top-level-first.md`
  * we verified that no `peaks audit` top-level exists; this is the only
  * file that owns the registration.
  */

package/dist/src/cli/commands/audit-commands.js

@@ -3,7 +3,7 @@
  *
  * Registers the new `peaks audit` top-level command with the
  * `red-lines` (L2.1) and `static` (L2.3 P2-a) subcommands.
- * Per `peaks-cli-when-adding-a-new-subcommand-check-for-existing-top-level-first.md`
+ * Per `peaks-loop-when-adding-a-new-subcommand-check-for-existing-top-level-first.md`
  * we verified that no `peaks audit` top-level exists; this is the only
  * file that owns the registration.
  */
@@ -50,7 +50,7 @@ function validateProjectRoot(projectArg) {
 export function registerAuditCommands(program, io) {
     const audit = program
         .command('audit')
-        .description('Audit a project for compliance with peaks-cli red lines (P0 / P1 / P2 tiers)');
+        .description('Audit a project for compliance with peaks-loop red lines (P0 / P1 / P2 tiers)');
     addJsonOption(audit
         .command('red-lines')
         .description('Scan skills/, .claude/rules/, and openspec/changes/ for MANDATORY / BLOCKING / MUST NOT / RED LINE markers; classify each as cli-backed / partial / prose-only')
@@ -88,12 +88,12 @@ export function registerAuditCommands(program, io) {
     // project-memory decision at `.peaks/memory/audit-decisions/<slug>.md`.
     // `--rid <id>` is an optional disambiguator for multiple audits on
     // the same day (slug becomes `audit-decision-<date>-<rid>`).
-    // Per `peaks-cli-when-adding-a-new-subcommand-check-for-existing-top-level-first`
+    // Per `peaks-loop-when-adding-a-new-subcommand-check-for-existing-top-level-first`
     // and the dev-preference red line "Default-no on new CLI commands",
     // we extend the existing command rather than register a new subcommand.
     addJsonOption(audit
         .command('static')
-        .description('Run the static audit (peaks-cli lint + optional ECC AgentShield subprocess). Per spec §5.3.')
+        .description('Run the static audit (peaks-loop lint + optional ECC AgentShield subprocess). Per spec §5.3.')
         .requiredOption('--project <path>', 'target project root')
         .option('--enable-agent-shield', 'force-enable ECC AgentShield subprocess for this call (overrides preference)')
         .option('--disable-agent-shield', 'force-disable ECC AgentShield subprocess for this call (overrides preference)')
@@ -155,7 +155,7 @@ export function registerAuditCommands(program, io) {
             const nextActions = [];
             // Per spec §5.3 + §7.2: when ECC is not installed, surface
             // the canonical 4-option user opt-in UX (a/b/c/d) via
-            // nextActions. The peaks-cli `peaks audit static` CLI is
+            // nextActions. The peaks-loop `peaks audit static` CLI is
             // non-interactive (JSON envelope by default), so the 4
             // options are surfaced as machine-readable action strings
             // — same pattern as understand-commands.ts `INSTALL_HINT`.
@@ -164,7 +164,7 @@ export function registerAuditCommands(program, io) {
                 nextActions.push('  a) Install: run `npx ecc-agentshield --help` to install, then re-run `peaks audit static`.');
                 nextActions.push('  b) Skip this run: pass `--disable-agent-shield` to suppress the subprocess for this call.');
                 nextActions.push('  c) Skip forever: run `peaks preferences set agentShieldEnabled false` (writes to `.peaks/preferences.json`).');
-                nextActions.push('  d) Learn more: see docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5.3 + §7.2.');
+                nextActions.push('  d) Learn more: see docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §5.3 + §7.2.');
             }
             if (result.agentShield.spawned && result.agentShield.findings.length > 0) {
                 nextActions.push(`${result.agentShield.findings.length} ECC findings merged into the audit. Review with \`peaks audit static --json\`.`);

package/dist/src/cli/commands/classify-classify-commands.js

@@ -139,7 +139,7 @@ export function registerClassifyCommands(program, io) {
     // Downgrade is REFUSED per spec §4. Surface this as a hard fail.
     classify
         .command('downgrade')
-        .description('REFUSED per spec §4 — peaks-cli never downgrades a classification; ask the user to override explicitly')
+        .description('REFUSED per spec §4 — peaks-loop never downgrades a classification; ask the user to override explicitly')
         .requiredOption('--level <level>', 'attempted level')
         .requiredOption('--reason <text>', 'reason for the attempt (always rejected)')
         .requiredOption('--project <path>', 'target project root')