peaks-loop 4.0.35 → 4.0.36

package/dist/cli/commands/wave-plan-commands.js

@@ -0,0 +1,93 @@
+import { readFileSync } from 'node:fs';
+import { getErrorMessage, ok, fail } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { planFileOverlapWaves } from '../../services/dispatch/file-overlap-wave-planner.js';
+export function registerWavePlanCommand(parent, io) {
+    addJsonOption(parent
+        .command('wave-plan')
+        .description('§3 file-overlap-aware scheduling: read slice descriptors ' +
+        '({slices:[{id,files:[]}]}) and emit a wave plan where every wave is ' +
+        'pairwise file-disjoint. Overlapping slices are deferred to later ' +
+        'waves with the colliding file named. Machine-readable envelope; the ' +
+        'LLM runs this, users never type it.')
+        .option('--slices <file>', 'path to a JSON file: { "slices": [{ "id": "s1", "files": ["src/a.ts"] }] }')
+        .option('--slices-json <json>', 'inline JSON with the same shape as --slices')).action((options) => {
+        const asJson = options.json === true;
+        const source = typeof options.slicesJson === 'string' && options.slicesJson.length > 0
+            ? { text: options.slicesJson }
+            : typeof options.slices === 'string' && options.slices.length > 0
+                ? readSlicesFile(options.slices)
+                : null;
+        if (source === null) {
+            printResult(io, fail('sub-agent.wave-plan', 'MISSING_INPUT', 'pass --slices <file> or --slices-json <json>', { ok: false, waves: [] }, ['Provide slice descriptors as { "slices": [{ "id": "s1", "files": ["src/a.ts"] }] }.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        if (source.error !== undefined) {
+            printResult(io, fail('sub-agent.wave-plan', 'INVALID_INPUT', source.error, { ok: false, waves: [] }, ['Check the JSON shape: { "slices": [{ "id": string, "files": string[] }] }.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(source.text);
+        }
+        catch (err) {
+            printResult(io, fail('sub-agent.wave-plan', 'INVALID_JSON', `input is not valid JSON: ${getErrorMessage(err)}`, { ok: false, waves: [] }, ['Fix the JSON syntax and re-run.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const descriptors = coerceDescriptors(parsed);
+        if (descriptors === null) {
+            printResult(io, fail('sub-agent.wave-plan', 'INVALID_SHAPE', 'expected { "slices": [{ "id": string, "files": string[] }] }', { ok: false, waves: [] }, ['Each entry needs a non-empty string id and an array of file paths.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const plan = planFileOverlapWaves(descriptors);
+        const warnings = plan.duplicateIds.length > 0
+            ? [`DUPLICATE_SLICE_IDS: ${plan.duplicateIds.join(', ')} (first descriptor wins; the rest were not scheduled)`]
+            : [];
+        printResult(io, ok('sub-agent.wave-plan', {
+            envelopeVersion: '2.1.0',
+            ok: true,
+            sliceCount: plan.sliceCount,
+            waveCount: plan.waves.length,
+            waves: plan.waves,
+            duplicateIds: plan.duplicateIds,
+            maxParallelism: plan.waves.reduce((max, w) => Math.max(max, w.slices.length), 0)
+        }, warnings, [
+            plan.waves.length <= 1
+                ? 'All slices are file-disjoint: dispatch them in a single wave.'
+                : `Dispatch wave 0 first, then each later wave after its predecessors finish; the deferred[] entries name the blocking file.`
+        ]), asJson);
+    });
+}
+function readSlicesFile(path) {
+    try {
+        return { text: readFileSync(path, 'utf8') };
+    }
+    catch (err) {
+        return { text: '', error: `cannot read --slices file ${path}: ${getErrorMessage(err)}` };
+    }
+}
+function coerceDescriptors(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const raw = parsed.slices;
+    if (!Array.isArray(raw))
+        return null;
+    const out = [];
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object' || Array.isArray(item))
+            return null;
+        const id = item.id;
+        const files = item.files;
+        if (typeof id !== 'string' || id.length === 0)
+            return null;
+        if (files !== undefined && (!Array.isArray(files) || files.some((f) => typeof f !== 'string'))) {
+            return null;
+        }
+        out.push({ id, files: files ?? [] });
+    }
+    return out;
+}

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

@@ -68,6 +68,22 @@ export interface DispatchPromptInput {
      *   and before the memory/task content.
      */
     freshContextBlock?: string | null;
+    /**
+     * Slice 2026-09-10-dispatch-token-and-swarm §4: session capsule
+     * published by the orchestrator through `peaks sub-agent share`.
+     *
+     * - `undefined` / `null` → no capsule pointer, no precedence line
+     *   (byte-identical legacy prompt).
+     * - `{ batchId, key, bytes }` → a `shared-read` pointer plus the
+     *   mandatory precedence line: the capsule is ADVISORY BACKGROUND only
+     *   and the task spec wins on conflict. Nothing the sub-agent must act
+     *   on may live only in the capsule.
+     */
+    capsule?: {
+        readonly batchId: string;
+        readonly key: string;
+        readonly bytes: number;
+    } | null;
 }
 /**
  * Slice 2026-07-29-worktree-l1: Layer 1 of the 3-layer worktree governance
@@ -91,7 +107,7 @@ export interface DispatchPromptInput {
  * 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";
+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\nThat chain ends with `git worktree add` (superpowers:using-git-worktrees SKILL.md line 96), which bypasses peaks-loop's L2 hook gate and L3 IDE `permissions.deny`. L3 denial is NOT sufficient \u2014 by then the chain has already taught raw `git worktree add`.\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\nSuperpowers skills remain 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";
 /**
  * Slice 2026-08-01-subagent-merge-and-e2e (Task 8): the dispatch
  * system prompt gains three lifecycle rules. The sub-agent must:
@@ -117,17 +133,38 @@ export declare const L1_WORKTREE_GOVERNANCE_BLOCK = "## Superpowers chain refusa
  * 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";
+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 best-effort-kills 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";
+/**
+ * Slice 2026-09-10-context-audit-and-discipline (Slice C): cap the sub-agent's
+ * FINAL report.
+ *
+ * Why (measured, session 2026-09-07-session-245530): 20 sub-agent final
+ * reports cost ≈ 60 KB ≈ 15K tokens of the ORCHESTRATOR's window in one
+ * session — the reports, not the dispatch boilerplate, were the second-largest
+ * consumer. The sub-agent already writes a full artifact to disk; the report
+ * only needs to be the index into it.
+ *
+ * QUALITY GUARD (binding): the cap removes no information. Everything the
+ * parent needs to ACT on stays in the report; everything longer lives in the
+ * artifact the parent can `Read`. The five mandatory fields below are exactly
+ * the ones the orchestrator must have to decide the next gate.
+ */
+export declare const REPORT_CAP_BLOCK = "## Final report cap (mandatory)\n\nYour FINAL report to the parent MUST be \u2264 40 lines and \u2264 2 KB. Write any longer detail into the artifact file you already own \u2014 the parent can `Read` that file for the full detail, so nothing is lost. The report itself MUST still carry: changed files (one line each), the exact commands you ran, pass/fail counts, tsc status, and any blocker. Do NOT paste file contents, full tool output, or logs into the report.\n";
 /**
- * Compose the system-prompt body that the dispatch site prepends to
- * `formatTestToolDetection()\n\n`.
+ * Compose the system-prompt body for a sub-agent dispatch.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): the composer owns the Test Tool
+ * Detection injection — ONE unified block for every role, prepended first.
+ * Callers MUST NOT prepend `formatTestToolDetection()` themselves or the
+ * block is injected twice.
  *
  * 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).
+ * controller brief): when the memory block is unavailable, the composed body is
+ * exactly `formatTestToolDetection() + "\n\n" + L1 + "\n" + LIFECYCLE +
+ * "\n" + REPORT_CAP + "\n" + contextBlock + taskBody`, so the unavailable
+ * branch MUST return `taskBody` unwrapped (NOT a `# title\n\n` wrap).
+ * (REPORT_CAP joined the stable prefix in slice
+ * 2026-09-10-context-audit-and-discipline, Slice C.)
  * The contract holds for callers that do not pass `codegraphBlock` (all
  * non-RD roles). Slice 2026-09-03-codegraph-preread deliberately inserts a
  * codegraph structure block (or its fail-soft unavailable note) for RD
@@ -151,3 +188,23 @@ export declare function buildDispatchSystemPrompt(input: DispatchPromptInput): s
  * byte-stable and trivially testable.
  */
 export declare const CODEGRAPH_UNAVAILABLE_BLOCK = "## Codegraph structure\n\ncodegraph unavailable \u2014 proceeding on project-scan only.\n";
+/** Binding phrases every dispatch prompt must contain, for every role. */
+export declare const BINDING_RULE_TOKENS: readonly string[];
+/**
+ * The runner-direct-path tokens: the refusal example, the two direct paths
+ * the block names (`peaks test --json` to introspect; PB-5, the repo-defined
+ * `test` / `test:*` scripts that are NOT gated), and the two pieces of
+ * quality guidance that must survive any compression — never assume a
+ * runner without asking the user as a last resort, and prefer
+ * `peaks test <file>` because it resolves the local binary Windows-aware.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): there is no role split any more,
+ * so this set is asserted IDENTICALLY for every role. The runner EXAMPLES
+ * were removed as part of the unification — they were never rules.
+ */
+export declare const TEST_RUNNER_RULE_TOKENS: readonly string[];
+/**
+ * Return the subset of `tokens` that `text` does NOT contain. Pure; used by
+ * the rule-presence guard and usable by any future prompt self-check.
+ */
+export declare function missingRuleTokens(text: string, tokens: readonly string[]): readonly string[];

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

@@ -1,3 +1,4 @@
+import { formatTestToolDetection } from '../dispatch/test-tool-detection.js';
 /**
  * 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
@@ -27,14 +28,14 @@ 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.
+That chain ends with \`git worktree add\` (superpowers:using-git-worktrees SKILL.md line 96), which bypasses peaks-loop's L2 hook gate and L3 IDE \`permissions.deny\`. L3 denial is NOT sufficient — by then the chain has already taught raw \`git worktree add\`.
 
 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.
+Superpowers skills remain 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\`:
 
@@ -69,20 +70,44 @@ If the upstream superpowers chain suggests raw \`git worktree add\`:
  */
 export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
 
-- 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.
-- Do NOT run E2E. The parent session runs Playwright verification once after merge-back (Task 10). Your E2E work is duplicate effort.
+- 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 best-effort-kills it before merge-back.
+- Do NOT run E2E. The parent session runs Playwright verification once after merge-back (Task 10); your E2E work is duplicate effort.
 - Do NOT call \`git merge\`, \`git pull\`, \`git rebase\`, or \`peaks worktree release\`. The parent session owns the merge-back step.
 `;
 /**
- * Compose the system-prompt body that the dispatch site prepends to
- * `formatTestToolDetection()\n\n`.
+ * Slice 2026-09-10-context-audit-and-discipline (Slice C): cap the sub-agent's
+ * FINAL report.
+ *
+ * Why (measured, session 2026-09-07-session-245530): 20 sub-agent final
+ * reports cost ≈ 60 KB ≈ 15K tokens of the ORCHESTRATOR's window in one
+ * session — the reports, not the dispatch boilerplate, were the second-largest
+ * consumer. The sub-agent already writes a full artifact to disk; the report
+ * only needs to be the index into it.
+ *
+ * QUALITY GUARD (binding): the cap removes no information. Everything the
+ * parent needs to ACT on stays in the report; everything longer lives in the
+ * artifact the parent can `Read`. The five mandatory fields below are exactly
+ * the ones the orchestrator must have to decide the next gate.
+ */
+export const REPORT_CAP_BLOCK = `## Final report cap (mandatory)
+
+Your FINAL report to the parent MUST be ≤ 40 lines and ≤ 2 KB. Write any longer detail into the artifact file you already own — the parent can \`Read\` that file for the full detail, so nothing is lost. The report itself MUST still carry: changed files (one line each), the exact commands you ran, pass/fail counts, tsc status, and any blocker. Do NOT paste file contents, full tool output, or logs into the report.
+`;
+/**
+ * Compose the system-prompt body for a sub-agent dispatch.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): the composer owns the Test Tool
+ * Detection injection — ONE unified block for every role, prepended first.
+ * Callers MUST NOT prepend `formatTestToolDetection()` themselves or the
+ * block is injected twice.
  *
  * 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).
+ * controller brief): when the memory block is unavailable, the composed body is
+ * exactly `formatTestToolDetection() + "\n\n" + L1 + "\n" + LIFECYCLE +
+ * "\n" + REPORT_CAP + "\n" + contextBlock + taskBody`, so the unavailable
+ * branch MUST return `taskBody` unwrapped (NOT a `# title\n\n` wrap).
+ * (REPORT_CAP joined the stable prefix in slice
+ * 2026-09-10-context-audit-and-discipline, Slice C.)
  * The contract holds for callers that do not pass `codegraphBlock` (all
  * non-RD roles). Slice 2026-09-03-codegraph-preread deliberately inserts a
  * codegraph structure block (or its fail-soft unavailable note) for RD
@@ -98,15 +123,33 @@ export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
  * refusal is in scope before any task-specific prose arrives.
  */
 export function buildDispatchSystemPrompt(input) {
-    const { taskBody, memoryBlock, contextProbe, codegraphBlock, projectStackBlock, freshContextBlock } = input;
+    const { taskBody, memoryBlock, contextProbe, codegraphBlock, projectStackBlock, freshContextBlock, capsule } = input;
+    // 2026-09-10-dispatch-block-d (Option D): ONE Test Tool Detection block
+    // for every role — the composer owns the injection so callers MUST NOT
+    // prepend `formatTestToolDetection()` themselves (double injection).
+    const testToolText = `${formatTestToolDetection()}\n\n`;
     const contextBlock = renderContextBlock(contextProbe ?? null);
     const codegraphText = renderCodegraphBlock(codegraphBlock);
     const projectStackText = renderProjectStackBlock(projectStackBlock);
     const freshContextText = renderFreshContextBlock(freshContextBlock);
+    const capsuleText = renderCapsulePointer(capsule);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${memoryBlock.block}\n## Task\n${taskBody}`;
+        return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${memoryBlock.block}\n## Task\n${taskBody}`;
     }
-    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${taskBody}`;
+    return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${taskBody}`;
+}
+/**
+ * Slice 2026-09-10-dispatch-token-and-swarm §4 — session capsule pointer.
+ *
+ * QUALITY GUARD: the capsule is BACKGROUND only. The precedence line below
+ * is part of the contract, not decoration — anything the sub-agent must
+ * ACT on stays inline in the task spec. The renderer therefore always
+ * emits the precedence sentence whenever it emits the pointer.
+ */
+function renderCapsulePointer(capsule) {
+    if (capsule === null || capsule === undefined)
+        return '';
+    return `## Shared session capsule (advisory background)\nBackground facts already established by the orchestrator (${capsule.bytes} bytes): read them with \`peaks sub-agent shared-read --batch ${capsule.batchId} --key ${capsule.key}\`. This capsule is ADVISORY BACKGROUND ONLY — it is not a task. Your task spec below is authoritative and wins on any conflict; anything you must act on is stated inline there.\n\n`;
 }
 /**
  * Slice 2026-09-03-codegraph-preread: fixed degradation string emitted
@@ -199,17 +242,89 @@ function renderContextBlock(probe) {
                     : '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).
+Context **${usedPct}% used** (${freePct}% free), token-counted by the IDE adapter's statusline (source: \`${probe.source}\`, IDE: \`${probe.ide}\`). This is the SAME value \`peaks code context-now\` returns — trust it; never derive a percentage from message length (char/4 diverges 2-4x and has 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\`.
+Before telling the parent "context pressure" or "context too low", re-run \`peaks code context-now\` and compare its \`ratio\` to the number above. Report pressure ONLY if it 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.
+No context-fill probe was captured before this dispatch. To evaluate context pressure, run \`peaks code context-now --project <root>\` and trust its \`ratio\` field. Do not estimate from message length.
 
 `;
 }
+/* ──────────────────────────────────────────────────────────────────────────
+ * Slice 2026-09-10-dispatch-token-and-swarm §1 — rule-presence guard.
+ *
+ * The compression + role-scoping in this file is allowed to shorten prose.
+ * It is NOT allowed to drop a binding rule. These token sets are the
+ * machine-checkable definition of "binding rule": each entry is a phrase
+ * that carries an obligation (MUST / MUST NOT / refused / a command the
+ * sub-agent is told to use or avoid). The guard test asserts that EVERY
+ * role's composed prompt contains EVERY token — so a future compression
+ * that deletes a rule fails CI instead of silently weakening the contract.
+ * ────────────────────────────────────────────────────────────────────────── */
+/** Binding phrases every dispatch prompt must contain, for every role. */
+export const BINDING_RULE_TOKENS = [
+    // L1 worktree governance
+    'MUST NOT follow the superpowers chain',
+    'superpowers:using-git-worktrees',
+    '`git worktree add`',
+    '`peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>`',
+    '`peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`',
+    'MUST NOT be used as a workflow',
+    'STOP',
+    'Re-author the plan as a peaks-rd artifact',
+    // lifecycle rules
+    '`peaks sub-agent shutdown register --pid <pid> --name <label>`',
+    'Do NOT run E2E',
+    'Do NOT call `git merge`, `git pull`, `git rebase`',
+    '`peaks worktree release`',
+    // context window
+    'do NOT estimate yourself',
+    '`peaks code context-now`',
+    '`verdict: red-line`',
+    // final report cap (Slice 2026-09-10-context-audit-and-discipline, Slice C)
+    '## Final report cap (mandatory)',
+    '≤ 40 lines and ≤ 2 KB',
+    'the parent can `Read` that file for the full detail',
+    'changed files (one line each)',
+    'pass/fail counts',
+    'tsc status',
+    // test scope — ONE unified block, byte-identical for EVERY role
+    '## Test Tool Detection (mandatory)',
+    '`package.json#scripts.test`',
+    'do NOT invoke `npx <runner>`',
+    '## Test Scope (mandatory)',
+    'PEAKS_FULL_TEST=1',
+    'refused',
+];
+/**
+ * The runner-direct-path tokens: the refusal example, the two direct paths
+ * the block names (`peaks test --json` to introspect; PB-5, the repo-defined
+ * `test` / `test:*` scripts that are NOT gated), and the two pieces of
+ * quality guidance that must survive any compression — never assume a
+ * runner without asking the user as a last resort, and prefer
+ * `peaks test <file>` because it resolves the local binary Windows-aware.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): there is no role split any more,
+ * so this set is asserted IDENTICALLY for every role. The runner EXAMPLES
+ * were removed as part of the unification — they were never rules.
+ */
+export const TEST_RUNNER_RULE_TOKENS = [
+    '`./node_modules/.bin/vitest run`',
+    'PB-5',
+    '`peaks test --json`',
+    'ask the user before assuming a runner',
+    '(Windows-aware)',
+];
+/**
+ * Return the subset of `tokens` that `text` does NOT contain. Pure; used by
+ * the rule-presence guard and usable by any future prompt self-check.
+ */
+export function missingRuleTokens(text, tokens) {
+    return tokens.filter((t) => !text.includes(t));
+}

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

@@ -0,0 +1,100 @@
+/**
+ * `peaks code context-audit` — what actually fills the orchestrator's window.
+ *
+ * Slice 2026-09-10-context-audit-and-discipline (Slice A).
+ *
+ * Why this exists: `peaks code context-now` reports a RATIO only. Nothing
+ * reported WHAT occupies the window, so the same 40K-token mistake (dumping a
+ * full `peaks memory reindex --json` array four times in one session) was
+ * invisible until the window was 68% gone. The IDE transcript already holds
+ * per-message tool results, so the breakdown is derivable locally, with zero
+ * tokens spent asking a model.
+ *
+ * Contract:
+ *   - READ-ONLY. The transcript is never modified.
+ *   - FAIL-SOFT. A missing / oversized / corrupt transcript yields
+ *     `available: false` plus a machine-readable `reason`. Never throws,
+ *     never blocks a workflow, never exits non-zero on its own.
+ *   - NO CONTENT. The envelope carries tool names, short command/path keys
+ *     and byte counts — never the tool result text itself (dumping it would
+ *     re-create the very problem this command measures).
+ *   - BOUNDED MEMORY. The transcript can be tens of MB; it is streamed in
+ *     fixed-size chunks with a carried partial line, never read whole.
+ *
+ * Grouping key = `(tool name, short input key)`. The key is a *stable
+ * summary* of the tool input — the Bash command line, the file path tail, the
+ * grep pattern — so "4 × the same 40KB reindex dump" collapses into ONE row
+ * with `count: 4` instead of four anonymous entries.
+ */
+/** Default number of top entries emitted. */
+export declare const CONTEXT_AUDIT_DEFAULT_TOP = 15;
+/** Hard ceiling for `--top` — the envelope must stay small by construction. */
+export declare const CONTEXT_AUDIT_MAX_TOP = 100;
+/** Transcripts larger than this are reported `available:false` (fail-soft). */
+export declare const CONTEXT_AUDIT_MAX_TRANSCRIPT_BYTES: number;
+export interface ContextAuditEntry {
+    /** Tool name (`Bash`, `Read`, `Grep`, …), or `unknown` when unmatched. */
+    readonly tool: string;
+    /** Short, stable summary of the tool input (command line / path tail / pattern). */
+    readonly key: string;
+    /** Total UTF-8 bytes of every tool result in this group. */
+    readonly bytes: number;
+    /**
+     * Share of the session's tool-result bytes, as a PERCENTAGE in `[0, 100]`
+     * with one decimal (e.g. `4.2` — not the `0.042` ratio). The name and the
+     * value agree: `pct` means percent.
+     */
+    readonly pctOfTotal: number;
+    /** How many tool results landed in this group. */
+    readonly count: number;
+}
+export interface ContextAuditResult {
+    /** False when the transcript could not be read; see `reason`. */
+    readonly available: boolean;
+    /** Machine-readable unavailability reason (`null` when available). */
+    readonly reason: string | null;
+    /** Absolute transcript path, or `null` when unresolved. */
+    readonly transcriptPath: string | null;
+    /** Total UTF-8 bytes of all tool results seen. */
+    readonly totalBytes: number;
+    /** Number of tool-result entries seen. */
+    readonly entryCount: number;
+    /** Distinct `(tool, key)` groups — always ≥ `entries.length`. */
+    readonly groupCount: number;
+    /** Number of top entries requested. */
+    readonly topN: number;
+    /** Top-N groups, sorted by bytes descending. */
+    readonly entries: readonly ContextAuditEntry[];
+}
+export interface ContextAuditInput {
+    /** Outer (harness) session id — the transcript is named by it. */
+    readonly outerSessionId?: string | null;
+    /** How many top entries to emit. Clamped to `[1, CONTEXT_AUDIT_MAX_TOP]`. */
+    readonly topN?: number;
+    /** Explicit transcript path override (test seam; skips the locator). */
+    readonly transcriptPath?: string | null;
+    /** Override the too-large threshold (test seam; default 256 MB). */
+    readonly maxTranscriptBytes?: number;
+    /** Env used to detect the active IDE (default `process.env`). */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/** Clamp a caller-supplied `--top` into the documented range. */
+export declare function normalizeTopN(value: unknown): number;
+/**
+ * Build the stable group key for one tool call. Unknown tools fall back to a
+ * clipped JSON rendering of their input so the group is still recognizable.
+ */
+export declare function contextAuditKey(tool: string, input: unknown): string;
+/**
+ * Audit the CURRENT session's transcript. Never throws.
+ *
+ * Unavailability reasons (all return `available: false`, exit code stays 0):
+ *   - `no-outer-session-id`  — the peaks session has no bound outer id
+ *   - `transcript-locator-unavailable` — the active IDE adapter does not
+ *                              declare `compact.resolveTranscriptPath`
+ *   - `transcript-not-found` — the adapter locator returned null
+ *   - `transcript-too-large` — above `CONTEXT_AUDIT_MAX_TRANSCRIPT_BYTES`
+ *   - `transcript-unreadable`— stat/open failed
+ *   - `audit-failed`         — any unexpected internal error
+ */
+export declare function auditContext(input?: ContextAuditInput): ContextAuditResult;