peaks-loop 4.0.36 → 4.0.38

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 4.0.38 — 2026-09-11 (适配外部闸门 + 多语言评审复活 + 测试不再弹窗)
+
+**Highlights**:
+
+1. **子代理被事先告知"先读再改",闸门不再被误判** — 外部插件（ECC）注册了一个 `PreToolUse` 闸门，会在编辑一个文件时要求 LLM 先建立事实，否则**拒绝**。问题不在闸门本身，而在它的提示词**读起来像工具坏了**——它从不说"你的编辑没有被应用"，也从不点名真正的前置动作是**先读文件**。现在每个派发出去的子代理的前缀里都有一段 ~693 B 的说明，**规矩在前、范围点名、失败声明在后**：先说"编辑前先读这个文件，这是这里的正常工作方式"，点名作用范围（`.peaks/**` 之外的所有路径），**最后**才说万一跳过会撞上什么、以及那不是失败、编辑未被应用。
+
+   - **代价如实记录**：这段是 7 个角色各加 694 B，大致**把 4.0.36 那一轮省下的 18% 还了回去**。这是用户明确要求的适配，它值这些字节（否则每次首次编辑都要多一轮往返），但提示词经济性的账今天倒退了，这件事应当被看见。
+
+2. **`.peaks/**` 豁免被自动声明** — peaks-loop **从 `2.0.1-bug3` 起就已经决定了** `.peaks/**` 不该被 fact-gate（那个切片就叫 *fact-forcing bypass*），只是外部闸门从没听说过。现在 `peaks hooks install` / `workspace init` 会把豁免写进**机器本地**的 `settings.local.json`。四条约束都做到了：**第三方变量名全仓库只出现一处**（adapter 单点映射）、**只进机器本地**（绝不进已提交的共享模板——一个第三方变量名不该推给每个消费者）、**合并而非覆盖**（用户已有的豁免取并集，无关 `env` 键保留）、范围用 **`.peaks/**` 而非 `_runtime/`**。15 个用例覆盖，含 uninstall（只剥自己的 glob）与非 Claude Code IDE（不写）。
+
+3. **测试套件不再往桌面弹 PowerShell 窗口** — `write-gate-decision-table.test.ts` 是全仓库唯一 spawn `powershell` 的测试，**没设 `windowsHide`**，且**对决策表每一行都 spawn 一次**。决定性的证据是它的隔壁文件：`gate-enforce-machine-local-shell.test.ts` 的开头就写明了"执行 hook 就是弹窗的原因"，因此**刻意不执行**——一个文件知道并回避，另一个照做。修法是**加 `windowsHide` 但保留执行**（真的把命令跑过每个 shell 正是当初抓出 C5 `argv` 反转的原因）。6 处已修，并确认仍在真实执行（`✓ given bash … 1583ms`、`✓ given powershell … 3755ms`）。
+
+4. **多语言评审在 Windows 上复活** — `peaks code-review detect-ocr-18` 在一台 `npx --version` 正常返回 `11.9.0` 的机器上报 `npxAvailable: false`，于是**八种语言**（python/go/java/rust/cpp/csharp/ruby/php，经 `@alibaba-group/open-code-review`）的评审路径**在这个平台上从未可达**。三处仍在 spawn 裸 `npx`（Windows 上是 `.cmd`，无法这样启动）——而**同一个目录里 `detect-eslint.ts` 早就改成正确形式了**。现在三处都走既有的 `resolveNpxInvocation`，并且**"npx 不存在"与"启动不了"分开报**（正是这个混淆让一台正常的机器报成缺工具）。修前 `ocr18-missing / npxAvailable:false` → 修后 **`ready / npxAvailable:true`**。
+
+5. **`peaks hooks install --global` 此前从未成功过** — ESM 包里用了裸 `__dirname`，抛 `__dirname is not defined`，于是**每一次** `--global` 都返回失败——而且是**在 settings 已经写完之后**才失败，把半成品报成失败。同时 `--dry-run --global` **真的会往 `~/.claude/` 拷文件**。两者都已修。
+
+**验证**：build clean、`tsc -p tsconfig.build.json` exit 0、宽口径 `tsconfig.json` 维持既有 142；全量 **179 files / 1736 passed（3 skipped）**；版本三处常量（`package.json` / `CLI_VERSION` / `RUNTIME_VERSION`）一致——4.0.37 补上的那条 sync 与那个"能真失败"的守卫当场兑现。
+
+## 4.0.37 — 2026-09-10 (Windows spawn 根因 + 会话解析 + 诚实性修复)
+
+**Highlights**:
+
+1. **Windows `.cmd` spawn 根因，7 处一并修复** — `execFile`/`spawnSync` 一个 `.cmd` shim：**带 shell 时路径里的空格会被 shell 切开，不带 shell 时 Node ≥20 直接 `EINVAL`**。两条分支都不成立，所以在不含空格的路径上一切正常、在每个测试里都绿。
+   - `peaks slice check` 在**路径含空格的项目上整体失效**——这是本仓库自己所在的平台。改为 `process.execPath` + 包的 JS entry（无 shim、无 shell）。
+   - `version-precheck`：`projectRoot` 作为 **git 的参数**传入，空格路径下 git 退出 128，该层退化成 "layer skipped" —— **把一个真实存在的 tag 冲突报告成了"只是延后"**。
+   - `peaks code orchestrator-can-do`：两个探针在 Windows 上**恒返回失败**，所以 `q2SubAgentAvailable` 永远是 false、`q4ContextRatio` 永远是硬编码的 `0`（那是 fallback，不是读数）。
+   - 其余：`slice-decompose-runners`（失败被吞进 `indexed:false`，codegraph 信号静默消失）、`detect-eslint`、`coverage-c8`（`--src=`/`--reports-dir=` 携带项目路径）、若干 release 脚本。
+
+2. **会话解析根因——显式 rebind 此前只对一半 CLI 生效** — 两个函数都在回答"当前是哪个 session"，来源却不同：`getCurrentSessionId` 读 `.peaks/_runtime/session.json`，`getSessionIdCanonical` **优先 per-caller binding**。`peaks workspace init --session-id X --allow-session-rebind` 只改前者，于是 caller binding **遮蔽**了显式 rebind。实测后果：`session checkpoint` 与 `24h-mode` 把状态写进**另一个 session 的目录**，而 `peaks job` 读的是正确的那个。现在 rebind 同步更新当前 caller 的 binding——**更新而非清除**，因为清除会丢掉 per-caller 身份且没有任何代码会重建它。未 rebind 的其它 caller 文件**字节不变**，隔离不受影响。
+
+3. **job 可按 session 寻址（D6）+ `--slice-id` 不再静默 no-op（D7）** — 11 个 job 子命令补上 `--session-id`，解析顺序 `flag → PEAKS_SESSION_ID → binding`；job 不在绑定的 session 里时不再吐 `UNHANDLED_ERROR`，而是 `JOB_NOT_IN_SESSION` **指名它在哪个 session** 并给出重跑命令。`--slice-id` 现在接受 label 别名，未匹配则 `SLICE_NOT_FOUND` 并**列出全部合法 id**，且**不写入任何文件**（此前 `ok: true` 却什么都没做）。
+
+4. **`peaks web open --profile <name>`——持久登录终于有人消费** — S4 落的 `~/.peaks/web-profiles/<name>/storageState.json` 此前**没有任何动词读取**。`--profile` 只加在 `open` 上；名字在 **CLI 与 daemon 两侧**各校验一次（走线上的名字不是证据）；profile **只读**（自动浏览是否该回写用户级凭据文件是未决设计问题，本轮不替你决定）；指定了不存在的 profile **按名字失败**，而不是静默用一个未登录的浏览器。
+
+5. **诚实性修复——工具不再报告它没有的证据** — `peaks best-practice-scan` 此前把 stub 片段渲染成 8 行表格 + "方案 A ★" + 强制 ⚠️ 闸门，**全部来自合成文本**；现在合成结果直接拒绝（`ok:false`、exit 1，无推荐无表格）。`peaks slice check` 的 typecheck 阶段此前跑默认 `tsconfig.json`（272 个既有错误、**全部在 `tests/`**），**永远红**；现在 gate 于干净的 build 配置，宽口径计数对基线比较并在 detail 里如实报出。`peaks scan file-size` 不再把**生成文件**（记忆索引、lockfile）算作超长。
+
+6. **两个"不可能失败"的守卫测试** — 重建被删的 session-dir 静态扫描时发现**原版三个不变量都失效**：`src/` 正则只匹配链条**末尾**的 session id（而它要防的 bug 在**中间**，命中 0 次）；`skills/` 遍历只下一层（**完全看不到** `skills/bee/<skill>/references/`，包括它当初就是为了守的那个文件）；占位符比自己的注释窄。两侧都补了永久性的可证伪用例。`withEnv` 此前通过**在测试体内部注册 `afterEach`** 来还原环境变量——作用域错误，值会漏给下一个测试；改用 `onTestFinished`。**当前没有测试是因为这个泄漏才通过的**——真实的假通过来源，暂无受害者。
+
+7. **write gate 收紧且与 shell 解耦** — 放行范围从"**除 8 个名字外全部放行**"（那会放行顶层的 `.peaks/<change-id>/`，而 CLAUDE.md 明令禁止）收紧为**仅 `.peaks/_runtime/`**。handler 从 `node -e "<bash 专属转义的内联 JS>"` 改为调用随包发布的脚本文件，因而可像它的兄弟一样 pin PowerShell。顺带查明：**这个 hook 在 Windows 上从未真正生效过**——Claude Code 的 payload 走 stdin，而它读 argv，所以每次写入都落到 fall-through。
+
+**验证**：build clean、`tsc -p tsconfig.build.json` exit 0、宽口径 `tsconfig.json` 维持既有 142；全量 **175 files / 1679 passed（3 skipped）**；0 个 `daemon-entry` 进程残留。以上每一项都在**构建产物**（`bin/peaks.js`，非 `tsx src/`）上冒烟过，含"路径含空格的项目"这一验收场景。
+
 ## 4.0.36 — 2026-09-10 (派发提示词瘦身 + 波次调度 + 编排器上下文审计)
 
 **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.17 (2026-08-07) |
+| **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) |
 | **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.32(2026-09-08) |
+| **最新版本** | [![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) |
 | **覆盖域** | 代码(`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/bin/peaks.js

@@ -1,2 +1,72 @@
 #!/usr/bin/env node
-import '../dist/cli/index.js';
+/**
+ * peaks-loop CLI shim.
+ *
+ * This file used to be a bare static `import '../dist/cli/index.js'`. That
+ * dies with a raw `ERR_MODULE_NOT_FOUND` stack trace — before any peaks code
+ * runs — whenever the local build is stale or incomplete. The reproducible
+ * trigger: `scripts/sync-version.mjs` (run by `npm run build`, `pretest`,
+ * `prepublish`) unlinks `packages/peaks-loop-shared/dist/version.js`, so every
+ * `node bin/peaks.js <anything>` fails with an opaque Node error until the
+ * workspace packages are rebuilt.
+ *
+ * The guard below is the only behaviour added. The happy path is unchanged:
+ * the same entry module is imported with the same `process.argv`, and the
+ * CLI's own exit codes pass through untouched. Only a resolution failure
+ * whose missing specifier is OURS — an internal workspace package or any
+ * `dist/` artifact — is converted into an actionable message; every other
+ * error is rethrown unchanged (a genuinely missing third-party dependency
+ * must still surface as the raw Node error).
+ */
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
+
+/** Workspace-internal packages whose absence always means "stale build". */
+const INTERNAL_PACKAGE_NAMES = ['peaks-loop-shared', 'peaks-loop-internal-runtime'];
+
+/**
+ * The specifier Node could not resolve. Prefer the structured `err.url`
+ * (a clean `file://` URL); fall back to the quoted target in the message.
+ * The importer path is deliberately never parsed — `dist/cli/index.js` is
+ * the importer for every error, so matching it would flag third-party
+ * misses as stale-build misses.
+ */
+function missingSpecifier(err) {
+  if (typeof err?.url === 'string' && err.url.length > 0) return err.url;
+  const message = typeof err?.message === 'string' ? err.message : '';
+  const pkg = /Cannot find package '([^']+)'/.exec(message);
+  if (pkg !== null) return pkg[1];
+  const mod = /Cannot find module '([^']+)'/.exec(message);
+  if (mod !== null) return mod[1];
+  return '';
+}
+
+function isInternalSpecifier(specifier) {
+  const normalized = specifier.replace(/\\/g, '/');
+  if (normalized.length === 0) return false;
+  for (const name of INTERNAL_PACKAGE_NAMES) {
+    if (
+      normalized === name ||
+      normalized.startsWith(`${name}/`) ||
+      normalized.includes(`/${name}/`) ||
+      normalized.endsWith(`/${name}`)
+    ) {
+      return true;
+    }
+  }
+  return normalized.startsWith('dist/') || /\/dist\//.test(normalized);
+}
+
+try {
+  await import('../dist/cli/index.js');
+} catch (err) {
+  const specifier = err?.code === 'ERR_MODULE_NOT_FOUND' ? missingSpecifier(err) : '';
+  if (specifier.length === 0 || !isInternalSpecifier(specifier)) throw err;
+  process.stderr.write(
+    'peaks-loop: internal module not found — the local build is stale or incomplete.\n' +
+      `  missing: ${specifier}\n` +
+      `  fix:     run \`npm run build\` in ${PACKAGE_ROOT}, then retry.\n`
+  );
+  process.exitCode = 1;
+}

package/dist/cli/cli-helpers.js

@@ -6,6 +6,13 @@ export function printResult(io, result, asJson = false) {
     }
     if (!result.ok) {
         io.stderr(`${result.code}: ${result.message}`);
+        // S1's F1, at the printer: a warning carried by a FAILED envelope is the
+        // only news some failures have — `peaks web login` reports a headed browser
+        // it could not close this way. `fail()` hard-codes `warnings: []`, so only
+        // an envelope that spreads its own warnings over a `fail()` reaches here.
+        for (const warning of result.warnings) {
+            io.stderr(`warning: ${warning}`);
+        }
         for (const action of result.nextActions) {
             io.stderr(`- ${action}`);
         }

package/dist/cli/commands/_register.js

@@ -80,6 +80,7 @@ import { registerVendorDetectCommand } from './vendor-detect.js';
 import { registerUpgradeCommands } from './upgrade-commands.js';
 import { registerUserTouchpointCommands } from './user-touchpoint-commands.js';
 import { registerVerdictAggregateCommands } from './verdict-aggregate-command.js';
+import { registerWebCommands } from './web-commands.js';
 import { registerWorkflowCommands } from './workflow-commands.js';
 import { registerWorkflowPlanCommands } from './workflow-plan-commands.js';
 import { registerWorktreeAuthCommand } from './worktree-auth-commands.js';
@@ -139,6 +140,7 @@ const REGISTRATIONS = [
     ['session-spill-demo', registerSpillDemoCommand],
     ['outer-cache-commands', registerOuterCacheCommands],
     ['vendor-detect', registerVendorDetectCommand],
+    ['web-commands', registerWebCommands],
 ];
 function dispatchRegister(register, program, io) {
     if (register.length <= 1) {

package/dist/cli/commands/best-practice-scan-command.d.ts

@@ -1,7 +1,7 @@
 /**
  * Slice 2026-08-12 best-practice-scan — CLI subcommand.
  *
- * `peaks best-practice-scan --project <path> [--lang <lang>] [--commit]`
+ * `peaks best-practice-scan --intent <goal> --project <path> [--lang <lang>] [--commit]`
  *
  * Pipeline:
  *   1. detect language via language-detector (or use --lang override)
@@ -12,6 +12,19 @@
  *       a future slice that opts the artifact into git tracking)
  *   5. print artifact path + the 8-row table to stdout
  *
+ * `--intent` is REQUIRED: it is the business goal the scan is for (Step 2.5
+ * fires from a non-empty business goal), and it is what the artifact slug is
+ * derived from. The project path is NOT an intent — falling back to it was
+ * the defect this command was fixed for (a `.`-titled "best-practice scan").
+ * Omitting `--intent` fails with `BEST_PRACTICE_SCAN_INTENT_REQUIRED`.
+ *
+ * Honesty gate: v1's Context7 / WebSearch lookups are stubs, so a scan can
+ * come back `synthetic: true` (see scan-orchestrator). A synthetic result is
+ * NOT a scan result — the command then prints a refusal (no table, no
+ * recommendation, no ⚠️ catch gate), records the skip, and exits non-zero
+ * with `BEST_PRACTICE_SCAN_SYNTHETIC_LOOKUP` so no automated caller can
+ * treat Step 2.5 as satisfied.
+ *
  * Catch-gate (spec §7): the command emits a 3-line prompt asking the
  * user to ack / pick alt / reject + reason. The gate is read from
  * stdin via `PEAKS_BEST_PRACTICE_STDIN` (test seam) or the real stdin

package/dist/cli/commands/best-practice-scan-command.js

@@ -9,6 +9,37 @@ const CATCH_GATE_PROMPT = [
     '⚠️ 任何跟你真实业务不一样,改 — LLM 推荐可能错。',
     '回应 (默认 = 接受): 接受 / 接受方案 A|接受方案 B|接受方案 C / 拒绝 + 原因'
 ].join('\n');
+const INTENT_REQUIRED_MESSAGE = 'best-practice-scan requires --intent <text>: the intent is the business goal the scan is ' +
+    'for, not the project path. Deriving it from the project path labelled a scan with a ' +
+    'non-goal, so there is no fallback.';
+const SYNTHETIC_SOURCE_MESSAGE = 'best-practice-scan: SKIPPED — the Context7 / WebSearch lookups in this build are stubs ' +
+    '(synthetic fragments), so no real documentation was consulted and there is nothing to ' +
+    'recommend. No recommendation, no comparison table and no ⚠️ catch gate were produced.';
+function bestPracticeDir(projectRoot) {
+    return join(projectRoot, 'best-practice');
+}
+function artifactPathFor(projectRoot, slugSource) {
+    const dateStr = new Date().toISOString().slice(0, 10);
+    const slug = slugSource.replace(/[^a-zA-Z0-9_-]+/g, '-').slice(0, 32) || 'intent';
+    return join(bestPracticeDir(projectRoot), `${dateStr}-${slug}.md`);
+}
+/** Refusal body for a synthetic scan. It is written to the artifact path so
+ *  the skip survives the fire-and-forget caller (`best-practice-auto-trigger`
+ *  spawns with `stdio: 'ignore'`, so stdout never reaches anyone). */
+function renderSyntheticRefusal(opts) {
+    return [
+        `# Best-Practice Scan — ${opts.intent}`,
+        '',
+        '> SKIPPED — synthetic (stub) lookup. No real documentation lookup was performed.',
+        '',
+        SYNTHETIC_SOURCE_MESSAGE,
+        '',
+        `- language: ${opts.language}`,
+        `- transport that answered: ${opts.source} (stub)`,
+        '- Step 2.5: recorded as skipped, reason "synthetic-lookup". Re-run this step once the real',
+        '  lookup lands; a gate cannot be satisfied from a fabricated scan.'
+    ].join('\n');
+}
 async function readUserInput() {
     const override = process.env.PEAKS_BEST_PRACTICE_STDIN;
     if (override !== undefined)
@@ -59,25 +90,54 @@ export function registerBestPracticeScanCommand(program, io) {
         .description('2026-08-12 best-practice-scan: language-aware + business-aware doc-fragment lookup ' +
         'via Context7 (priority 1) → WebSearch (priority 2) → empty fallback. ' +
         'Renders the 8-row comparison table from spec §5 + §6 + §7. ' +
-        'Writes the artifact to <project>/best-practice/<date>-<intent>.md (gitignored).')
+        'Writes the artifact to <project>/best-practice/<date>-<intent>.md (gitignored). ' +
+        '--intent is required; a synthetic (stub) lookup refuses instead of rendering a ' +
+        'recommendation and exits non-zero.')
+        .option('--intent <text>', 'business goal the scan is for (required)')
         .option('--project <path>', 'project root (default cwd)', process.cwd())
         .option('--lang <lang>', 'language override (skip auto-detect)')
         .option('--commit', 'reserved flag — opts the artifact into git tracking (future slice)')).action(async (opts) => {
         try {
+            const intent = (opts.intent ?? '').trim();
+            if (intent.length === 0) {
+                printResult(io, fail('best-practice.scan', 'BEST_PRACTICE_SCAN_INTENT_REQUIRED', INTENT_REQUIRED_MESSAGE, { project: opts.project }, [
+                    'Rerun with --intent "<business goal>" — the goal from the PRD artifact'
+                ]), opts.json === true);
+                process.exitCode = 1;
+                return;
+            }
             const detection = opts.lang === undefined ? detectLanguage(opts.project) : null;
             const language = opts.lang ?? detection?.language ?? 'unknown';
-            io.stdout(`[best-practice-scan] project=${opts.project} language=${language}`);
+            io.stdout(`[best-practice-scan] project=${opts.project} intent=${intent} language=${language}`);
             const scan = await scanBestPractice({
-                intent: opts.project,
+                intent,
                 language,
                 projectRoot: opts.project,
                 io
             });
+            if (scan.synthetic) {
+                const refusal = renderSyntheticRefusal({ intent, language, source: scan.source });
+                io.stdout(refusal);
+                const refusedPath = artifactPathFor(opts.project, intent);
+                mkdirSync(bestPracticeDir(opts.project), { recursive: true });
+                writeFileSync(refusedPath, refusal + '\n', 'utf8');
+                printResult(io, fail('best-practice.scan', 'BEST_PRACTICE_SCAN_SYNTHETIC_LOOKUP', SYNTHETIC_SOURCE_MESSAGE, {
+                    project: opts.project,
+                    intent,
+                    language,
+                    scanSource: scan.source,
+                    synthetic: true,
+                    step25: 'skipped-synthetic-lookup',
+                    artifactPath: refusedPath
+                }, ['Re-run once real Context7 / WebSearch wiring lands', `Skip record written to ${refusedPath}`]), opts.json === true);
+                process.exitCode = 1;
+                return;
+            }
             const recommendation = scan.results.length > 0 ? 'A' : 'B';
             const reasoning = `基于 ${scan.fragments.length} 个 ${scan.source} 文档片段;` +
                 `语言=${language};LLM 推断方案 ${recommendation} 与项目阶段最匹配。`;
             const table = formatOutputTable({
-                intent: opts.project,
+                intent,
                 language,
                 fragments: scan.results,
                 recommendation,
@@ -92,14 +152,12 @@ export function registerBestPracticeScanCommand(program, io) {
             io.stdout(CATCH_GATE_PROMPT);
             const userInput = await readUserInput();
             const outcome = parseCatchGateReply(userInput, recommendation);
-            const outDir = join(opts.project, 'best-practice');
-            mkdirSync(outDir, { recursive: true });
-            const dateStr = new Date().toISOString().slice(0, 10);
-            const slug = opts.project.replace(/[^a-zA-Z0-9_-]+/g, '-').slice(0, 32) || 'intent';
-            const artifactPath = join(outDir, `${dateStr}-${slug}.md`);
+            const artifactPath = artifactPathFor(opts.project, intent);
+            mkdirSync(bestPracticeDir(opts.project), { recursive: true });
             writeFileSync(artifactPath, table + '\n', 'utf8');
             printResult(io, ok('best-practice.scan', {
                 project: opts.project,
+                intent,
                 language,
                 scanSource: scan.source,
                 fragments: scan.results,

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

@@ -14,6 +14,7 @@ import { fail, ok } from 'peaks-loop-shared/result';
 import { detectPostCompactResume, formatPostCompactResumeLogLine } from '../../services/code/post-compact-detector.js';
 import { runAutoCompact } from '../../services/code/auto-compact-orchestrator.js';
 import { auditContext } from '../../services/context/context-audit.js';
+import { buildContextAuditHint } from '../../services/context/context-audit-hint.js';
 import { evaluateStep08, STEP_08_BACKUP_REGEX } from '../../services/code/step-08-gate.js';
 import { evaluateEmitHandoff, JOB_NOT_INITIALIZED, JOB_REMAINING_BLOCKED } from '../../services/code/emit-handoff.js';
 import { readJobShapeDecision, JobShapeDecisionError } from '../../services/code/job-shape-decision.js';
@@ -320,7 +321,8 @@ export function registerCodeRuntimeCommands(code, io) {
         'fail-closed backup regex when missing. Exit 0 = allow, exit 2 = block. ' +
         'When the decision says isJob=true AND progress.json exists, the stdout ' +
         'also carries `Next: slice #N+1 of M (<currentSlice>)` so the LLM cannot ' +
-        'wake up cold.')
+        'wake up cold. When the context ratio is ≥ 0.70 the stdout gains ONE more ' +
+        'line naming the largest context consumer (audit cached ≥ 5 min; fail-soft).')
         .requiredOption('--project <path>', 'target project root (the hook passes "." so resolveCanonicalProjectRoot promotes it to the git root)')
         .option('--session-id <sid>', 'override session id (default: read from active presence)')
         .option('--prompt <text>', 'explicit prompt text (default: read last-prompt.txt; stdin ignored)')).action((opts) => {
@@ -340,6 +342,17 @@ export function registerCodeRuntimeCommands(code, io) {
                 printResult(io, envelope, opts.json);
                 return;
             }
+            // Slice 2026-09-10-three-fixes (Slice 2): proactive context-consumer
+            // hint. Runs ONLY when the window is ≥ 0.70 full, caches the audit
+            // result for ≥ 5 min so the transcript is scanned at most once per
+            // TTL window, and is fail-soft (null → no extra line). It never
+            // changes the exit code and never blocks.
+            const hintLine = buildContextAuditHint({
+                projectRoot: opts.project,
+                sessionId,
+                outerSessionId: resolveOuterSessionId(opts.project, sessionId)
+            });
+            const hintActions = hintLine === null ? [] : [hintLine];
             const evalInput = {
                 projectRoot: opts.project,
                 sessionId
@@ -355,7 +368,7 @@ export function registerCodeRuntimeCommands(code, io) {
                     decision: verdict.decision,
                     progress: verdict.progress,
                     nextSlice: result.nextSliceLine
-                }, [], result.nextSliceLine !== null ? [result.nextSliceLine] : []);
+                }, [], [...(result.nextSliceLine !== null ? [result.nextSliceLine] : []), ...hintActions]);
                 printResult(io, envelope, opts.json);
                 return;
             }
@@ -366,7 +379,8 @@ export function registerCodeRuntimeCommands(code, io) {
                     decision: null,
                     nextSlice: null
                 }, [], [
-                    'job-shape.json says isJob=false; single-rid mode (gate allows).'
+                    'job-shape.json says isJob=false; single-rid mode (gate allows).',
+                    ...hintActions
                 ]);
                 printResult(io, envelope, opts.json);
                 return;
@@ -381,7 +395,8 @@ export function registerCodeRuntimeCommands(code, io) {
                     backupRegex: STEP_08_BACKUP_REGEX.toString()
                 }, [
                     'Run `peaks code detect-job --is-job true --rationale <text> --suggested-job-id <slug>` to record the Job-shape verdict.',
-                    'Then re-run the Bash tool call.'
+                    'Then re-run the Bash tool call.',
+                    ...hintActions
                 ]);
                 io.stderr(`${blockMessage}\n`);
                 printResult(io, envelope, opts.json);
@@ -396,7 +411,8 @@ export function registerCodeRuntimeCommands(code, io) {
                 nextSlice: null,
                 promptSource: verdict.promptSource
             }, [], [
-                'No job-shape.json AND no backup-regex match on prompt → allow (most prompts are not Job-shaped).'
+                'No job-shape.json AND no backup-regex match on prompt → allow (most prompts are not Job-shaped).',
+                ...hintActions
             ]);
             printResult(io, envelope, opts.json);
             return;

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

@@ -1,5 +1,6 @@
 import { existsSync, copyFileSync, mkdirSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
@@ -7,6 +8,16 @@ import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntries
 import { readJsonObjectFile } from '../../services/ide/shared/atomic-json.js';
 import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
 import { getAdapter } from '../../services/ide/ide-registry.js';
+/**
+ * This module's own directory — `<root>/src/cli/commands` in the source tree,
+ * `<root>/dist/cli/commands` in a build. Same reason as
+ * `claude-settings-template.ts`: `package.json#type` is `module`, so the CJS
+ * module-directory global does not exist here (it is a ReferenceError under
+ * both tsx and the shipped `dist` build — see the guard in
+ * `tests/unit/hooks/gate-enforce-machine-local-shell.test.ts`), and
+ * `process.argv[1]` names a different file per entry point.
+ */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 function resolveScope(options) {
     return options.global ? 'global' : 'project';
 }
@@ -97,12 +108,15 @@ function readOnDiskDenyEntries(settings) {
         return [];
     return deny.filter((d) => typeof d === 'string');
 }
-function copyBridgeHookIfPresent(userHome) {
-    const source = resolve(__dirname, '..', '..', 'services', 'hooks', 'pre-tool-superpowers-bridge.sh');
+function copyBridgeHookIfPresent(userHome, dryRun = false) {
+    const source = resolve(MODULE_DIR, '..', '..', 'services', 'hooks', 'pre-tool-superpowers-bridge.sh');
     const target = resolve(userHome, '.claude', 'skills', 'peaks-code', 'hooks', 'pre-tool-superpowers-bridge.sh');
     if (!existsSync(source)) {
         return { copied: false, source, target };
     }
+    if (dryRun) {
+        return { copied: true, source, target };
+    }
     mkdirSync(dirname(target), { recursive: true });
     copyFileSync(source, target);
     return { copied: true, source, target };
@@ -117,12 +131,15 @@ function copyBridgeHookIfPresent(userHome) {
  * runtime entry; the shell script is the canonical artifact distributed
  * alongside the bridge hook.
  */
-function copyCodeGateHookIfPresent(userHome) {
-    const source = resolve(__dirname, '..', '..', 'services', 'hooks', 'pre-tool-code-gate.sh');
+function copyCodeGateHookIfPresent(userHome, dryRun = false) {
+    const source = resolve(MODULE_DIR, '..', '..', 'services', 'hooks', 'pre-tool-code-gate.sh');
     const target = resolve(userHome, '.claude', 'skills', 'peaks-code', 'hooks', 'pre-tool-code-gate.sh');
     if (!existsSync(source)) {
         return { copied: false, source, target };
     }
+    if (dryRun) {
+        return { copied: true, source, target };
+    }
     mkdirSync(dirname(target), { recursive: true });
     copyFileSync(source, target);
     return { copied: true, source, target };
@@ -147,8 +164,10 @@ export function registerHooksCommands(program, io) {
             if (options.dryRun === true) {
                 const plan = planHookInstall(scope, projectRoot, { ide, skipProgress });
                 const dryRunEntries = listExpectedEntriesForIde(ide, skipProgress);
+                // `dryRun: true` — a --dry-run must not write anything, and these
+                // helpers' target is the user's home directory.
                 const bridgeCopy = scope === 'global'
-                    ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
+                    ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '', true)
                     : { copied: false, source: '', target: '' };
                 // Slice 2026-08-06-codegate-vendor-neutral: also copy the
                 // code-gate hook script. The runtime gate lives at
@@ -156,7 +175,7 @@ export function registerHooksCommands(program, io) {
                 // in the install output); the script is the build artifact
                 // distributed alongside the bridge hook.
                 const codeGateCopy = scope === 'global'
-                    ? copyCodeGateHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
+                    ? copyCodeGateHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '', true)
                     : { copied: false, source: '', target: '' };
                 printResult(io, ok('hooks.install', {
                     ...plan,
@@ -176,6 +195,12 @@ export function registerHooksCommands(program, io) {
                     permissionsDenyEntries: listSuperpowersDenyEntries()
                 }, [], [
                     `would install ${dryRunEntries.length} peaks-managed hook entries`,
+                    // Name the target file of every entry: the gate-enforce entry is
+                    // routed to the machine-local settings file (see
+                    // `resolveHookTargets`), so a summary that only listed
+                    // `settingsPath` + the entry names read as if it landed in the
+                    // committed, shared file.
+                    ...plan.entryTargets.map((entry) => `would write ${entry.matcher || '(no matcher)'} → ${entry.sentinel} to ${entry.settingsPath}`),
                     `would write ${listSuperpowersDenyEntries().length} permissions.deny entries (Layer 3 worktree governance)`,
                     bridgeCopy.copied
                         ? `would copy bridge hook from ${bridgeCopy.source} to ${bridgeCopy.target}`
@@ -300,6 +325,12 @@ export function registerHooksCommands(program, io) {
             // install left behind.
             const settingsPath = status.settingsPath;
             const settings = existsSync(settingsPath) ? readJsonObjectFile(settingsPath) : {};
+            // The gate-enforce entry is materialized into the machine-local
+            // settings file (see `resolveHookTargets`), so the on-disk entry list
+            // must be read from both files or `status` would report it missing.
+            const localSettings = status.localSettingsPath !== undefined && existsSync(status.localSettingsPath)
+                ? readJsonObjectFile(status.localSettingsPath)
+                : {};
             // Slice 2026-07-29-worktree-layer3-deny: report the Layer 3 deny
             // entries actually on disk. We read the existing settings.json
             // (above) and surface its `permissions.deny` block. Any entry
@@ -311,7 +342,10 @@ export function registerHooksCommands(program, io) {
             printResult(io, ok('hooks.status', {
                 ...status,
                 ide,
-                entries: readInstalledEntriesFromSettings(settings, ide),
+                entries: [
+                    ...readInstalledEntriesFromSettings(settings, ide),
+                    ...readInstalledEntriesFromSettings(localSettings, ide)
+                ],
                 permissionsDenyEntries: listSuperpowersDenyEntries(),
                 permissionsDenyOnDisk: onDiskDeny
             }), options.json);