peaks-loop 4.0.38 → 4.0.40

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 4.0.40 — 2026-09-11 (两条被 4.0.39 暴露出来的既有缺陷)
+
+**Highlights**:
+
+1. **4.0.39 的闸门指导写了一个错误的因果 —— 已更正。** 那段文字告诉每个技能:"编辑前先读这个文件,**跳过这一步会撞上闸门**"。**这是假的。** 用户在 Mac 上装完 4.0.39 后拿实际日志打回来,促使我们去读 ECC 闸门的源码(`gateguard-fact-force.js`)：
+
+   ```js
+   if (!isChecked(filePath)) {
+     markCheckedAndCountDenial(filePath);   // 同一个调用里:先标记,再拒绝
+     return denyResult(...);
+   }
+   return rawInput;                          // 第二次直接放行
+   ```
+
+   **它是"每个路径首次接触拒绝一次"的减速带,不是"你有没有读过"的检查。** 先读**并不能**避免拒绝;拒绝由"编辑"触发,与是否读过无关。而给一个错的因果**比不给更糟** —— 模型照做了、仍被拦时,会得出"我哪里做错了",这正是这段指导本来要防的误读。现在它陈述真实机制与真实对策:每个文件预期被拦一次,**那不是失败、编辑未被应用、重试即放行**。
+
+   - 顺带记录边界:子代理豁免(父会话已过闸);`.peaks/**` 经 `GATEGUARD_EXEMPT_GLOBS` 豁免;**重试是否放行与"有没有列出那四条事实"无关** —— 闸门不校验事实。
+   - **闸门本身以后仍会拦**,那是它被设计成这样的;peaks 不该也无法替非 `.peaks/**` 路径压制它。能改的只是让模型别误读。
+
+2. **四个 `SKILL.md` 的 frontmatter 是无效 YAML,其中两个的 `description` 从未被加载过。** `peaks-perf-audit` 与 `peaks-security-audit` 的 `sources:` 里有未加引号的 `schemaVersion: 2`,YAML 把其中的冒号+空格读成嵌套映射的开头,整个 frontmatter 解析失败 —— 而 Claude Code 在解析失败时会**回退到闭合 `---` 之后的第一行**,于是它们的 description 从未生效,**两个技能都无法按自己的描述被发现**。
+
+   - **这个缺陷为何一直看不见:** 回退渲染出来的是紧跟其后的标题(`# peaks-perf-audit`),**读起来像标题而不像损坏**。只有当 4.0.39 把 loop-hygiene 块放进那个位置后,技能列表开始显示块里的 HTML 注释,它才显形。
+   - `peaks-issue-fix-orchestrator` 与 `peaks-sop` 带同样的病(值里未加引号的 `: `)。Claude Code 自己的解析器足够宽松能读它们,所以看着正常,但它们不是合法 YAML,任何更严格的读取方都会拒绝。
+   - 四处均已加引号,**逐字验证无损**(重写的两条描述 662 / 654 字符前后完全一致)。
+   - 新增守卫:每个 `SKILL.md` 的 frontmatter 必须能解析为 YAML 且产出可用的 `description`。
+
+**验证**:三个版本常量一致(4.0.40);`tsc -p tsconfig.build.json` exit 0;宽 `tsconfig.json` 保持 **142** 基线;`tests/unit` **188 files / 1794 passed / 3 skipped / 0 failed**。
+
+## 4.0.39 — 2026-09-11 (四条"死机制" + 可见的 OCR 获取)
+
+**Highlights**:
+
+1. **本轮查出的东西有一个共同形状:机制写好了、但从没执行过。** 四条各自独立,每一条都能通过全部现有测试,因为**测试断言的是"声明存在",不是"它真的跑"**:
+
+   - **`24h` 模式从没选过 `partial`。** `--mode` 声明里带了 commander 默认值 `'standard'`,于是 `opts.mode` **永远有值**,orchestrator 里 `input.mode ?? resolveAutoCompactMode(projectRoot)` 的右边**永远不执行**。每个 24h 会话都在按 standard 的 0.80/0.85 跑,而 help 文本写着 0.65/0.70。症状看起来是"两个命令报的 mode 不一致",根因是**默认值顶掉了一条分支**。修的时候要动两处:只删默认值不够,handler 仍会把 `'standard'` 显式传下去。
+   - **auto-compact 的 hook 一次都没触发过。** 安装进 `settings.local.json` 的命令是 `peaks code auto-compact`,而 `--project` 是 `.requiredOption` —— 于是它挂在 `Bash|Task` 上,**每次工具调用都以"缺 --project"失败**。非阻塞错误,桌面上什么都看不到。更要紧的是:光改常量**到不了任何已有安装**,因为安装器只比对 matcher、从不比对命令,一看到 `Bash|Task` 条目就返回"已安装"。现在它是一起迁移。
+   - **那条"忽略离线模板"的 managed 规则,在任何项目里都没生效过。** 模式是按**项目根**写的,却被写进 `.peaks/.gitignore` —— 带 `/` 的 gitignore 模式锚定到所在目录,于是解析成 `.peaks/.peaks/...`,匹配不到任何东西;而根级的 `.claude/settings.local.json` 更是**根本无法**从 `.peaks/` 内部表达(gitignore 没有 `..`)。后果在本仓库可见:模板文件因为这条规则never生效而一直被跟踪,每次发版都显示 modified,被当"机器路径泄漏"**回滚了三次**——它从来不是泄漏。snippet 已改写到根,并加了**行为式**守卫(逐条模式用 `git check-ignore --no-index` 验证生效;已实测对旧行为失败)。顺带:搬家会留下僵尸块,`workspace init` 现在把它剥掉(保留用户写的每一行,畸形块不动)。
+   - **`--graph-node` 的强制只由 `.requiredOption` 支撑。** 传一个**根本不存在的**节点,dispatch 照样成功 —— 下游从不校验,`PEAKS_GRAPH_NODE_NOT_PREPARED` 只被 import、从未抛出;而且 `graphNodeId`/`workflowId`/`graphRef` **从未传给记录写入器**,记录上恒为 null,那条 transition 永远不触发。**这个特性整条链是死的,唯一真实的是它的前置条件** —— 而那个前置条件正好把每个没有图基础设施的项目(即:除了 peaks-loop 自己以外的所有项目)全打断。那句"友好提示"指向的路径本身也走不通:`workflow node prepare` **从不落盘**(打印一个节点就丢),而它要求的图没有任何命令会创建。现在可选 + 按需 provision,三步压成一步,并把三个字段真正写进记录。
+
+2. **契约与指导,现在能到达它们该到的地方。** 零暂停契约(「compaction 是技能自己的动作,不是用户的」)早就写在 `peaks-code/SKILL.md` 里,`:180` 甚至点名禁止"prompt the user to run `/compact`" —— **而它依然被违反了,因为 SKILL.md 正文只加载一次、随后会被 compact 掉,规则恰好在上下文压力大到需要它的那一刻失效**;而且 22 个技能里只有 1 个有这段。现在它挂在**每轮必调的 tool 输出**上(`peaks skill presence --json` 的返回值里带 `context: { ratioPct, action, mode }`),compact 不掉,且技能无关。同样地,read-first 指导此前只注入了**子代理**的 system prompt,真正被闸门拒的**主会话**从没收到 —— 现在两者都在 22 个技能共享的、有**漂移守卫**的块里。
+
+3. **OCR 获取变成显式、可见的一步。** dogfood 时桌面上弹出了一个标题为 `npm i @alibaba-group/open-code-review@1.11.9` 的窗口,而它来自一个自称 **"Read-only probe"** 的命令 —— `npx --package …` 在包未缓存时会**安装**。因果值得记下:**是今天的 unblock 让它暴露的** —— 修好之前,探针在启动步就死了,根本走不到安装。现在探针**只看不取**,获取成为独立动词,带安装锁与下载前告警,输出走 `inherit` 让 npm 自己的进度到达用户终端。Shell 偏好 **Git Bash → PowerShell**,且**每次都上报用了哪个** —— 静默换壳正是这场混乱的起点。
+
+4. **本轮的一条自查:我写的守卫,自己犯了它要防的病。** 漂移守卫用 `execSync('find skills -name SKILL.md')` 找文件。`execSync` 走平台 shell,CI 的 Windows 上是 `cmd.exe`,那里的 `find` 是 `System32\find.exe`(另一个程序,不认 `-name`)。**本地能过,只因为 Git Bash 的 `find` 在 PATH 上胜出** —— 典型的"测试断言的是这台笔记本"。CI 第一次推就抓到。已改成 `fs` 遍历,无 shell 参与。
+
+**验证**:三个版本常量一致(4.0.39);`tsc -p tsconfig.build.json` exit 0;宽 `tsconfig.json` 保持 **142** 基线;`tests/unit` **188 files / 1793 passed / 3 skipped / 0 failed**;CI 在 ubuntu + windows(Node 22)双平台绿。本轮新增的守卫**每一条都实测过"对旧行为会失败"**。
+
 ## 4.0.38 — 2026-09-11 (适配外部闸门 + 多语言评审复活 + 测试不再弹窗)
 
 **Highlights**:

package/README-en.md

@@ -140,7 +140,7 @@ Every lane opens with **one slash command**.
 
 | | |
 | --- | --- |
-| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.38 (2026-09-11) |
+| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.40 (2026-09-11) |
 | **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test` · `peaks-slice-decompose`) |
 | **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
 | **Test suite** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · **0 timeouts** · 14 BDD caller-binding edge cases |

package/README.md

@@ -140,7 +140,7 @@ npm i -g peaks-loop
 
 | | |
 | --- | --- |
-| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.38(2026-09-11) |
+| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.40(2026-09-11) |
 | **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测 / `peaks-slice-decompose` 切片) |
 | **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
 | **测试套件** | 1096 cases · 4 packages (peaks-loop 1015 / runtime 39 / mut 22 / shared-channel 20) · **CI 首次全绿**(ubuntu + windows) · 14 BDD caller-binding coverage |

package/dist/cli/commands/code-review-commands.js

@@ -1,8 +1,11 @@
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { detectOcr18 } from '../../services/lint/detect-ocr-18.js';
-import { OCR_18_LANGUAGES, runOcr18 } from '../../services/lint/ocr-multilang-adapter.js';
+import { acquireOcr18 } from '../../services/lint/ocr-18-acquire.js';
+import { OCR_18_LANGUAGES, OCR_18_PACKAGE, runOcr18 } from '../../services/lint/ocr-multilang-adapter.js';
 const SUPPORTED_LANGUAGES_SET = new Set(OCR_18_LANGUAGES);
+/** What a caller can do when the acquisition did not land the package. */
+const ACQUIRE_RETRY_ACTION = 'Re-run `peaks code-review acquire-ocr-18` once the network is available.';
 export function registerCodeReviewCommands(program, io) {
     const codeReview = program
         .command('code-review', { hidden: true })
@@ -23,6 +26,45 @@ export function registerCodeReviewCommands(program, io) {
             printResult(io, fail('code-review.detect-ocr-18', 'DETECT_FAILED', getErrorMessage(error), { state: 'detection-failed' }, ['Re-run with a valid npx on PATH.']), options.json);
         }
     });
+    addJsonOption(codeReview
+        .command('acquire-ocr-18')
+        .description('Acquire the OCR 1.8.x reviewer: runs the pinned npx package VISIBLY (npm progress on the ' +
+        'terminal) and installs it once when it is not already cached. The companion to the read-only ' +
+        '`detect-ocr-18` probe, which never installs.')).action(async (options) => {
+        const command = 'code-review.acquire-ocr-18';
+        try {
+            // R6's other half, mirrored from `peaks web install`: "nothing to fetch"
+            // is the only reason not to fetch, so an acquisition with nothing to do
+            // says so without spawning anything.
+            const before = detectOcr18();
+            if (before.state === 'ready') {
+                printResult(io, ok(command, { acquired: false, state: before.state, package: before.package, shell: null, shellNote: null }, [], []), options.json);
+                return;
+            }
+            // `asJson` is threaded in so the installer cannot write its stdout into
+            // the envelope this verb prints to the same stream.
+            const outcome = await acquireOcr18({ asJson: options.json === true });
+            if (!outcome.ok) {
+                printResult(io, fail(command, outcome.code, outcome.message, { state: 'acquire-failed', shell: outcome.shell.kind, shellNote: outcome.shell.note }, [ACQUIRE_RETRY_ACTION]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            // R7, mirrored: an installer that exits 0 without landing the package is
+            // CONSULTED, not assumed — a proxy filtering the registry, or `npx`
+            // resolving into a different cache root, both exit 0.
+            const after = detectOcr18();
+            if (after.state !== 'ready') {
+                printResult(io, fail(command, 'OCR18_ACQUIRE_INCOMPLETE', `the acquisition exited 0 but ${OCR_18_PACKAGE} still does not resolve (${after.state})`, { state: after.state, shell: outcome.shell.kind, shellNote: outcome.shell.note }, [...after.nextActions]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok(command, { acquired: true, state: after.state, package: after.package, shell: outcome.shell.kind, shellNote: outcome.shell.note, durationMs: outcome.durationMs }, [...outcome.warnings]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail(command, 'OCR18_ACQUIRE_FAILED', getErrorMessage(error), { state: 'acquire-failed' }, [ACQUIRE_RETRY_ACTION]), options.json);
+            process.exitCode = 1;
+        }
+    });
     addJsonOption(codeReview
         .command('run-ocr-18')
         .description('Invoke `ocr review --filter-language <lang>` (or `ocr delegate preview` when --delegate) for one of 8 supported languages.')

package/dist/cli/commands/code-runtime-commands.js

@@ -60,8 +60,11 @@ export function registerCodeRuntimeCommands(code, io) {
         'context-fill % via the active IDE adapter; ≥ 0.85 writes a pre-compact ' +
         'checkpoint + convergence plan + auto-decisions log; ≥ 0.95 forces ' +
         'synchronous IDE-side compact. The LLM / runner keeps working with ' +
-        'context < 95% without human intervention. pair with `peaks context ' +
-        'now` (AC-1) which feeds the ratio into this command. rid-027 ' +
+        'context < 95% without human intervention. Pair with `peaks code ' +
+        'context-now` (AC-1), the read-only probe that reports the ratio this ' +
+        'command acts on. This command is also fired by the installed ' +
+        'PreToolUse hook, which passes `--project .` — without that argument ' +
+        'the hook could never run at all. rid-027 ' +
         'adds `--mode <mode>`: `standard` (0.85/0.95) or `partial` (0.70/0.85 ' +
         'for 24h long-run mode).')
         .requiredOption('--project <path>', 'target project root')
@@ -69,7 +72,12 @@ export function registerCodeRuntimeCommands(code, io) {
         .option('--in-flight-batch', 'defer if a sub-agent batch is in flight (D6.e)')
         .option('--force', 'force compact at any ratio (test seam)')
         .option('--bypass-red-line', 'skip the 95% red-line gate (test seam; never true in production)')
-        .option('--mode <mode>', 'auto-compact mode (standard | partial). Default: standard. 24h mode auto-selects partial.', 'standard')).action(async (opts) => {
+        // No commander default here, deliberately. A declared default makes
+        // `opts.mode` permanently defined, which defeats the orchestrator's
+        // `input.mode ?? resolveAutoCompactMode(projectRoot)` fallback and
+        // silently disables "24h mode auto-selects partial" — the help text
+        // below promises it. Absence must stay absent.
+        .option('--mode <mode>', 'auto-compact mode (standard | partial). Default: standard. 24h mode auto-selects partial.')).action(async (opts) => {
         try {
             const { isValidMode } = await import('../../services/code/auto-compact-modes.js');
             const modeName = opts.mode ?? 'standard';
@@ -112,7 +120,11 @@ export function registerCodeRuntimeCommands(code, io) {
                     : {}),
                 force: opts.force === true,
                 bypassRedLine: opts.bypassRedLine === true,
-                mode: modeName
+                // Forward the FLAG verbatim — `undefined` when the user named no
+                // mode — so the orchestrator's fallback to the presence-derived
+                // mode can actually run. Forwarding the validated `modeName` is
+                // what disabled 24h → partial.
+                mode: opts.mode === undefined ? undefined : modeName
             });
             const code = result.code;
             const exitOk = result.ok || code === 'AUTO_COMPACT_SKIP' || code === 'AUTO_COMPACT_WAIT';

package/dist/cli/commands/core/skill-command.d.ts

@@ -1,3 +1,47 @@
 import type { Command } from 'commander';
+import type { AutoCompactMode } from '../../../services/code/auto-compact-modes.js';
+/**
+ * Canonicalize a user-supplied `--project <path>` value.
+ *
+ * Git Bash on Windows hands us forward-slash paths
+ * (`C:/Users/.../peaks-loop`) while `peaks workspace init` writes the
+ * backslash form, and either side may carry a trailing separator or
+ * differing case. Resolving to the real path here means every
+ * downstream consumer (`getSessionId`, `setSessionMeta`,
+ * `setSkillPresence`) sees one stable form.
+ *
+ * Returns the input unchanged when it cannot be resolved (path does
+ * not exist yet, or is not readable) so a bad `--project` still
+ * reaches the existing error handling rather than throwing here.
+ */
+/**
+ * The loop-hygiene verdict attached to every ACTIVE `skill.presence` read.
+ *
+ * Why it lives here instead of only in a SKILL.md body: the zero-pause
+ * contract ("auto-compact is the skill's own action, never the user's")
+ * was already written into `peaks-code/SKILL.md`, including an explicit
+ * ban on the exact phrasing "prompt the user to run `/compact`" — and it
+ * was still violated. A SKILL.md body is loaded once and is then
+ * compacted away, so the rule stops governing at precisely the moment
+ * context pressure makes it matter. `skill.presence` is the one call
+ * EVERY skill makes on EVERY turn, in EVERY consumer project and EVERY
+ * mode, so a value carried here cannot be forgotten, and no skill has to
+ * be edited for the obligation to reach the model.
+ *
+ * READ-ONLY by contract. It probes and reports; it never compacts.
+ * Executing `peaks code auto-compact` stays the skill's own action — a
+ * side effect here would fire on every single turn.
+ *
+ * Failure swallows to `null`: the hygiene verdict is advisory and must
+ * never be able to break the presence read itself.
+ */
+export declare function buildContextVerdict(ratio: number, mode: AutoCompactMode): {
+    context: {
+        ratioPct: string;
+        action: string;
+        mode: string;
+    };
+    nextActions: string[];
+};
 import { type ProgramIO } from '../../cli-helpers.js';
 export declare function registerSkillCommand(program: Command, io: ProgramIO): void;

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

@@ -8,6 +8,10 @@ import { findProjectRoot } from '../../../services/config/config-safety.js';
 import { generateProjectContext } from '../../../services/memory/project-context-service.js';
 import { getSessionId, setSessionMeta } from '../../../services/session/session-manager.js';
 import { resolveCallerProjection } from '../../../services/session/resolve-caller-id.js';
+import { readContextPercent } from '../../../services/context/auto-compact-reader.js';
+import { resolveOuterSessionId } from '../../../services/session/binding-status-service.js';
+import { evaluateCompactTrigger } from '../../../services/code/auto-compact-orchestrator.js';
+import { resolveAutoCompactProfile } from '../../../services/mode/mode-status-service.js';
 import { gcStalePresenceLeases } from '../../../services/skills/presence-lease-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { stableRealPath } from '../../../shared/path-utils.js';
@@ -25,6 +29,61 @@ import { stableRealPath } from '../../../shared/path-utils.js';
  * not exist yet, or is not readable) so a bad `--project` still
  * reaches the existing error handling rather than throwing here.
  */
+/**
+ * The loop-hygiene verdict attached to every ACTIVE `skill.presence` read.
+ *
+ * Why it lives here instead of only in a SKILL.md body: the zero-pause
+ * contract ("auto-compact is the skill's own action, never the user's")
+ * was already written into `peaks-code/SKILL.md`, including an explicit
+ * ban on the exact phrasing "prompt the user to run `/compact`" — and it
+ * was still violated. A SKILL.md body is loaded once and is then
+ * compacted away, so the rule stops governing at precisely the moment
+ * context pressure makes it matter. `skill.presence` is the one call
+ * EVERY skill makes on EVERY turn, in EVERY consumer project and EVERY
+ * mode, so a value carried here cannot be forgotten, and no skill has to
+ * be edited for the obligation to reach the model.
+ *
+ * READ-ONLY by contract. It probes and reports; it never compacts.
+ * Executing `peaks code auto-compact` stays the skill's own action — a
+ * side effect here would fire on every single turn.
+ *
+ * Failure swallows to `null`: the hygiene verdict is advisory and must
+ * never be able to break the presence read itself.
+ */
+export function buildContextVerdict(ratio, mode) {
+    const trigger = evaluateCompactTrigger(ratio, mode);
+    const ratioPct = `${(ratio * 100).toFixed(1)}%`;
+    // `auto-fire` belongs in the in-zone set: it is the tier where
+    // peaks-loop preempts rather than asking the LLM to decide.
+    const inZone = trigger.kind === 'auto-fire' || trigger.kind === 'pre-compact' || trigger.kind === 'red-line';
+    return {
+        context: { ratioPct, action: trigger.kind, mode },
+        nextActions: inZone
+            ? [
+                `Context at ${ratioPct} is in the '${trigger.kind}' zone (mode=${mode}).`,
+                'Run `peaks code auto-compact --project .` YOURSELF now, then continue. Do NOT ask the user to run /compact — that is the regression the zero-pause contract forbids.'
+            ]
+            : []
+    };
+}
+function contextVerdict(projectRoot) {
+    try {
+        const sessionId = getSessionId(projectRoot);
+        if (sessionId === null)
+            return { context: null, nextActions: [] };
+        const mode = resolveAutoCompactProfile(projectRoot);
+        // `outerSessionId` is NOT optional in practice: without it the
+        // adapter cannot find the harness transcript and falls back to
+        // conservative-zero, reporting a serene "0.0%" that never crosses
+        // any threshold. Same resolution order the orchestrator uses.
+        const outerSessionId = resolveOuterSessionId(projectRoot, sessionId, process.env);
+        const probe = readContextPercent({ projectRoot, sessionId, outerSessionId, env: process.env });
+        return buildContextVerdict(probe.ratio, mode);
+    }
+    catch {
+        return { context: null, nextActions: [] };
+    }
+}
 function canonicalizeProjectOption(project) {
     if (project === undefined)
         return undefined;
@@ -174,6 +233,10 @@ export function registerSkillCommand(program, io) {
             printResult(io, ok('skill.presence', { active: false }), options.json);
             return;
         }
+        // Loop-hygiene verdict: attached to every ACTIVE read, so the
+        // zero-pause contract travels with the one call every skill already
+        // makes — in every mode and every consumer project.
+        const verdict = contextVerdict(projectOption ?? process.cwd());
         if (options.checkStale === true) {
             // Slice 002 (v2.15.0) AC-1: pair the read with a staleness
             // check so callers (peaks-code Step 1, statusline) get both
@@ -187,11 +250,12 @@ export function registerSkillCommand(program, io) {
                 stale: staleness.stale,
                 staleReason: staleness.reason,
                 currentOuterSessionId: staleness.currentOuterSessionId,
-                recordedOuterSessionId: staleness.recordedOuterSessionId
-            }), options.json);
+                recordedOuterSessionId: staleness.recordedOuterSessionId,
+                ...(verdict.context !== null ? { context: verdict.context } : {})
+            }, [], verdict.nextActions), options.json);
             return;
         }
-        printResult(io, ok('skill.presence', { active: true, ...presence }), options.json);
+        printResult(io, ok('skill.presence', { active: true, ...presence, ...(verdict.context !== null ? { context: verdict.context } : {}) }, [], verdict.nextActions), options.json);
     });
     addJsonOption(skill
         .command('presence:set <name>')

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

@@ -24,6 +24,7 @@ import { SubAgentNotSupportedError } from '../../services/dispatch/sub-agent-dis
 import { emitObservabilityEvent, OBSERVABILITY_SUBAGENT_ROLES } from '../../services/observability/observability-service.js';
 import { noteDispatched, BATCH_LIMIT } from '../../services/dispatch/batch-counter.js';
 import { writeInitialDispatchRecord } from '../../services/dispatch/dispatch-record-writer.js';
+import { provisionDispatchNode } from '../../services/workflow/provision-dispatch-node.js';
 import { evaluatePromptSize } from '../../services/context/context-guard.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { resolveOuterSessionId } from '../../services/session/binding-status-service.js';
@@ -69,9 +70,13 @@ export function registerDispatchCommand(parent, io) {
         .option('--force', 'G9: override the 80% hard reject threshold at CLI (NOT allowed at hook layer per RL-30 strict)')
         .option('--from-dag <file>', '2.7.0 slice-dag-dispatcher MVP: read a SliceDag JSON file, dispatch one sub-agent per node in topological order; --batch-id overrides the auto-generated batch id (mutually exclusive with <role>)')
         .option('--isolation <mode>', 'slice 2026-07-29-worktree-l2-extended Part 2.C: isolation mode for the sub-agent. Accepts "worktree" (Part 2.C + Part 12 L2 surface), "container" (Part 8 contract + Part 12 L4 docker runtime), or "vm" (Part 25 contract; the VM runtime is a follow-up rid and fail-fasts with ISOLATION_VM_NOT_YET_IMPLEMENTED). Auto-spawns a lease + injects PEAKS_<MODE>_LEASE_ID into the dispatch envelope so the sub-agent can write to the isolated surface without a separate auth grant.')
-        // Slice 4.0.8 RD §4: required --graph-node binding. Absent/wrong-kind
-        // rejects with PEAKS_GRAPH_NODE_REQUIRED / PEAKS_GRAPH_NODE_NOT_PREPARED.
-        .requiredOption('--graph-node <id>', 'graph node id this dispatch binds to (RD §4 D4c)')
+        // Slice 4.0.8 RD §4 made this a `.requiredOption`. It is optional now:
+        // the requirement was enforced but never validated — nothing downstream
+        // reads the node, and the record writer's graph transition is
+        // best-effort — so its only observable effect was to block dispatch in
+        // every project without graph infrastructure. See
+        // `provisionDispatchNode`.
+        .option('--graph-node <id>', 'graph node id this dispatch binds to (default: a node is provisioned on demand)')
         .option('--workflow-id <id>', 'workflow id the graph node belongs to (defaults to derived from session)')
         .option('--graph-ref <ref>', 'graphRef (defaults to graphs/<workflow-id>.json)')
         // rid-001 detached sub-agent dispatch: 4 new options. Default
@@ -175,15 +180,9 @@ export function registerDispatchCommand(parent, io) {
             process.exitCode = 1;
             return;
         }
-        // Slice 4.0.8 RD §4 D4c: --graph-node is REQUIRED for single dispatch.
-        // commander.js `.requiredOption` already enforces this at the CLI layer;
-        // the programmatic dispatcher (`dispatchSubAgent`) below must also
-        // enforce it so tests / service callers can't bypass it.
-        if (typeof options.graphNode !== 'string' || options.graphNode.length === 0) {
-            printResult(io, fail('sub-agent.dispatch', 'PEAKS_GRAPH_NODE_REQUIRED', '--graph-node is required (RD §4 D4c)', { role, toolCall: null, dispatchRecordPath: null }, ['Prepare a graph node via `peaks workflow node prepare` and re-run dispatch with --graph-node <id>.']), asJson);
-            process.exitCode = 1;
-            return;
-        }
+        // Slice 4.0.8 RD §4 D4c required `--graph-node` here, before the session
+        // id existed, so the only recovery it could offer was prose. The node is
+        // now provisioned inside the try block below, once `sid` is known.
         // DOGFOOD ONLY: --prompt-length overrides the actual prompt content with
         // a synthetic prompt of the given size in bytes. The original --prompt
         // is still required (commander needs it). This avoids ARG_MAX limits
@@ -623,12 +622,43 @@ export function registerDispatchCommand(parent, io) {
                     warnings.push(`ARTIFACT_PATH_INVALID: ${getErrorMessage(err)}`);
                 }
             }
+            // Slice 4.0.8 RD §4 D4c: bind this dispatch to a graph node. When the
+            // caller names none, provision one — that is what collapses the
+            // documented three-step ritual (create graph -> `peaks workflow node
+            // prepare` -> dispatch) into a single call. Those three fields were
+            // also never passed to the writer, so the record's graph binding was
+            // always null and the writer's transition never fired: the feature was
+            // inert, and only its precondition (the required flag) was real.
+            const graphBinding = (() => {
+                if (typeof options.graphNode === 'string' && options.graphNode.length > 0) {
+                    return {
+                        nodeId: options.graphNode,
+                        workflowId: options.workflowId ?? null,
+                        graphRef: options.graphRef ?? null
+                    };
+                }
+                const provisioned = provisionDispatchNode({
+                    projectRoot,
+                    sessionId: sid,
+                    role,
+                    workflowId: options.workflowId,
+                    graphRef: options.graphRef
+                });
+                return {
+                    nodeId: provisioned.nodeId,
+                    workflowId: provisioned.workflowId,
+                    graphRef: provisioned.graphRef
+                };
+            })();
             const { path: dispatchRecordPath } = writeInitialDispatchRecord({
                 projectRoot,
                 sessionId: sid,
                 requestId: rid,
                 role,
                 prompt: effectivePrompt,
+                workflowId: graphBinding.workflowId,
+                graphNodeId: graphBinding.nodeId,
+                graphRef: graphBinding.graphRef,
                 toolCall,
                 batchId,
                 // Slice 2026-07-29-worktree-l2-extended Part 3.A: persist the

package/dist/services/code/auto-compact-orchestrator.js

@@ -32,7 +32,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } fr
 import { dirname, join } from 'node:path';
 import { getSessionIdCanonical } from '../session/session-manager.js';
 import { resolveOuterSessionId } from '../session/binding-status-service.js';
-import { AUTO_COMPACT_PRE_COMPACT_RATIO, AUTO_COMPACT_THRESHOLD_RATIO } from '../context/auto-compact-types.js';
+import { AUTO_COMPACT_PRE_COMPACT_RATIO } from '../context/auto-compact-types.js';
 import { describeMode, thresholdFor } from './auto-compact-modes.js';
 import { resolveAutoCompactProfile } from '../mode/mode-status-service.js';
 import { CompactLifecyclePublisher, newCompactRunId, settleOpenLifecycleRun, summarizeLifecycleError } from './auto-compact-lifecycle.js';
@@ -352,7 +352,7 @@ export async function runAutoCompact(input) {
                 ? decision.trigger.message
                 : decision.reason === 'in-flight-batch'
                     ? `In-flight batch detected; deferring pre-compact (ratio=${(probe.ratio * 100).toFixed(1)}%); next probe will re-evaluate.`
-                    : `Context at ${(probe.ratio * 100).toFixed(1)}%; below ${(AUTO_COMPACT_THRESHOLD_RATIO * 100).toFixed(0)}% threshold.`,
+                    : `Context at ${(probe.ratio * 100).toFixed(1)}%; below the ${(thresholdFor(mode, 'autoFire') * 100).toFixed(0)}% auto-fire threshold (mode=${mode}).`,
             data: {
                 sessionId,
                 ratio: probe.ratio,

package/dist/services/context/auto-compact-dispatcher.js

@@ -165,6 +165,8 @@ async function dispatchIdeNativeHook(input) {
         pathway: 'ide-native',
         message: result.action === 'installed'
             ? `Auto-compact PreToolUse hook installed at ${result.settingsPath}. Next Bash/Task tool call will read CLAUDE_CONTEXT_USAGE_PERCENT and compact in-band at ratio ≥ 95%.`
-            : `Auto-compact PreToolUse hook already installed at ${result.settingsPath}; next Bash/Task tool call will trigger compact in-band at ratio ≥ 95%.`
+            : result.action === 'updated'
+                ? `Auto-compact PreToolUse hook REPAIRED at ${result.settingsPath} — the installed entry carried a stale command and was rewritten.`
+                : `Auto-compact PreToolUse hook already installed at ${result.settingsPath}; next Bash/Task tool call will trigger compact in-band at ratio ≥ 95%.`
     };
 }

package/dist/services/hooks/auto-compact-hook-install.d.ts

@@ -41,12 +41,22 @@ export declare const AUTO_COMPACT_HOOK_MATCHER = "Bash|Task";
  * heavy lifting (ratio probe + in-band `claude --compact` spawn)
  * lives in the CLI surface, not inlined into the hook.
  *
+ * `--project .` is LOAD-BEARING, not decoration. `--project` is a
+ * `.requiredOption` on `peaks code auto-compact`, and a hook has no way
+ * to prompt for a missing required option. Without this argument the
+ * hook exited with `error: required option '--project <path>' not
+ * specified` on EVERY matching tool call — a non-blocking failure, so
+ * the hook looked installed while the zero-human-intervention
+ * auto-compact contract never once fired. `.` is promoted to the git
+ * root by `resolveCanonicalProjectRoot`, the same convention the
+ * `post-compact-detect` hook already documents in its own option help.
+ *
  * `npx peaks` is deliberately omitted: the project-local install
  * puts `peaks` on PATH inside the consumer repo (postinstall step),
  * so the unqualified command works in the same shell the runner
  * is using.
  */
-export declare const AUTO_COMPACT_HOOK_COMMAND = "peaks code auto-compact";
+export declare const AUTO_COMPACT_HOOK_COMMAND = "peaks code auto-compact --project .";
 /**
  * Magic comment marker that fences the auto-compatchook block.
  * Both install (writes the marker) and remove (matches on it) use
@@ -68,6 +78,9 @@ export type AutoCompactHookInstallResult = {
 } | {
     readonly action: 'already-installed';
     readonly settingsPath: string;
+} | {
+    readonly action: 'updated';
+    readonly settingsPath: string;
 };
 /**
  * Result envelope for `removeAutoCompactHook`.

package/dist/services/hooks/auto-compact-hook-install.js

@@ -44,12 +44,22 @@ export const AUTO_COMPACT_HOOK_MATCHER = 'Bash|Task';
  * heavy lifting (ratio probe + in-band `claude --compact` spawn)
  * lives in the CLI surface, not inlined into the hook.
  *
+ * `--project .` is LOAD-BEARING, not decoration. `--project` is a
+ * `.requiredOption` on `peaks code auto-compact`, and a hook has no way
+ * to prompt for a missing required option. Without this argument the
+ * hook exited with `error: required option '--project <path>' not
+ * specified` on EVERY matching tool call — a non-blocking failure, so
+ * the hook looked installed while the zero-human-intervention
+ * auto-compact contract never once fired. `.` is promoted to the git
+ * root by `resolveCanonicalProjectRoot`, the same convention the
+ * `post-compact-detect` hook already documents in its own option help.
+ *
  * `npx peaks` is deliberately omitted: the project-local install
  * puts `peaks` on PATH inside the consumer repo (postinstall step),
  * so the unqualified command works in the same shell the runner
  * is using.
  */
-export const AUTO_COMPACT_HOOK_COMMAND = 'peaks code auto-compact';
+export const AUTO_COMPACT_HOOK_COMMAND = 'peaks code auto-compact --project .';
 /**
  * Magic comment marker that fences the auto-compatchook block.
  * Both install (writes the marker) and remove (matches on it) use
@@ -102,10 +112,6 @@ export function installAutoCompactHook(input) {
     const settings = readSettings(settingsPath);
     const hooks = settings.hooks ?? {};
     const preToolUse = hooks.PreToolUse ?? [];
-    const alreadyInstalled = preToolUse.some(isAutoCompactEntry);
-    if (alreadyInstalled) {
-        return { action: 'already-installed', settingsPath };
-    }
     // The matcher is `Bash|Task`, so on Windows this runs on the same
     // Git-Bash / MSYS2 shell-form path as the other peaks Bash hooks, which
     // force-allocates a console window on every matching tool call. The
@@ -113,18 +119,36 @@ export function installAutoCompactHook(input) {
     // `.claude/settings.local.json`, so a machine-specific `shell` cannot
     // leak into a shared file. `undefined` on POSIX omits the key entirely.
     const shell = resolveHookShell();
+    const desiredHook = {
+        type: 'command',
+        command: AUTO_COMPACT_HOOK_COMMAND,
+        ...(shell !== undefined ? { shell } : {})
+    };
+    const existing = preToolUse.find(isAutoCompactEntry);
+    // "Already installed" must mean installed CORRECTLY.
+    //
+    // Keying only off the matcher is how a corrected command never reaches
+    // an existing install: the entry is present, so the installer returns
+    // early and the stale string stays in the settings file forever. That
+    // is not hypothetical — it is exactly how the missing `--project`
+    // survived on every machine that had already installed the hook, and
+    // re-running the installer could not repair any of them.
+    if (existing !== undefined) {
+        if (existing.hooks?.[0]?.command === AUTO_COMPACT_HOOK_COMMAND) {
+            return { action: 'already-installed', settingsPath };
+        }
+        const migrated = preToolUse.map((entry) => isAutoCompactEntry(entry)
+            ? { ...entry, matcher: AUTO_COMPACT_HOOK_MATCHER, hooks: [desiredHook] }
+            : entry);
+        writeSettings(settingsPath, {
+            ...settings,
+            hooks: { ...hooks, PreToolUse: migrated }
+        });
+        return { action: 'updated', settingsPath };
+    }
     const nextPreToolUse = [
         ...preToolUse,
-        {
-            matcher: AUTO_COMPACT_HOOK_MATCHER,
-            hooks: [
-                {
-                    type: 'command',
-                    command: AUTO_COMPACT_HOOK_COMMAND,
-                    ...(shell !== undefined ? { shell } : {})
-                }
-            ]
-        }
+        { matcher: AUTO_COMPACT_HOOK_MATCHER, hooks: [desiredHook] }
     ];
     writeSettings(settingsPath, {
         ...settings,

package/dist/services/lint/detect-ocr-18.d.ts

@@ -9,4 +9,10 @@ export type Ocr18DetectResult = {
 };
 /** Named code for "npx itself could not be launched" — distinct from "npx is absent". */
 export declare const NPX_PROBE_UNRESOLVED_CODE = "NPX_PROBE_UNRESOLVED";
-export declare function detectOcr18(): Ocr18DetectResult;
+/**
+ * `cwd` is where the local npm tree is looked for (defaults to the process
+ * cwd, like `runOcr18`'s own `cwd`); the npx cache roots are the machine's.
+ */
+export declare function detectOcr18(options?: {
+    readonly cwd?: string;
+}): Ocr18DetectResult;