peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,164 @@
+/**
+ * AC-1 — auto context-percent probe.
+ *
+ * Reads the current AI CLI context-fill ratio without requiring the
+ * LLM to pass `--prompt-size <bytes>` manually. Strategy: ask the
+ * registered `IdeAdapter.compact` profile which env-var to read;
+ * no hard-coded IDE names. Per-adapter:
+ *
+ *   - claude-code: `CLAUDE_CONTEXT_USAGE_PERCENT` (MVP)
+ *   - trae / codex / cursor / qoder / tongyi-lingma / hermes /
+ *     openclaw: each adapter fills its own env-var; until L2-dogfood
+ *     verifies each surface, adapters may omit `compact` and the
+ *     probe returns `source: 'conservative-fallback'`.
+ *
+ * Fallback chain (when adapter.compact is undefined OR the env-var
+ * is missing):
+ *   1. statusline poll (`~/.claude/statusline-state.json` for
+ *      Claude Code MVP; other IDEs register their own poll path
+ *      by exposing `compact.postCompactDetectCommand`).
+ *   2. Conservative transcript-size estimate
+ *      (`~/.claude/projects/<hash>/<sid>.jsonl` for Claude Code).
+ *   3. `ratio: 0` with `source: 'conservative-fallback'` — the
+ *      orchestrator MUST NOT auto-fire compact on this signal.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { detectIdeFromEnv } from './ide-detect.js';
+import { getAdapter } from '../ide/ide-registry.js';
+/**
+ * Read env-var-based context percentage. Returns `null` when the env
+ * is absent or unparseable. Adapter-driven: the caller passes the
+ * env-var name from `IdeAdapter.compact.envVarForContextPercent`,
+ * so the function itself has no hard-coded IDE names.
+ */
+function readEnvPercent(env, varName) {
+    const raw = env[varName];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    const parsed = Number.parseFloat(raw);
+    if (!Number.isFinite(parsed))
+        return null;
+    if (parsed < 0 || parsed > 1.5)
+        return null;
+    return Math.max(0, Math.min(1, parsed));
+}
+/**
+ * Read the IDE-specific statusline state. MVP path is Claude Code's
+ * `~/.claude/statusline-state.json`; other IDEs are intentionally
+ * left for future slices (each IDE will expose its own
+ * `compact.postCompactDetectCommand` to drive this).
+ */
+function readClaudeStatuslinePercent() {
+    const path = join(homedir(), '.claude', 'statusline-state.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const json = JSON.parse(readFileSync(path, 'utf8'));
+        const candidates = ['contextPercent', 'context_usage_percent', 'contextPercentUsed'];
+        for (const key of candidates) {
+            const raw = json[key];
+            if (typeof raw === 'number' && Number.isFinite(raw)) {
+                return raw > 1.5 ? raw / 100 : Math.max(0, Math.min(1, raw));
+            }
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    return null;
+}
+/**
+ * Conservative transcript-size fallback. Walks
+ * `~/.claude/projects/<hash>/<sid>.jsonl` and estimates
+ * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
+ * orchestrator can show "estimated from 124KB of 256KB transcript"
+ * in the envelope. Tagged `'conservative-fallback'` so callers
+ * know NOT to treat this as a hard gate.
+ */
+function readClaudeTranscriptFallback(sessionId) {
+    const projectsDir = join(homedir(), '.claude', 'projects');
+    if (!existsSync(projectsDir))
+        return null;
+    try {
+        const { readdirSync } = require('node:fs');
+        for (const hashDir of readdirSync(projectsDir)) {
+            const candidate = join(projectsDir, hashDir, `${sessionId}.jsonl`);
+            if (existsSync(candidate)) {
+                const bytes = statSync(candidate).size;
+                const ratio = Math.min(1, bytes / (256 * 1024));
+                return { ratio, bytes };
+            }
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    return null;
+}
+/**
+ * Probe the current AI CLI's context-fill ratio. Adapter-driven:
+ * looks up the registered `IdeAdapter.compact` profile via
+ * `getIdeAdapter(detectIdeFromEnv(env))` and reads the
+ * adapter-declared env-var. Falls back to statusline poll +
+ * transcript estimate ONLY for adapters that opt in
+ * (`adapter.id === 'claude-code'` for the MVP); other adapters
+ * without an env-var hit return `source: 'conservative-fallback'`
+ * with `ratio: 0` so the orchestrator never auto-fires on a
+ * missing signal.
+ */
+export function readContextPercent(input) {
+    const env = input.env ?? process.env;
+    const capturedAt = new Date().toISOString();
+    const capacityBytes = 256 * 1024;
+    const detected = detectIdeFromEnv(env);
+    // `detectIdeFromEnv` may return `'unknown'` when no IDE-specific
+    // marker is on PATH; narrow to a registered adapter id so the
+    // typed `getAdapter` call accepts it. `'unknown'` falls through to
+    // the conservative-zero probe (no compact dispatch). IdeKind is a
+    // narrow 3-element union (claude-code / trae / opencode); cast
+    // through `unknown` to IdeId's wider 8-element set.
+    const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+    const adapter = getAdapter(ideId);
+    // Primary: read the adapter-declared env-var (no hard-coded IDE names).
+    if (adapter.compact) {
+        const primary = readEnvPercent(env, adapter.compact.envVarForContextPercent);
+        if (primary !== null) {
+            return {
+                ratio: primary,
+                source: `${ideId}-env`,
+                capacityBytes,
+                ide: ideId,
+                capturedAt
+            };
+        }
+    }
+    // MVP-only fallback chain: statusline poll + transcript estimate.
+    // Non-MVP adapters that don't fill `compact` skip this and return
+    // a conservative-zero probe (the orchestrator will stay in
+    // 'none' / 'soft-warn' zone and never auto-fire compact).
+    if (ideId === 'claude-code') {
+        const statusline = readClaudeStatuslinePercent();
+        if (statusline !== null) {
+            return { ratio: statusline, source: 'statusline-poll', capacityBytes, ide: ideId, capturedAt };
+        }
+        const fallback = readClaudeTranscriptFallback(input.sessionId);
+        if (fallback !== null) {
+            return {
+                ratio: fallback.ratio,
+                source: 'conservative-fallback',
+                rawBytes: fallback.bytes,
+                capacityBytes,
+                ide: ideId,
+                capturedAt
+            };
+        }
+    }
+    // No signal available — return `ratio: 0` so the orchestrator
+    // stays in `none` zone and the LLM can still pass `--prompt-size`
+    // explicitly via `peaks context check`.
+    return { ratio: 0, source: 'conservative-fallback', capacityBytes, ide: ideId, capturedAt };
+}
+/** Re-export the env-var probe for unit tests. */
+export const _internal = { readEnvPercent, readClaudeStatuslinePercent, readClaudeTranscriptFallback };

package/dist/services/context/auto-compact-types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Auto-compact shared types (v2.13.0 AC-1..AC-4).
+ *
+ * Two-tier threshold model — peaks-loop is project-aware and the LLM
+ * is the decision-maker:
+ *
+ *   - 50%  soft warn          — log a one-line info row; continue.
+ *   - 85%  pre-compact zone   — peaks-loop prepares the convergence
+ *                                toolkit (checkpoint + convergence
+ *                                plan + auto-decisions log +
+ *                                IDE-compact dispatcher). The LLM
+ *                                DECIDES when (or whether) to fire
+ *                                compact during this zone. The
+ *                                toolkit is "ready to use" so the
+ *                                LLM doesn't lose context to a
+ *                                last-second `/compact` panic.
+ *   - 95%  RED LINE           — peaks-loop refuses to dispatch any
+ *                                further sub-agent and synchronously
+ *                                triggers IDE-side compact. At 95%+
+ *                                the context window is too tight to
+ *                                continue safely; the LLM cannot
+ *                                opt out. This is the compact red
+ *                                line that guarantees the LLM-runner
+ *                                keeps working with context < 95%.
+ *
+ * Why 0.85 / 0.95 split: the LLM uses the 0.85–0.95 zone to do
+ * intelligent convergence — wait for in-flight sub-agents, finish
+ * the current todo row, persist a checkpoint, then compact. peaks-loop
+ * provides the toolkit; the LLM picks the moment. At 0.95 the window
+ * is gone and peaks-loop takes over synchronously to keep the runner
+ * alive.
+ */
+export declare const AUTO_COMPACT_SOFT_WARN_RATIO = 0.5;
+export declare const AUTO_COMPACT_AUTO_FIRE_RATIO = 0.8;
+export declare const AUTO_COMPACT_PRE_COMPACT_RATIO = 0.85;
+export declare const AUTO_COMPACT_RED_LINE_RATIO = 0.95;
+export declare const AUTO_COMPACT_THRESHOLD_RATIO = 0.8;
+/** Single source of truth for "what should we do at ratio X?" */
+export type CompactTrigger = {
+    kind: 'none';
+} | {
+    kind: 'soft-warn';
+    ratio: number;
+    message: string;
+}
+/**
+ * Part 22: auto-fire zone (0.80 ≤ ratio < 0.85). peaks-loop
+ * preempts and runs `peaks compact auto --execute` itself
+ * without LLM involvement. The LLM is not asked to "decide";
+ * the toolkit is applied synchronously.
+ */
+ | {
+    kind: 'auto-fire';
+    ratio: number;
+    message: string;
+}
+/**
+ * Pre-compact zone (0.85 ≤ ratio < 0.95): LLM-runner can still
+ * pre-empt the compact for one in-flight sub-agent or one
+ * todo row, but peaks-loop flags this as the last safe
+ * window. Kept for backward compat; in practice peaks-loop
+ * auto-fired at 0.80 already.
+ */
+ | {
+    kind: 'pre-compact';
+    ratio: number;
+    message: string;
+    toolkitReady: true;
+}
+/** Red line (ratio ≥ 0.95): peaks-loop forces synchronous compact; LLM cannot opt out. */
+ | {
+    kind: 'red-line';
+    ratio: number;
+    message: string;
+};
+/** Caller-side info about sub-agent batches in flight (D6.e). */
+export interface InFlightBatchProbe {
+    readonly hasInFlightBatch: boolean;
+    readonly sharedChannelEntries?: number;
+    readonly batchId?: string;
+}
+/** What the post-compact LLM reads to resume exactly where it stopped. */
+export interface ConvergencePlan {
+    readonly schemaVersion: 1;
+    readonly sessionId: string;
+    readonly projectRoot: string;
+    readonly createdAt: string;
+    readonly ratio: number;
+    readonly checkpointPath: string;
+    readonly nextActions: readonly string[];
+    readonly resumeHint: string;
+}
+/** Per-IDE compact pathway chosen by AC-3. */
+export interface CompactDispatchResult {
+    readonly ok: boolean;
+    readonly ide: string;
+    readonly pathway: 'ide-native' | 'llm-self-compress' | 'shell-exec' | 'noop';
+    readonly message: string;
+}
+/** Final envelope returned by `runAutoCompact`. */
+export type AutoCompactResult = {
+    readonly ok: false;
+    readonly code: 'AUTO_COMPACT_NO_SESSION';
+    readonly message: string;
+    readonly nextActions: readonly string[];
+} | {
+    readonly ok: true;
+    readonly code: 'AUTO_COMPACT_SKIP' | 'AUTO_COMPACT_WAIT';
+    readonly message: string;
+    readonly data: {
+        readonly sessionId: string;
+        readonly ratio: number;
+        readonly source: string;
+        readonly decision: 'below-threshold' | 'in-flight-batch';
+    };
+} | {
+    readonly ok: boolean;
+    readonly code: 'AUTO_COMPACT_DISPATCHED' | 'AUTO_COMPACT_DISPATCH_FAILED' | 'AUTO_COMPACT_RED_LINE';
+    readonly message: string;
+    readonly data: {
+        readonly sessionId: string;
+        readonly ratio: number;
+        readonly source: string;
+        readonly checkpointPath?: string;
+        readonly convergencePlan?: ConvergencePlan;
+        readonly dispatch?: CompactDispatchResult;
+        /**
+         * Slice 2026-06-28-code-mode-bypass-fix (defect #4): which
+         * session the compact targeted. `'main'` (default) means the
+         * main-session Claude Code window will fire `/compact` on its
+         * next turn; `'sub-agent'` means the dispatcher shell-spawned
+         * `/compact` in a child process (legacy behaviour).
+         */
+        readonly target?: 'main' | 'sub-agent';
+        /**
+         * Slice 2026-07-28 (rid-027): which mode's threshold table
+         * was used. Defaults to `'standard'` (0.85/0.95). `'partial'`
+         * (0.70/0.85) is selected when 24h mode is active or the
+         * caller passes `--mode partial`.
+         */
+        readonly mode?: 'standard' | 'partial';
+        readonly redLineGated?: boolean;
+    };
+};
+/**
+ * Probe shape returned by AC-1 (`readContextPercent`). The source
+ * field tells callers how the ratio was obtained (env-var, statusline
+ * poller, IDE hook, conservative fallback) so the CLI can show
+ * "context % (source: statusline-poll)" and the LLM can trust it.
+ */
+export interface ContextPercentProbe {
+    readonly ratio: number;
+    /**
+     * Adapter-driven source tag. Fixed values:
+     *   - `${ideId}-env`            (e.g. `claude-code-env`)
+     *   - `statusline-poll`         (Claude Code MVP fallback)
+     *   - `conservative-fallback`   (transcript size estimate OR
+     *                                no signal available — caller
+     *                                MUST NOT treat as hard gate)
+     * Future IDEs may add per-ide sources; the type accepts any
+     * string to keep the schema forward-compatible.
+     */
+    readonly source: string;
+    readonly rawBytes?: number;
+    readonly capacityBytes?: number;
+    readonly ide: string;
+    readonly capturedAt: string;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Auto-compact shared types (v2.13.0 AC-1..AC-4).
+ *
+ * Two-tier threshold model — peaks-loop is project-aware and the LLM
+ * is the decision-maker:
+ *
+ *   - 50%  soft warn          — log a one-line info row; continue.
+ *   - 85%  pre-compact zone   — peaks-loop prepares the convergence
+ *                                toolkit (checkpoint + convergence
+ *                                plan + auto-decisions log +
+ *                                IDE-compact dispatcher). The LLM
+ *                                DECIDES when (or whether) to fire
+ *                                compact during this zone. The
+ *                                toolkit is "ready to use" so the
+ *                                LLM doesn't lose context to a
+ *                                last-second `/compact` panic.
+ *   - 95%  RED LINE           — peaks-loop refuses to dispatch any
+ *                                further sub-agent and synchronously
+ *                                triggers IDE-side compact. At 95%+
+ *                                the context window is too tight to
+ *                                continue safely; the LLM cannot
+ *                                opt out. This is the compact red
+ *                                line that guarantees the LLM-runner
+ *                                keeps working with context < 95%.
+ *
+ * Why 0.85 / 0.95 split: the LLM uses the 0.85–0.95 zone to do
+ * intelligent convergence — wait for in-flight sub-agents, finish
+ * the current todo row, persist a checkpoint, then compact. peaks-loop
+ * provides the toolkit; the LLM picks the moment. At 0.95 the window
+ * is gone and peaks-loop takes over synchronously to keep the runner
+ * alive.
+ */
+export const AUTO_COMPACT_SOFT_WARN_RATIO = 0.5;
+// Part 22: auto-fire threshold (was 0.85 pre-compact zone where
+// the LLM had to decide; LLM misjudged 0.85–0.95 and only fired
+// at 0.95, which let the LLM time the run anyway). Lowered to
+// 0.80 so peaks-loop auto-fires compact without LLM involvement
+// — the LLM keeps working, peaks-loop preempts when ratio crosses
+// the new threshold.
+export const AUTO_COMPACT_AUTO_FIRE_RATIO = 0.80;
+export const AUTO_COMPACT_PRE_COMPACT_RATIO = 0.85;
+export const AUTO_COMPACT_RED_LINE_RATIO = 0.95;
+export const AUTO_COMPACT_THRESHOLD_RATIO = AUTO_COMPACT_AUTO_FIRE_RATIO;

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

@@ -0,0 +1,75 @@
+/**
+ * buildDispatchSystemPrompt — pure-function prompt composer for sub-agent dispatch.
+ *
+ * Slice 2026-07-22-orchestrator-memory-preflight (Task 5). The orchestrator
+ * dispatch flow (`src/cli/commands/dispatch-commands.ts`) calls
+ * `MemoryPreflightService.fetchBlock` and feeds the result into this builder
+ * so the memory block, when available, is prepended BEFORE the task brief.
+ *
+ * Keeping the builder a pure function (no IO) makes the three acceptance
+ * cases easy to test in isolation:
+ *   1. returns the original prompt (sans memory block) when unavailable
+ *   2. prepends the memory block when available
+ *   3. never pushes the memory block below the task brief
+ */
+import type { MemoryPreflightResult } from './memory-preflight-service.js';
+import type { ContextPercentProbe } from './auto-compact-types.js';
+export interface DispatchPromptInput {
+    taskTitle: string;
+    taskBody: string;
+    memoryBlock: MemoryPreflightResult;
+    /**
+     * Slice 2026-07-29-context-evaluation-accuracy: the live
+     * context-fill probe. When provided, the composer prepends
+     * a `## Context window` block with the authoritative ratio so
+     * the dispatched sub-agent does NOT estimate context from
+     * message length. The ratio comes from the IDE adapter's
+     * `compact` env-var / statusline (token-counted), NOT from
+     * a byte-counted estimate.
+     */
+    contextProbe?: ContextPercentProbe | null;
+}
+/**
+ * Slice 2026-07-29-worktree-l1: Layer 1 of the 3-layer worktree governance
+ * defence. The block below is prepended to every sub-agent dispatch system
+ * prompt so the LLM sees the superpowers-chain refusal BEFORE any task
+ * content. The block mirrors the prose in
+ * `skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md` (and the
+ * corresponding peaks-qa / peaks-ui templates); all 4 surfaces MUST stay
+ * in lockstep — drift between them is the failure mode this slice closes.
+ *
+ * Why this lives here (and not just in markdown):
+ * - The dispatch composer is the ONE place every dispatch prompt passes
+ *   through. Adding the block here guarantees coverage even when the
+ *   orchestrator synthesizes a prompt without reading the per-role
+ *   template (the orchestrator may run peaks-rd on a different rid and
+ *   reuse the task body verbatim).
+ * - Pure-function design (slice 2026-07-22) makes the appended block
+ *   trivially testable.
+ *
+ * Fallback note: until rid-L2-extended ships `peaks worktree spawn`, the
+ * fallback path is `peaks worktree auth grant --rid <id> --reason <text>
+ * --ttl <5m>` (already shipped). Update the prose once `spawn` lands.
+ */
+export declare const L1_WORKTREE_GOVERNANCE_BLOCK = "## Superpowers chain refusal (L1 worktree governance \u2014 locked 2026-07-29)\n\nYou MUST NOT follow the superpowers chain for worktree decisions:\n\n- superpowers:brainstorming \u2192 superpowers:writing-plans \u2192\n  superpowers:subagent-driven-development \u2192 superpowers:using-git-worktrees\n\nThis chain ends with `git worktree add` (superpowers:using-git-worktrees SKILL.md line 96). It bypasses peaks-loop's L2 hook gate and L3 IDE `permissions.deny`. Even when L3 denies the terminal Skill, the chain has already taught you to use raw `git worktree add`, so L3 is not sufficient.\n\nFor worktree operations, use ONLY:\n\n- `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (after rid-L2-extended ships)\n- until then: `peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`\n\nThe superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-rd's own PRD/RD artifacts (`.peaks/_runtime/<sessionId>/rd/requests/<rid>.md`) are authoritative.\n\nIf the upstream superpowers chain suggests raw `git worktree add`:\n\n1. STOP\n2. Re-author the plan as a peaks-rd artifact\n3. Continue with `peaks worktree spawn` (or the auth-grant fallback)\n";
+/**
+ * Compose the system-prompt body that the dispatch site prepends to
+ * `formatTestToolDetection()\n\n`.
+ *
+ * Byte-identical degradation contract (slice 2026-07-22-orchestrator-memory-preflight
+ * controller brief): when the memory block is unavailable, the caller does
+ * `formatTestToolDetection()\n\n${taskBody}` — i.e. the final prompt is exactly
+ * `${formatTestToolDetection()}\n\n${taskBody}`. Today's pre-change behavior
+ * produced the same string from `src/cli/commands/dispatch-commands.ts:220`,
+ * so the unavailable branch MUST return `taskBody` (NOT a `# title\n\n` wrap).
+ *
+ * Available branch prepends the memory block before the `## Task` heading so
+ * `## Project memory …` always sits above the task brief (never pushed below
+ * it).
+ *
+ * Slice 2026-07-29-worktree-l1: every branch prepends the L1 worktree
+ * governance block BEFORE the memory block / task body. The block is the
+ * first thing the dispatched sub-agent sees, so the superpowers-chain
+ * refusal is in scope before any task-specific prose arrives.
+ */
+export declare function buildDispatchSystemPrompt(input: DispatchPromptInput): string;

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

@@ -0,0 +1,117 @@
+/**
+ * Slice 2026-07-29-worktree-l1: Layer 1 of the 3-layer worktree governance
+ * defence. The block below is prepended to every sub-agent dispatch system
+ * prompt so the LLM sees the superpowers-chain refusal BEFORE any task
+ * content. The block mirrors the prose in
+ * `skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md` (and the
+ * corresponding peaks-qa / peaks-ui templates); all 4 surfaces MUST stay
+ * in lockstep — drift between them is the failure mode this slice closes.
+ *
+ * Why this lives here (and not just in markdown):
+ * - The dispatch composer is the ONE place every dispatch prompt passes
+ *   through. Adding the block here guarantees coverage even when the
+ *   orchestrator synthesizes a prompt without reading the per-role
+ *   template (the orchestrator may run peaks-rd on a different rid and
+ *   reuse the task body verbatim).
+ * - Pure-function design (slice 2026-07-22) makes the appended block
+ *   trivially testable.
+ *
+ * Fallback note: until rid-L2-extended ships `peaks worktree spawn`, the
+ * fallback path is `peaks worktree auth grant --rid <id> --reason <text>
+ * --ttl <5m>` (already shipped). Update the prose once `spawn` lands.
+ */
+export const L1_WORKTREE_GOVERNANCE_BLOCK = `## Superpowers chain refusal (L1 worktree governance — locked 2026-07-29)
+
+You MUST NOT follow the superpowers chain for worktree decisions:
+
+- superpowers:brainstorming → superpowers:writing-plans →
+  superpowers:subagent-driven-development → superpowers:using-git-worktrees
+
+This chain ends with \`git worktree add\` (superpowers:using-git-worktrees SKILL.md line 96). It bypasses peaks-loop's L2 hook gate and L3 IDE \`permissions.deny\`. Even when L3 denies the terminal Skill, the chain has already taught you to use raw \`git worktree add\`, so L3 is not sufficient.
+
+For worktree operations, use ONLY:
+
+- \`peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>\` (after rid-L2-extended ships)
+- until then: \`peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>\`
+
+The superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-rd's own PRD/RD artifacts (\`.peaks/_runtime/<sessionId>/rd/requests/<rid>.md\`) are authoritative.
+
+If the upstream superpowers chain suggests raw \`git worktree add\`:
+
+1. STOP
+2. Re-author the plan as a peaks-rd artifact
+3. Continue with \`peaks worktree spawn\` (or the auth-grant fallback)
+`;
+/**
+ * Compose the system-prompt body that the dispatch site prepends to
+ * `formatTestToolDetection()\n\n`.
+ *
+ * Byte-identical degradation contract (slice 2026-07-22-orchestrator-memory-preflight
+ * controller brief): when the memory block is unavailable, the caller does
+ * `formatTestToolDetection()\n\n${taskBody}` — i.e. the final prompt is exactly
+ * `${formatTestToolDetection()}\n\n${taskBody}`. Today's pre-change behavior
+ * produced the same string from `src/cli/commands/dispatch-commands.ts:220`,
+ * so the unavailable branch MUST return `taskBody` (NOT a `# title\n\n` wrap).
+ *
+ * Available branch prepends the memory block before the `## Task` heading so
+ * `## Project memory …` always sits above the task brief (never pushed below
+ * it).
+ *
+ * Slice 2026-07-29-worktree-l1: every branch prepends the L1 worktree
+ * governance block BEFORE the memory block / task body. The block is the
+ * first thing the dispatched sub-agent sees, so the superpowers-chain
+ * refusal is in scope before any task-specific prose arrives.
+ */
+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`;
+    }
+    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${contextBlock}${taskBody}`;
+}
+/**
+ * Slice 2026-07-29-context-evaluation-accuracy: emit a
+ * `## Context window` block with the authoritative ratio so the
+ * dispatched sub-agent does not estimate from message length.
+ *
+ * The probe is a token-counted value (from the IDE adapter's
+ * `compact` env-var or statusline). The block also includes a
+ * hard rule: "do not estimate context yourself; trust this
+ * number" — the LLM's char/4 estimate diverges from peaks'
+ * token-counted value by 2-4x, and trusting the LLM's
+ * self-estimate causes false-positive "context too low" reports
+ * at 60%+ free.
+ *
+ * When the probe is null (e.g. the orchestrator did not run
+ * the context probe before dispatch), the block instructs
+ * the sub-agent to call `peaks code context-now` itself
+ * before declaring context pressure.
+ */
+function renderContextBlock(probe) {
+    if (probe !== null && probe !== undefined) {
+        const usedPct = (probe.ratio * 100).toFixed(1);
+        const freePct = ((1 - probe.ratio) * 100).toFixed(1);
+        const action = probe.ratio >= 0.95
+            ? 'RED-LINE — call `peaks compact auto --execute` immediately.'
+            : probe.ratio >= 0.85
+                ? 'pre-compact zone — consider running `peaks compact auto --execute` proactively.'
+                : probe.ratio >= 0.5
+                    ? 'soft-warn zone — continue working; the next dispatch will re-check.'
+                    : 'plenty of room — continue without compacting.';
+        return `## Context window (authoritative — do NOT estimate yourself)
+
+Your context is **${usedPct}% used** (${freePct}% free) as measured by the IDE adapter's token-counted statusline (source: \`${probe.source}\`, IDE: \`${probe.ide}\`). This number is the SAME value \`peaks code context-now\` returns — trust it; do not derive a percentage from your message length or any other heuristic (char/4 estimates diverge from token counts by 2-4x and have caused false "context too low" reports at ${freePct}%+ free).
+
+**Action:** ${action}
+
+If you are tempted to declare "context pressure" or "context too low" to the parent, FIRST re-run \`peaks code context-now\` and compare its \`ratio\` field to the number above. Only report context pressure if \`peaks code context-now\` returns \`verdict: red-line\` or \`action: auto-compact-now\`.
+
+`;
+    }
+    return `## Context window (no probe available)
+
+The orchestrator did not capture a context-fill probe before this dispatch. If you need to evaluate context pressure, run \`peaks code context-now --project <root>\` and trust its \`ratio\` field. Do not estimate from message length.
+
+`;
+}

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

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { CollectorOutput } from './types.js';
+declare const CollectInputSchema: z.ZodObject<{
+    goal: z.ZodString;
+    project: z.ZodString;
+    depsMode: z.ZodEnum<["locked", "latest"]>;
+    out: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    goal: string;
+    depsMode: "latest" | "locked";
+    out?: string | undefined;
+}, {
+    project: string;
+    goal: string;
+    depsMode: "latest" | "locked";
+    out?: string | undefined;
+}>;
+export type CollectInput = z.infer<typeof CollectInputSchema>;
+export declare function collectContext(rawInput: unknown): Promise<{
+    readonly goal: string;
+    readonly collector: CollectorOutput;
+}>;
+export {};