peaks-loop 4.0.24 → 4.0.26

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 4.0.26 — 2026-09-01 (headroom removal + prompt-cache prefix alignment)
+
+**2 atomic commits from session 2026-09-01-session-fdd7aa**:
+
+- `3d8c911a` refactor(context): remove headroom-ai half-baked integration
+- `2086074b` perf(dispatch): stabilize sub-agent prompt prefix for prompt-cache alignment
+
+**Highlights**:
+
+1. **移除 headroom-ai 半成品集成** — headroom-ai 的 TS SDK 已接但 Python proxy 后端（N-7）从未集成，`--use-headroom` / `--compress-results` 是静默 no-op。删除依赖 + headroom-client/prefs + G7.7 opt-in 路径 + HeadroomPreferences；保留 G7 metadata-only + auto-compact + prompt-cache 对齐作为省 token 主杠杆。通用 DocFetcher 保留为 doc-cache-fetcher.ts。42 文件，+100/−909。
+
+2. **dispatch 前缀稳定化（prompt-cache 对齐）** — 把 LIFECYCLE_RULES 从 prompt 尾部挪到 L1 worktree 块之后，让所有稳定 boilerplate 连续排在最前，最大化 Anthropic prompt-cache 前缀复用（缓存读价约 90% 折扣）。变量块（context % / project memory / task）留在最后。
+
+## 4.0.25 — 2026-09-01 (codegraph hint fix + post-slice re-index + frontend ACL)
+
+**1 atomic commit from session 2026-09-01-session-fdd7aa** (user feedback batch):
+
+- `70184e1f` feat(peaks-code): apply feedback batch — codegraph hint fix + post-slice re-index + frontend ACL + headroom sediment
+
+**Highlights**:
+
+1. **codegraph 提示泄漏修复** — `peaks codegraph <subcommand>` 透传上游 stdout/stderr 前，新增 `rewriteBareCodegraphHints` 纯函数，把上游裸 `codegraph <sub>` 提示改写为 `peaks codegraph <sub>`（上游 binary 是嵌套传递依赖、不在 PATH，裸命令提示会误导 LLM 敲 "command not found"）。8 个 vitest 用例：quoted/backtick hint、7 子命令全量、幂等、`@colbymchenry/codegraph` 包名不误伤。
+
+2. **codegraph post-slice 增量刷新** — peaks-code 编排规范：每个 slice/task 完成后主动 `peaks codegraph index`，让下一 slice 的 affected/query/context 基于最新代码图，而不是过期的 pre-slice 图。
+
+3. **前端防腐层 ACL 标准** — peaks-rd 新增硬约束：前端内部模型不被外部/API 形状污染；DTO ↔ ViewModel 映射（外部字段 → 内部字段）；Mapper 聚合单文件（如 `mappers/user.mapper.ts`），不散落各页面。QA / code-review 校验。
+
+4. **headroom-ai 半成品 finding sediment** — 记录 headroom proxy 后端（N-7）未接、当前 0 token 节省；省 token 主杠杆是 G7 metadata-only + auto-compact + cache 对齐。
+
 ## 4.0.24 — 2026-08-12 (zod v4 + Context7 + Step 2.5 best-practice scan)
 
 **6 atomic commits from session 2026-08-12-session-4aaf2b** (5 functional + 1 sediment):

package/dist/cli/commands/codegraph-commands.d.ts

@@ -1,3 +1,13 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * Rewrites bare upstream `codegraph <subcommand>` hints to the peaks-loop
+ * equivalent (`peaks codegraph <subcommand>`). The upstream binary is a
+ * nested transitive dependency and is NOT on PATH, so an LLM that follows
+ * a bare hint like `Run "codegraph init" to initialize` would hit
+ * "command not found". Already-prefixed `peaks codegraph ...` hints and
+ * other `codegraph` references (e.g. `@colbymchenry/codegraph`) are left
+ * untouched.
+ */
+export declare function rewriteBareCodegraphHints(text: string): string;
 export declare function registerCodegraphCommands(program: Command, io: ProgramIO): void;

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

@@ -24,6 +24,18 @@ function printCodegraphFailure(io, command, error, asJson, exitCode = 1) {
     printResult(io, fail(command, 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(getErrorMessage(error)), {}, ['Check the codegraph command options and project path before retrying']), asJson);
     process.exitCode = exitCode;
 }
+/**
+ * Rewrites bare upstream `codegraph <subcommand>` hints to the peaks-loop
+ * equivalent (`peaks codegraph <subcommand>`). The upstream binary is a
+ * nested transitive dependency and is NOT on PATH, so an LLM that follows
+ * a bare hint like `Run "codegraph init" to initialize` would hit
+ * "command not found". Already-prefixed `peaks codegraph ...` hints and
+ * other `codegraph` references (e.g. `@colbymchenry/codegraph`) are left
+ * untouched.
+ */
+export function rewriteBareCodegraphHints(text) {
+    return text.replace(/(?<![\w-])(?<!peaks\s)codegraph(?=\s+(?:status|init|index|query|files|context|affected)\b)/g, 'peaks codegraph');
+}
 async function runCodegraphCommand(io, command, options, asJson) {
     try {
         const invocation = createCodegraphInvocation(options);
@@ -33,11 +45,13 @@ async function runCodegraphCommand(io, command, options, asJson) {
             return;
         }
         const didFail = result.exitCode !== null && result.exitCode !== 0;
-        if (result.stdout.length > 0) {
-            io.stdout((didFail ? redactSensitiveErrorMessage(result.stdout) : result.stdout).trimEnd());
+        const stdout = rewriteBareCodegraphHints(result.stdout);
+        const stderr = rewriteBareCodegraphHints(result.stderr);
+        if (stdout.length > 0) {
+            io.stdout((didFail ? redactSensitiveErrorMessage(stdout) : stdout).trimEnd());
         }
-        if (result.stderr.length > 0) {
-            io.stderr((didFail ? redactSensitiveErrorMessage(result.stderr) : result.stderr).trimEnd());
+        if (stderr.length > 0) {
+            io.stderr((didFail ? redactSensitiveErrorMessage(stderr) : stderr).trimEnd());
         }
         if (didFail) {
             process.exitCode = result.exitCode;

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

@@ -74,10 +74,9 @@ export function registerMemoryCommand(program, io) {
     });
     addJsonOption(memory
         .command('search <query>')
-        .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6. Pass --compress-results to also emit a headroom-compressed text view of the matches for LLM-side prompt assembly.')
+        .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6.')
         .option('--kind <kind>', 'filter by memory kind (one of: project, rule, decision, reference, feedback, convention, module, lesson)')
         .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
-        .option('--compress-results', 'compress joined match text via headroom-ai (uses preferences.headroom.perTouchpoint.memorySearch mode)')
         .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
         // Lazy import avoids a top-of-file import cycle (memory-commands.ts
         // imports services that the rest of this file may also touch).
@@ -86,7 +85,6 @@ export function registerMemoryCommand(program, io) {
                 query,
                 ...(options.kind !== undefined ? { kind: options.kind } : {}),
                 ...(options.limit !== undefined ? { limit: options.limit } : {}),
-                ...(options.compressResults === true ? { compressResults: true } : {}),
                 ...(options.project !== undefined ? { project: options.project } : {}),
                 ...(options.json !== undefined ? { json: options.json } : {}),
             });

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

@@ -29,13 +29,11 @@ import { evaluatePromptSize } from '../../services/context/context-guard.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { buildArtifactMeta, buildContextImpact } from '../../services/context/artifact-meta.js';
 import { assertSafeArtifactPath } from 'peaks-loop-shared-channel';
-import { compressPrompt } from '../../services/context/headroom-client.js';
-import { resolveHeadroomOptions } from '../../services/context/headroom-prefs.js';
 import { playwrightProfilePaths } from '../../services/worktree/playwright-profile.js';
 import { loadPreferences } from '../../services/preferences/preferences-service.js';
 import { DEFAULT_PREFERENCES } from '../../services/preferences/preferences-types.js';
 import { writeLogEntry } from '../../services/log/logger.js';
-import { HEADROOM_MODES, PROMPT_LIMIT_BYTES, RECOMMENDED_ROLES, validateRole } from './sub-agent-shared.js';
+import { PROMPT_LIMIT_BYTES, RECOMMENDED_ROLES, validateRole } from './sub-agent-shared.js';
 import { runDispatchFromDag } from './dispatch-from-dag.js';
 import { TEST_TOOL_DETECTION_BLOCK, formatTestToolDetection } from '../../services/dispatch/test-tool-detection.js';
 import { MemoryPreflightService } from '../../services/context/memory-preflight-service.js';
@@ -46,7 +44,7 @@ export function registerDispatchCommand(parent, io) {
         .command('dispatch')
         .description('Build an IDE-specific tool-call descriptor for a sub-agent dispatch. ' +
         'Dry-run by design; the LLM executes the returned toolCall in its own ' +
-        'environment. Flags: --write-artifact (G7), --use-headroom (G7.7), ' +
+        'environment. Flags: --write-artifact (G7), ' +
         '--force (G9 CLI 兜底). ' +
         'See skills/peaks-code/references/sub-agent-dispatch.md for the ' +
         'orchestrator contract.')
@@ -63,8 +61,6 @@ export function registerDispatchCommand(parent, io) {
         .option('--project <path>', 'target project root (defaults to cwd)')
         .option('--batch-id <uuid>', 'batch id for the dispatch (default: auto-generated UUID)')
         .option('--write-artifact <path>', 'G7: register an artifact file at <path>; CLI computes sha256 + size + writes ArtifactMeta to the dispatch record')
-        .option('--use-headroom', 'G7.7/G9: compress the prompt via headroom-ai before dispatch (opt-in; falls back to G7 metadata-only if headroom unavailable)')
-        .option('--headroom-mode <mode>', `G7.7: headroom mode (${HEADROOM_MODES.join(' | ')}); default balanced`)
         .option('--force', 'G9: override the 80% hard reject threshold at CLI (NOT allowed at hook layer per RL-30 strict)')
         .option('--from-dag <file>', '2.7.0 slice-dag-dispatcher MVP: read a SliceDag JSON file, dispatch one sub-agent per node in topological order; --batch-id overrides the auto-generated batch id (mutually exclusive with <role>)')
         .option('--isolation <mode>', 'slice 2026-07-29-worktree-l2-extended Part 2.C: isolation mode for the sub-agent. Accepts "worktree" (Part 2.C + Part 12 L2 surface), "container" (Part 8 contract + Part 12 L4 docker runtime), or "vm" (Part 25 contract; the VM runtime is a follow-up rid and fail-fasts with ISOLATION_VM_NOT_YET_IMPLEMENTED). Auto-spawns a lease + injects PEAKS_<MODE>_LEASE_ID into the dispatch envelope so the sub-agent can write to the isolated surface without a separate auth grant.')
@@ -351,35 +347,14 @@ export function registerDispatchCommand(parent, io) {
                     return;
                 }
             }
-            // G7.7 / G9: resolve headroom options from preferences + CLI overrides.
-            // Preferences hard-block when headroom.enabled=false (returns HEADROOM_DISABLED_BY_PREFERENCE).
-            // loadPreferences can throw on schema mismatch; we fall back to defaults to avoid
-            // breaking the dispatch on a stale preferences.json file.
+            // loadPreferences can throw on schema mismatch; we fall back to defaults
+            // to avoid breaking the dispatch on a stale preferences.json file.
             let projectPrefs = DEFAULT_PREFERENCES;
-            let headroomPrefs = DEFAULT_PREFERENCES.headroom;
             try {
                 projectPrefs = loadPreferences(projectRoot);
-                headroomPrefs = projectPrefs.headroom;
             }
             catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                // Keep default preferences; the user can re-run with explicit --headroom-mode
-                // if they want to override the fallback.
-            }
-            const headroomResolved = resolveHeadroomOptions(headroomPrefs, {
-                useHeadroom: options.useHeadroom === true,
-                ...(options.headroomMode !== undefined ? { headroomMode: options.headroomMode } : {})
-            });
-            if (headroomResolved.blocked !== null) {
-                printResult(io, fail('sub-agent.dispatch', headroomResolved.blocked, `headroom integration is disabled in preferences (headroom.enabled=false); pass --headroom-mode and update preferences first, or run without --use-headroom`, {
-                    role,
-                    toolCall: null,
-                    dispatchRecordPath: null
-                }, [
-                    'Edit .peaks/preferences.json: set headroom.enabled = true (per-touchpoint mode is headroom.perTouchpoint.subAgentDispatch).',
-                    'Or re-run without --use-headroom to dispatch without compression.'
-                ]), asJson);
-                process.exitCode = 1;
-                return;
+                // Keep default preferences.
             }
             const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
             const adapter = getAdapter(ide);
@@ -390,12 +365,9 @@ export function registerDispatchCommand(parent, io) {
                 process.exitCode = 1;
                 return;
             }
-            // G7.7 headroom compress (opt-in). If headroom fails or is unavailable,
-            // fall back to the original prompt + emit warning.
             // Slice 2026-07-22-orchestrator-memory-preflight (Task 5): prepend the
             // memory preflight block (or silently skip when unavailable) via the
-            // pure-function builder, BEFORE the headroom-ai compress step so the
-            // compressor sees the augmented payload.
+            // pure-function builder.
             const preflightService = new MemoryPreflightService(projectRoot, projectPrefs);
             const memoryBlock = await preflightService.fetchBlock(role);
             // Slice 2026-07-29-context-evaluation-accuracy: capture the
@@ -428,9 +400,8 @@ export function registerDispatchCommand(parent, io) {
                 contextProbe
             });
             // Part 2.C: when --isolation worktree, prepend an isolation envelope
-            // block so the sub-agent sees the lease id + worktree path BEFORE
-            // headroom-ai compress. The block is short (a few lines) and the
-            // compressor is expected to keep it. We deliberately do NOT set
+            // block so the sub-agent sees the lease id + worktree path. The block
+            // is short (a few lines). We deliberately do NOT set
             // process.env.PEAKS_WORKTREE_LEASE_ID here — sub-agents are spawned
             // by the LLM in its own environment, not as children of this CLI;
             // the lease id travels through the dispatch record + prompt body.
@@ -465,20 +436,8 @@ export function registerDispatchCommand(parent, io) {
                     `confirm the file exists. Anti-fake-green rule (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure §Lesson 1): ` +
                     `if the file does not exist, your verdict MUST be \`status: "blocked"\` with reason "must_ls_files_failed". Do NOT silently skip this step.\n`;
             }
-            let effectivePrompt = `${formatTestToolDetection()}\n\n${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`;
-            let headroomCompressed = false;
-            let headroomResult = null;
+            const effectivePrompt = `${formatTestToolDetection()}\n\n${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`;
             const warnings = [...decision.warnings];
-            if (headroomResolved.mode !== null) {
-                headroomResult = await compressPrompt(effectivePrompt, headroomResolved.mode);
-                if (headroomResult.warning !== null) {
-                    warnings.push(headroomResult.warning);
-                }
-                if (headroomResult.compressed && headroomResult.compressedPrompt !== null) {
-                    effectivePrompt = headroomResult.compressedPrompt;
-                    headroomCompressed = true;
-                }
-            }
             let toolCall;
             try {
                 toolCall = adapter.subAgentDispatcher.buildToolCall({ role, prompt: effectivePrompt, requestId: rid, sessionId: sid });
@@ -554,8 +513,7 @@ export function registerDispatchCommand(parent, io) {
                     detail: {
                         requestId: rid,
                         ide: adapter.subAgentDispatcher.label,
-                        promptBytes: effectivePrompt.length,
-                        headroomCompressed
+                        promptBytes: effectivePrompt.length
                     }
                 }, { projectRoot });
             }
@@ -628,9 +586,6 @@ export function registerDispatchCommand(parent, io) {
             if (counter.warning) {
                 nextActions.push(`Batch is over the RL-1 limit (${BATCH_LIMIT}); consider splitting into multiple batches.`);
             }
-            if (headroomResult && headroomResult.warning === 'HEADROOM_UNAVAILABLE') {
-                nextActions.push('Headroom daemon unavailable; dispatched with G7 metadata-only fallback.');
-            }
             const expectedCompletionSeconds = 45;
             const artifactsPublicPaths = typeof options.writeArtifact === 'string' && options.writeArtifact.length > 0
                 ? [options.writeArtifact]
@@ -650,7 +605,7 @@ export function registerDispatchCommand(parent, io) {
                 // disk (gitignored under .peaks/_sub_agents/) keeps the prompt
                 // for the sub-agent to read; CLI stdout stays metadata-only.
                 // Surface promptSize + originalPromptSize so the LLM-side
-                // runner can still reason about headroom without seeing the
+                // runner can reason about the size delta without seeing the
                 // content.
                 originalPromptSize: options.prompt.length,
                 promptSize: effectivePrompt.length,
@@ -658,16 +613,6 @@ export function registerDispatchCommand(parent, io) {
                 dispatchRecordPath,
                 batchId,
                 dispatchedInBatch: counter.count,
-                headroomCompressed,
-                headroomResult: headroomResult
-                    ? {
-                        mode: headroomResult.mode,
-                        compressed: headroomResult.compressed,
-                        compressionRatio: headroomResult.compressionRatio,
-                        tokensSaved: headroomResult.tokensSaved,
-                        warning: headroomResult.warning
-                    }
-                    : null,
                 forcedAt: decision.forcedAt,
                 contextImpact,
                 artifactMetas: artifactMeta ? [artifactMeta] : [],
@@ -706,7 +651,6 @@ export function registerDispatchCommand(parent, io) {
                         role,
                         batchId,
                         dispatchedInBatch: counter.count,
-                        headroomCompressed,
                         forcedAt: decision.forcedAt
                     }
                 });

package/dist/cli/commands/memory-commands.d.ts

@@ -5,8 +5,6 @@ export interface MemorySearchCommandOptions {
     limit?: number;
     project?: string;
     json?: boolean;
-    /** When true, call headroom-ai to compress joined match text for LLM-side prompt assembly. */
-    compressResults?: boolean;
 }
 export interface MemoryListCommandOptions {
     kind?: string;

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

@@ -1,6 +1,6 @@
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
-import { loadMemoryIndex, searchMemoryWithResults } from '../../services/memory/memory-search-service.js';
+import { loadMemoryIndex, searchMemory } from '../../services/memory/memory-search-service.js';
 import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult } from '../cli-helpers.js';
@@ -97,19 +97,16 @@ export async function runMemorySearch(io, options) {
         ? options.kind
         : undefined;
     try {
-        const out = await searchMemoryWithResults({
+        const matches = searchMemory({
             query: options.query,
             projectRoot,
             ...(options.limit !== undefined ? { limit: options.limit } : {}),
             ...(kindFilter !== undefined ? { kind: kindFilter } : {}),
-        }, {
-            ...(options.compressResults === true ? { compressResults: true } : {})
         });
         printResult(io, ok('memory.search', {
             query: options.query,
-            total: out.matches.length,
-            matches: out.matches,
-            ...(out.compressedResults !== null ? { compressedResults: out.compressedResults } : {}),
+            total: matches.length,
+            matches,
             warnings: [],
         }, []), options.json);
     }

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

@@ -8,7 +8,6 @@ const ALLOWED_KEYS = new Set([
     'agentShieldPrompt',
     'classifyConservatism',
     'classifyRules',
-    'headroom',
     'swarmSpeculative',
     'loopAutonomousEnabled',
 ]);

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

@@ -36,13 +36,13 @@ import { BROWSER_REUSE_HINT } from '../../services/qa/browser-reuse-hint.js';
 // Plan 1 / Task 9 — auto-build peaks-context before peaks-qa runs.
 import { buildContext } from '../../services/context/context-builder.js';
 // Plan 1 / Task 10 — production fetcher (replaces mockFetcher).
-import { createHeadroomFetcher } from '../../services/context/headroom-fetcher.js';
+import { createDocCacheFetcher } from '../../services/context/doc-cache-fetcher.js';
 // Plan 2 / Task 8 — consume MUT.sig from peaks-mut into verdict envelope.
 import { loadMutReport, mutReportPath } from 'peaks-loop-mut';
-function buildHeadroomFetcher(sid) {
-    return createHeadroomFetcher({
+function buildDocFetcher(sid) {
+    return createDocCacheFetcher({
         cacheDir: `.peaks/_runtime/${sid}/doc-cache`,
-        // remoteFetcher wired in a future slice (headroom-ai programmatic API).
+        // remoteFetcher wired in a future slice.
     });
 }
 async function ensureContextForQa(goal, project, sid) {
@@ -55,7 +55,7 @@ async function ensureContextForQa(goal, project, sid) {
             depsMode: 'locked',
             docBudgetTokens: 8000,
             out,
-            fetcher: buildHeadroomFetcher(sid),
+            fetcher: buildDocFetcher(sid),
         });
     }
     catch (error) {

package/dist/cli/commands/sub-agent-shared.d.ts

@@ -12,12 +12,10 @@
  * Everything else is internal to the `peaks sub-agent` group.
  */
 import type { SubAgentBatchResult } from '../../services/dispatch/sub-agent-dispatcher.js';
-import type { HeadroomMode } from '../../services/context/headroom-client.js';
 import type { HeartbeatStatus } from '../../services/dispatch/dispatch-record-writer.js';
 export { probeShell, type ShellProbeReport, type ShellProbeOptions } from '../../services/env/shell-probe.js';
 export declare const RECOMMENDED_ROLES = "rd | qa | ui | txt | qa-business | qa-perf | qa-security | qa-business-<*> | general-purpose";
 export declare const HEARTBEAT_STATUSES: readonly HeartbeatStatus[];
-export declare const HEADROOM_MODES: readonly HeadroomMode[];
 export declare const PROMPT_LIMIT_BYTES: number;
 export type DispatchOptions = {
     prompt?: string;
@@ -27,8 +25,6 @@ export type DispatchOptions = {
     project?: string;
     batchId?: string;
     writeArtifact?: string;
-    useHeadroom?: boolean;
-    headroomMode?: string;
     force?: boolean;
     fromDag?: string;
     /**

package/dist/cli/commands/sub-agent-shared.js

@@ -25,7 +25,6 @@ export const HEARTBEAT_STATUSES = [
     'never-started',
     'unreadable'
 ];
-export const HEADROOM_MODES = ['balanced', 'aggressive', 'conservative'];
 export const PROMPT_LIMIT_BYTES = 256 * 1024;
 /**
  * Validate a role string. Returns `null` when valid, otherwise the
@@ -75,16 +74,3 @@ export function summarizeBatchResults(results) {
     }
     return { total: results.length, done, failed, cancelled, timeout };
 }
-// Note: `isHeadroomMode` and `RegisterSubCommand` used to live here as
-// duplicate exports. Removed in slice 2026-06-23-audit-p0-cleanup:
-//   - `isHeadroomMode` is exported by `src/services/context/headroom-prefs.ts`
-//     and that is the canonical source — dispatch consumer imports from
-//     there directly.
-//   - `RegisterSubCommand` was never used as a type anywhere; the entry
-//     point (`sub-agent-commands.ts`) calls each register function with
-//     `(program, io)` directly.
-//   - `deriveProjectRoot` (audit-p0-reaudit) was removed in slice
-//     2026-06-23-audit-3rd: it trusted the record path's `.peaks` segment,
-//     letting a caller point `--record` at any project's record tree. The
-//     heartbeat command now trusts `--project` (or `process.cwd()`) and
-//     leaves the relative() backstop to the R-2 guard.

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

@@ -36,11 +36,11 @@ import { registerWorkflowLifecycleCommand } from './workflow-lifecycle-commands.
 // Plan 1 / Task 9 — auto-build peaks-context before peaks-rd runs.
 import { buildContext } from '../../services/context/context-builder.js';
 // Plan 1 / Task 10 — production fetcher (replaces mockFetcher).
-import { createHeadroomFetcher } from '../../services/context/headroom-fetcher.js';
-function buildHeadroomFetcher(sid) {
-    return createHeadroomFetcher({
+import { createDocCacheFetcher } from '../../services/context/doc-cache-fetcher.js';
+function buildDocFetcher(sid) {
+    return createDocCacheFetcher({
         cacheDir: `.peaks/_runtime/${sid}/doc-cache`,
-        // remoteFetcher wired in a future slice (headroom-ai programmatic API).
+        // remoteFetcher wired in a future slice.
     });
 }
 async function ensureContextForRd(goal, project, sid) {
@@ -53,7 +53,7 @@ async function ensureContextForRd(goal, project, sid) {
             depsMode: 'locked',
             docBudgetTokens: 8000,
             out,
-            fetcher: buildHeadroomFetcher(sid),
+            fetcher: buildDocFetcher(sid),
         });
     }
     catch (error) {

package/dist/services/context/build-dispatch-system-prompt.d.ts

@@ -72,10 +72,10 @@ export declare const L1_WORKTREE_GOVERNANCE_BLOCK = "## Superpowers chain refusa
  *      index, race the worktree release, and can corrupt the
  *      caller's working branch.
  *
- * These rules are appended to the system prompt on top of the L1
- * worktree governance block so the sub-agent sees them last (i.e.
- * most-recently-read), which is the strongest prompt position in
- * transformer attention.
+ * These rules are placed immediately after the L1 worktree governance
+ * block so every stable boilerplate block is contiguous at the prompt
+ * start, maximizing Anthropic prompt-cache prefix reuse (stable-first
+ * ordering).
  */
 export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 2026-08-01)\n\n- If you start a long-lived local service (vite dev, mock API, docker container, etc.), register it with `peaks sub-agent shutdown register --pid <pid> --name <label>` before you exit. The parent session will best-effort-kill it before merge-back.\n- Do NOT run E2E. The parent session runs Playwright verification once after merge-back (Task 10). Your E2E work is duplicate effort.\n- Do NOT call `git merge`, `git pull`, `git rebase`, or `peaks worktree release`. The parent session owns the merge-back step.\n";
 /**

package/dist/services/context/build-dispatch-system-prompt.js

@@ -62,10 +62,10 @@ If the upstream superpowers chain suggests raw \`git worktree add\`:
  *      index, race the worktree release, and can corrupt the
  *      caller's working branch.
  *
- * These rules are appended to the system prompt on top of the L1
- * worktree governance block so the sub-agent sees them last (i.e.
- * most-recently-read), which is the strongest prompt position in
- * transformer attention.
+ * These rules are placed immediately after the L1 worktree governance
+ * block so every stable boilerplate block is contiguous at the prompt
+ * start, maximizing Anthropic prompt-cache prefix reuse (stable-first
+ * ordering).
  */
 export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
 
@@ -97,9 +97,9 @@ export function buildDispatchSystemPrompt(input) {
     const { taskBody, memoryBlock, contextProbe } = input;
     const contextBlock = renderContextBlock(contextProbe ?? null);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${contextBlock}${memoryBlock.block}\n## Task\n${taskBody}\n${LIFECYCLE_RULES}`;
+        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${memoryBlock.block}\n## Task\n${taskBody}`;
     }
-    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${contextBlock}${taskBody}\n${LIFECYCLE_RULES}`;
+    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${taskBody}`;
 }
 /**
  * Slice 2026-07-29-context-evaluation-accuracy: emit a

package/dist/services/context/context-guard.d.ts

@@ -8,13 +8,11 @@
  *
  * Decision codes:
  *   - `OK`                          — under 50%
- *   - `CONTEXT_SOFT_WARN`           — 50-75%, suggest --use-headroom
- *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, mandatory --use-headroom suggestion
+ *   - `CONTEXT_SOFT_WARN`           — 50-75%, prompt is large
+ *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, prompt is near the limit
  *   - `PROMPT_TOO_LARGE`            — 80-90%, hard reject (allow = false)
  *   - `PROMPT_EMERGENCY`            — ≥ 90%, hard reject + emergency
  *   - `FORCED_OVER_THRESHOLD`       — user passed --force at CLI; allow = true
- *
- * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`.
  */
 import { tierToCode, type ThresholdEvaluation } from './threshold.js';
 export type ContextGuardCode = 'OK' | 'CONTEXT_SOFT_WARN' | 'CONTEXT_NEAR_LIMIT' | 'PROMPT_TOO_LARGE' | 'PROMPT_EMERGENCY' | 'FORCED_OVER_THRESHOLD';

package/dist/services/context/context-guard.js

@@ -8,17 +8,15 @@
  *
  * Decision codes:
  *   - `OK`                          — under 50%
- *   - `CONTEXT_SOFT_WARN`           — 50-75%, suggest --use-headroom
- *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, mandatory --use-headroom suggestion
+ *   - `CONTEXT_SOFT_WARN`           — 50-75%, prompt is large
+ *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, prompt is near the limit
  *   - `PROMPT_TOO_LARGE`            — 80-90%, hard reject (allow = false)
  *   - `PROMPT_EMERGENCY`            — ≥ 90%, hard reject + emergency
  *   - `FORCED_OVER_THRESHOLD`       — user passed --force at CLI; allow = true
- *
- * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`.
  */
 import { CONTEXT_CAPACITY_DEFAULT_BYTES, evaluateThresholdTier, tierToCode } from './threshold.js';
-const NEAR_LIMIT_SUGGEST = 'Consider --use-headroom to compress prompt.';
-const SOFT_WARN_SUGGEST = 'Use --use-headroom to compress prompt proactively.';
+const NEAR_LIMIT_SUGGEST = 'Prompt is near the context limit; trim the prompt or split into multiple dispatches.';
+const SOFT_WARN_SUGGEST = 'Prompt is large; trim or split into multiple dispatches to stay within context budget.';
 const HARD_REJECT_SUGGEST = 'Trim prompt to < 80% of context capacity. Pass --force at CLI to override (NOT allowed at hook layer).';
 const EMERGENCY_SUGGEST = 'Prompt exceeds 90% of context. Trim aggressively or split into multiple dispatches.';
 /**

package/dist/services/context/{headroom-fetcher.d.ts → doc-cache-fetcher.d.ts}

@@ -1,6 +1,6 @@
 import type { DocFetcher } from './doc-retriever.js';
-export interface HeadroomFetcherOptions {
+export interface DocCacheFetcherOptions {
     readonly cacheDir: string;
     readonly remoteFetcher?: DocFetcher;
 }
-export declare function createHeadroomFetcher(opts: HeadroomFetcherOptions): DocFetcher;
+export declare function createDocCacheFetcher(opts: DocCacheFetcherOptions): DocFetcher;

package/dist/services/context/{headroom-fetcher.js → doc-cache-fetcher.js}

@@ -1,6 +1,7 @@
 /**
- * Production DocFetcher. Uses existing headroom-ai dependency for remote
- * fetch; local cache (per-session, per-dep markdown) preferred when version matches.
+ * Production DocFetcher. Local cache (per-session, per-dep markdown)
+ * preferred when version matches; otherwise delegates to an injected
+ * remote fetcher.
  *
  * Hard constraint H2 (locked version): never returns a doc whose version
  * differs from the requested locked version.
@@ -12,7 +13,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-export function createHeadroomFetcher(opts) {
+export function createDocCacheFetcher(opts) {
     return async (dep, version) => {
         const cachePath = join(opts.cacheDir, `${dep}@${version}.md`);
         try {

package/dist/services/context/memory-preflight-service.js

@@ -8,7 +8,7 @@
  *   - MemoryIndexReader (Task 3)            — reads .peaks/memory/index.json + layer=A filter
  *   - MemoryLruCache (Task 2)               — constructed for capacity parity, but NOT used
  *                                            for memo content (see deviation note below)
- *   - compressPrompt (existing)             — headroom-ai wrapper for hard-cap compression
+ *   - truncateToCap                         — byte-cap truncation of the composed block
  *
  * Deviation from brief — controller-accepted (pre-task 4):
  *   The brief mandated use of `MemoryLruCache` for memo content caching. The
@@ -20,25 +20,14 @@
  *   `MemoryLruCache` class remains as a separate, reusable LRU primitive
  *   (Task 2) and is not consumed by this service.
  */
-import { compressPrompt } from './headroom-client.js';
 import { MemoryIndexReader } from './memory-index-reader.js';
 import { resolveMemoryPreflightConfig, } from './memory-preflight-config.js';
-async function compressToCap(text, capBytes, mode) {
-    try {
-        const result = await compressPrompt(text, mode);
-        if (result.warning !== null || result.compressedPrompt === null) {
-            return { text, truncated: false };
-        }
-        const compressed = result.compressedPrompt;
-        if (Buffer.byteLength(compressed, 'utf8') > capBytes) {
-            const sliced = compressed.slice(0, Math.max(0, capBytes - 64)) + '\n…[truncated]';
-            return { text: sliced, truncated: true };
-        }
-        return { text: compressed, truncated: false };
-    }
-    catch {
+function truncateToCap(text, capBytes) {
+    if (Buffer.byteLength(text, 'utf8') <= capBytes) {
         return { text, truncated: false };
     }
+    const sliced = text.slice(0, Math.max(0, capBytes - 64)) + '\n…[truncated]';
+    return { text: sliced, truncated: true };
 }
 export class MemoryPreflightService {
     reader;
@@ -85,7 +74,7 @@ export class MemoryPreflightService {
         const header = '## Project memory relevant to this task\n';
         const composed = `${header}${listLines}${tail}`;
         const capBytes = Math.max(64, this.config.maxTokens * 4);
-        const { text, truncated } = await compressToCap(composed, capBytes, 'balanced');
+        const { text, truncated } = truncateToCap(composed, capBytes);
         const droppedCount = truncated ? selected.length - countItemsInBlock(text) : 0;
         return {
             available: true,

package/dist/services/context/threshold.d.ts

@@ -4,9 +4,6 @@
  * 256K default context capacity is a conservative proxy. The LLM's real
  * capacity is its private business (R-1 / R-8 / R-10 / R-13 boundary
  * inherited from slice #009); we use prompt size as the gate signal.
- *
- * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`
- * for the full G9 rule (RL-27..RL-32, AC-50..AC-65).
  */
 export declare const CONTEXT_CAPACITY_DEFAULT_BYTES: number;
 export declare const THRESHOLD_SOFT_WARN_RATIO = 0.5;

package/dist/services/context/threshold.js

@@ -4,9 +4,6 @@
  * 256K default context capacity is a conservative proxy. The LLM's real
  * capacity is its private business (R-1 / R-8 / R-10 / R-13 boundary
  * inherited from slice #009); we use prompt size as the gate signal.
- *
- * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`
- * for the full G9 rule (RL-27..RL-32, AC-50..AC-65).
  */
 export const CONTEXT_CAPACITY_DEFAULT_BYTES = 256 * 1024; // 256K
 export const THRESHOLD_SOFT_WARN_RATIO = 0.5; // 50%

package/dist/services/dispatch/batch-counter.js

@@ -5,7 +5,7 @@
  * Above 6, the LLM / human is encouraged to split into multiple
  * batches with an explicit reducer step in between. peaks-code's
  * swarm phase dispatches 3; peaks-rd's 4-way fan-out dispatches 4;
- * peaks-qa's 3-way fan-out dispatches 3. The 6 limit leaves headroom
+ * peaks-qa's 3-way fan-out dispatches 3. The 6 limit leaves margin
  * for "qa-business-api" / "qa-business-frontend" / "qa-business-regression"
  * subdivisions (3-way + 3-way = 6) without crossing the line.
  *