peaks-loop 4.1.16 → 4.1.18

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.
Files changed (48) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +193 -0
  3. package/dist/cli/commands/code-auto-compact-command.js +46 -23
  4. package/dist/cli/commands/code-auto-compact-deferral.d.ts +34 -0
  5. package/dist/cli/commands/code-auto-compact-deferral.js +59 -0
  6. package/dist/cli/commands/code-gate-command.d.ts +4 -4
  7. package/dist/cli/commands/code-gate-command.js +4 -4
  8. package/dist/cli/commands/core/skill-registry-commands.js +32 -0
  9. package/dist/cli/commands/core/skill-store-report.d.ts +8 -0
  10. package/dist/cli/commands/core/skill-store-report.js +79 -0
  11. package/dist/cli/commands/dispatch-prompt-composition.js +7 -2
  12. package/dist/cli/commands/dispatch-scratch-path-block.d.ts +73 -0
  13. package/dist/cli/commands/dispatch-scratch-path-block.js +131 -0
  14. package/dist/cli/commands/hooks-commands.js +36 -7
  15. package/dist/cli/commands/hooks-uninstall-command.js +5 -5
  16. package/dist/services/code/auto-compact-orchestrator.js +7 -5
  17. package/dist/services/code/auto-compact-run-types.d.ts +8 -4
  18. package/dist/services/dispatch/dispatch-ledger-reader.d.ts +13 -0
  19. package/dist/services/dispatch/dispatch-ledger-reader.js +164 -0
  20. package/dist/services/doctor/doctor-service/checks/canonical-store-version.d.ts +57 -0
  21. package/dist/services/doctor/doctor-service/checks/canonical-store-version.js +190 -0
  22. package/dist/services/doctor/doctor-service/plugin-registry.js +2 -0
  23. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  24. package/dist/services/hooks/gate-path-normalize.d.ts +37 -0
  25. package/dist/services/hooks/gate-path-normalize.js +74 -4
  26. package/dist/services/hooks/hook-payload-cwd.js +25 -9
  27. package/dist/services/hooks/pre-tool-code-gate.d.ts +24 -4
  28. package/dist/services/hooks/pre-tool-code-gate.js +72 -22
  29. package/dist/services/session/getSessionDir.d.ts +13 -0
  30. package/dist/services/session/getSessionDir.js +7 -1
  31. package/dist/services/skills/hooks-settings-types.d.ts +17 -21
  32. package/dist/services/skills/sync-service-support.d.ts +27 -0
  33. package/dist/services/skills/sync-service.js +1 -0
  34. package/dist/services/workflow/workflow-inflight-probe.d.ts +68 -31
  35. package/dist/services/workflow/workflow-inflight-probe.js +163 -75
  36. package/package.json +7 -5
  37. package/scripts/canonical-store-fs.mjs +112 -0
  38. package/scripts/canonical-store-link.mjs +13 -22
  39. package/scripts/canonical-store-marker.mjs +241 -0
  40. package/scripts/canonical-store.mjs +119 -141
  41. package/scripts/install-skills-bundles.mjs +56 -13
  42. package/scripts/install-skills-fs.mjs +73 -0
  43. package/scripts/install-skills-output-styles.mjs +8 -2
  44. package/scripts/install-skills-report.mjs +19 -0
  45. package/scripts/install-skills.mjs +9 -0
  46. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +20 -1
  47. package/skills/peaks-code/SKILL.md +1 -1
  48. package/skills/peaks-race-code/SKILL.md +6 -3
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.16"
4
+ "version": "4.1.18"
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.16",
10
+ "version": "4.1.18",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,198 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.18 — 2026-10-23(下游机器的技能商店会说谎了;门禁不再对自己的沉默撒谎)
4
+
5
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
6
+ 既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、
7
+ peaks-code 的 11 步工序与 Gate A–G **一字不改**。
8
+
9
+ 本次修的是同一条线上的**七个洞**,它们是**同一类**:**一个表面说自己做了、其实没做的事**。
10
+ 下游 macOS 机器报告"`~/.peaks/skills/peaks-code` 在,但 `~/.claude/skills/peaks-code` 软链后面的内容没有完整更新" ——
11
+ 查到最后,**发布包是好的**(4.1.16 / 4.1.17 的 tarball 里 49 个 reference 文件一个不少),
12
+ 坏的是**商店那一侧**,而且坏的方式是:**没有任何地方记录版本号**,所以"冻结在 4.1.15"和"是当前的"
13
+ **长得一模一样**。
14
+
15
+ **下游那台机器要做的:装上这个版本,跑 `peaks skill sync`。** 这次切片要的是一条**命令**,
16
+ 不是一个诊断。
17
+
18
+ ### 1. 商店的陈旧必须**可检测**,也必须**可修复**
19
+
20
+ - 此前:`~/.peaks/skills/<name>.peaks-managed` 这个 sidecar **只记了来源路径**,不记版本。
21
+ 归属靠"sidecar 在不在"判定,刷新靠**逐字节比对**。没有版本 ⇒ 陈旧**不可知** ——
22
+ 安装器不知道、`peaks doctor` 不知道、用户不知道。
23
+ - 现在:sidecar 记**两个事实** —— 来源路径 **和** 产出这份副本的**包版本**(一行 JSON)。
24
+ **旧格式仍然读得动**:只有路径的老 sidecar 解析成"是我们的,但版本未知",而**版本未知即陈旧**
25
+ (当前来源才是权威)—— 一个会在旧格式上抛错的读取器会**弄坏每一个已存在的安装**。
26
+ - 陈旧现在**按版本**判定,不只按字节。所以**记录的路径已经失效**(npm 全局前缀换了)但版本落后时,
27
+ 照样刷新;而路径失效、版本却对得上时,**不重拷**,只**订正 marker** ——
28
+ 一条指向已经不存在的路径的 marker,本身就是一条陈旧的事实。
29
+ - **用户自己写的那份仍然受保护**:**没有 marker** 的商店条目**永远不会被覆盖**。
30
+ - **doctor 检查** `skills:store-version:store` 比的是**商店记录的版本 ↔ 已安装包的版本**,
31
+ **永远只出一行**:落后=红并给出补救命令 `peaks skill sync`;当前=绿并**同时写出两个版本**;
32
+ 没有商店=绿且只是"无可比较"(没有商店的机器不是坏机器);读不出来=红、severity `warning`。
33
+ **它只读,不写。**
34
+ - **修复命令**是 `peaks skill sync`。它对 legacy、v2、以及**路径已经失效**的 marker **一律能修**。
35
+
36
+ ### 2. 为什么已有的那条检查看不见它(这一条比修复本身更值得记)
37
+
38
+ `skills:reference-parity` 检查的名字里就写着下游那个形状,它比对的是**商店 ↔ IDE 树**。
39
+ 但那台机器上 `~/.claude/skills/peaks-code` 是**指向商店的软链** —— 两棵树**是同一棵树**,
40
+ 永远"一致"。**一份冻结在旧版本的商店是完全自洽的**,所以 parity 检查永远沉默。
41
+ **store↔IDE 的一致性看不见 store↔package 的陈旧** —— 这是两个不同的轴,此前只有一个。
42
+ 新加的那条检查在**另一个轴**上,它**不是** parity 检查的替代品。
43
+
44
+ ### 3. 同样这一类:门禁说的和门禁做的不一致
45
+
46
+ - **`peaks hooks install --help`** 描述了一个命令**早就不做**的效果:`--no-progress`
47
+ 说自己会"跳过 progress-start 那个 PreToolUse 条目",而**父命令自己的描述**说那个条目
48
+ **早已不再安装**(slice #014)。这个参数被穿了四层、最终进到一个**下划线开头、根本没被读**的参数里。
49
+ 它的帮助文本还**没提**全局安装会往用户全局的 `~/.claude/skills/peaks-code/hooks/` 里拷两个脚本 ——
50
+ 下游那台机器正是跑过这条命令的机器。
51
+ - **`build-integrity`**:零个带 `.ts` 源码的包,会打出和"核对了二十个包"**一模一样**的
52
+ `build-integrity: OK`。空集是**合法的**,所以**退出码仍然是 0**;变的是**那句话**,而且它
53
+ **刻意不含那个全清字符串** —— `build-integrity: OK (nothing to check)` 仍然**包含**
54
+ `build-integrity: OK`,而那正是这条切片要防的"读平了"。
55
+ - **提交门**:本次之前,同一个切片里有**三个**文件**带着未格式化**的状态进了 commit,
56
+ 而**提交时跑的每一个门都是绿的**;是**推送门**把它们拦下来的。原因是
57
+ `lint-staged` 把 `tests/**` 当作"在 lint scope 之外"**直接丢掉了**。
58
+ 现在提交门多了一条**宽格式腿**:scope 之外但在宽 glob 之内的**已暂存**文件不干净就**拒**,
59
+ 并**点名文件与确切的修法**。
60
+ **宽检查的基线集合是空的**(债在 2026-10-17 收干净了),所以这条规则字面上就是
61
+ "**不许有未格式化的文件**",**不需要逐文件的基线行** —— 它和提交门那条**逐文件棘轮**
62
+ 是**两种**机制,owner 2026-10-03 的 lint scope 决定**没有被重开**,eslint 腿**也没有被放宽**。
63
+ - **叶子代理的临时目录**不再依赖 cwd:派发提示里现在**机器注入**一块绝对路径的说明 ——
64
+ 和 Karpathy 那一块**同一个机制**("一个忙起来会忘掉的义务不是执行器")。
65
+ 路径是 `<projectRoot>/.peaks/_runtime/<sid>/<role>/scratch/`,且用**正斜杠** ——
66
+ 因为反斜杠对 POSIX shell 是转义字符,`> D:\repo\x.log` 在那里写的是 `D:repox.log`,
67
+ **就落在 cwd 里**。**那正是这个泄漏本身,被"修"出来时的形状。**
68
+ - **auto-compact 的延后**此前**在生产里从来没有触发过**:探针被喂了空的图(`graphs: []`),
69
+ 即使有图也**不可能**满足 —— 它要的是 `status === 'running'` **且**带心跳的节点,
70
+ 而图的三处写入方**从不**产出这两样。现在延后读**派发账本**(owner 2026-10-22 裁定:
71
+ 账本是唯一真相源),"在飞"= **未终态且新鲜**,新鲜度复用既有的 30 分钟阈值(**没有重复一个常量**)。
72
+ **六种"不知道"全部延后**:账本读不出、记录读不出、状态不认识、新鲜度解析不出、
73
+ 记录版本不认识、记录越出账本。
74
+ - **`.sh` 兄弟实现**(Code-Gate 的那份)现在是 **Node 命令的薄壳**:找 CLI(`PATH` 上的 `peaks`,
75
+ 否则安装器写在旁边的包根指针),`exec` 过去,子进程继承 stdin —— 载荷**原样**抵达,薄壳**不读**它。
76
+ - **`peaks skill sync --dry-run`** 以前**会建目录**,还会报"装了 184 个符号链接"——而它一个链接都没建。
77
+ 现在 dry run **什么都不写**,报 0。
78
+
79
+ ### 4. 被有意接受的取舍(写在这里以免看起来像疏漏)
80
+
81
+ - **兄弟实现的 fallback 路径**(**没有 CLI 可达**的那种情形)**仍然是第二份实现**,仍然带着 bash 规则,
82
+ 仍然和命令在 **336 行矩阵里的 130 行**上分歧:**116 行误拒**(fallback 自己的拒绝)与
83
+ **14 行偏放行**(全是同一种形状:项目内的**绝对路径** —— fallback 没有 payload 自己拼写下的项目根,
84
+ **无法相对化**)。那 14 行**既有的、未变的**,而且**薄壳委派时它不存在**。
85
+ **更便宜也更诚实的修法没有被采纳**(把 fallback 变成**一律拒绝**就能关掉那 14 行、
86
+ 让"一份实现"字面为真),代价是**在一台没有 Node CLI 的机器上拒绝一切编辑**。
87
+ **这是 owner 的取舍,留着。**
88
+ - **doctor 的一条检查"干净时不说一声"这件事没有在本版修**。`compareSkillReferenceParity`
89
+ 在完全一致时返回 `[]` —— 没有"干净"这一行,所以报告**分不清**"跑了、没发现问题"和"根本没跑"。
90
+ 本机实测:`peaks doctor --json` 出了 **88 条检查,没有一条**带 `skills:` 前缀。
91
+ 改**所有**检查的报告形状是另一件事(另一个决定、另一条切片),**不在本次**;
92
+ 本次新增的商店版本检查**干净时会出一行**。
93
+ - **`--no-progress` 没有被删掉**:它是已发布的 CLI 表面,删是破坏性变更。
94
+ 这次只把它的帮助文本**改成它实际的样子**,并用一条测试把这个事实**钉住**
95
+ (`resolveHookEntries` 两种参数返回**同一组**条目 —— 将来谁给它加上效果,那条测试会红)。
96
+ - **auto-compact 延后的"不知道就延后"是**没有时间上限**的**(+6 个月仍然如此),
97
+ 只有红线或 6 小时回收器能解开它;**三档阈值一个数字没动**,变的是**延后真的会触发**。
98
+ - **本版找到了 `diff-proj-*` 那些残留的来源,而它不是一段签进来的测试**:`diff-proj` 这个字符串在
99
+ `src/`、`scripts/`、`tests/`、`.husky/` 里**一处都没有**,那些 fixture 的 `link` 是一个指向
100
+ MSYS 风格 `/d/projects/peaks-loop/...` 的 POSIX 软链 ⇒ 是**上一轮会话里一条临时 bash 命令**,
101
+ 从仓库根按 **cwd 相对**路径写进去的。**这恰恰是本切片要治的那个习惯本身** —— 比任何测试都更有
102
+ 力地说明"规则必须机器注入"。
103
+ 那一类才是主题;找到那一个测试是另一条请求。
104
+
105
+ ### 5. 验证
106
+
107
+ - **每个切片的 QA 判决**:技能商店的版本可检测性 `pass-with-notes`;D-1(宽格式腿)
108
+ `pass-with-notes`;§2.18(nothing-to-check)`pass`;§2.31(scratch 路径块)`pass-with-notes`;
109
+ D-3(hook 帮助文本)`pass-with-notes`;§20(ledger 延后)`pass-with-notes`;
110
+ §19.1(薄壳)`pass-with-notes`,**外加一条被点名的 finding**。
111
+ - **每一条天花板都没有涨**:eslint 1696/1700、错误 560/561、prettier 0、tsc 0、
112
+ 注释死引用 0、叙述行 22/22、文件尺寸 77/77 与 21935/21935、静默告警 44/44 与 60/60。
113
+ - **商店那条**:owner 的形状被**原样重建并修好** —— legacy marker + 旧字节 + 删掉的
114
+ `references/fast-lane-norm.md` ⇒ `peaks doctor` **点名了它**("2 of 23 … peaks-code (no version recorded)")
115
+ ⇒ `peaks skill sync` ⇒ 文件回来了、`SKILL.md` 是当前的、marker 变成 v2(记着当时的包版本 4.1.17)。
116
+ **用户自己写的那一份 survived**(没有 marker 的条目**没有被覆盖**,也**没有被塞进 sidecar**,
117
+ 并且被报成"没有动它")。doctor 检查**永远只出一行**,**没有继承** parity 检查"干净时不出声"的形状。
118
+ 该切片动过的文件里 **0** 个失败。
119
+ - **§20 的延后现在真的会在生产里触发**(对着真 CLI 端到端量过):ledger 1 分钟 ⇒
120
+ `"decision": "in-flight-batch"`;31 分钟 ⇒ 照常压缩;没有 ledger ⇒ 照常压缩;
121
+ **读不出来的 ledger ⇒ 也延后**(安全方向);红线 0.96 仍然压过一切。
122
+ reader 热态成本 **2.03 ms**(5 条记录的会话上)。
123
+ - **§19.1 的差分**:**薄壳委派与 Node 命令 0 行分歧**(一份实现,结构上不可能分歧)。
124
+ **fallback 与命令的分歧**:**336 行矩阵里的 130 行**(116 误拒 + 14 偏放行);
125
+ QA 另在 **448 行**上重新导出 **15** 行偏放行 —— **同一种形状**,**既有**,**没有一行是回归**。
126
+ **仍然开着的一条残留,而且被直接量过**:`file_path = <root>/src/x.ts` ⇒ **Node 命令 deny**
127
+ (`data.action = deny`)、**fallback allow**(exit 0)—— fallback 没有 payload 自己拼写下的项目根,
128
+ **无法相对化一个绝对路径**。**既有残留**,且**只在 fallback 路径上**。记在 backlog §19.2 与安全审计里,
129
+ **没有当作已修**。
130
+ - **§19.1 的 QA 找到一条 finding,并且它推翻了刚刚重发的安全审计里的一句话**:fallback 的 payload
131
+ 扫描当时是 `grep -oE '"cwd":…' | head -n1`,扫的是**整个** payload,所以一个**嵌套**的 `cwd` 键会
132
+ 抢到首次匹配 —— 此时 fallback **不拒绝**,按 `$PWD` 读,于是**放行**了 Node 命令**拒绝**的文件。
133
+ 这与文件自己的注释和审计摘要里的断言**矛盾**(那句断言说 fallback 现在"拒绝而不是猜")。
134
+ **洞是既有的、只在 Mode 2 上、且可达性很窄**(Claude Code 的 Edit/Write/MultiEdit 的 `input`
135
+ 里没有 `cwd`)。**本次修掉了**:扫描换成一段**带深度感知**(认识字符串和花括号)的 `awk`,
136
+ 读**顶层**的 `tool_name`/`tool`/`cwd` 与 `tool_input`/`input` 里的
137
+ `file_path`/`path`/`notebook_path`;**读不懂的 payload(括号不平衡、值里带换行)一律拒绝**。
138
+ **编排器直接对着当前代码量过**:Node 命令拒,fallback 现在也拒。**审计因此又重发了一次** ——
139
+ **审计不是最后一句话**。
140
+ - **BDD 测试风格契约**(本仓库有检查器,但**没有 CI 门**):本次动过的测试文件里 **21 个**不合规,
141
+ 拆开是 **11 个在 HEAD 上就已经不合规**(本次**没有引入**那份债,记在 backlog §21.9 里
142
+ 作为另一条更大的改动)**和 12 个本次新增的**,那 12 个本次全部改到合规。
143
+ - **lint scope 的影子(`scripts/` + `tests/`)**的文件数从 818 涨到 842 —— 按 owner 2026-10-03 的决定,
144
+ **影子目录是豁免的**,所以这条**不是** finding。
145
+
146
+ ## 4.1.17 — 2026-10-22(相对路径按它**在哪个目录**判,不按它**怎么拼写**判)
147
+
148
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
149
+ 既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、
150
+ peaks-code 的 11 步工序与 Gate A–G **一字不改**。
151
+ 上一版(4.1.16)把相对路径的**基准**改成了"工具调用实际所在的目录",但**基准与项目根是按字面比较的** ——
152
+ 本次把这个洞收口。
153
+
154
+ ### 1. 一个目录可以有两种拼法,判决不能因此不同
155
+
156
+ - 此前:相对路径的**基准**(工具调用的目录)与**项目根**按**字面**比较。路径里有符号链接时,
157
+ 两者对不上 ⇒ 门禁判定"文件在项目外" ⇒ 退回**按拼写读** ⇒ 拼得像 `src/` 的写法**被放行**。
158
+ - **macOS 上这不是假设**:测试 harness 的项目根来自 `mkdtempSync(tmpdir())`,是**非规范**的
159
+ `/var/folders/...`;而门禁进程自己的工作目录是**规范**的 `/private/var/...`(`/var` 是
160
+ `private/var` 的符号链接)。两者一错配就中招 ⇒ **4.1.16 推上去时 `macos-latest` 那条 job 是红的**,
161
+ 8 个用例失败。**Windows 一个月没暴露,只因为本机 temp 路径里没有符号链接。**
162
+ - 现在:路径读**两遍** —— **词面**(怎么写的)与**规范**(文件真实在哪)—— 判决取**最严**的那个。
163
+ **白名单是每一遍各自先判的**:一遍命中白名单不会因为另一遍命中族而变成拒绝。
164
+ - **裁决原则用的是本仓库自己的那条**(见 4.1.15):**误放是漏洞,误拒只是碍事**。
165
+ 所以**不是**"规范读法当权威"——那会在 `src` → `shared/src` 这种常见布局里**放宽**门禁
166
+ (词面 `src/x.ts` 拒、规范 `shared/src/x.ts` 放行);而是**任一遍命中族就拒**。
167
+
168
+ ### 2. `.sh` 兄弟实现也走同一条规则
169
+
170
+ 它原本只按**拼写**判,于是和 Node 版**越漂越远**:Node 拒的写法它放行。
171
+ 现在它取同样两遍读法、取同样的最严判决,而且**规范读法相对的是它自己解析出来的那个基准** ——
172
+ 两套实现因此不可能对"文件在哪"给出不同答案。
173
+ **两个实现同一条规则,就必须互相测,而不是各自对着自己的预期测。**
174
+
175
+ ### 3. 被有意接受的取舍(写在这里以免看起来像疏漏)
176
+
177
+ - **落在项目之外的相对路径**仍按"拼写相对项目根"读 ⇒ **不会放宽**门禁。
178
+ - **一个被纠正的误拒**:当**基准在非族目录**(例如 `<root>/docs`)时,旧的拼写锚定规则会把
179
+ `src/x.ts` 这类写法**拒**掉,而那些文件其实落在 `<root>/docs/…`、**在所有硬阻断族之外**。
180
+ 现在按文件真实所在判 ⇒ **放行**。这是**放宽**,方向是裁定自己的不变量(判决跟文件走,不跟拼写走),
181
+ **已接受并记录**(不 claim 掉)。
182
+ - **兄弟实现还有三处已知短板**(它**读不到** payload 顶层 `cwd`、**推导**项目根、**无法相对化绝对路径**),
183
+ 归在 backlog §19.1/§19.2 的 owner 决策里,不在本次收口。
184
+
185
+ ### 4. 验证
186
+
187
+ - 与**改动前**的代码逐行对照:**896 行里 0 行**让任一实现放行了落在拒绝族里的文件。
188
+ - **不得放宽**:Node 命令**收紧 92 / 放宽 0**;兄弟实现**收紧 76 / 放宽 0**。
189
+ 相对**切片前**的代码,Node 112/40、兄弟 108/36 —— 那 76 个放宽**全部**在非族目录的基准上,
190
+ 每个文件都落在所有族之外(§3 那个被纠正的误拒),**不是洞**。
191
+ - 家族成员零行改动,fail-open 不变,fast lane 仍然打开这些族。
192
+ - **顺手订正一句注释**:它描述了一种代码并不做的比较(审计里的第六条 LOW)——现在它说的是代码做的事。
193
+ - 另附一条**实测**:门禁读的 payload 顶层 `cwd` **确实是 PreToolUse payload 的顶层字段**
194
+ (对着本机装的 Claude Code 二进制读到构造点,不是推断);**任何 IDE 都会这么发**这一条**仍未实测**。
195
+
3
196
  ## 4.1.16 — 2026-10-22(相对路径按工具调用实际所在的目录解析)
4
197
 
5
198
  **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
@@ -2,8 +2,10 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
2
2
  import { fail } from 'peaks-loop-shared/result';
3
3
  import { runAutoCompact } from '../../services/code/auto-compact-orchestrator.js';
4
4
  import { probeInFlightBatch } from '../../services/workflow/workflow-inflight-probe.js';
5
+ import { readDispatchLedgerFacts } from '../../services/dispatch/dispatch-ledger-reader.js';
5
6
  import { readActiveSid } from './code-runtime-session.js';
6
7
  import { buildAutoCompactEnvelope } from './code-auto-compact-envelope.js';
8
+ import { describeDeferral, withDeferralDetail } from './code-auto-compact-deferral.js';
7
9
  const AUTO_COMPACT_DESCRIPTION = 'v2.13.0 AC-4: zero-human-intervention auto-compact. Probes current ' +
8
10
  'context-fill % via the active IDE adapter; ≥ 0.85 writes a pre-compact ' +
9
11
  'checkpoint + convergence plan + auto-decisions log; ≥ 0.95 ASKS the ' +
@@ -26,35 +28,39 @@ function reportInvalidAutoCompactMode(io, modeName, json) {
26
28
  * The `runAutoCompact` input object, lifted verbatim: it reads only its two
27
29
  * parameters, so it has no ordering dependency on the call site.
28
30
  */
29
- function buildAutoCompactInput(opts, modeName) {
30
- // Slice 4.0.8 (D4d): production `inFlightBatch` MUST come from
31
- // the workflow graph probe. The legacy `--in-flight-batch`
32
- // boolean CLI flag is a TEST-ONLY seam (gated by
33
- // `PEAKS_TEST_SEAM === '1'`). When the env flag is unset
34
- // (the production case), we wire `probeInflightBatch` to the
35
- // canonical `workflow-inflight-probe.ts` service so the
36
- // production decision is graph-backed, not lease-age.
31
+ function buildAutoCompactInput(opts, modeName, capture) {
32
+ // The in-flight signal comes from the session's DISPATCH LEDGER — the
33
+ // `active-dispatches.json` index and the dispatch records it names. The
34
+ // workflow graphs never carried the fact (a dispatch node sits at
35
+ // `prepared` and no writer stamps a heartbeat onto it), so a graph-backed
36
+ // probe could only ever answer "no" and the deferral was unreachable.
37
+ //
38
+ // The legacy `--in-flight-batch` boolean CLI flag is a TEST-ONLY seam
39
+ // (gated by `PEAKS_TEST_SEAM === '1'`). When the env flag is unset (the
40
+ // production case), we wire `probeInflightBatch` to the canonical
41
+ // `workflow-inflight-probe.ts` service fed by the ledger reader, so the
42
+ // production decision is ledger-backed.
37
43
  const isTestSeam = process.env.PEAKS_TEST_SEAM === '1';
44
+ const projectRoot = opts.project;
38
45
  return {
39
- projectRoot: opts.project,
46
+ projectRoot,
40
47
  sessionId: opts.sessionId ?? readActiveSid(opts.project) ?? undefined,
41
48
  ...(isTestSeam && opts.inFlightBatch === true
42
49
  ? { inFlightBatch: { hasInFlightBatch: true } }
43
50
  : {}),
44
51
  ...(!isTestSeam
45
52
  ? {
46
- probeInflightBatch: () => {
47
- // Synchronous probe: the workflow-inflight-probe
48
- // service is pure / synchronous (no I/O). The
49
- // empty `graphs` array is the production CLI
50
- // default — callers that want a richer fixture
51
- // (e.g. `peaks session 24h-mode`) should hand-roll
52
- // a probe and pass it via the orchestrator's
53
- // input. When no graph is materialized, the
54
- // probe returns `inFlightBatch: false`, matching
55
- // the 4.0.7 zero-pause contract for stock
56
- // projects.
57
- const out = probeInFlightBatch({ now: new Date().toISOString(), graphs: [] });
53
+ probeInflightBatch: (sessionId) => {
54
+ // Synchronous probe: the reader reads files and the
55
+ // workflow-inflight-probe service is pure / synchronous
56
+ // (no I/O). The reader gathers the ledger's facts and the
57
+ // probe decides from them; the reader/probe boundary is
58
+ // what keeps the decision testable on its own.
59
+ const ledger = readDispatchLedgerFacts({ projectRoot, sessionId });
60
+ const out = probeInFlightBatch({ now: new Date().toISOString(), ledger });
61
+ // The whole answer is kept, not just its boolean: the deferral
62
+ // reports WHICH deferral it was, and the reason is in here.
63
+ capture.last = out;
58
64
  return out.inFlightBatch === true;
59
65
  }
60
66
  }
@@ -75,6 +81,21 @@ function reportAutoCompactFailure(io, err, json) {
75
81
  ]), json);
76
82
  process.exitCode = 1;
77
83
  }
84
+ /**
85
+ * The deferral's detail — or null when this run did not defer.
86
+ *
87
+ * The code is the gate: `AUTO_COMPACT_WAIT` is the one the orchestrator returns
88
+ * when the in-flight deferral applied. A run that skipped for another reason, or
89
+ * that reached the red line (where the deferral does not apply), carries no
90
+ * detail, because there was no deferral to describe.
91
+ */
92
+ function deferralDetail(result, probe) {
93
+ if (result.code !== 'AUTO_COMPACT_WAIT')
94
+ return null;
95
+ if (probe === null)
96
+ return null;
97
+ return describeDeferral(probe);
98
+ }
78
99
  /** The action body, lifted to a module-level function so both it and the registrar fit in 50 lines. */
79
100
  async function runAutoCompactAction(opts, io) {
80
101
  try {
@@ -84,14 +105,16 @@ async function runAutoCompactAction(opts, io) {
84
105
  reportInvalidAutoCompactMode(io, modeName, opts.json);
85
106
  return;
86
107
  }
87
- const result = await runAutoCompact(buildAutoCompactInput(opts, modeName));
108
+ const capture = { last: null };
109
+ const result = await runAutoCompact(buildAutoCompactInput(opts, modeName, capture));
88
110
  const code = result.code;
89
111
  const exitOk = result.ok || code === 'AUTO_COMPACT_SKIP' || code === 'AUTO_COMPACT_WAIT';
90
112
  // Adapt AutoCompactResult → ResultEnvelope so printResult's
91
113
  // generic accepts it. The orchestrator envelope carries
92
114
  // `data` on success-path and `nextActions` on the error
93
115
  // path; surface both directly to the user.
94
- printResult(io, buildAutoCompactEnvelope(result), opts.json);
116
+ const envelope = buildAutoCompactEnvelope(result);
117
+ printResult(io, withDeferralDetail(envelope, deferralDetail(result, capture.last)), opts.json);
95
118
  if (!exitOk)
96
119
  process.exitCode = 1;
97
120
  }
@@ -0,0 +1,34 @@
1
+ import type { ResultEnvelope } from 'peaks-loop-shared/result';
2
+ import type { ProbeResult } from '../../services/workflow/workflow-inflight-probe.js';
3
+ /** One probe diagnostic, reduced to the two fields a consumer needs. */
4
+ export interface DeferralCode {
5
+ readonly code: string;
6
+ readonly message: string;
7
+ }
8
+ /** What the deferral was, in the shape the envelope carries it. */
9
+ export interface DeferralDetail {
10
+ /** The probe's own reason: `fresh-dispatch` or `unknown-ledger-state`. */
11
+ readonly reason: string;
12
+ /** True when the deferral rests on something the probe could not establish. */
13
+ readonly unknown: boolean;
14
+ readonly warnings: readonly DeferralCode[];
15
+ readonly errors: readonly DeferralCode[];
16
+ }
17
+ /** The probe's answer, in the shape the envelope carries it. */
18
+ export declare function describeDeferral(probe: ProbeResult): DeferralDetail;
19
+ /**
20
+ * The one sentence that tells the two deferrals apart.
21
+ *
22
+ * The codes are named because they are the machine-readable half of the same
23
+ * fact, and an operator who wants the detail can grep the code.
24
+ */
25
+ export declare function deferralSentence(detail: DeferralDetail): string;
26
+ /**
27
+ * The envelope, with the deferral's reason attached.
28
+ *
29
+ * The detail lands in three places, because three readers exist: `data.deferral`
30
+ * for a machine, `warnings` for the codes the probe collected, and the message
31
+ * itself for whoever reads the printed output. An envelope that did not defer
32
+ * comes back unchanged.
33
+ */
34
+ export declare function withDeferralDetail(envelope: ResultEnvelope<unknown>, detail: DeferralDetail | null): ResultEnvelope<unknown>;
@@ -0,0 +1,59 @@
1
+ /** The probe's reason when it defers because a fact about the batch is unknown. */
2
+ const UNKNOWN_REASON = 'unknown-ledger-state';
3
+ function toCode(warning) {
4
+ return { code: warning.code, message: warning.message };
5
+ }
6
+ /** The probe's answer, in the shape the envelope carries it. */
7
+ export function describeDeferral(probe) {
8
+ return {
9
+ reason: probe.reason,
10
+ unknown: probe.reason === UNKNOWN_REASON,
11
+ warnings: probe.warnings.map(toCode),
12
+ errors: probe.errors.map(toCode)
13
+ };
14
+ }
15
+ /**
16
+ * The one sentence that tells the two deferrals apart.
17
+ *
18
+ * The codes are named because they are the machine-readable half of the same
19
+ * fact, and an operator who wants the detail can grep the code.
20
+ */
21
+ export function deferralSentence(detail) {
22
+ const codes = [...detail.errors, ...detail.warnings].map((code) => code.code);
23
+ const head = detail.unknown
24
+ ? 'Deferral reason: the dispatch ledger state is UNKNOWN'
25
+ : 'Deferral reason: a dispatch IS in flight';
26
+ const why = detail.unknown
27
+ ? 'the ledger, or one of the records it names, could not be read, or a record said ' +
28
+ 'something this probe does not recognise, so this deferral is NOT a known running batch'
29
+ : 'the ledger holds a live dispatch, so the compaction waits for it; this is the ' +
30
+ 'expected deferral, not a ledger problem';
31
+ const named = codes.length === 0 ? '' : ` Codes: ${codes.join(', ')}.`;
32
+ return `${head} (reason=${detail.reason}) — ${why}.${named}`;
33
+ }
34
+ /**
35
+ * The envelope, with the deferral's reason attached.
36
+ *
37
+ * The detail lands in three places, because three readers exist: `data.deferral`
38
+ * for a machine, `warnings` for the codes the probe collected, and the message
39
+ * itself for whoever reads the printed output. An envelope that did not defer
40
+ * comes back unchanged.
41
+ */
42
+ export function withDeferralDetail(envelope, detail) {
43
+ if (detail === null)
44
+ return envelope;
45
+ const sentence = deferralSentence(detail);
46
+ const codes = [...detail.errors, ...detail.warnings].map((code) => `${code.code}: ${code.message}`);
47
+ const data = typeof envelope.data === 'object' && envelope.data !== null ? { ...envelope.data } : {};
48
+ const nextActions = [...envelope.nextActions];
49
+ if (nextActions.length === 0)
50
+ nextActions.push(sentence);
51
+ else
52
+ nextActions[0] = `${nextActions[0]} ${sentence}`;
53
+ return {
54
+ ...envelope,
55
+ data: { ...data, deferral: detail },
56
+ warnings: [...envelope.warnings, ...codes],
57
+ nextActions
58
+ };
59
+ }
@@ -4,10 +4,10 @@
4
4
  * payload from stdin and either exits 0 (allow) or exits 2 with stderr
5
5
  * containing PEAKS_CODE_PROHIBITED_DIRECT_EDIT (deny).
6
6
  *
7
- * This command is the runtime adapter for the shell-script sibling
8
- * (`src/services/hooks/pre-tool-code-gate.sh`). Both share the same
9
- * path-family decision; the CLI invokes the same pure decision
10
- * function (`decideGateAction`) the shell script encodes.
7
+ * This command is the runtime adapter the shell-script sibling
8
+ * (`src/services/hooks/pre-tool-code-gate.sh`) EXECS. The path-family
9
+ * decision lives in ONE implementation — `decideGateAction` — and the
10
+ * sibling's own no-CLI fallback is a narrower copy of it.
11
11
  *
12
12
  * Settings.json entry shape (vendor-neutral, registered by
13
13
  * `peaks hooks install`): an `Edit|Write|MultiEdit` matcher whose command is
@@ -4,10 +4,10 @@
4
4
  * payload from stdin and either exits 0 (allow) or exits 2 with stderr
5
5
  * containing PEAKS_CODE_PROHIBITED_DIRECT_EDIT (deny).
6
6
  *
7
- * This command is the runtime adapter for the shell-script sibling
8
- * (`src/services/hooks/pre-tool-code-gate.sh`). Both share the same
9
- * path-family decision; the CLI invokes the same pure decision
10
- * function (`decideGateAction`) the shell script encodes.
7
+ * This command is the runtime adapter the shell-script sibling
8
+ * (`src/services/hooks/pre-tool-code-gate.sh`) EXECS. The path-family
9
+ * decision lives in ONE implementation — `decideGateAction` — and the
10
+ * sibling's own no-CLI fallback is a narrower copy of it.
11
11
  *
12
12
  * Settings.json entry shape (vendor-neutral, registered by
13
13
  * `peaks hooks install`): an `Edit|Write|MultiEdit` matcher whose command is
@@ -3,6 +3,7 @@ import { listSkills } from '../../../services/skills/skill-registry.js';
3
3
  import { runSkillSync, SYNC_PLATFORMS } from '../../../services/skills/sync-service.js';
4
4
  import { ok, fail } from 'peaks-loop-shared/result';
5
5
  import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
6
+ import { renderStoreReport } from './skill-store-report.js';
6
7
  const PLATFORM_IDS = SYNC_PLATFORMS.join(', ');
7
8
  const LIST_DESCRIPTION = 'List skills derived from skills/*/SKILL.md';
8
9
  const LIST_INCLUDE_INTERNAL_HELP = 'include skills with visibility: internal (default: hide them)';
@@ -74,6 +75,34 @@ function runSkillDoctor(options, io) {
74
75
  }
75
76
  });
76
77
  }
78
+ /**
79
+ * The canonical store's state, as the install found it: which entries are behind
80
+ * the installed release, which ones are the user's own, and how many are current.
81
+ *
82
+ * WHY IT IS REPORTED HERE. The install's `skipped` list used to be a value in a
83
+ * return object nobody read — a store entry that is left alone, or a copy that
84
+ * is behind, both looked exactly like a successful install from the outside.
85
+ * A dry run is where that report belongs: it says what a repair WOULD do,
86
+ * before anything is written.
87
+ *
88
+ * The FIRST platform's report is the one shown. The canonical store is shared by
89
+ * every platform, so the first pass sees the state as it was found; the later
90
+ * passes see what the first one already fixed.
91
+ */
92
+ function storeReport(result, dryRun) {
93
+ const entries = result.perPlatform.find((platform) => platform.entries !== undefined)?.entries;
94
+ return renderStoreReport(entries, dryRun);
95
+ }
96
+ /** The report, as the next action the envelope carries — or none at all. */
97
+ function reportAction(report) {
98
+ return report === null ? [] : [report];
99
+ }
100
+ /** The human line, for the non-JSON output. The JSON envelope carries it too. */
101
+ function printStoreReport(io, report, asJson) {
102
+ if (report === null || asJson === true)
103
+ return;
104
+ io.stdout(` ${report}\n`);
105
+ }
77
106
  async function runSkillSyncCommand(options, io) {
78
107
  try {
79
108
  const projectRoot = options.project ?? process.cwd();
@@ -84,14 +113,17 @@ async function runSkillSyncCommand(options, io) {
84
113
  ...(options.dryRun === true ? { dryRun: true } : {}),
85
114
  ...(options.reconcileJunctions === true ? { reconcileJunctions: true } : {})
86
115
  });
116
+ const report = storeReport(result, options.dryRun === true);
87
117
  const envelope = ok('skill.sync', result, [], [
88
118
  `syncedCount: ${result.syncedCount}/${result.perPlatform.length} platforms`,
89
119
  `totalInstalled: ${result.totalInstalled} skill symlinks`,
120
+ ...reportAction(report),
90
121
  result.failedCount > 0
91
122
  ? `failedCount: ${result.failedCount} (run \`peaks skill status\` for details)`
92
123
  : 'no failures'
93
124
  ]);
94
125
  printResult(io, envelope, options.json);
126
+ printStoreReport(io, report, options.json === true);
95
127
  if (result.failedCount > 0) {
96
128
  process.exitCode = 1;
97
129
  }
@@ -0,0 +1,8 @@
1
+ import type { StoreEntryReport } from '../../../services/skills/sync-service-support.js';
2
+ /**
3
+ * The store report line, or null when the installer reported no rows at all.
4
+ *
5
+ * @param entries the rows the installer reported, or undefined when it reported none
6
+ * @param dryRun whether this run wrote nothing
7
+ */
8
+ export declare function renderStoreReport(entries: readonly StoreEntryReport[] | undefined, dryRun: boolean): string | null;
@@ -0,0 +1,79 @@
1
+ /** The states, in the order the counts are printed. */
2
+ const STATE_ORDER = [
3
+ 'current',
4
+ 'stale',
5
+ 'unmanaged',
6
+ 'retired',
7
+ 'absent'
8
+ ];
9
+ /** The rows in one state. */
10
+ function rowsIn(entries, state) {
11
+ return entries.filter((entry) => entry.state === state);
12
+ }
13
+ /**
14
+ * What this run did about a group of rows, in words.
15
+ *
16
+ * The suffix is per STATE as well as per action: an absent entry that was installed
17
+ * is not an entry that was repaired.
18
+ */
19
+ function actionSuffix(state, action) {
20
+ if (action === 'installed') {
21
+ return state === 'absent' ? 'installed by this run' : 'repaired by this run';
22
+ }
23
+ if (action === 'planned') {
24
+ if (state === 'absent')
25
+ return 'would be installed';
26
+ if (state === 'retired')
27
+ return 'would be removed';
28
+ return 'would be repaired';
29
+ }
30
+ if (action === 'pruned')
31
+ return 'removed by this run';
32
+ return '';
33
+ }
34
+ /**
35
+ * The names of a group, with what the run did about it.
36
+ */
37
+ function describeGroup(entries, state, label) {
38
+ const rows = rowsIn(entries, state);
39
+ if (rows.length === 0)
40
+ return null;
41
+ const names = rows.map((entry) => entry.name).join(', ');
42
+ const suffix = actionSuffix(state, rows[0]?.action);
43
+ return `${label}: ${names}${suffix.length > 0 ? ` (${suffix})` : ''}`;
44
+ }
45
+ /**
46
+ * The absent group, as a count.
47
+ *
48
+ * The names are not listed: on a machine that has never run the install this group
49
+ * holds every skill the package ships, and a line with a hundred names in it is a
50
+ * line nobody reads. What the group MEANT is what the count carries — that many
51
+ * skills were not in the store, and what this run did about them.
52
+ */
53
+ function describeAbsent(entries) {
54
+ const rows = rowsIn(entries, 'absent');
55
+ if (rows.length === 0)
56
+ return null;
57
+ const suffix = actionSuffix('absent', rows[0]?.action);
58
+ const label = suffix.length > 0 ? suffix : 'not in the store';
59
+ return `${label}: ${rows.length} skill${rows.length === 1 ? '' : 's'}`;
60
+ }
61
+ /**
62
+ * The store report line, or null when the installer reported no rows at all.
63
+ *
64
+ * @param entries the rows the installer reported, or undefined when it reported none
65
+ * @param dryRun whether this run wrote nothing
66
+ */
67
+ export function renderStoreReport(entries, dryRun) {
68
+ if (entries === undefined)
69
+ return null;
70
+ const counts = STATE_ORDER.map((state) => `${rowsIn(entries, state).length} ${state}`).join(', ');
71
+ const detail = [
72
+ describeGroup(entries, 'stale', 'stale'),
73
+ describeGroup(entries, 'retired', 'retired (this release does not ship them)'),
74
+ describeGroup(entries, 'unmanaged', "left alone (not peaks-loop's to replace)"),
75
+ describeAbsent(entries)
76
+ ].filter((line) => line !== null);
77
+ const reading = dryRun ? 'state as found; dry run: nothing written' : 'state as found';
78
+ return `skill store: ${counts} (${reading})${detail.length > 0 ? ` — ${detail.join('; ')}` : ''}`;
79
+ }