peaks-loop 4.1.5 → 4.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +36 -0
- package/README-en.md +47 -183
- package/README.md +24 -188
- package/dist/cli/commands/best-practice-scan-command.d.ts +11 -6
- package/dist/cli/commands/best-practice-scan-command.js +35 -20
- package/dist/cli/commands/best-practice-scan-helpers.d.ts +47 -0
- package/dist/cli/commands/best-practice-scan-helpers.js +88 -5
- package/dist/cli/commands/best-practice-scan-lookup-results.d.ts +13 -0
- package/dist/cli/commands/best-practice-scan-lookup-results.js +237 -0
- package/dist/cli/commands/dispatch-command-spec.js +1 -1
- package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
- package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
- package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
- package/dist/cli/commands/dispatch-prompt-composition.d.ts +1 -1
- package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
- package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
- package/dist/cli/commands/openspec-command-shared.js +2 -2
- package/dist/cli/commands/request-transition-failures.js +31 -4
- package/dist/cli/commands/request-transition-preflight.js +1 -1
- package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
- package/dist/cli/commands/verdict-aggregate-command.js +2 -1
- package/dist/cli/commands/workflow-gate-commands.js +4 -4
- package/dist/cli/program.js +0 -2
- package/dist/services/artifacts/artifact-contract-block.js +21 -2
- package/dist/services/artifacts/artifact-prerequisites.js +7 -7
- package/dist/services/artifacts/rd-transition-gates.d.ts +33 -0
- package/dist/services/artifacts/rd-transition-gates.js +71 -0
- package/dist/services/artifacts/request-artifact-service.js +22 -20
- package/dist/services/artifacts/request-artifact-state-helpers.d.ts +9 -1
- package/dist/services/artifacts/request-artifact-state-helpers.js +6 -4
- package/dist/services/audit-independent/judged-declaration-check.d.ts +1 -0
- package/dist/services/audit-independent/judged-declaration-check.js +62 -1
- package/dist/services/context/build-dispatch-system-prompt.d.ts +5 -9
- package/dist/services/context/build-dispatch-system-prompt.js +11 -11
- package/dist/services/context/post-compact-reinjection.js +1 -1
- package/dist/services/dispatch/test-tool-detection.d.ts +17 -1
- package/dist/services/dispatch/test-tool-detection.js +12 -1
- package/dist/services/evidence/evidence-generator.js +8 -4
- package/dist/services/openspec/coverage-evidence-reader.d.ts +9 -9
- package/dist/services/openspec/coverage-evidence-reader.js +8 -8
- package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
- package/dist/services/openspec/openspec-archive-service.js +6 -6
- package/dist/services/scan/file-size-baseline.d.ts +13 -6
- package/dist/services/scan/file-size-baseline.js +54 -31
- package/dist/services/scan/file-size-scan.d.ts +7 -14
- package/dist/services/scan/file-size-scan.js +6 -1
- package/dist/services/scan/type-corroboration.d.ts +32 -0
- package/dist/services/scan/type-corroboration.js +51 -0
- package/dist/services/scan/type-sanity-service.d.ts +14 -0
- package/dist/services/scan/type-sanity-service.js +10 -19
- package/dist/services/security/safe-settings-path.d.ts +5 -0
- package/dist/services/security/safe-settings-path.js +64 -8
- package/dist/services/skill/resume-detector.js +8 -8
- package/dist/services/workflow/pipeline-verify-gate-support.d.ts +24 -8
- package/dist/services/workflow/pipeline-verify-gate-support.js +32 -38
- package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
- package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
- package/dist/services/workflow/pipeline-verify-service.js +26 -27
- package/dist/services/workflow/request-type-resolution.d.ts +99 -0
- package/dist/services/workflow/request-type-resolution.js +130 -0
- package/dist/services/workflow/workflow-skip-service.d.ts +1 -0
- package/dist/services/workflow/workflow-skip-service.js +19 -21
- package/dist/services/workflow/workflow-state-store.d.ts +9 -0
- package/dist/services/workflow/workflow-state-store.js +26 -1
- package/dist/shared/incrementing-number.d.ts +23 -2
- package/dist/shared/incrementing-number.js +57 -15
- package/package.json +5 -7
- package/skills/bee/peaks-prd/SKILL.md +3 -2
- package/skills/peaks-code/SKILL.md +32 -15
- package/dist/cli/commands/vm-command-shared.d.ts +0 -23
- package/dist/cli/commands/vm-command-shared.js +0 -23
- package/dist/cli/commands/vm-commands.d.ts +0 -3
- package/dist/cli/commands/vm-commands.js +0 -45
- package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
- package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
- package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
- package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
- package/dist/cli/commands/vm-release-command.d.ts +0 -5
- package/dist/cli/commands/vm-release-command.js +0 -101
- package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
- package/dist/cli/commands/vm-spawn-command.js +0 -177
- package/dist/cli/commands/vm-status-command.d.ts +0 -3
- package/dist/cli/commands/vm-status-command.js +0 -50
- package/dist/services/vm/vm-lease.d.ts +0 -40
- package/dist/services/vm/vm-lease.js +0 -160
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"metadata": {
|
|
3
3
|
"pluginRoot": ".",
|
|
4
|
-
"version": "4.1.
|
|
4
|
+
"version": "4.1.6"
|
|
5
5
|
},
|
|
6
6
|
"plugins": [
|
|
7
7
|
{
|
|
8
8
|
"name": "peaks-loop",
|
|
9
9
|
"description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
|
|
10
|
-
"version": "4.1.
|
|
10
|
+
"version": "4.1.6",
|
|
11
11
|
"author": {
|
|
12
12
|
"name": "SquabbyZ"
|
|
13
13
|
},
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,41 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 4.1.6 — 2026-10-18(三类闸规则收紧:配置路径的 reader、skip 允许列表、声明类型;两个 refactor 切片被自己新增的规则抓住)
|
|
4
|
+
|
|
5
|
+
**版本级别**: 未发布区间 `v4.1.5..HEAD` 共 **38 个 commit**(**2 feat / 11 fix / 3 refactor / 7 chore / 8 docs / 4 test+style**)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。**本版含两处用户可见的行为收紧**,按 4.1.5 的先例明写:声明为 `docs`/`chore`/`config` 的请求不能再携带产品源码;`config` 不再能通过 skip 记录跳过它的 QA 阶段。
|
|
6
|
+
|
|
7
|
+
### 1. 声明类型第一次被改动内容佐证(`f7de7828`)
|
|
8
|
+
|
|
9
|
+
前置表由 rid 的**声明类型**选择,而没有任何东西检查类型与 diff 是否一致——一个标成 `chore` 的请求可以改运行时代码并通过提交闸。现在 `docs`/`chore`/`config` 的请求若触及 `src/**` 或 `packages/<name>/src/**`,会在 `rd:implemented`、`rd:qa-handoff` 和 `rd:handed-off` 被拒绝;工具链路径(`scripts/`、`tests/`、`.husky/`、配置、lockfile)不受影响。规则与 file-size 棘轮**共用一次 git 枚举**(`-z` + `--relative`),非 ASCII 路径不能借 C-quote 逃过 `src/` 判定。**原建议"把 `checkTypeSanity` 接到提交腿"被测量否决**:它对 `chore` 只与纯 lockfile 一致,会拒掉本仓库自己的基础设施切片;提交腿也没有 rid↔commit 绑定。
|
|
10
|
+
|
|
11
|
+
**这个切片被它自己的规则抓住了**:它声明 `chore` 却改 `src/`,于是重定向为 `refactor`,走完 handoff / code review / security / perf / QA 的完整证据链,而不是给自己开豁免。perf 在 `qa-handoff`/`handed-off` 记了一个 `block`(+2 次 git spawn,约 126 ms 一次性),为关闭"`implemented` 之后再加 `src/` 变更"的窗口而**显式豁免并记录**。
|
|
12
|
+
|
|
13
|
+
### 2. skip 允许列表从 QA-free 类型派生(`98614528`)
|
|
14
|
+
|
|
15
|
+
`SKIPPABLE_TYPES` 此前是手写列表 `['docs','config','chore']`,而 `typeRequiresQaPhase('config')` 为 **true**——一条本地 skip 记录可以跳过 config 本来要求的 `SECURITY_REVIEW` 与 `TEST_REPORT`。现在 `QA_FREE_TYPES = VALID_REQUEST_TYPES.filter(t => !typeRequiresQaPhase(t))`,允许列表就是它(今天 `docs` + `chore`),`config` 退出。读路径还拒绝写入侧不可能产生的记录:空 reason、空/未 trim/含控制字符的 gate 名(C0/DEL/C1)、控制字符字段;坏记录读成 `null`,闸照常执行。署名行改成 **"record says applied by …"**——它是自述,不是证明。
|
|
16
|
+
|
|
17
|
+
### 3. 配置路径的 reader 不再在复合 diff 里消失(`43f3cc51`)
|
|
18
|
+
|
|
19
|
+
分类器只看映射决定网:一个不映射到任何测试的路径既不触发全量回退,也不扩大子集。`.gitignore + src/` 因此会跳过读根 `.gitignore` 的 `tests/unit/workspace/top-level-change-id-guard.test.ts`——用线上分类器扫全部 2246 个非空提交,**9 个提交就是这个复合形状**。落地的是一条**声明映射**(`.gitignore`、`pnpm-workspace.yaml`)+ `/^\.gitattributes$/` 全量触发器(它没有根 reader,记下的映射指向的测试只把键写在注释里)。arm 要求一行非注释代码同时命名键、带读/join 调用、绑定 `REPO_ROOT`、且不带写调用;红控包括注释-only、临时根读取、写操作和缺失的 reader。
|
|
20
|
+
|
|
21
|
+
### 4. 两个"把崩溃/竞态读成通过"的修复(`988c6197`、`1cba9312`)
|
|
22
|
+
|
|
23
|
+
- **format 棘轮把 prettier 崩溃读成干净树**:`typeof '' === 'string'` 让 exit 1 + 空 stdout 返回 `''`,腿打印 `0 unformatted file(s)` + held。现在只有 prettier **确实列出**了文件才返回列表。
|
|
24
|
+
- **树扫描器在文件消失时杀死整个测试文件**:`ENOENT` 发生在枚举与读取之间,而扫描在模块作用域运行,失败是 `(0 tests)`。现在只容忍 `ENOENT`,并报告 `listed/read/vanished`,缺口可见而不是被吞掉。
|
|
25
|
+
|
|
26
|
+
### 5. 其余已落地
|
|
27
|
+
|
|
28
|
+
- **A–F sweep 的闸改进**:`.github/` 与 `.husky/` 成为全量触发器(`af8f8053`);`GATE_GUARD_SUITES` 的根层按规则并入每个子集(`27a85b7f`);`src/` 的每一段都映射到 `tests/unit/<area>`,130 个孤儿测试降到 6 个且逐个记录(`7fa29669`);类型表决定 QA 相位(`d62eda51`)。
|
|
29
|
+
- **CI 与门禁**:覆盖率地板成为 CI 可执行的棘轮(`87b76fa3`);coverage 地板测量它记录的人口(`b1c5c89e`);一个要求 100% 且无人调用的门被移除(`888fb3e9`)。
|
|
30
|
+
- **CLI**:`peaks scan best-practice` 可以真正查阅文档(`195f573b`);VM isolation 表面(从未运行)被移除(`0172d89f`);路径守卫判断目录本身而不是调用者的拼写(`82c6f384`)。
|
|
31
|
+
|
|
32
|
+
### 已知残余(记录,不粉饰)
|
|
33
|
+
|
|
34
|
+
- ③c 的反向不可发现性(未在映射中的 reader)、tooling 路径的误标、skip 记录 provenance 不可验证。
|
|
35
|
+
- 13 个 A–F 的 RD 工件停在 `implemented`——**grandfathered**;现在回溯关闭会触发 ③c。
|
|
36
|
+
- ③c 的 perf `block` 已显式豁免;③b 的安全/文档 LOW 已记录。
|
|
37
|
+
- 4 个 workspace 包随根版本各 +1 patch(internal-runtime 0.0.46、mut 0.1.60、shared 0.0.95、shared-channel 0.0.63),`CLI_VERSION` 与 `RUNTIME_VERSION` 由 `scripts/sync-version.mjs` 同步。
|
|
38
|
+
|
|
3
39
|
## 4.1.5 — 2026-10-14 (快车道从设计走到落地并带来一个新命令族;代码门与提交禁令第一次真的会拒绝;提交边界补齐三道门;派发提示第一次被自己的 CLI 校验;artifact 按 rid 落盘,两条切片停止互相覆写)
|
|
4
40
|
|
|
5
41
|
**版本级别**: 未发布区间 `v4.1.4..HEAD` 共 **125 个 commit**(**13 feat / 37 fix / 2 refactor / 5 chore / 3 test / 3 style** / 其余 62 docs+memory)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。
|
package/README-en.md
CHANGED
|
@@ -9,7 +9,6 @@
|
|
|
9
9
|
[](https://github.com/SquabbyZ/peaks-loop/actions/workflows/ci.yml)
|
|
10
10
|
[](./LICENSE)
|
|
11
11
|
[](https://www.npmjs.com/package/peaks-loop)
|
|
12
|
-
[](#status)
|
|
13
12
|
[](https://github.com/SquabbyZ/peaks-loop/stargazers)
|
|
14
13
|
|
|
15
14
|
**English** · [简体中文](./README.md)
|
|
@@ -24,22 +23,13 @@
|
|
|
24
23
|
|
|
25
24
|
## What it is
|
|
26
25
|
|
|
27
|
-
peaks-loop is
|
|
26
|
+
peaks-loop is an orchestration layer that sits on the AI coding tool you already use (**Claude Code** / **Z Code**). You send one slash command in the chat box and it runs the whole chain for you: split the work → run it gate by gate → **stop at the gate that breaks**.
|
|
28
27
|
|
|
29
|
-
|
|
30
|
-
| --- | --- | --- |
|
|
31
|
-
| **Loop Engineering Asset** | Method system, first-class | Answers "why this loop exists, when it fires, what counts as success, how it improves" |
|
|
32
|
-
| **Bee Asset** | Executable body, first-class | The runnable body of a Loop Engineering Asset — every bee in the swarm |
|
|
33
|
-
| **Workflow Trace** | Evidence, **NOT** the durable product | Immutable per-run record; feeds crystallization + evaluation, not the user-facing asset |
|
|
34
|
-
| **Evolution Evaluation** | Anti-drift gate, mandatory | Every improvement needs an independent-context scorer + a regression skeptic; keep only if it passes, otherwise revert |
|
|
35
|
-
|
|
36
|
-
- **Engineering principles = karpathy-style · Verify every improvement = darwin-style** — both are required, not optional. Drop karpathy and your principles are never written down; drop darwin and your changes are never verified. They are co-equal layers, not sequential steps.
|
|
37
|
-
- `/peaks-code` is the **code-domain** long-task Loop Engineering orchestrator, not a general orchestrator; non-code lanes (`peaks-content` / `peaks-doctor` / `peaks-issue-fix-orchestrator` / `peaks-sop`) ship as independent `peaks-*` bees, **not** as subclasses of `peaks-code`.
|
|
38
|
-
- Twice-clean runs sediment into your local tactic pool (bee); broken runs come back for you to redefine. Your few bees grow with your taste.
|
|
28
|
+
There are only two things you ever do: **say a sentence**, or **pick one option**.
|
|
39
29
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
30
|
+
- **It is not a new AI CLI.** It does not grab your shell, your prompt, or your IDE, and it does not replace any native entry point inside them.
|
|
31
|
+
- **You memorize no CLI, hand-author no manifest, hand-fill no form.** All CLI verbs are hidden from you and open to the LLM; it runs the commands, you just talk.
|
|
32
|
+
- **It does not decide for you.** Decisions that touch your assets come back to you as a choice; everything else it runs on its own.
|
|
43
33
|
|
|
44
34
|
---
|
|
45
35
|
|
|
@@ -60,11 +50,15 @@ npm i -g peaks-loop
|
|
|
60
50
|
>
|
|
61
51
|
> If you suspect the skills did not land, **no CLI command reports that state today**
|
|
62
52
|
> (`peaks skill search` queries the in-package skill pool, which says nothing about your IDE directory), so
|
|
63
|
-
> look at the directory itself:
|
|
64
|
-
>
|
|
65
|
-
>
|
|
53
|
+
> look at the directory itself:
|
|
54
|
+
>
|
|
55
|
+
> ```bash
|
|
56
|
+
> ls ~/.claude/skills | grep '^peaks-' | head # or the IDE dir you actually use
|
|
57
|
+
> ```
|
|
58
|
+
>
|
|
59
|
+
> Empty means the CLI installed but the skills did not. The gap is recorded in `.peaks/docs/backlog.md` §2.52a.
|
|
66
60
|
|
|
67
|
-
Then, in the **Claude Code** or **Z Code** chat you already use, send an **explicit slash command** (the leading slash is what triggers peaks-loop
|
|
61
|
+
Then, in the **Claude Code** or **Z Code** chat you already use, send an **explicit slash command** (the leading slash is what triggers peaks-loop):
|
|
68
62
|
|
|
69
63
|
```
|
|
70
64
|
/peaks-code walk me through this codebase
|
|
@@ -80,7 +74,6 @@ Other slash commands you'll reach for:
|
|
|
80
74
|
/peaks-issue-fix-orchestrator fix the next 30 open issues upstream
|
|
81
75
|
/peaks-sop author the team's release SOP
|
|
82
76
|
/peaks-solo I'll do this again — sediment it as a local tactic
|
|
83
|
-
/peaks-solo run it like last time
|
|
84
77
|
```
|
|
85
78
|
|
|
86
79
|
<sub>📦 Adapters for other AI coding tools are coming — contributions welcome → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues).</sub>
|
|
@@ -89,13 +82,33 @@ No CLI to memorize. No manifest to hand-author. No second terminal to open. **Se
|
|
|
89
82
|
|
|
90
83
|
---
|
|
91
84
|
|
|
92
|
-
##
|
|
85
|
+
## Where files land after install
|
|
93
86
|
|
|
94
|
-
|
|
87
|
+
After `npm i -g`, the three asset classes (**skills / agents / output-styles**) are stored **once**, under
|
|
88
|
+
`~/.peaks/{skills,agents,output-styles}` in your own home directory. Every entry in each IDE directory
|
|
89
|
+
(`~/.claude/…`, `~/.trae/…`, and so on) is **a link to it** — directories via junction, individual `.md` files
|
|
90
|
+
via symlink. So upgrading `peaks-loop` leaves the link targets unchanged and needs no rebuild.
|
|
95
91
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
92
|
+
Two things that affect you directly:
|
|
93
|
+
|
|
94
|
+
- **Managed entries are overwritten on upgrade.** An entry peaks-loop installed (say
|
|
95
|
+
`~/.claude/agents/karpathy-reviewer.md`) sits next to a `.peaks-managed` sidecar that marks ownership, and its
|
|
96
|
+
contents are updated on upgrade. **To keep your own version instead, delete that sidecar** — an entry without
|
|
97
|
+
the marker is always treated as yours, and is **never replaced and never deleted**.
|
|
98
|
+
- **On some Windows hosts they degrade to real copies.** Without Developer Mode and without administrator
|
|
99
|
+
rights, **file** symlinks cannot be created (the junctions used for directories are unaffected), so the
|
|
100
|
+
installer writes real copies and says so on stderr: `installed as REAL COPIES because this host refused a symlink`.
|
|
101
|
+
The contents still follow the upgrade.
|
|
102
|
+
|
|
103
|
+
The true-source root can be redirected with the `PEAKS_HOME` environment variable. The full model, what happens
|
|
104
|
+
when you upgrade from 4.1.1, and how to verify and roll back →
|
|
105
|
+
[`.peaks/docs/canonical-store.md`](./.peaks/docs/canonical-store.md).
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## What it does for you
|
|
110
|
+
|
|
111
|
+
Code, content, project health, issue sweeps, custom workflows — **every domain has its own orchestrator**, and each one runs under the same discipline: "gate fails = stop". All you do is pick a command and send it:
|
|
99
112
|
|
|
100
113
|
| Domain | Send this slash command | It will… |
|
|
101
114
|
| --- | --- | --- |
|
|
@@ -121,112 +134,25 @@ Every lane opens with **one slash command**.
|
|
|
121
134
|
## Why people pick it
|
|
122
135
|
|
|
123
136
|
- **Natural language is the interface.** No CLI to learn, no commands to memorize. **Use an explicit slash command (e.g. `/peaks-code xxx`)** to route to the right orchestrator; everything after the slash is plain language. The LLM runs the commands on your behalf.
|
|
124
|
-
- **Gates that actually block, not decorate.**
|
|
125
|
-
- **Run-once flows become local tactics (bees).**
|
|
126
|
-
- **Sits on top of what you already run.** Not a new AI CLI to learn — it rides on **Claude Code** and **Z Code**. No shell grab, no prompt grab, no IDE grab. Other tools: adapters in progress
|
|
137
|
+
- **Gates that actually block, not decorate.** Code audit, security scan, QA gate, review sign-off — all on by default. **Audit fails = stop. QA fails = stop.**
|
|
138
|
+
- **Run-once flows become local tactics (bees).** What sediments lands in your local `~/.peaks/` pool — twice-clean runs auto-promote, broken runs come back for you to redefine. **Next time, just say "run that one" and the whole playbook slots back in.** Your few tactics grow with your taste.
|
|
139
|
+
- **Sits on top of what you already run.** Not a new AI CLI to learn — it rides on **Claude Code** and **Z Code**. No shell grab, no prompt grab, no IDE grab. Other tools: adapters in progress.
|
|
127
140
|
- **You decide, it executes.** Decisions that touch your assets are yours; everything else it runs on its own. **Zero learning cost. One minute to first task.**
|
|
128
141
|
|
|
129
142
|
---
|
|
130
143
|
|
|
131
|
-
##
|
|
132
|
-
|
|
133
|
-
| Gate | Default | What it catches |
|
|
134
|
-
| --- | --- | --- |
|
|
135
|
-
| Unit + integration tests | ✅ on | regressions at the code level |
|
|
136
|
-
| Code audit (lint / prose / type) | ✅ on | drift in style and intent |
|
|
137
|
-
| Security scan | ✅ on | secrets, SSRF, injection, dangerous IO |
|
|
138
|
-
| QA review | ✅ on | task-level gate — fails loud, stops clean |
|
|
139
|
-
| Review sign-off | ✅ on | nothing ships without eyes on it |
|
|
140
|
-
| Anti-drift evaluation (Evolution Evaluation) | ✅ on | every improvement needs an independent scorer + a regression skeptic, otherwise revert |
|
|
141
|
-
|
|
142
|
-
**All gates on by default. You only speak to turn one off.**
|
|
143
|
-
|
|
144
|
-
---
|
|
145
|
-
|
|
146
|
-
## Status · shipping 4.0.17
|
|
147
|
-
|
|
148
|
-
<p align="center">
|
|
149
|
-
<img src="./assets/readme/pulse.svg" alt="peaks-loop live metrics — 4 tiles + sparkline + pipeline progress" width="92%"/>
|
|
150
|
-
</p>
|
|
151
|
-
|
|
152
|
-
<p align="center">
|
|
153
|
-
<img src="./assets/readme/trace-stream.svg" alt="peaks-loop live diff & log stream — code diff + scrolling log + 7-gate chain" width="92%"/>
|
|
154
|
-
</p>
|
|
155
|
-
|
|
156
|
-
| | |
|
|
157
|
-
| --- | --- |
|
|
158
|
-
| **Latest** | [](https://www.npmjs.com/package/peaks-loop) — 4.1.5 (2026-10-14) |
|
|
159
|
-
| **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`) |
|
|
160
|
-
| **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 |
|
|
161
|
-
| **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 |
|
|
162
|
-
| **IDE adapters** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder (adapters in progress — contributions welcome) |
|
|
163
|
-
| **Runtime** | Node ≥ 20 |
|
|
164
|
-
| **License** | MIT |
|
|
165
|
-
|
|
166
|
-
### What 4.0.17 actually shipped (2026-08-07)
|
|
144
|
+
## Strongly recommended · compose these three
|
|
167
145
|
|
|
168
|
-
|
|
169
|
-
| --- | --- | --- |
|
|
170
|
-
| **Vitest worker cap (root-cause fix)** | 17 timeouts blocked the full suite; the root cause was `pool: 'forks' + fileParallelism: true` with no `maxWorkers` cap. On a 16-core box, ~15 fork workers + 2 files spawning real `node` processes = 8.8× oversubscription. `testTimeout` measures wall clock, so descheduled tests burned 30s doing nothing. Fix: `maxWorkers = floor(cpus/2)` + `PEAKS_VITEST_MAX_WORKERS` env override + 6-case drift-guard test. **17 timeouts → 0, wall 383.67s → 360.40s, 3/3 AC-1 runs all 0 timeouts.** | commit `ace1a03d` + guard test `tests/unit/vitest-concurrency-guard.test.ts` |
|
|
171
|
-
| **PRD-002b ESLint strictification (`no-magic-numbers`)** | Slice 2 dropped 917 → 192 violations (−725). 20 source files extracted 140+ inline magic numbers into named `const`s. `no-magic-numbers` config got `ignore: [-1, 0, 1, 2, 100, 1000]` + `ignoreArrayIndexes / ignoreDefaultValues`. 7 BDD tests, 31/31 lint tests PASS. Severity stayed `warn` (D5 no-touch-stockcode). | commits `d5ef17c1` + `0c3187c4` + 7 BDD tests |
|
|
172
|
-
| **Statusline `--now` injection + 24-spawn amortization** | Slice 1 root cause: the test wrote `updatedAt = new Date().toISOString()` (just-NOW) and expected the lifecycle to be "within 10s window", but under full-suite concurrency the spawned subprocess is descheduled and only executes several seconds later — the completed-expiry window ages out → C1 baseline fallback → `expected '' to contain '[████████]'`. Fix: add `--now <ms>` CLI option; test pins `TEST_NOW_MS` shared by both CLI and lifecycle. **Slice 7** went further: replaced 24 real `node dist/cli/index.js` spawns with a single `beforeAll` IPC server (JSON over stdio). Wall 216s → 29s (7.5× speedup), 24/24 PASS. | commit `3d6e4bc9` (slice 1 inside) + `44c42424` (slice 7) |
|
|
173
|
-
| **Complexity refactor (slice 3 A+B+C+D + slice 4 bundle-reader rewrite)** | Slice 3 four-stage refactor dropped 357 → 330 complexity violations (target ≤90, this wave covers the high cohort): spec-service parser → table-dispatch, slice-decompose → FSM, project-context `detectComponentLibrary` → 11-dispatch table. **Slice 4** = bundle-reader full rewrite, 5 violations → 1, public API preserved verbatim. | commits `72ef798c` + `31160051` + `1ac6e56d` + `923be824` + `0603754d` + `6b27eb94` |
|
|
174
|
-
| **Type-narrowing + max-lines pilot (slice 5+6)** | Slice 5 closed 670 violations: 667 phantom `no-explicit-any` config swap (broken ruleId fix, same pattern as the no-duplicate-imports 4.0.16 fix) + 3 real narrowings (`catch (error: any)` → `unknown` + `instanceof Error`). Slice 6 split 4 over-length functions in `dispatch-record-writer.ts`, 4 → 0 in target file. Both slices prove the rules are essentially exhausted — true count is an order of magnitude smaller than the sediment claimed. | commits `fbb43e9e` + `3d6e4bc9` (inside) |
|
|
175
|
-
| **Mac auto-compact ESM anti-fake-green: 5/5 verified** | Slice 8 audit-only: 5 defenses (`readClaudeTranscriptFallback` / `readClaudeStatuslinePercent` / `presence-marker-detector` / `post-compact-detector` / `step-08-gate`) all in place, ESM `require()` 0 hits, legacy silent-catch blocks already explicit re-throw `ReferenceError` / `SyntaxError`. | sediment `.peaks/memory/2026-08-07-mac-esm-defense-audit.md` |
|
|
176
|
-
| **Caller-binding coverage extension (slice 9)** | 14 BDD tests covering 5 gap categories: multi-tenant isolation / post-rotation recovery / TTL freshness / rotation hygiene / primary-wins contract. `tests/unit/session/*` grew from 51 → 65 tests. | commit `823be8c4` + new file `tests/unit/session/caller-binding-slice-9-edge-cases.test.ts` |
|
|
177
|
-
| **Pre-publish gates all green** | `gate-cli-version` ALIGNED (root 4.0.17 == shared CLI_VERSION 4.0.17), `build-integrity: OK`, 0 `Co-Authored-By` trailers. | per `peaks-loop-publishing-critical-hard-rules` recipe |
|
|
178
|
-
|
|
179
|
-
---
|
|
180
|
-
|
|
181
|
-
## Strongly recommended · compose these four
|
|
182
|
-
|
|
183
|
-
> **Zero learning cost.** That's the biggest reason to use them together — not just that the effect is excellent, but that **all four projects speak the same interface: natural language + a choice.** You say one sentence; the LLM runs the commands, applies the gates, and follows the playbook.
|
|
184
|
-
|
|
185
|
-
<p align="center">
|
|
186
|
-
<img src="./assets/readme/footer.svg" alt="peaks-loop recommended stack" width="92%"/>
|
|
187
|
-
</p>
|
|
146
|
+
> **Zero learning cost.** The biggest reason to use them together is that all three speak the same interface — "natural language + one choice". You say one sentence; the LLM runs the commands, applies the gates, and follows the playbook, with nothing for you to memorize.
|
|
188
147
|
|
|
189
148
|
| Role | Project | One-liner |
|
|
190
149
|
| --- | --- | --- |
|
|
191
|
-
| **Sediment + gates** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← you are here |
|
|
150
|
+
| **Sediment + gates** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← you are here | install → PRD/RD/QA/UI/SC/TXT as one chain + sediment |
|
|
192
151
|
| **Tactical handbook** | [affaan-m/ECC](https://github.com/affaan-m/ECC) | the best tactics, skills, and SOPs you can put on top of Claude Code |
|
|
193
152
|
| **Process & discipline** | [obra/superpowers](https://github.com/obra/superpowers) | brainstorming / TDD / debugging / code-review as flow disciplines, every one with a hard exit |
|
|
194
153
|
|
|
195
154
|
**One sentence to use them all**: clone the two repos above, install peaks-loop, hand the rest to your LLM — it pulls what it needs, holds the gates, lands the tactics, sediments the flow.
|
|
196
155
|
|
|
197
|
-
### Tribute
|
|
198
|
-
|
|
199
|
-
peaks-loop's two engineering spines come straight from these projects:
|
|
200
|
-
|
|
201
|
-
- [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) — "engineer every rule" is etched into our method layer.
|
|
202
|
-
- [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill) — "verify every improvement" is etched into our anti-drift gate.
|
|
203
|
-
|
|
204
|
-
---
|
|
205
|
-
|
|
206
|
-
## For developers · 24h mode and batch tooling
|
|
207
|
-
|
|
208
|
-
> **For peaks-loop project maintainers and "24h mode" users** — end-users, skip this section and head straight to FAQ.
|
|
209
|
-
|
|
210
|
-
If your workflow reaches **24h mode** (`peaks session 24h-mode` → `24H_ACTIVE`), **batch closure passes**, or anything that needs to spawn many `peaks request transition` (or similar) calls from a parent LLM context, **install Python 3.10+ first**:
|
|
211
|
-
|
|
212
|
-
```bash
|
|
213
|
-
# macOS / Linux
|
|
214
|
-
brew install python@3.12 # or: pyenv install 3.12
|
|
215
|
-
|
|
216
|
-
# Windows
|
|
217
|
-
winget install Python.Python.3.12
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
**Why not Node.js?peaks-loop itself is Node/pnpm, isn't it?** — peaks-loop's *own* hard dep stays Node.js, **unchanged**. The reason Python wins for *batch-utility scripting* is the `subprocess` layer: Python's `subprocess.run(capture_output=True, env=...)` is significantly less painful than Node's `child_process.spawn` on Windows + UTF-8 + cross-platform (one line of `LANG` / `LC_ALL` / `PYTHONIOENCODING` env in the child fixes it; Node's `child_process` needs separate `windowsHide` + `console.log` encoding tricks). And the code is shorter.
|
|
221
|
-
|
|
222
|
-
**Rules** (sedimented at `.peaks/memory/2026-08-01-24h-mode-59-rid-closure-pass.md`):
|
|
223
|
-
|
|
224
|
-
1. **Detect-then-pick**: probe `python3 --version` (or `py -3` on Windows) first; use Python if available; else fall back to `node`; else surface the missing-runtime error — do not silently degrade.
|
|
225
|
-
2. **Path**: place the script at **`.peaks/_tools/<name>.py`** (or `.mjs`). Do **not** place under `bin/` — that directory is reserved for peaks-loop's own source-shipped scripts and pollution from temporary helpers is a maintenance hazard. The `_`-prefixed `.peaks/_tools/` mirrors `.peaks/_runtime/`, `.peaks/_sub_agents/`, `.peaks/_dogfood/` and is gitignored.
|
|
226
|
-
3. **Delete when the work is done.** Temporary scripts are not deliverables; leaving them around invites the "what is this?" question.
|
|
227
|
-
|
|
228
|
-
This section is **not for ordinary end-users** — `npm i -g peaks-loop` + a slash command is all you need. Python is for the layer of people who want to write their own batch utilities.
|
|
229
|
-
|
|
230
156
|
---
|
|
231
157
|
|
|
232
158
|
## FAQ
|
|
@@ -234,14 +160,7 @@ This section is **not for ordinary end-users** — `npm i -g peaks-loop` + a sla
|
|
|
234
160
|
<details>
|
|
235
161
|
<summary><b>How does it relate to Claude Code / Z Code?</b></summary>
|
|
236
162
|
|
|
237
|
-
It **sits on top of** them, not in place of.
|
|
238
|
-
|
|
239
|
-
</details>
|
|
240
|
-
|
|
241
|
-
<details>
|
|
242
|
-
<summary><b>Do I need to learn CLI commands?</b></summary>
|
|
243
|
-
|
|
244
|
-
No. You speak or pick; the LLM runs the commands. **All CLI verbs are hidden from you, open to the LLM.**
|
|
163
|
+
It **sits on top of** them, not in place of. It doesn't grab your shell, your prompt, or your IDE — you keep using them as usual. **Adapters for other AI coding tools are in progress — contributions welcome** → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues).
|
|
245
164
|
|
|
246
165
|
</details>
|
|
247
166
|
|
|
@@ -262,78 +181,23 @@ It changes, but **the gates hold**. Audit fails = nothing ships. QA fails = noth
|
|
|
262
181
|
<details>
|
|
263
182
|
<summary><b>What's new in 4.x vs 3.x?</b></summary>
|
|
264
183
|
|
|
265
|
-
**
|
|
184
|
+
**From a code-only tool to multi-domain orchestration:** it ships four new domain chains — `peaks-content` (content production), `peaks-doctor` (project health), `peaks-issue-fix-orchestrator` (batch issue fix), `peaks-sop` (custom SOPs) — plus `peaks-solo`, a dispatcher that routes from plain language to the right domain. Full list → [`CHANGELOG.md`](./CHANGELOG.md).
|
|
266
185
|
|
|
267
186
|
</details>
|
|
268
187
|
|
|
269
188
|
---
|
|
270
189
|
|
|
271
|
-
## Full skill index
|
|
272
|
-
|
|
273
|
-
13 user skills · every entry point lives in `skills/<name>/SKILL.md`:
|
|
274
|
-
|
|
275
|
-
<p align="center">
|
|
276
|
-
<img src="./assets/readme/skill-index.svg" alt="peaks-loop 13 user skills — full index with category badges" width="92%"/>
|
|
277
|
-
</p>
|
|
278
|
-
|
|
279
|
-
---
|
|
280
|
-
|
|
281
|
-
## Ship summary (4.x · 19 rids)
|
|
282
|
-
|
|
283
|
-
`009 · 010 · 011 · 014 · 015 · 016 · 017 · 020b · 024 · 025 · 026 · 027 · 028 · 029 · 030 · 031 · 032 · 033 · 034` — CLI surface collapse (73 → 5 byte-identical), Trusted Publishing + OIDC, 24h-mode, context spillover, DAG wave + barrier, dashboard aggregation, test-rebuild epic, karpathy-cost self-review, compact visibility, retire-auto-compact-hook, and more.
|
|
284
|
-
|
|
285
|
-
<p align="center">
|
|
286
|
-
<img src="./assets/readme/ship-summary.svg" alt="peaks-loop 4.x 19-rid ship timeline with category chips" width="92%"/>
|
|
287
|
-
</p>
|
|
288
|
-
|
|
289
|
-
---
|
|
290
|
-
|
|
291
|
-
## Downstream consumer notes
|
|
292
|
-
|
|
293
|
-
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:
|
|
294
|
-
|
|
295
|
-
- **`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.
|
|
296
|
-
- **`.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`.
|
|
297
|
-
- **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.
|
|
298
|
-
- **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`).
|
|
299
|
-
- **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.
|
|
300
|
-
|
|
301
|
-
Install snippet (typical consumer):
|
|
302
|
-
|
|
303
|
-
```bash
|
|
304
|
-
# Add peaks-loop to your project
|
|
305
|
-
npm install peaks-loop
|
|
306
|
-
|
|
307
|
-
# Bootstrap codegraph for the first time (refuses if .codegraph/ already
|
|
308
|
-
# exists with a non-peaks-loop schema; exit code 73 + envelope)
|
|
309
|
-
npx peaks codegraph init --project .
|
|
310
|
-
|
|
311
|
-
# Verify the doctor is green for downstream resolution modes
|
|
312
|
-
npx peaks doctor --project .
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
Three common pitfalls:
|
|
316
|
-
|
|
317
|
-
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.
|
|
318
|
-
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.
|
|
319
|
-
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.
|
|
320
|
-
|
|
321
|
-
---
|
|
322
|
-
|
|
323
190
|
## Links
|
|
324
191
|
|
|
325
192
|
- All skills → [`skills/`](./skills/)
|
|
326
193
|
- Changelog → [`CHANGELOG.md`](./CHANGELOG.md)
|
|
327
194
|
- Questions → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
|
|
328
|
-
- Tribute: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
|
|
329
195
|
- Recommended combo: [affaan-m/ECC](https://github.com/affaan-m/ECC) · [obra/superpowers](https://github.com/obra/superpowers)
|
|
330
196
|
|
|
331
197
|
---
|
|
332
198
|
|
|
333
|
-
---
|
|
334
|
-
|
|
335
199
|
<div align="center">
|
|
336
200
|
|
|
337
201
|
MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · English · [简体中文](./README.md)
|
|
338
202
|
|
|
339
|
-
</div>
|
|
203
|
+
</div>
|