peaks-loop 3.0.1 → 3.0.3

package/CHANGELOG.md

@@ -1,8 +1,43 @@
 # Changelog
 
-## [Unreleased] — 2026-06-29 — change-id shim (cleanup post v2.17.0 hard-kill)
+## [3.0.3] — 2026-07-02 — auto-compact zero-pause (ide-native pathway)
 
-**MINOR bump target: v2.19.0**. Full removal of the peaks-loop change-id axis (filesystem axis, code shim, envelope JSON slug, CLI flags). OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched. One cleanup slice that retires the v2.17.0 shim half-life.
+**PATCH bump from 3.0.2**. Closes the user-pause gap on long Claude Code sessions: at context ratio ≥ 0.95 the runner now compacts itself via a PreToolUse hook, no human intervention required.
+
+### Added — `ide-native` pathway + `peaks session auto-compact-hook`
+
+The v2.13.0 auto-compact design shipped `shell-exec` as the only pathway, which spawns a NEW claude child process and cannot compact the current runner. Long-task users hit a UX gap: AI CLI still stopped and asked the human to run `/compact` manually.
+
+- **New `ide-native` pathway** — `src/services/context/auto-compact-dispatcher.ts:138-155` routes main-session compacts through `installAutoCompactHook`, which writes a PreToolUse hook into `.claude/settings.local.json` (matcher `Bash|Task`, command `peaks session auto-compact-hook`).
+- **New `peaks session auto-compact-hook` CLI** — `src/cli/commands/session-auto-compact-hook-command.ts`. Reads `CLAUDE_CONTEXT_USAGE_PERCENT`; below 0.95 exits 0 silent; at ratio ≥ 0.95 spawns `claude --compact` in-band against the **current** runner (detached + unref, never blocks the runner's tool call). ENOENT-safe: if `claude` is not on PATH (e.g. user runs Claude Code as an MCP), the hook logs a stderr hint and exits 0 silent rather than crashing the runner.
+- **New `installAutoCompactHook` / `removeAutoCompactHook` service** — `src/services/hooks/auto-compact-hook-install.ts`. Idempotent: re-install returns `already-installed` and does NOT re-write the file; remove preserves other PreToolUse entries (the existing fact-forcing bypass hook on every peaks-loop consumer project survives).
+- **Lazy install** — hook is installed on first `peaks solo auto-compact` invocation, NOT on `peaks workspace init`. User has opted in by running the command; no zero-touch surprise.
+- **Claude Code adapter** — `compactPathway` changed from `shell-exec` to `ide-native` for `target='main'`. Sub-agent shells still get the legacy `shell-exec` pathway.
+
+### Fixed — Solo Step N+2 prose (was 75% / "do NOT auto-execute")
+
+- `skills/peaks-solo/SKILL.md` Step N+2 paragraph rewritten: thresholds now 0.85 pre-compact / 0.95 red-line (matches v2.13.0 auto-compact), explicit Karpathy §4 compact-red-line exception cited, `peaks solo context-now --json` is the canonical probe primitive (replaces `peaks context check --prompt-size <bytes>` hand-pass).
+- `src/services/context/main-session-monitor.ts` — `@deprecated` JSDoc on `evaluateMainSessionThreshold` cross-links to `evaluateCompactTrigger` (0.85/0.95); legacy 4-tier envelope retained for statusline callers (migration to v2.15.0).
+
+### Tests — 4 new suites + 3 modified files
+
+- `tests/unit/services/hooks/auto-compact-hook-install.test.ts` (7 cases) — install / idempotent / remove / preservation of unrelated entries.
+- `tests/unit/services/context/auto-compact-dispatcher-ide-native.test.ts` (9 cases) — `dispatchIdeCompact({ target: 'main' })` routes to `ide-native`; round-trip install / remove.
+- `tests/unit/skills/solo-step-n-plus-2-prose.test.ts` (6 cases) — pins the 0.85 / 0.95 / Karpathy §4 contract; asserts `75%` is NOT in the paragraph.
+- `tests/unit/cli/session-auto-compact-hook-command.test.ts` (3 cases) — dogfood surfacing: below-threshold silent, missing env-var silent, red-line + ENOENT exits 0 with stderr hint.
+- `tests/unit/services/context/main-session-monitor.test.ts` (+2 AC-4 cases), `tests/unit/context/auto-compact-main-target.test.ts` (pathway assertion updated) — coverage.
+
+### Dogfood verified
+
+Validated on `C:/Users/smallMark/Desktop/peaksclaw/ice-cola` (consumer project). End-to-end: install hook alongside existing fact-forcing bypass → idempotent re-run → below-threshold silent → red-line + no-claude-on-PATH exits 0 with hint → remove strips only the auto-compact matcher. No regressions in 5,139 / 5,158 vitest pass.
+
+## [3.0.2] — 2026-07-02 — change-id shim retirement (v2.19.0) + Understand Anything hybrid context (3.0.2)
+
+**PATCH bump from 3.0.1**. Two independent slices bundled into one release:
+- **v2.19.0 change-id shim retirement** — full removal of the peaks-loop change-id axis (filesystem axis, code shim, envelope JSON slug, CLI flags). The change-id was a no-op post-v2.17.0 hard-kill; this slice retires the v2.17.0 shim half-life. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched.
+- **3.0.2 Understand Anything hybrid context** — new `peaks understand context` subcommand that encapsulates the UA-first / codegraph-fallback / hybrid-union routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture). Consumers no longer pick one or the other at the LLM level.
+
+The v2.19.0 work shipped as code commits (`f91d71c`, `5186d3d`, `b598612`, `ced835e`, `7ee9d8f`, plus follow-up tests) but was never formally released. v2.19.0 is therefore *not* a separate release line — its changes are rolled forward into 3.0.2. Future releases resume numeric sequence from 3.0.3.
 
 ### Removed — change-id shim (cleanup post v2.17.0 hard-kill)
 
@@ -70,7 +105,38 @@
 - Existing RD/QA artifacts in `.peaks/_runtime/<sid>/<role>/` remain readable; the planner no longer requires a change-id, and the change-id (if any) is embedded only as a filename slug.
 - The 2.8.3 hard-ban on `.peaks/_runtime/<YYYY-MM-DD-*>/` sibling directories is still enforced via the rewritten guard test and the inline `lstatSync` in `initWorkspace`.
 
-## [2.18.4] — 2026-06-29 — peaks-solo first-run step gates: hard-pause 1.x→2.0 upgrade + make `--mode` optional on Step 1
+## [3.0.2] — 2026-07-02 — change-id shim retirement (v2.19.0) + Understand Anything hybrid context (3.0.2)
+
+**PATCH bump from 3.0.1**. Two independent slices bundled into one release:
+- **v2.19.0 change-id shim retirement** — full removal of the peaks-loop change-id axis (filesystem axis, code shim, envelope JSON slug, CLI flags). The change-id was a no-op post-v2.17.0 hard-kill; this slice retires the v2.17.0 shim half-life. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched.
+- **3.0.2 Understand Anything hybrid context** — new `peaks understand context` subcommand that encapsulates the UA-first / codegraph-fallback / hybrid-union routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture). Consumers no longer pick one or the other at the LLM level.
+
+The v2.19.0 work shipped as code commits (`f91d71c`, `5186d3d`, `b598612`, `ced835e`, `7ee9d8f`, plus follow-up tests) but was never formally released. v2.19.0 is therefore *not* a separate release line — its changes are rolled forward into 3.0.2. Future releases resume numeric sequence from 3.0.3.
+
+### Added — `peaks understand context` (3.0.2 user-facing feature)
+
+The Understand Anything (UA) Claude Code plugin and `@colbymchenry/codegraph` are both complementary project-analysis tools. UA provides a high-level knowledge graph (tours, layers, expert prompts); codegraph provides low-level affected-file analysis. Until 3.0.2, peaks-loop consumers had to choose one or the other at the LLM level — there was no service-layer enforcement of either.
+
+This slice adds a single `peaks understand context` subcommand that encapsulates the routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture — see `peaks-solo` SKILL.md). The envelope carries a `source` tag so downstream consumers can audit which evidence contributed to the context.
+
+**Source routing** (deterministic, decided in `buildUnderstandContext`):
+- `ua-only` — UA knowledge graph present, no codegraph
+- `ua-missing-fallback-codegraph` — UA absent, codegraph produced evidence
+- `ua-and-codegraph-hybrid` — both present, both contribute (parallel `Promise.all`)
+- `both-missing` — neither produced evidence, exit code 2
+
+**Added files (5):**
+- `src/services/understand/understand-hybrid-service.ts` (133L, new): `buildUnderstandContext({projectRoot, files?, sampleSize?, artifactDir?, codegraphRunner?})` uses `Promise.all` to run UA scan and codegraph affected in parallel; total wall-clock = `max(uaMs, codegraphMs)`, not sum. Failures are caught into `warnings[]` (best-effort); the main envelope is always returned so consumers can audit missing evidence.
+- `src/services/understand/hybrid-types.ts` (39L, new): `UnderstandContextResult` envelope + 4-value source enum + `CodegraphContextBlock`.
+- `src/cli/commands/understand-commands.ts` (208L, +51L net): new `peaks understand context` subcommand at base path `admin/audit-logs` (the only 3rd CLI surface in the understand module family). The subcommand accepts `--project --files --sample --artifact-dir` and emits the envelope as JSON or human-readable summary.
+- `tests/unit/understand-hybrid-service.test.ts` (110L, 4 cases): `ua-only` / `fallback` / `hybrid` / `both-missing`.
+- `tests/integration/understand-hybrid-cli.test.ts` (85L, 3 cases): end-to-end CLI both-missing / ua-only / envelope-shape-stability.
+
+**Test evidence:** 7/7 vitest (4 unit + 3 integration), `tsc --noEmit` clean.
+
+The peak-loop skill-external-invocation audit pattern (capability discovery + references only + do-not-execute + Peaks authoritative) is preserved: codegraph is consumed via the existing `executeCodegraphInvocation` (no upstream installer calls); UA installation is a text `INSTALL_HINT` only.
+
+### Removed — change-id shim (cleanup post v2.17.0 hard-kill, rolled up from v2.19.0)
 
 **PATCH bump from 2.18.3**. Resolves the user-reported "新项目第一次使用 peaks-solo 时初始化完不按流程走、开发效果差、再开 session 后才正常" defect. Two surgical fixes to the first-run Solo gates (3 source files, 1 new test file, 2 test-regression updates; no schema change, no new dependencies, no public API change).
 

package/README-en.md

@@ -137,7 +137,7 @@ peaks project dashboard --project . --json   # one-shot project view
 
 **3 solo wrappers + 7 role skills + 2 standalone audits + 1 orchestrator = 13 skills.** In daily use, 1 skill (`peaks-solo`) covers ≥ 90% of needs.
 
-> **v2.13.0**: zero-human-intervention **auto-compact** (`peaks solo context-now` + `peaks solo auto-compact`) — peaks-loop probes context-fill % autonomously. ≥85% writes a pre-compact checkpoint + convergence plan + dispatches IDE compact. ≥95% forces a synchronous RED-LINE compact. The LLM-runner stays alive with context < 95% without human intervention. **v2.13.4 fix**: auto-compact now targets the **main-session** context (not a sub-agent shell) by writing a `.peaks/_runtime/<sid>/txt/auto-compact-pending.json` intent file that the main-session LLM picks up on its next turn and fires `/compact` in-band.
+> **v2.13.0**: zero-human-intervention **auto-compact** (`peaks solo context-now` + `peaks solo auto-compact`) — peaks-loop probes context-fill % autonomously. ≥85% writes a pre-compact checkpoint + convergence plan + dispatches IDE compact. ≥95% forces a synchronous RED-LINE compact. The LLM-runner stays alive with context < 95% without human intervention. **v2.13.4 fix**: auto-compact now targets the **main-session** context (not a sub-agent shell). **3.0.3 new `ide-native` pathway**: installs a PreToolUse hook into `.claude/settings.local.json` (`Bash|Task` matcher → `peaks session auto-compact-hook`); the runner's next Bash/Task tool call in-band spawns `claude --compact`, no longer relying on the LLM to remember to fire `/compact`. Hook is ENOENT-safe (exits 0 + stderr hint if `claude` is not on PATH; runner is never interrupted).
 
 ## 🚧 Killer feature: un-bypassable gates
 

package/README.md

@@ -175,7 +175,7 @@ peaks project dashboard --project . --json   # 当前项目一眼看完
 
 **3 solo 包装 + 7 角色技能 + 2 独立审计 + 1 编排器 = 13 个。日常 1 个 `peaks-solo` 覆盖 ≥ 90%。**
 
-> **v2.13.0 新增**：zero-human-intervention **auto-compact**（`peaks solo context-now` + `peaks solo auto-compact`）——peaks-loop 自己探测 context %，≥85% 主动收敛（写 checkpoint + 收敛计划 + 触发 IDE compact），≥95% 强制同步压缩红线。LLM-runner 上下文始终 < 95% 自主运行，零介入。**v2.13.4 修复**：`auto-compact` 现在默认压缩**主会话**上下文（不是 sub-agent shell 自己的），通过写 `.peaks/_runtime/<sid>/txt/auto-compact-pending.json` 意图文件让主 LLM 下一轮 in-band 触发 `/compact`。
+> **v2.13.0 新增**：zero-human-intervention **auto-compact**（`peaks solo context-now` + `peaks solo auto-compact`）——peaks-loop 自己探测 context %，≥85% 主动收敛（写 checkpoint + 收敛计划 + 触发 IDE compact），≥95% 强制同步压缩红线。LLM-runner 上下文始终 < 95% 自主运行，零介入。**v2.13.4 修复**：`auto-compact` 现在默认压缩**主会话**上下文（不是 sub-agent shell 自己的）。**3.0.3 新增 `ide-native` 通路**：在 `.claude/settings.local.json` 装 PreToolUse hook（`Bash|Task` matcher → `peaks session auto-compact-hook`），runner 下一次 Bash/Task tool call **in-band** 触发 `claude --compact`，不再依赖 LLM 自己 fire `/compact`。Hook ENOENT-safe（claude CLI 不在 PATH 时退出 0 + stderr 提示，runner 不会被中断）。
 
 ## 🚧 杀手锏：不可绕过的门禁
 

package/dist/src/cli/commands/core/session-command.js

@@ -13,6 +13,7 @@ import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.j
 // saw them — they were effectively hidden.
 import { registerSessionCheckpointCommand } from '../session-checkpoint-command.js';
 import { registerSessionResumeCommand } from '../session-resume-command.js';
+import { registerSessionAutoCompactHookCommand } from '../session-auto-compact-hook-command.js';
 export function registerSessionCommand(program, io) {
     const session = program.command('session').description('Manage Peaks session directories');
     addJsonOption(session
@@ -186,6 +187,11 @@ export function registerSessionCommand(program, io) {
     // `<TAB>`-discovery and the LLM never saw them.
     registerSessionCheckpointCommand(session, io);
     registerSessionResumeCommand(session, io);
+    // Slice 2026-07-02-auto-compact-zero-pause: the Bash command the
+    // PreToolUse hook in `.claude/settings.local.json` fires. Keeping
+    // it eager (same fix as checkpoint + resume) so `peaks session --help`
+    // lists it for LLM `<TAB>`-discovery.
+    registerSessionAutoCompactHookCommand(session);
     addJsonOption(session
         .command('rotate')
         .description('Drop the project-level session binding so the next peaks call auto-generates a fresh session id. The on-disk session directory is left intact — only .peaks/.session.json is removed.')

package/dist/src/cli/commands/session-auto-compact-hook-command.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `peaks session auto-compact-hook` — slice 2026-07-02-auto-compact-zero-pause.
+ *
+ * The Bash entrypoint the PreToolUse hook fires on every Bash/Task
+ * tool call from the Claude Code runner. Behaviour:
+ *
+ *   1. Read `CLAUDE_CONTEXT_USAGE_PERCENT` (or any adapter-declared
+ *      env-var via the registry — claude-code MVP). If ratio is below
+ *      the red-line threshold (0.95), exit 0 silent — the runner's
+ *      normal flow continues.
+ *   2. If ratio is ≥ 0.95 (red line), write a one-line stderr hint
+ *      so the human sees what happened, then in-band spawn
+ *      `claude --compact` so the **current** runner's context
+ *      window collapses (not a new claude process).
+ *   3. Always exit 0. The hook is a probe, not a gate — the gate is
+ *      `claude --compact` itself returning 0.
+ *
+ * Idempotency: re-running the hook is safe; if `claude --compact`
+ * is already in flight, the new process just exits 0 immediately
+ * (Claude Code's compact is a one-shot operation against the
+ * current runner).
+ *
+ * Why a CLI subcommand instead of an inline JS hook:
+ *   - Keeps the hook payload in `.claude/settings.local.json` small
+ *     (one line: `peaks session auto-compact-hook`).
+ *   - Lets the heavy lifting (ratio parsing, IDE-aware env-var
+ *     resolution, spawning `claude --compact`) live in TypeScript
+ *     where it's unit-testable.
+ *   - Discoverable via `peaks session --help` — future LLM sessions
+ *     see the primitive exists.
+ *
+ * Karpathy §2: 50 lines, no abstractions, no speculative error
+ * handling. The hook command is a single-purpose muscle; if it
+ * grows beyond ~80 lines, that's a signal to split.
+ */
+import type { Command } from 'commander';
+export declare function registerSessionAutoCompactHookCommand(session: Command): void;

package/dist/src/cli/commands/session-auto-compact-hook-command.js

@@ -0,0 +1,127 @@
+/**
+ * `peaks session auto-compact-hook` — slice 2026-07-02-auto-compact-zero-pause.
+ *
+ * The Bash entrypoint the PreToolUse hook fires on every Bash/Task
+ * tool call from the Claude Code runner. Behaviour:
+ *
+ *   1. Read `CLAUDE_CONTEXT_USAGE_PERCENT` (or any adapter-declared
+ *      env-var via the registry — claude-code MVP). If ratio is below
+ *      the red-line threshold (0.95), exit 0 silent — the runner's
+ *      normal flow continues.
+ *   2. If ratio is ≥ 0.95 (red line), write a one-line stderr hint
+ *      so the human sees what happened, then in-band spawn
+ *      `claude --compact` so the **current** runner's context
+ *      window collapses (not a new claude process).
+ *   3. Always exit 0. The hook is a probe, not a gate — the gate is
+ *      `claude --compact` itself returning 0.
+ *
+ * Idempotency: re-running the hook is safe; if `claude --compact`
+ * is already in flight, the new process just exits 0 immediately
+ * (Claude Code's compact is a one-shot operation against the
+ * current runner).
+ *
+ * Why a CLI subcommand instead of an inline JS hook:
+ *   - Keeps the hook payload in `.claude/settings.local.json` small
+ *     (one line: `peaks session auto-compact-hook`).
+ *   - Lets the heavy lifting (ratio parsing, IDE-aware env-var
+ *     resolution, spawning `claude --compact`) live in TypeScript
+ *     where it's unit-testable.
+ *   - Discoverable via `peaks session --help` — future LLM sessions
+ *     see the primitive exists.
+ *
+ * Karpathy §2: 50 lines, no abstractions, no speculative error
+ * handling. The hook command is a single-purpose muscle; if it
+ * grows beyond ~80 lines, that's a signal to split.
+ */
+import { spawn } from 'node:child_process';
+import { detectIdeFromEnv } from '../../services/context/main-session-monitor.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+/**
+ * Red-line ratio threshold. Must match the orchestrator's
+ * AUTO_COMPACT_RED_LINE_RATIO constant (0.95). Kept here as a
+ * literal so the hook command stays self-contained — a future
+ * slice may move this to a shared constant module if the value
+ * starts drifting.
+ */
+const RED_LINE_RATIO = 0.95;
+/**
+ * Parse `CLAUDE_CONTEXT_USAGE_PERCENT` (or the adapter-declared
+ * env-var) into a ratio in [0, 1]. Returns null on missing /
+ * malformed input. Mirrors `readEnvPercent` in
+ * `auto-compact-reader.ts` so the hook command and the
+ * orchestrator agree on parsing semantics.
+ */
+function readRatioFromEnv(env) {
+    const detected = detectIdeFromEnv(env);
+    const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+    const adapter = getAdapter(ideId);
+    if (!adapter.compact)
+        return null;
+    const varName = adapter.compact.envVarForContextPercent;
+    const raw = env[varName];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    const parsed = Number.parseFloat(raw);
+    if (!Number.isFinite(parsed))
+        return null;
+    // Allow either "0..1" or "0..100" encoding. Claude Code writes
+    // "0..1" today; statusline tools sometimes write "0..100". Normalize.
+    const ratio = parsed > 1.5 ? parsed / 100 : Math.max(0, Math.min(1, parsed));
+    return { ratio, varName };
+}
+export function registerSessionAutoCompactHookCommand(session) {
+    session
+        .command('auto-compact-hook')
+        .description('PreToolUse hook entrypoint — read CLAUDE_CONTEXT_USAGE_PERCENT and, ' +
+        'at ratio ≥ 0.95, in-band spawn `claude --compact` against the current ' +
+        'runner. Designed for invocation from `.claude/settings.local.json` ' +
+        'PreToolUse hooks; safe to re-run.')
+        .action(() => {
+        const probe = readRatioFromEnv(process.env);
+        if (probe === null) {
+            // No signal → exit 0 silent. The hook must never block the
+            // runner's normal flow on a missing env-var.
+            return;
+        }
+        if (probe.ratio < RED_LINE_RATIO) {
+            // Below red line → exit 0 silent. The orchestrator's
+            // pre-compact zone (0.85–0.95) is handled out-of-band by
+            // the LLM firing `peaks solo auto-compact --execute`; the
+            // hook only fires on the synchronous red-line path.
+            return;
+        }
+        // Red line reached — compact the current runner in-band.
+        // The `detached: true` + `unref()` pair lets the hook return
+        // immediately while Claude Code's own slash-command processor
+        // picks up `claude --compact` against the runner's session.
+        // This is the fix for the shell-exec-spawns-a-child-process
+        // bug documented in `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`.
+        //
+        // Dogfood 2026-07-02 fix: when `claude` is not on PATH (the
+        // user runs Claude Code as an MCP rather than via the CLI
+        // binary), `spawn` raises ENOENT. Catching this MUST NOT crash
+        // the runner's tool call — the hook must exit 0 silently with
+        // a one-line stderr hint so the runner keeps working. The user
+        // can then run `/compact` manually (or `peaks solo auto-compact`
+        // from another terminal).
+        try {
+            const child = spawn('claude', ['--compact'], {
+                stdio: 'ignore',
+                detached: true,
+                env: process.env
+            });
+            child.on('error', () => {
+                // Spawn failed (ENOENT or EPERM). Exit 0 silently with a
+                // stderr hint — the hook contract is "never crash the
+                // runner's tool call".
+                process.stderr.write('[peaks:auto-compact-hook] claude CLI not on PATH; cannot fire in-band. Run `/compact` manually or set up the Claude Code CLI binary.\n');
+            });
+            child.unref();
+            process.stderr.write(`[peaks:auto-compact-hook] ratio=${(probe.ratio * 100).toFixed(1)}% ≥ ${(RED_LINE_RATIO * 100).toFixed(0)}%; firing claude --compact in-band\n`);
+        }
+        catch {
+            // Defensive: `spawn` can throw synchronously on some platforms.
+            process.stderr.write('[peaks:auto-compact-hook] failed to spawn claude --compact; run `/compact` manually.\n');
+        }
+    });
+}

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

@@ -1,5 +1,6 @@
 import { InvalidArgumentError } from 'commander';
 import { scanUnderstandAnything, summarizeKnowledgeGraph } from '../../services/understand/understand-scan-service.js';
+import { buildUnderstandContext } from '../../services/understand/understand-hybrid-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function parsePositiveInteger(value) {
@@ -109,4 +110,39 @@ export function registerUnderstandCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // Slice 2026-07-02-codegraph-ua-hybrid: hybrid context subcommand.
+    // Routes UA-first / codegraph-fallback / hybrid in the service layer;
+    // the CLI is a thin shell that surfaces the envelope and exit code.
+    addJsonOption(understand
+        .command('context')
+        .description('Build a hybrid project-context envelope: UA knowledge graph when present, codegraph affected as fallback, or both in parallel')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--artifact-dir <path>', 'override the default .understand-anything directory')
+        .option('--sample <n>', 'maximum number of sample node ids to include (default 5)', parsePositiveInteger)
+        .option('--files <file...>', 'file globs to feed `codegraph affected` (default: src/index.ts, package.json, README.md)')).action(async (options) => {
+        try {
+            const ctxOptions = { projectRoot: options.project };
+            if (options.artifactDir !== undefined)
+                ctxOptions.artifactDir = options.artifactDir;
+            if (options.sample !== undefined)
+                ctxOptions.sampleSize = options.sample;
+            if (options.files !== undefined)
+                ctxOptions.files = options.files;
+            const result = await buildUnderstandContext(ctxOptions);
+            const exitCode = result.source === 'both-missing' ? 2 : 0;
+            if (exitCode !== 0) {
+                printResult(io, fail('understand.context', 'UNDERSTAND_CONTEXT_NO_EVIDENCE', `No UA graph and codegraph affected produced no usable evidence`, result, [
+                    INSTALL_HINT,
+                    'Run `peaks codegraph index` in this project to populate the codegraph index, then retry'
+                ]), options.json);
+                process.exitCode = exitCode;
+                return;
+            }
+            printResult(io, ok('understand.context', result, [], result.warnings.length > 0 ? result.warnings : undefined), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('understand.context', 'UNDERSTAND_CONTEXT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and codegraph installation before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -100,16 +100,36 @@ export async function dispatchIdeCompact(input) {
                 timeoutMs
             });
         case 'ide-native':
-            // Future slice: write the compact intent to the IDE's hook
-            // file (per `IdeSettingsLocation`). For v2.13.0 MVP the
-            // shell-exec pathway covers Claude Code; this branch stays
-            // reserved.
-            return {
-                ok: false,
-                ide: ideId,
-                pathway: 'ide-native',
-                message: `ide-native compact pathway is reserved for a future slice; adapter '${ideId}' should declare shell-exec or llm-self-compress for now.`
-            };
+            // Slice 2026-07-02-auto-compact-zero-pause: write the auto-compact
+            // PreToolUse hook into `.claude/settings.local.json`. The hook
+            // command (`peaks session auto-compact-hook`) reads
+            // `CLAUDE_CONTEXT_USAGE_PERCENT` on every subsequent Bash/Task
+            // tool call from the runner and, at ratio ≥ 0.95, in-band spawns
+            // `claude --compact` against the CURRENT runner (not a child
+            // process — the bug documented in
+            // `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`).
+            //
+            // `ide-native` is ONLY for the main-session runner. When the
+            // caller is a sub-agent shell (which has its own ephemeral
+            // context window — not the runner's), fall through to
+            // shell-exec so the sub-agent's `compactCommand` spawns a
+            // child claude process and the sub-agent's own runner doesn't
+            // get a PreToolUse hook installed in the wrong place.
+            if (target === 'sub-agent') {
+                return await dispatchShellExec({
+                    ideId,
+                    command: profile.compactCommand,
+                    timeoutMs
+                });
+            }
+            // Lazy install: we only get here when the caller explicitly
+            // invokes `peaks solo auto-compact --execute`, so the user has
+            // already opted in. No zero-touch surprise on workspace init.
+            return await dispatchIdeNativeHook({
+                projectRoot: input.projectRoot,
+                sessionId: input.sessionId,
+                target
+            });
         case 'llm-self-compress':
             return {
                 ok: true,
@@ -188,3 +208,33 @@ function dispatchShellExec(input) {
         });
     });
 }
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause: implement the
+ * `ide-native` pathway. Writes the auto-compact PreToolUse hook
+ * into `.claude/settings.local.json` (idempotent; the install
+ * service is a no-op if the hook is already present). On the next
+ * Bash/Task tool call from the runner, the hook fires
+ * `peaks session auto-compact-hook` which in-band spawns
+ * `claude --compact` against the CURRENT runner session.
+ *
+ * Returns `ok: true, pathway: 'ide-native'` regardless of install
+ * action (`installed` vs `already-installed`) — both states
+ * achieve the operational goal: the hook is wired and the next
+ * Bash call will trigger it.
+ */
+async function dispatchIdeNativeHook(input) {
+    // Lazy dynamic import — matches the existing pattern in
+    // `runAutoCompact` for `auto-compact-reader.ts` (line 311) and
+    // avoids a static cycle if future slices add cross-imports
+    // between dispatcher and hook-install.
+    const { installAutoCompactHook } = await import('../hooks/auto-compact-hook-install.js');
+    const result = installAutoCompactHook({ projectRoot: input.projectRoot });
+    return {
+        ok: true,
+        ide: 'claude-code',
+        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%.`
+    };
+}

package/dist/src/services/context/main-session-monitor.d.ts

@@ -56,6 +56,18 @@ export declare function detectIdeFromEnv(env?: NodeJS.ProcessEnv): IdeKind;
  * Threshold check. Pure function (no IO). `capacityBytes` is injectable
  * for tests and future per-IDE capacity overrides. Defaults to the
  * G9 256K proxy (matches G9 for cognitive continuity).
+ *
+ * @deprecated Slice 2026-07-02-auto-compact-zero-pause: the
+ * 50/75/90 tier thresholds pre-date the v2.13.0 auto-compact
+ * design. The authoritative tier table for triggering compaction
+ * now lives in `evaluateCompactTrigger` (auto-compact-orchestrator.ts)
+ * with the 0.85 pre-compact / 0.95 red-line thresholds. New
+ * callers should call `evaluateCompactTrigger(ratio)` directly.
+ * This function is retained because legacy `peaks context check
+ * --prompt-size` still emits its 4-tier envelope for callers that
+ * need the soft signal (e.g. statusline display). Migration is
+ * scheduled for v2.15.0; the @deprecated tag flips callers'
+ * eslint warnings so the migration is mechanical.
  */
 export declare function evaluateMainSessionThreshold(promptSize: number, capacityBytes?: number): MainSessionEvaluation;
 export interface InFlightBatchProbe {

package/dist/src/services/context/main-session-monitor.js

@@ -55,6 +55,18 @@ export function detectIdeFromEnv(env = process.env) {
  * Threshold check. Pure function (no IO). `capacityBytes` is injectable
  * for tests and future per-IDE capacity overrides. Defaults to the
  * G9 256K proxy (matches G9 for cognitive continuity).
+ *
+ * @deprecated Slice 2026-07-02-auto-compact-zero-pause: the
+ * 50/75/90 tier thresholds pre-date the v2.13.0 auto-compact
+ * design. The authoritative tier table for triggering compaction
+ * now lives in `evaluateCompactTrigger` (auto-compact-orchestrator.ts)
+ * with the 0.85 pre-compact / 0.95 red-line thresholds. New
+ * callers should call `evaluateCompactTrigger(ratio)` directly.
+ * This function is retained because legacy `peaks context check
+ * --prompt-size` still emits its 4-tier envelope for callers that
+ * need the soft signal (e.g. statusline display). Migration is
+ * scheduled for v2.15.0; the @deprecated tag flips callers'
+ * eslint warnings so the migration is mechanical.
  */
 export function evaluateMainSessionThreshold(promptSize, capacityBytes = CONTEXT_CAPACITY_DEFAULT_BYTES) {
     const inner = evaluateThresholdTier(promptSize, capacityBytes);

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

@@ -0,0 +1,104 @@
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause — `ide-native` pathway
+ * hook install/remove service.
+ *
+ * Writes the auto-compact PreToolUse hook into the consumer
+ * project's `.claude/settings.local.json` so the next Bash or Task
+ * tool call from the running Claude Code session reads
+ * `CLAUDE_CONTEXT_USAGE_PERCENT` and, at ratio ≥ 0.95, in-band fires
+ * `claude --compact` against the current runner (not a child process).
+ *
+ * Idempotency contract:
+ *   - install is idempotent — calling `installAutoCompactHook`
+ *     twice produces a byte-identical file (after stripping the
+ *     magic comment). The on-disk matcher entry is the single
+ *     source of truth.
+ *   - remove is idempotent — calling `removeAutoCompactHook` when
+ *     the hook is absent is a no-op.
+ *   - other PreToolUse entries are untouched on install AND remove.
+ *
+ * Magic comment marker: `peaks:auto-compact-hook-do-not-edit`. The
+ * comment sits next to the matcher entry so a human reading the file
+ * sees the boundary; an automated diff/remove op keys off the marker
+ * + the `matcher` regex.
+ *
+ * Pure data + minimal IO: `installAutoCompactHook` and
+ * `removeAutoCompactHook` accept `settingsPath` so callers can pick
+ * `.claude/settings.local.json` (default) or pass an explicit path
+ * for tests. The functions write to disk via `fs.writeFileSync` so
+ * the on-disk file matches the in-memory template byte-for-byte
+ * (modulo the magic comment which is excluded from the data
+ * structure; see `AUTO_COMPACT_HOOK_MATCHER`).
+ */
+/**
+ * Stable matcher for the auto-compact hook. Single source of truth
+ * — `install` and `remove` both key off this constant so the
+ * invariants can't drift between the two paths.
+ */
+export declare const AUTO_COMPACT_HOOK_MATCHER = "Bash|Task";
+/**
+ * Stable command the hook fires. Wraps `peaks session
+ * auto-compact-hook` so the heavy lifting (ratio probe + in-band
+ * `claude --compact` spawn) lives in the CLI surface, not inlined
+ * into the hook.
+ *
+ * `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 session auto-compact-hook";
+/**
+ * Magic comment marker that fences the auto-compatchook block.
+ * Both install (writes the marker) and remove (matches on it) use
+ * this string so the comment is the only place the boundary lives.
+ */
+export declare const AUTO_COMPACT_HOOK_MARKER = "peaks:auto-compact-hook-do-not-edit";
+/**
+ * Default on-disk location — kept here (not in claude-settings-template)
+ * because the auto-compact hook is a separate install surface from
+ * the fact-forcing gate bypass template.
+ */
+export declare const AUTO_COMPACT_HOOK_SETTINGS_PATH = ".claude/settings.local.json";
+/**
+ * Result envelope for `installAutoCompactHook`.
+ */
+export type AutoCompactHookInstallResult = {
+    readonly action: 'installed';
+    readonly settingsPath: string;
+} | {
+    readonly action: 'already-installed';
+    readonly settingsPath: string;
+};
+/**
+ * Result envelope for `removeAutoCompactHook`.
+ */
+export type AutoCompactHookRemoveResult = {
+    readonly action: 'removed';
+    readonly settingsPath: string;
+} | {
+    readonly action: 'absent';
+    readonly settingsPath: string;
+};
+/**
+ * Install the auto-compact PreToolUse hook. Idempotent: a re-run
+ * returns `action: 'already-installed'` and does NOT re-write the
+ * file (preserves any unrelated edits the user has made to other
+ * entries).
+ */
+export declare function installAutoCompactHook(input: {
+    readonly projectRoot: string;
+    readonly settingsPath?: string;
+}): AutoCompactHookInstallResult;
+/**
+ * Remove the auto-compact PreToolUse hook. Idempotent: missing hook
+ * returns `action: 'absent'` without re-writing the file.
+ *
+ * Other PreToolUse entries are left untouched. The settings file
+ * structure is preserved (top-level keys like `permissions` are not
+ * deleted).
+ */
+export declare function removeAutoCompactHook(input: {
+    readonly projectRoot: string;
+    readonly settingsPath?: string;
+}): AutoCompactHookRemoveResult;

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

@@ -0,0 +1,157 @@
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause — `ide-native` pathway
+ * hook install/remove service.
+ *
+ * Writes the auto-compact PreToolUse hook into the consumer
+ * project's `.claude/settings.local.json` so the next Bash or Task
+ * tool call from the running Claude Code session reads
+ * `CLAUDE_CONTEXT_USAGE_PERCENT` and, at ratio ≥ 0.95, in-band fires
+ * `claude --compact` against the current runner (not a child process).
+ *
+ * Idempotency contract:
+ *   - install is idempotent — calling `installAutoCompactHook`
+ *     twice produces a byte-identical file (after stripping the
+ *     magic comment). The on-disk matcher entry is the single
+ *     source of truth.
+ *   - remove is idempotent — calling `removeAutoCompactHook` when
+ *     the hook is absent is a no-op.
+ *   - other PreToolUse entries are untouched on install AND remove.
+ *
+ * Magic comment marker: `peaks:auto-compact-hook-do-not-edit`. The
+ * comment sits next to the matcher entry so a human reading the file
+ * sees the boundary; an automated diff/remove op keys off the marker
+ * + the `matcher` regex.
+ *
+ * Pure data + minimal IO: `installAutoCompactHook` and
+ * `removeAutoCompactHook` accept `settingsPath` so callers can pick
+ * `.claude/settings.local.json` (default) or pass an explicit path
+ * for tests. The functions write to disk via `fs.writeFileSync` so
+ * the on-disk file matches the in-memory template byte-for-byte
+ * (modulo the magic comment which is excluded from the data
+ * structure; see `AUTO_COMPACT_HOOK_MATCHER`).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Stable matcher for the auto-compact hook. Single source of truth
+ * — `install` and `remove` both key off this constant so the
+ * invariants can't drift between the two paths.
+ */
+export const AUTO_COMPACT_HOOK_MATCHER = 'Bash|Task';
+/**
+ * Stable command the hook fires. Wraps `peaks session
+ * auto-compact-hook` so the heavy lifting (ratio probe + in-band
+ * `claude --compact` spawn) lives in the CLI surface, not inlined
+ * into the hook.
+ *
+ * `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 session auto-compact-hook';
+/**
+ * Magic comment marker that fences the auto-compatchook block.
+ * Both install (writes the marker) and remove (matches on it) use
+ * this string so the comment is the only place the boundary lives.
+ */
+export const AUTO_COMPACT_HOOK_MARKER = 'peaks:auto-compact-hook-do-not-edit';
+/**
+ * Default on-disk location — kept here (not in claude-settings-template)
+ * because the auto-compact hook is a separate install surface from
+ * the fact-forcing gate bypass template.
+ */
+export const AUTO_COMPACT_HOOK_SETTINGS_PATH = '.claude/settings.local.json';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return {};
+    try {
+        const raw = readFileSync(settingsPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return isObject(parsed) ? parsed : {};
+    }
+    catch {
+        // Malformed JSON → start fresh so install doesn't error. The
+        // caller is the human / CLI, not an LLM (idempotency matters
+        // more than preserve-on-corruption here).
+        return {};
+    }
+}
+function writeSettings(settingsPath, settings) {
+    const dir = dirname(settingsPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // 2-space JSON matches the existing template writer's style so
+    // `diff` against pre-install files is minimal.
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+function isAutoCompactEntry(entry) {
+    return entry.matcher === AUTO_COMPACT_HOOK_MATCHER;
+}
+/**
+ * Install the auto-compact PreToolUse hook. Idempotent: a re-run
+ * returns `action: 'already-installed'` and does NOT re-write the
+ * file (preserves any unrelated edits the user has made to other
+ * entries).
+ */
+export function installAutoCompactHook(input) {
+    const settingsPath = input.settingsPath ?? join(input.projectRoot, AUTO_COMPACT_HOOK_SETTINGS_PATH);
+    const settings = readSettings(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const preToolUse = hooks.PreToolUse ?? [];
+    const alreadyInstalled = preToolUse.some(isAutoCompactEntry);
+    if (alreadyInstalled) {
+        return { action: 'already-installed', settingsPath };
+    }
+    const nextPreToolUse = [
+        ...preToolUse,
+        {
+            matcher: AUTO_COMPACT_HOOK_MATCHER,
+            hooks: [
+                {
+                    type: 'command',
+                    command: AUTO_COMPACT_HOOK_COMMAND
+                }
+            ]
+        }
+    ];
+    writeSettings(settingsPath, {
+        ...settings,
+        hooks: {
+            ...hooks,
+            PreToolUse: nextPreToolUse
+        }
+    });
+    return { action: 'installed', settingsPath };
+}
+/**
+ * Remove the auto-compact PreToolUse hook. Idempotent: missing hook
+ * returns `action: 'absent'` without re-writing the file.
+ *
+ * Other PreToolUse entries are left untouched. The settings file
+ * structure is preserved (top-level keys like `permissions` are not
+ * deleted).
+ */
+export function removeAutoCompactHook(input) {
+    const settingsPath = input.settingsPath ?? join(input.projectRoot, AUTO_COMPACT_HOOK_SETTINGS_PATH);
+    if (!existsSync(settingsPath))
+        return { action: 'absent', settingsPath };
+    const settings = readSettings(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const preToolUse = hooks.PreToolUse ?? [];
+    const nextPreToolUse = preToolUse.filter((entry) => !isAutoCompactEntry(entry));
+    if (nextPreToolUse.length === preToolUse.length) {
+        return { action: 'absent', settingsPath };
+    }
+    writeSettings(settingsPath, {
+        ...settings,
+        hooks: {
+            ...hooks,
+            PreToolUse: nextPreToolUse
+        }
+    });
+    return { action: 'removed', settingsPath };
+}

package/dist/src/services/ide/adapters/claude-code-adapter.js

@@ -47,18 +47,30 @@ export const CLAUDE_CODE_ADAPTER = {
         gateEnforce: true,
         statusline: true,
     },
-    // v2.13.0 AC-1 + AC-3 MVP: Claude Code is the first IDE to fill
-    // the `compact` profile. Future adapters (trae / codex / cursor /
-    // qoder / tongyi-lingma / hermes / openclaw) follow the same
-    // shape — peaks-loop reads the env-var and dispatches the
-    // command via `IdeAdapter.compact`, with zero hard-coded IDE
-    // names anywhere in the orchestrator. If your IDE exposes a
-    // context-percent env-var and a slash-style compact command,
-    // register `compact` here and the auto-compact protocol activates.
+    // v2.13.0 AC-1 + AC-3 MVP, slice 2026-07-02-auto-compact-zero-pause:
+    // Claude Code is the first IDE to fill the `compact` profile.
+    // Future adapters (trae / codex / cursor / qoder / tongyi-lingma /
+    // hermes / openclaw) follow the same shape — peaks-loop reads the
+    // env-var and dispatches the command via `IdeAdapter.compact`, with
+    // zero hard-coded IDE names anywhere in the orchestrator. If your
+    // IDE exposes a context-percent env-var and a slash-style compact
+    // command, register `compact` here and the auto-compact protocol
+    // activates.
+    //
+    // Pathway = 'ide-native' (not 'shell-exec') so the dispatcher
+    // routes main-session compacts through the PreToolUse hook in
+    // `.claude/settings.local.json`. The hook fires
+    // `peaks session auto-compact-hook` on the NEXT Bash/Task tool
+    // call from the runner, which in-band spawns `claude --compact`
+    // against the CURRENT runner — not a child process (the
+    // shell-exec spawn-new-claude bug documented in
+    // `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`).
+    // Sub-agent shells still get the legacy shell-exec pathway via
+    // `dispatchIdeCompact({ target: 'sub-agent' })`.
     compact: {
         envVarForContextPercent: 'CLAUDE_CONTEXT_USAGE_PERCENT',
         compactCommand: 'claude --compact',
-        compactPathway: 'shell-exec',
+        compactPathway: 'ide-native',
         postCompactDetectCommand: 'peaks context now --json'
     },
     // Slice #011: standards profile. Claude Code reads its constitution at

package/dist/src/services/understand/hybrid-types.d.ts

@@ -0,0 +1,32 @@
+import type { CodegraphExecutionResult } from '../codegraph/codegraph-service.js';
+import type { UnderstandScanReport } from './understand-types.js';
+import type { UnderstandGraphSummary } from './understand-scan-service.js';
+/**
+ * Slice 2026-07-02-codegraph-ua-hybrid — envelope contract for the
+ * `peaks understand context` command. The service layer decides which
+ * evidence to include based on environment detection; the source field
+ * is the authoritative routing signal.
+ */
+export type UnderstandContextSource = 'ua-only' | 'ua-missing-fallback-codegraph' | 'ua-and-codegraph-hybrid' | 'both-missing';
+export type CodegraphContextBlock = {
+    invocation: {
+        subcommand: 'affected';
+        files: string[];
+    };
+    execution: CodegraphExecutionResult;
+    /** Parsed JSON from `codegraph affected --json` when exitCode === 0; null otherwise. */
+    payload: unknown;
+    parseError?: string;
+};
+export type UnderstandContextResult = {
+    projectRoot: string;
+    source: UnderstandContextSource;
+    ua?: {
+        scan: UnderstandScanReport;
+        summary?: UnderstandGraphSummary;
+    };
+    codegraph?: CodegraphContextBlock;
+    /** Wall-clock milliseconds spent on the slowest parallel branch. */
+    durationMs: number;
+    warnings: string[];
+};

package/dist/src/services/understand/hybrid-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/services/understand/understand-hybrid-service.d.ts

@@ -0,0 +1,10 @@
+import { type CodegraphProcessRunner } from '../codegraph/codegraph-service.js';
+import type { UnderstandContextResult } from './hybrid-types.js';
+export type BuildUnderstandContextOptions = {
+    projectRoot: string;
+    files?: string[];
+    sampleSize?: number;
+    artifactDir?: string;
+    codegraphRunner?: CodegraphProcessRunner;
+};
+export declare function buildUnderstandContext(options: BuildUnderstandContextOptions): Promise<UnderstandContextResult>;

package/dist/src/services/understand/understand-hybrid-service.js

@@ -0,0 +1,100 @@
+import { createCodegraphInvocation, executeCodegraphInvocation } from '../codegraph/codegraph-service.js';
+import { scanUnderstandAnything, summarizeKnowledgeGraph } from './understand-scan-service.js';
+import { getErrorMessage } from '../../shared/result.js';
+const DEFAULT_FILES = ['src/index.ts', 'package.json', 'README.md'];
+function resolveFiles(files) {
+    if (files !== undefined && files.length > 0) {
+        return [...files];
+    }
+    return [...DEFAULT_FILES];
+}
+async function safeSummarize(options) {
+    try {
+        return { summary: await summarizeKnowledgeGraph(options) };
+    }
+    catch (error) {
+        return { warning: `UA summary failed: ${getErrorMessage(error)}` };
+    }
+}
+async function runCodegraph(projectRoot, files, runner) {
+    try {
+        const invocation = createCodegraphInvocation({
+            subcommand: 'affected',
+            project: projectRoot,
+            files,
+            json: true
+        });
+        const execution = await executeCodegraphInvocation(invocation, runner);
+        if (execution.exitCode !== 0) {
+            return { warning: `codegraph affected exited with code ${execution.exitCode}: ${execution.stderr.slice(0, 200)}` };
+        }
+        let payload = null;
+        let parseError;
+        try {
+            payload = JSON.parse(execution.stdout);
+        }
+        catch (error) {
+            parseError = getErrorMessage(error);
+        }
+        return {
+            block: {
+                invocation: { subcommand: 'affected', files },
+                execution,
+                payload,
+                ...(parseError !== undefined ? { parseError } : {})
+            }
+        };
+    }
+    catch (error) {
+        return { warning: `codegraph affected failed: ${getErrorMessage(error)}` };
+    }
+}
+function decideSource(uaScan, hasCodegraph) {
+    const uaPresent = uaScan.exists && uaScan.graph.exists && uaScan.graph.parseError === undefined;
+    if (uaPresent && hasCodegraph)
+        return 'ua-and-codegraph-hybrid';
+    if (uaPresent)
+        return 'ua-only';
+    if (hasCodegraph)
+        return 'ua-missing-fallback-codegraph';
+    return 'both-missing';
+}
+export async function buildUnderstandContext(options) {
+    const startedAt = Date.now();
+    const files = resolveFiles(options.files);
+    const sampleSize = options.sampleSize ?? 5;
+    const warnings = [];
+    const scanOptions = { projectRoot: options.projectRoot };
+    if (options.artifactDir !== undefined) {
+        scanOptions.artifactDir = options.artifactDir;
+    }
+    const uaScan = await scanUnderstandAnything(scanOptions);
+    const uaSummaryPromise = uaScan.exists && uaScan.graph.exists
+        ? safeSummarize({ projectRoot: options.projectRoot, sampleSize, ...(options.artifactDir !== undefined ? { artifactDir: options.artifactDir } : {}) })
+        : Promise.resolve({});
+    const [uaSummary, codegraphResult] = await Promise.all([
+        uaSummaryPromise,
+        runCodegraph(options.projectRoot, files, options.codegraphRunner)
+    ]);
+    if (uaSummary.warning)
+        warnings.push(uaSummary.warning);
+    if (codegraphResult.warning)
+        warnings.push(codegraphResult.warning);
+    const source = decideSource(uaScan, codegraphResult.block !== undefined);
+    const result = {
+        projectRoot: options.projectRoot,
+        source,
+        durationMs: Date.now() - startedAt,
+        warnings
+    };
+    if (source === 'ua-only' || source === 'ua-and-codegraph-hybrid') {
+        result.ua = {
+            scan: uaScan,
+            ...(uaSummary.summary !== undefined ? { summary: uaSummary.summary } : {})
+        };
+    }
+    if (codegraphResult.block) {
+        result.codegraph = codegraphResult.block;
+    }
+    return result;
+}

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "3.0.1";
+export declare const CLI_VERSION = "3.0.3";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "3.0.1";
+export const CLI_VERSION = "3.0.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-solo/SKILL.md

@@ -5,22 +5,18 @@ description: Full-auto orchestration facade for the Peaks-Loop skill family. Use
 
 ## Single-scope-axis naming convention (2.7.1)
 
-> **Read once at the top of this file.**
-
 The `.peaks/` workspace has a **single scope axis** (session-id) plus a nested **sub-agent axis** under `.peaks/_sub_agents/<sessionId>/...`. Use `<sessionId>` (NEVER bare `<sid>`). The change-id axis is gone as of slice `2026-06-29-change-id-root-removal` — reviewable artifacts now live at `.peaks/_runtime/<sessionId>/<role>/...` (gitignored) with the change-id optionally embedded as a filename slug. CLI surface: session-id → `peaks session *`; sub-agent → `peaks sub-agent *`. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched.
 
 **2.7.1:** `recordBypass` / `isBypassLimitReached` had a legacy write path that bypassed `.peaks/_runtime/` (slice 2.7.1 fix in `request-commands.ts:410`). Now writes canonical `.peaks/_runtime/<sid>/`. `getChangeArtifactRoot` removed. Test `skills-skill-md-naming.test.ts` enforces (a) zero bare `<sid>`, (b) axis labels, (c) this callout.
 
-## Hard ban (effective 2.8.3 — read every session, no exceptions)
-
-Never create `.peaks/_runtime/<YYYY-MM-DD-*>/` at the top level of `.peaks/`. The post-v2.19.0 single-scope-axis convention requires ALL reviewable artifact dirs to live under `.peaks/_runtime/<sessionId>/<role>/...` (gitignored) — never as siblings of `.peaks/_runtime/`. The `peaks workspace init` flow creates only `.peaks/_runtime/<sessionId>/session.json`; reviewable artifact files are placed under that same dir by the writer. The change-id is preserved as an optional filename slug inside `.peaks/_runtime/<sessionId>/<role>/requests/<rid>-<change-id>.md` but does NOT route filesystem writes. If you find yourself about to write a date-prefixed directory directly under `.peaks/`, STOP and reroute under `.peaks/_runtime/<sessionId>/`. The `.gitignore` rule `.peaks/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-*/` will block the write at commit time; the vitest guard at `tests/unit/workspace/top-level-change-id-guard.test.ts` (8 cases, including CLI help-text) will fail the suite if a regression sneaks through.
-
 ## Karpathy guidance (Slice 1/6 — karpathy prompt-injection-lift)
 
-> **Read once per Solo invocation; the 4 Karpathy guidelines are mandatory context for every sub-agent Solo dispatches.**
-
 Every sub-agent dispatch (`peaks-prd`, `peaks-rd`, `peaks-qa`, `peaks-ui`, `peaks-sc`, `peaks-txt`) MUST receive the 4 Karpathy guidelines. Append the verbatim block from `peaks-rd/references/rd-sub-agent-dispatch.md` §"Karpathy-guidelines context" to the dispatch prompt; never silently drop it. Canonical skill id: `andrej-karpathy-skills:karpathy-guidelines`. Summary: **#1 Think Before Coding** (surface assumptions, name tradeoffs), **#2 Simplicity First** (min code, no speculative features, 800-line file cap), **#3 Surgical Changes** (touch only what the request requires), **#4 Goal-Driven Execution** (verifiable ACs, plan + verify checkpoints).
 
+## Hard ban (effective 2.8.3 — read every session, no exceptions)
+
+Never create `.peaks/_runtime/<YYYY-MM-DD-*>/` at the top level of `.peaks/`. The post-v2.19.0 single-scope-axis convention requires ALL reviewable artifact dirs to live under `.peaks/_runtime/<sessionId>/<role>/...` (gitignored) — never as siblings of `.peaks/_runtime/`. The `peaks workspace init` flow creates only `.peaks/_runtime/<sessionId>/session.json`; reviewable artifact files are placed under that same dir by the writer. The change-id is preserved as an optional filename slug inside `.peaks/_runtime/<sessionId>/<role>/requests/<rid>-<change-id>.md` but does NOT route filesystem writes. If you find yourself about to write a date-prefixed directory directly under `.peaks/`, STOP and reroute under `.peaks/_runtime/<sessionId>/`. The `.gitignore` rule `.peaks/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-*/` will block the write at commit time; the vitest guard at `tests/unit/workspace/top-level-change-id-guard.test.ts` (8 cases, including CLI help-text) will fail the suite if a regression sneaks through.
+
 # Peaks-Loop Solo
 
 Peaks-Loop Solo is the orchestration facade for the Peaks-Loop short skill family. Use it to identify the user scenario, recommend an execution mode, coordinate role skills, and produce the final handoff report. Do not collapse role responsibilities into this skill.
@@ -31,56 +27,25 @@ Peaks-Loop Solo is the orchestration facade for the Peaks-Loop short skill famil
 
 ## Skill-first architecture note (read once, internalise)
 
-This skill is the **primary surface**. The `peaks <cmd>` CLI is **auxiliary** — invoked by the skill prompt only when a primitive is the right tool (atomic side effect, machine-enforced gate, structured JSON for a downstream decision, or backstop the LLM cannot skip). Behaviour only an LLM in a skill prompt would use lives **here in the SKILL.md**, not as a new CLI command.
+This skill is the **primary surface**. The `peaks <cmd>` CLI is **auxiliary** — invoked by the skill prompt only when a primitive is the right tool. Behaviour only an LLM in a skill prompt would use lives **here in the SKILL.md**.
 
 ## Code-Change Red Line (BLOCKING — read before ANY tool call)
 
-**Peaks-Loop Solo is an orchestrator, NOT an implementer. You MUST NOT write, edit, or modify any application source code directly.**
-
-Every code change — bugfix, feature, refactor, or config — MUST go through the full pipeline:
-
-```
-peaks-solo (orchestrate only)
-  → RD work   ← ALL code changes happen HERE
-    → Unit tests written + pass (Peaks-Loop Gate B2)
-    → Karpathy standards enforced (file-size ≤800 lines, TypeScript rules)
-    → Code review evidence (Peaks-Loop Gate B3)
-    → Security review evidence (Peaks-Loop Gate B4)
-  → QA work  ← ALL validation happens HERE
-    → Functional test execution (Peaks-Loop Gate A2)
-    → Performance check (Peaks-Loop Gate A4)
-    → Security test (Peaks-Loop Gate A3)
-    → Browser E2E (when frontend; Peaks-Loop Gate D)
-    → Verdict: pass | return-to-rd | blocked
-```
-
-**Mechanism for "RD work" / "QA work" depends on the orchestration mode:** `full-auto`/`swarm` use `peaks sub-agent dispatch <role>` (IDE-agnostic dispatch primitive); `assisted`/`strict`/inline-fallback executes inline. In all modes, the work itself follows the same `peaks-rd` and `peaks-qa` contracts. **Never bypass the role contracts regardless of which path runs.**
-
-**Violations (BLOCKING — Solo must refuse to proceed):**
-
-1. Writing implementation code directly instead of routing through the RD contract
-2. Declaring work "done" without producing QA evidence after RD
-3. Skipping unit tests ("it's a small change")
-4. Skipping code review or security review
-5. Skipping QA functional/performance/security validation
-
-**If you catch yourself about to write code in this skill, STOP. Hand off to the RD contract path immediately** (sub-agent Task in full-auto, inline execution in assisted/strict).
-
-**Before declaring workflow complete, run:** `peaks workflow verify-pipeline --rid <rid> --project <repo> --json`
+**Peaks-Loop Solo is an orchestrator, NOT an implementer. You MUST NOT write, edit, or modify any application source code directly.** Every code change goes through `peaks-solo → RD → QA → verdict`. `full-auto`/`swarm` use `peaks sub-agent dispatch <role>`; `assisted`/`strict`/inline-fallback executes inline. Both follow `peaks-rd` + `peaks-qa` contracts. **If you catch yourself about to write code, STOP.** Hand off to RD. Before declaring workflow complete, run `peaks workflow verify-pipeline --rid <rid> --project <repo> --json`.
 
 ## Peaks-Loop Startup sequence (MANDATORY — execute in order)
 
 ### Peaks-Loop Slice 011 — workspace consolidate + session checkpoint/resume
 
-`peaks workspace consolidate` is the slice-011 umbrella primitive. `peaks session checkpoint` (proactive context-overflow defense) and `peaks session resume` (cross-session continuity) are surfaced in SKILL.md as Step 0.75 and Step N headings (slice 2.5.0, sub-fix A). See `references/cross-date-session-check.md` for the umbrella. IDE-agnostic.
+`peaks workspace consolidate` is the slice-011 umbrella primitive. `peaks session checkpoint` (context-overflow defense) and `peaks session resume` surface as Step 0.75 + Step N. See `references/cross-date-session-check.md`.
 
 ### Peaks-Loop Step 0.75: Resume from checkpoint (BLOCKING on same-day re-invocation)
 
-When a NEW conversation opens on a session whose `lastActivity` is from today AND `.peaks/_runtime/<sessionId>/checkpoints/` contains at least one `*.json`, surface the most recent checkpoint. Run `peaks session info --active --json` to resolve the canonical session id, then `peaks session resume --from <path> --project <repo>` to emit a markdown "resume context" block. Prompt the user via IDE-native `AskUserQuestion` (resume / start fresh), and if "resume", prepend the emitted block to its own prompt. Honors the user choice on "fresh" — the on-disk checkpoint stays untouched. Step 0.75 is a no-op if any precondition fails (no sid, wrong day, no checkpoint). Full probe + decision tree: `references/checkpoint-resume.md`.
+When a NEW conversation opens on a session whose `lastActivity` is from today AND `.peaks/_runtime/<sessionId>/checkpoints/` contains a `*.json`, surface via `peaks session info --active --json` + `peaks session resume --from <path> --project <repo>`. Prompt via `AskUserQuestion` (resume / fresh); if "resume", prepend the block. Honors "fresh" — on-disk checkpoint stays untouched. Step 0.75 is no-op on precondition fail. See `references/checkpoint-resume.md`.
 
 ### Peaks-Loop Step N: Periodic checkpoint (auto-fire, no user action)
 
-Proactive defense vs context overflow. CLI: `peaks session checkpoint [--reason <r>] [--session-id <sessionId>] [--project <p>] [--current-plan <text>] [--open-questions <list>] [--recent-decisions <list>] [--recent-artifact-paths <list>] [--git-status <text>] [--skills-active <list>] [--todo-state <list>] [--json]`. Fire `--reason periodic` every 20 tool calls (G1 hard-coded), `--reason artifact-written` per PRD/RD/QA/TXT write, `--reason context-fill` when full, `--reason user-pause` on save, `--reason user-close` before handoff. 20-call cadence locked here + `references/periodic-checkpoint.md` (otherwise `tests/unit/solo/checkpoint-periodic-frequency.test.ts` fails).
+Proactive context-overflow defense. CLI: `peaks session checkpoint [--reason <r>] [...flags]`. Fire `--reason periodic` every 20 tool calls (G1 hard-coded), `--reason artifact-written` per PRD/RD/QA/TXT write, `--reason context-fill` / `user-pause` / `user-close` as appropriate. 20-call cadence locked; see `references/periodic-checkpoint.md` (otherwise `tests/unit/solo/checkpoint-periodic-frequency.test.ts` fails).
 
 ### Peaks-Loop Step 0.5: OpenSpec first-run opt-in (conditional)
 
@@ -90,21 +55,21 @@ Run when `openspec/` is absent and `.peaks/.peaks-openspec-opt-in.json` is missi
 
 ### Peaks-Loop Step 0.6: Audit + Goal (NEW)
 
-After human expresses need, invoke peaks-audit to summarize + multi-dim audit + propose goal. Display audit + goal to human for one-shot approval. Store approved goal at `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`. **All subsequent autonomous work requires an approved goal.**
-
-> **v2.15.0+ 校准:** 业务 goal 与技术 goal 必须分离,user 不被推到技术决策位。详见 `.peaks/memory/peaks-loop-user-role-and-tech-decision.md`。
+Invoke peaks-audit after need expressed; store approved goal at `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`. **All autonomous work requires approved goal.** (v2.15.0+ business vs tech goal separated; see `.peaks/memory/peaks-loop-user-role-and-tech-decision.md`.)
 
-→ see `references/audit-goal-gate.md` for the full Step 0.6 contract.
+→ see `references/audit-goal-gate.md`.
 
 ### Peaks-Loop Step N+1: Final Review (NEW)
 
-After all autonomous LLM work (RD, QA, security, perf) completes, invoke peaks-final-review to prepare 4-dim evidence. Display evidence to human for judgment. If all 4 dims pass → final delivery. If any fail → loop back with feedback.
+After autonomous work (RD, QA, security, perf), invoke peaks-final-review for 4-dim evidence. All 4 pass → final delivery; else loop back. See `references/final-review-gate.md`.
+
+### Peaks-Loop Step N+2: Main-session context monitor (D6 + slice 2026-07-02)
 
-→ see `references/final-review-gate.md` for the full Step N+1 contract.
+After every 4th tool call, probe via `peaks solo context-now --project <repo> --json`. Thresholds: 50% / **0.85 pre-compact / 0.95 red-line** (v2.13.0).
 
-### Peaks-Loop Step N+2: Main-session context monitor (v2.11.0 D6)
+**≥ 0.85**, LLM MUST fire `peaks solo auto-compact --execute --project <repo>` autonomously (zero-human-intervention). **≥ 0.95** red line: next Bash/Task tool call fires `peaks session auto-compact-hook` (PreToolUse), which in-band spawns `claude --compact` against the **current** runner.
 
-After every 4th tool call (complement to Step N), probe via `peaks context check --prompt-size <bytes> --auto-trigger --json`. Thresholds: 50% soft warn / 75% user red line (return trigger path, do NOT auto-execute — Karpathy §4) / 90% emergency. Use `--in-flight-batch` to defer until batch converges (D6.e). Companion to Step N (soft signal); D6 is the hard signal.
+**Karpathy §4 exception**: compact red line keeps runner alive → zero-intervention wins. LLM does NOT ask user to run `/compact`. Honor `--in-flight-batch` (D6.e).
 
 ### Peaks-Loop Step 0: Anchor the workflow (MANDATORY FIRST ACTIONS — no bail-out)
 
@@ -170,19 +135,15 @@ Peaks-Loop Solo must NOT silently install hooks, create agents, enable MCP serve
 
 ## Peaks-Loop GStack integration
 
-Map gstack stages to Peaks-Loop role artifacts; preserve confirmation gates. Do not delegate orchestration to gstack commands. RD and QA use Playwright MCP for browser E2E.
-
-→ see `references/gstack-integration.md` and `references/browser-workflow.md`.
+Map gstack stages to Peaks-Loop role artifacts; preserve confirmation gates. → `references/gstack-integration.md` + `references/browser-workflow.md`.
 
 ## Peaks-Loop Local intermediate artifact workspace (MANDATORY)
 
-The workspace is created in Step 0 as a mandatory first action. All intermediate artifacts land under `.peaks/_runtime/<sessionId>/`. NEVER write Peaks-Loop intermediate artifacts to the project root directory.
+Step 0 creates the workspace; all intermediate artifacts land under `.peaks/_runtime/<sessionId>/`. NEVER write Peaks-Loop intermediate artifacts to the project root directory.
 
 ## Peaks-Loop Pre-RD project scan checklist (MANDATORY)
 
-Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/_runtime/<sessionId>/rd/project-scan.md`. The project-scan checklist (archetype detection, build-tool / component-library / CSS-framework / state-routing-data tables, legacy signals, artifact template) lives in the references file.
-
-→ see `references/project-scan-checklist.md` for the checklist.
+Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/_runtime/<sessionId>/rd/project-scan.md`. → `references/project-scan-checklist.md`.
 
 ## Peaks-Loop Frontend-only development mode
 
@@ -249,31 +210,59 @@ Five CLI commands harden the workflow against silent skips: `peaks request lint`
 
 After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Use Peaks-Loop TXT for the compact handoff capsule: mode, validated decisions, artifact paths, standards deltas, open questions, next action. **Presence management is delegated to the last downstream skill** — peaks-solo does not call `peaks skill presence:clear` itself.
 
-## Peaks-Loop External references and lifecycle
+## Peaks-Loop Step 11: Memory sediment (BLOCKING on workflow complete)
 
-3rd-party integrations (codegraph, mattpocock/skills, shadcn/ui, MCPs, Context7) follow Discovery → Reference → Side effect through Peaks CLI only. Before naming external skills, run `peaks capabilities` for capability discovery; treat all external skills as reference material only. Peaks-Loop artifacts and ACs remain authoritative; do not execute upstream installers; MCP servers (Playwright / Chrome DevTools / Figma) are user-installed — check the tool list for `mcp__<server>__*` entries.
+> **Hard rule.** Solo MUST NOT declare a workflow complete until Step 11 has produced ≥ 1 file in `.peaks/memory/` (the durable, LLM-authored memory store) OR the user has explicitly approved a no-sediment outcome via AskUserQuestion. This applies to **all modes** including `assisted` and `strict` — `assisted` previously skipped Step 10 because there was no `[CONFIRM]` gate; Step 11 fixes that.
 
-→ see `references/external-references.md` and `references/external-skill-invocation.md`.
+### Substeps (BLOCKING)
 
-## Codegraph orchestration context
+**11a — Gate A (txt/ inventory):**
 
-`peaks codegraph affected` is an optional project-analysis enhancement; treat output as untrusted supporting evidence. Solo must not treat codegraph output as approval for scope, design, or QA verdict. Never mutate agent settings, Claude settings, or hooks from codegraph; do not commit `.codegraph/` artifacts. RD writes `.peaks/_runtime/<sessionId>/rd/codegraph-context.md`; QA / TXT consume the same envelope in the role handoff.
+```bash
+find .peaks/_runtime/<sessionId>/txt/ -type f -name '*.md' | head
+```
 
-→ see `references/codegraph-orchestration.md`.
+If **0 files** → STOP. Dispatch `peaks-txt` first to write `handoff.md`, then return to 11c.
 
-## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
+**11b — Gate B (memory block embed scan, skill-side only):**
 
-Layer 3.5 context-governance push for sub-agent dispatch. Main LLM reducer sees metadata-only view (~200 chars/sub-agent); on-demand `Read` for full content. Threshold table: 50% soft warn, 75% `CONTEXT_NEAR_LIMIT`, 80% hard reject (CLI + hook double-guard). See `references/context-governance.md` for the full protocol.
+```bash
+grep -c 'peaks-memory:start' .peaks/_runtime/<sessionId>/txt/handoff.md || true
+```
 
-## Sub-agent cross-batch signal — G8.4 share / shared-read / await (slice 2026-06-23-audit-3rd)
+If **0 AND this session surfaced a stable project fact** (decision / convention / approved refactor / hard rule), STOP and tell peaks-txt to embed at least one `<!-- peaks-memory:start -->` block first.
+
+**11c — Canonical extract (the only CLI that writes `.peaks/memory/`):**
+
+```bash
+peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json
+```
+
+`--apply` is REQUIRED. Without it the command only previews — no files land in `.peaks/memory/`.
+
+**11d — Gate C (zero-write outcome):** If `extractedCount === 0` after 11c, fire AskUserQuestion:
+
+> "本次 solo 未沉淀任何 `.peaks/memory` 文件。可选: (a) 回去在 handoff.md 嵌入至少 1 个 `peaks-memory:start` block 后重试; (b) 显式接受 no-sediment 并记录为 lesson; (c) 取消完成。"
 
-Three CLI primitives let sibling sub-agents coordinate within a batch without peer-to-peer messaging. LLM-invoked from peaks-rd / peaks-qa / peaks-ui / peaks-txt skills.
+Default option = (a). Solo MUST NOT silently accept (b) without user pick.
 
-- **`peaks sub-agent share --batch <id> --key <role>.<event> --value <json> [--from <role>]`** — write to per-batch channel (≤ 1KB warn, ≥ 64KB reject). Last-write-wins.
-- **`peaks sub-agent shared-read --batch <id> [--since <iso>] [--key <glob>]`** — read sibling entries (glob `*`).
-- **`peaks sub-agent await --batch <id> [--timeout <ms>]`** — block until batch finishes (claude-code 1.2 MVP; other IDEs LLM-side await).
+**Why this step exists:** audit 2026-07-03 confirmed 2 consecutive sessions produced zero `.peaks/memory/` files despite completing RD + QA + handoff artifacts. Root cause: `assisted` mode silently skipped runbook Step 10 (no STOP condition). Step 11 makes the BLOCKING semantics explicit. **Why `peaks memory extract` (not `peaks project memories:extract`):** the artifact-scoped extract is the canonical command next to its capsule; the batch-scoped sibling is for non-handoff flows (out of scope). For Step 11, **always** use `peaks memory extract --apply`.
+
+## Peaks-Loop External references and lifecycle
+
+3rd-party integrations (codegraph, mattpocock/skills, shadcn/ui, MCPs, Context7) follow Discovery → Reference → Side effect through Peaks CLI only. Run `peaks capabilities` for capability discovery; treat external skills as reference material only. MCP servers (Playwright / Chrome DevTools / Figma) are user-installed — check the tool list for `mcp__<server>__*` entries. → `references/external-references.md` + `references/external-skill-invocation.md`.
+
+## Codegraph orchestration context
+
+`peaks codegraph affected` is an optional project-analysis enhancement (untrusted supporting evidence) used during role handoff. Solo must not treat codegraph output as approval for scope, design, or QA verdict. Never mutate agent settings / Claude settings / hooks from codegraph; do not commit `.codegraph/` artifacts. RD writes `.peaks/_runtime/<sessionId>/rd/codegraph-context.md`; QA / TXT consume the same envelope. → `references/codegraph-orchestration.md`.
+
+## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
+
+Main LLM reducer sees metadata-only view (~200 chars/sub-agent); on-demand `Read` for full content. Threshold table: 50% soft warn, 75% `CONTEXT_NEAR_LIMIT`, 80% hard reject (CLI + hook double-guard). → `references/context-governance.md`.
+
+## Sub-agent cross-batch signal — G8.4 share / shared-read / await (slice 2026-06-23-audit-3rd)
 
-Channel file gitignored under `.peaks/_sub_agents/<sessionId>/shared/`.
+Three CLI primitives let sibling sub-agents coordinate within a batch without peer-to-peer messaging: `peaks sub-agent share / shared-read / await` (last-write-wins channel ≤ 1KB warn / ≥ 64KB reject). Channel file gitignored under `.peaks/_sub_agents/<sessionId>/shared/`.
 
 ## References
 

package/skills/peaks-solo/references/completion-handoff.md

@@ -12,7 +12,12 @@ peaks-solo does NOT itself call `peaks skill presence:clear --project <repo>` at
 
 The user can continue with follow-up requirements naturally — no need to re-invoke `/peaks-solo` to do so. The header continues to display whatever skill is active; the user can `/peaks-solo` again to re-anchor.
 
-Before ending, extract durable memories from this session:
-```bash
-peaks project memories:extract --session-id <session-id> --project <repo> --json
-```
+Before ending, extract durable memories from this session.
+
+> **Owned by runbook Step 10 (TXT handoff) + Step 11 (Memory sediment in SKILL.md).** Do not duplicate the CLI invocation here — the canonical command is:
+>
+> ```bash
+> peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json
+> ```
+>
+> `peaks project memories:extract` is a different (batch-scoped, no-artifact) CLI used in non-handoff flows. Step 11 in SKILL.md enforces the artifact-scoped path; follow that.

package/skills/peaks-solo/references/periodic-checkpoint.md

@@ -68,4 +68,14 @@ checkpoint as often as it wants.
 
 ## Checkpoint IDE note
 
-This step is strictly IDE-agnostic. The LLM calls the peaks CLI; no IDE-specific tools or paths are involved.
+This step is strictly IDE-agnostic. The LLM calls the peaks CLI; no IDE-specific tools or paths are involved.
+
+## Companion surface — auto-compact (zero-pause)
+
+When the runner crosses the v2.13.0 auto-compact thresholds (0.85 pre-compact / 0.95 red-line), `peaks session checkpoint` is NOT enough on its own — the LLM must also fire `peaks solo auto-compact --execute` (or wait for the in-band PreToolUse hook at ratio ≥ 0.95 to compact the runner itself). See:
+
+- `peaks solo auto-compact --execute` — orchestrator that writes the convergence plan + dispatches the compact pathway
+- `peaks session auto-compact-hook` — the PreToolUse hook entrypoint fired by `.claude/settings.local.json` (slice 2026-07-02-auto-compact-zero-pause)
+- `.peaks/memory/2026-06-27-auto-compact-design.md` — zero-human-intervention design rationale
+
+The two surfaces compose: `peaks session checkpoint` persists the context state, `peaks solo auto-compact` collapses the runner's window. The LLM fires both in the 0.85–0.95 zone; the hook fires alone at ≥ 0.95.

package/skills/peaks-solo/references/runbook.md

@@ -154,10 +154,11 @@ peaks openspec validate <cid> --project <repo> --json
 peaks openspec archive <cid> --project <repo> --apply --json
 peaks workspace reconcile --project <repo> --apply --older-than 7
 
-# 10. Peaks-Loop TXT handoff — invoke peaks-txt which embeds memory markers and extracts
+# 10. Peaks-Loop TXT handoff — invoke peaks-txt which embeds memory markers (BLOCKING)
 #     peaks-txt writes the handoff capsule to .peaks/_runtime/<id>/txt/handoff.md. Inside the
 #     capsule body, peaks-txt embeds <!-- peaks-memory:start --> blocks for every
-#     stable project fact surfaced this session.
+#     stable project fact surfaced this session. Applies to ALL modes including
+#     `assisted` (audit 2026-07-03 found `assisted` previously skipped this step).
 #
 # 10a. Skill-side scan (do this BEFORE the AskUserQuestion below):
 #      grep -n "peaks-memory:start" .peaks/_runtime/<id>/txt/handoff.md