peaks-loop 4.0.35 → 4.0.36

package/dist/services/dispatch/session-capsule.d.ts

@@ -0,0 +1,23 @@
+/** Reserved batch id for the session capsule (matches the channel path pattern). */
+export declare const SESSION_CAPSULE_BATCH_ID = "session-capsule";
+/** Reserved key inside that channel. */
+export declare const SESSION_CAPSULE_KEY = "orchestrator.capsule";
+export interface SessionCapsuleRef {
+    readonly batchId: string;
+    readonly key: string;
+    /** Byte size of the published value (for the pointer line). */
+    readonly bytes: number;
+    /** ISO8601 timestamp of the last write. */
+    readonly updatedAt: string;
+}
+/**
+ * Read the session capsule, if one was published. Returns `null` when the
+ * channel is absent, empty, or unreadable — the dispatch prompt then
+ * renders neither the pointer nor the precedence line (byte-identical to
+ * the pre-slice shape).
+ */
+export declare function readSessionCapsule(opts: {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+}): SessionCapsuleRef | null;

package/dist/services/dispatch/session-capsule.js

@@ -0,0 +1,56 @@
+/**
+ * Slice 2026-09-10-dispatch-token-and-swarm §4 — session capsule reader.
+ *
+ * The orchestrator publishes already-known background ONCE per session
+ * through the existing G8.4 channel:
+ *
+ *   peaks sub-agent share \
+ *     --batch session-capsule \
+ *     --key orchestrator.capsule \
+ *     --value '{"rootCauses":[...],"decisions":[...],"fileMap":{...}}'
+ *
+ * Dispatch prompts then carry a one-line `shared-read` pointer instead of
+ * re-explaining that background in every task spec.
+ *
+ * QUALITY GUARD: the capsule is ADVISORY BACKGROUND ONLY. Nothing a
+ * sub-agent must ACT on may live only in the capsule — the task spec is
+ * authoritative and wins on conflict. The precedence sentence is rendered
+ * by `renderCapsulePointer` in build-dispatch-system-prompt.ts and is not
+ * optional when the pointer is emitted.
+ *
+ * This module only READS. Publishing is the orchestrator's job through the
+ * already-shipped `peaks sub-agent share` primitive — no new write path.
+ */
+import { readSharedChannel } from 'peaks-loop-shared-channel';
+/** Reserved batch id for the session capsule (matches the channel path pattern). */
+export const SESSION_CAPSULE_BATCH_ID = 'session-capsule';
+/** Reserved key inside that channel. */
+export const SESSION_CAPSULE_KEY = 'orchestrator.capsule';
+/**
+ * Read the session capsule, if one was published. Returns `null` when the
+ * channel is absent, empty, or unreadable — the dispatch prompt then
+ * renders neither the pointer nor the precedence line (byte-identical to
+ * the pre-slice shape).
+ */
+export function readSessionCapsule(opts) {
+    try {
+        const channel = readSharedChannel({
+            projectRoot: opts.projectRoot,
+            sid: opts.sid,
+            rid: opts.rid,
+            batchId: SESSION_CAPSULE_BATCH_ID
+        });
+        const entry = channel.entries[SESSION_CAPSULE_KEY];
+        if (entry === undefined)
+            return null;
+        return {
+            batchId: SESSION_CAPSULE_BATCH_ID,
+            key: SESSION_CAPSULE_KEY,
+            bytes: entry.valueSize,
+            updatedAt: entry.at
+        };
+    }
+    catch {
+        return null; // fail-soft: a missing capsule never blocks a dispatch
+    }
+}

package/dist/services/dispatch/slice-dag.d.ts

@@ -31,6 +31,15 @@ export interface SliceNode {
      * (complex = user-attended, simple/trivial = overnight). Optional.
      */
     readonly complexity?: SliceComplexity;
+    /**
+     * Slice 2026-09-10-dispatch-token-and-swarm §3: files this slice is
+     * expected to touch. When EVERY node of a topological level declares
+     * `files`, `--from-dag` emits a file-overlap wave plan (`firstLevelWaves`)
+     * so the LLM can fan the level out without serializing on a shared file.
+     * Optional and additive: absent → DAG hash and dispatch behavior are
+     * byte-identical to before this slice.
+     */
+    readonly files?: readonly string[];
 }
 export interface DependsOn {
     readonly from: string;

package/dist/services/dispatch/slice-dag.js

@@ -103,6 +103,11 @@ export function validateDag(dag) {
         if (n.complexity !== undefined && !isSliceComplexity(n.complexity)) {
             throw new InvalidSliceDagError(`node ${n.id} complexity must be one of ${SLICE_COMPLEXITIES.join('|')} when present`);
         }
+        // Slice 2026-09-10 §3: optional file list. Only shape-checked when
+        // present so pre-existing DAGs stay valid.
+        if (n.files !== undefined && (!Array.isArray(n.files) || n.files.some((f) => typeof f !== 'string' || f.length === 0))) {
+            throw new InvalidSliceDagError(`node ${n.id} files must be an array of non-empty strings when present`);
+        }
     }
     // v2.15.0 follow-up — G12 defensive rule: foundation slice can only
     // depend on another foundation slice. Business depending on foundation
@@ -219,7 +224,10 @@ export function serializeDag(dag) {
         // (only when present, preserving hash stability for old DAGs).
         ...(n.foundation !== undefined ? { foundation: n.foundation } : {}),
         ...(n.upstreamSync !== undefined ? { upstreamSync: n.upstreamSync } : {}),
-        ...(n.complexity !== undefined ? { complexity: n.complexity } : {})
+        ...(n.complexity !== undefined ? { complexity: n.complexity } : {}),
+        // Slice 2026-09-10 §3: only present when declared, so the hash of a
+        // file-less DAG is unchanged.
+        ...(n.files !== undefined ? { files: [...n.files] } : {})
     }));
     const edges = [...dag.edges]
         .sort((a, b) => {

package/dist/services/dispatch/test-tool-detection.d.ts

@@ -26,8 +26,19 @@
  *  "remove the redundancy" of a test-tool-detection instruction because
  *  the dispatch CLI always prepends it. This is a guarantee, not a
  *  suggestion.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): ONE block for EVERY role. The
+ * runner-table EXAMPLES were dropped — they were never rules, and
+ * `package.json#scripts.test` is the source of truth at run time — while
+ * the one missing real rule is stated inline: PB-5, i.e. repo-defined
+ * `test` / `test:*` scripts are the human/LLM direct path and are NOT
+ * gated by the scope rule. The soft fallback ("only as a last resort, ask
+ * the user before assuming a runner") and the Windows-aware note on
+ * `peaks test <file>` are RETAINED — they are quality guidance, not
+ * examples. No role split remains, so every role receives a byte-identical
+ * block.
  */
-export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nBefore running any test, read `package.json#scripts.test` to identify the project's test framework. Use the project-local runner \u2014 do NOT invoke `npx <runner>`:\n\n- **vitest** \u2192 `./node_modules/.bin/vitest run <file>` (or `pnpm test -- <file>`)\n- **jest**   \u2192 `./node_modules/.bin/jest <file>`   (or `pnpm test -- <file>`)\n- **mocha**  \u2192 `./node_modules/.bin/mocha <file>`  (or `pnpm test -- <file>`)\n\n## Test Scope (mandatory)\n\nThe dispatched test command MUST be **scoped** to a single file or pattern. An unscoped `./node_modules/.bin/vitest run` (no path filter) is **refused** because the 483-file suite is one keystroke from a 36-minute wall clock:\n\n- **scoped**    \u2192 `./node_modules/.bin/vitest run tests/unit/foo.test.ts` (or any explicit file/pattern)\n- **intentional full run** \u2192 prefix with the explicit opt-in token `PEAKS_FULL_TEST=1` to override the scope gate. Use only for CI / release verification, never for routine verification during a slice.\n- **refused**   \u2192 bare `./node_modules/.bin/vitest run` (no argument after `run`) without the opt-in token.\n\n`pnpm test` / `pnpm test:unit` / `pnpm test:cli` / `pnpm test:integration` and any repo-defined `test*` script remain the **human / LLM direct path** and are not gated by this rule (PB-5).\n\nIf unsure which framework the consumer project uses, run `peaks test --json` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command `peaks test <file>` already resolves the local binary for you (Windows-aware).";
+export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nRead `package.json#scripts.test` for the project's framework and use the project-local runner \u2014 do NOT invoke `npx <runner>`. If unsure, run `peaks test --json` first. Only as a last resort, ask the user before assuming a runner. `peaks test <file>` already resolves the local binary for you (Windows-aware).\n\n## Test Scope (mandatory)\n\nAny test command MUST be **scoped** to a single file or pattern; a bare `./node_modules/.bin/vitest run` is **refused** unless you prefix the explicit opt-in token `PEAKS_FULL_TEST=1` (CI / release verification only, never routine slice verification).\n\nRepo-defined `test` / `test:*` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).";
 /**
  * Pure helper that returns the block. Exists as a function (not just an
  * exported constant) so future variants can take a runtime parameter

package/dist/services/dispatch/test-tool-detection.js

@@ -26,26 +26,27 @@
  *  "remove the redundancy" of a test-tool-detection instruction because
  *  the dispatch CLI always prepends it. This is a guarantee, not a
  *  suggestion.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): ONE block for EVERY role. The
+ * runner-table EXAMPLES were dropped — they were never rules, and
+ * `package.json#scripts.test` is the source of truth at run time — while
+ * the one missing real rule is stated inline: PB-5, i.e. repo-defined
+ * `test` / `test:*` scripts are the human/LLM direct path and are NOT
+ * gated by the scope rule. The soft fallback ("only as a last resort, ask
+ * the user before assuming a runner") and the Windows-aware note on
+ * `peaks test <file>` are RETAINED — they are quality guidance, not
+ * examples. No role split remains, so every role receives a byte-identical
+ * block.
  */
 export const TEST_TOOL_DETECTION_BLOCK = `## Test Tool Detection (mandatory)
 
-Before running any test, read \`package.json#scripts.test\` to identify the project's test framework. Use the project-local runner — do NOT invoke \`npx <runner>\`:
-
-- **vitest** → \`./node_modules/.bin/vitest run <file>\` (or \`pnpm test -- <file>\`)
-- **jest**   → \`./node_modules/.bin/jest <file>\`   (or \`pnpm test -- <file>\`)
-- **mocha**  → \`./node_modules/.bin/mocha <file>\`  (or \`pnpm test -- <file>\`)
+Read \`package.json#scripts.test\` for the project's framework and use the project-local runner — do NOT invoke \`npx <runner>\`. If unsure, run \`peaks test --json\` first. Only as a last resort, ask the user before assuming a runner. \`peaks test <file>\` already resolves the local binary for you (Windows-aware).
 
 ## Test Scope (mandatory)
 
-The dispatched test command MUST be **scoped** to a single file or pattern. An unscoped \`./node_modules/.bin/vitest run\` (no path filter) is **refused** because the 483-file suite is one keystroke from a 36-minute wall clock:
-
-- **scoped**    → \`./node_modules/.bin/vitest run tests/unit/foo.test.ts\` (or any explicit file/pattern)
-- **intentional full run** → prefix with the explicit opt-in token \`PEAKS_FULL_TEST=1\` to override the scope gate. Use only for CI / release verification, never for routine verification during a slice.
-- **refused**   → bare \`./node_modules/.bin/vitest run\` (no argument after \`run\`) without the opt-in token.
-
-\`pnpm test\` / \`pnpm test:unit\` / \`pnpm test:cli\` / \`pnpm test:integration\` and any repo-defined \`test*\` script remain the **human / LLM direct path** and are not gated by this rule (PB-5).
+Any test command MUST be **scoped** to a single file or pattern; a bare \`./node_modules/.bin/vitest run\` is **refused** unless you prefix the explicit opt-in token \`PEAKS_FULL_TEST=1\` (CI / release verification only, never routine slice verification).
 
-If unsure which framework the consumer project uses, run \`peaks test --json\` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command \`peaks test <file>\` already resolves the local binary for you (Windows-aware).`;
+Repo-defined \`test\` / \`test:*\` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).`;
 /**
  * Pure helper that returns the block. Exists as a function (not just an
  * exported constant) so future variants can take a runtime parameter

package/dist/services/ide/adapters/claude-code-adapter.d.ts

@@ -1,4 +1,14 @@
 import type { IdeAdapter } from '../ide-types.js';
+/**
+ * Resolve the absolute path of a Claude Code transcript jsonl by OUTER
+ * session id, searching `~/.claude/projects/**` recursively.
+ *
+ * Exported (slice 2026-09-10-context-audit-and-discipline, Slice A) so
+ * `peaks code context-audit` reuses THIS locator instead of re-implementing
+ * the recursive find. Returns `null` when the transcript does not exist —
+ * callers MUST treat that as "unavailable", never as an error.
+ */
+export declare function resolveClaudeTranscriptPath(outerSessionId: string, projectsDir?: string): string | null;
 /**
  * Resolve the currently-active Claude Code model id from a runtime env map.
  * Returns the first non-empty `CLAUDE_CODE_MODEL_ENV_VARS` value (trimmed), or

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

@@ -90,6 +90,20 @@ function findTranscriptJsonl(projectsDir, outerSessionId) {
     }
     return null;
 }
+/**
+ * Resolve the absolute path of a Claude Code transcript jsonl by OUTER
+ * session id, searching `~/.claude/projects/**` recursively.
+ *
+ * Exported (slice 2026-09-10-context-audit-and-discipline, Slice A) so
+ * `peaks code context-audit` reuses THIS locator instead of re-implementing
+ * the recursive find. Returns `null` when the transcript does not exist —
+ * callers MUST treat that as "unavailable", never as an error.
+ */
+export function resolveClaudeTranscriptPath(outerSessionId, projectsDir = join(homedir(), '.claude', 'projects')) {
+    if (typeof outerSessionId !== 'string' || outerSessionId.length === 0)
+        return null;
+    return findTranscriptJsonl(projectsDir, outerSessionId);
+}
 /** 1M-context window size in tokens (documented single choice: 1,000,000). */
 const ONE_MILLION_CONTEXT_TOKENS = 1_000_000;
 /** Safe-default (non-1M) context window size in tokens. */
@@ -483,7 +497,12 @@ export const CLAUDE_CODE_ADAPTER = {
         compactCommand: 'claude --compact',
         compactPathway: 'ide-native',
         postCompactDetectCommand: 'peaks code auto-compact --json',
-        readContextPercentFallback
+        readContextPercentFallback,
+        // Slice 2026-09-10-context-audit-and-discipline (Slice A): the vendor
+        // layout knowledge (`~/.claude/projects/**/<outerSessionId>.jsonl`)
+        // stays here; `peaks code context-audit` resolves it through the
+        // adapter registry, never by naming this adapter directly.
+        resolveTranscriptPath: (outerSessionId) => resolveClaudeTranscriptPath(outerSessionId),
     },
     // Slice #011: standards profile. Claude Code reads its constitution at
     // CLAUDE.md + module-level rules under .claude/rules/**. The values mirror

package/dist/services/ide/ide-types.d.ts

@@ -217,6 +217,21 @@ export interface IdeCompactProfile {
      * Added in slice 2026-09-02-vendor-neutral-context-probe.
      */
     readonly readContextPercentFallback?: (input: ContextPercentFallbackInput) => ContextPercentProbe | null;
+    /**
+     * Optional locator for the IDE's per-session transcript file (jsonl),
+     * keyed by the OUTER (harness) session id. `peaks code context-audit`
+     * (slice 2026-09-10-context-audit-and-discipline, Slice A) uses it to
+     * group the session's tool results by tool + short input key, so the
+     * generic audit service never learns any vendor's on-disk layout.
+     *
+     * Returns the absolute path, or `null` when the transcript does not
+     * exist. Adapters MUST NOT throw on a missing file — the audit treats
+     * `null` as `available: false` and continues.
+     *
+     * Adapters that do not opt in simply omit the field; the audit then
+     * reports `transcript-locator-unavailable`.
+     */
+    readonly resolveTranscriptPath?: (outerSessionId: string) => string | null;
 }
 /**
  * Input the generic `readContextPercent` reader passes to an adapter's

package/dist/services/memory/project-memory-service/parsers/frontmatter.d.ts

@@ -55,6 +55,11 @@ export declare function resolveMemoryKind(content: string): MemoryKindResolution
  * `parseStoredMemoryFile` (read path) and the reindex / ingest / doctor
  * classifiers consume this so there is exactly one kind-resolution rule
  * in the codebase.
+ *
+ * Tolerates a leading run of HTML-comment lines (e.g. the
+ * `<!-- peaks-memory:start -->` sediment marker) before the opening `---`
+ * fence. The closing fence is still required and body extraction is
+ * unchanged: the body is the text after the closing fence.
  */
 export declare function parseMemoryFrontmatter(content: string): ParsedMemoryFrontmatter;
 /** Which frontmatter field (or the filename) supplied a memory's name. */

package/dist/services/memory/project-memory-service/parsers/frontmatter.js

@@ -10,7 +10,10 @@
 //
 //   2. `parseStoredMemoryFile` — read-path side. Files in `.peaks/memory/`
 //      are stored as standard YAML frontmatter (name / description /
-//      metadata.type / metadata.sourceArtifact) followed by the body.
+//      metadata.type / metadata.sourceArtifact) followed by the body. A file
+//      may also open with HTML-comment lines (the `<!-- peaks-memory:start -->`
+//      sediment marker) before the frontmatter; `parseMemoryFrontmatter`
+//      skips that leading comment run before looking for the `---` fence.
 //
 // Both parsers share the `VALID_MEMORY_KINDS` allow-list (derived from the
 // canonical `PROJECT_MEMORY_KINDS` tuple in `../types.ts`) and the
@@ -83,23 +86,70 @@ export function resolveMemoryKind(content) {
     const parsed = parseMemoryFrontmatter(content);
     return parsed.kind;
 }
+/** Start of an HTML comment line, allowing leading horizontal whitespace. */
+const LEADING_COMMENT_OPEN = /^[ \t]*<!--/;
+/**
+ * Length of the leading run of blank lines and standalone HTML-comment lines.
+ *
+ * A stored memory may be written with the documented sediment marker
+ * (`<!-- peaks-memory:start -->`) — or any HTML comment — BEFORE its YAML
+ * frontmatter. This helper reports how much of the file to skip so the fence
+ * can still be found. At least one comment line must be present: a file that
+ * merely starts with blank lines is not treated as marker-prefixed, so the
+ * pre-existing (fence-at-byte-0) behaviour is preserved exactly.
+ */
+function leadingCommentPrefixLength(normalized) {
+    let offset = 0;
+    let sawComment = false;
+    for (;;) {
+        const rest = normalized.slice(offset);
+        const blank = /^[ \t]*\n/.exec(rest);
+        if (blank !== null) {
+            offset += blank[0].length;
+            continue;
+        }
+        const open = LEADING_COMMENT_OPEN.exec(rest);
+        if (open === null)
+            break;
+        const closeIndex = rest.indexOf('-->', open[0].length);
+        if (closeIndex < 0)
+            break;
+        const afterClose = closeIndex + '-->'.length;
+        const lineEnd = rest.indexOf('\n', afterClose);
+        if (lineEnd < 0)
+            break;
+        // Only a whole comment line counts; trailing prose after `-->` means the
+        // file does not open with a comment block.
+        if (rest.slice(afterClose, lineEnd).trim() !== '')
+            break;
+        offset += lineEnd + 1;
+        sawComment = true;
+    }
+    return sawComment ? offset : 0;
+}
 /**
  * Single parse surface for stored memory frontmatter. Both
  * `parseStoredMemoryFile` (read path) and the reindex / ingest / doctor
  * classifiers consume this so there is exactly one kind-resolution rule
  * in the codebase.
+ *
+ * Tolerates a leading run of HTML-comment lines (e.g. the
+ * `<!-- peaks-memory:start -->` sediment marker) before the opening `---`
+ * fence. The closing fence is still required and body extraction is
+ * unchanged: the body is the text after the closing fence.
  */
 export function parseMemoryFrontmatter(content) {
     const normalized = content.replace(/\r\n/g, '\n');
-    if (!normalized.startsWith('---\n')) {
+    const head = normalized.slice(leadingCommentPrefixLength(normalized));
+    if (!head.startsWith('---\n')) {
         return { hasFrontmatter: false, kind: { kind: null, source: 'none', rawKind: null }, frontmatter: '', body: normalized.trim() };
     }
-    const endIndex = normalized.indexOf('\n---\n', 4);
+    const endIndex = head.indexOf('\n---\n', 4);
     if (endIndex < 0) {
         return { hasFrontmatter: false, kind: { kind: null, source: 'none', rawKind: null }, frontmatter: '', body: normalized.trim() };
     }
-    const frontmatter = normalized.slice(4, endIndex);
-    const body = normalized.slice(endIndex + '\n---\n'.length).trim();
+    const frontmatter = head.slice(4, endIndex);
+    const body = head.slice(endIndex + '\n---\n'.length).trim();
     let name;
     let titleField;
     let description;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.35",
+  "version": "4.0.36",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -101,10 +101,10 @@
     "fzf": "^0.5.2",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.20",
-    "peaks-loop-mut": "0.1.33",
-    "peaks-loop-shared": "0.0.69",
-    "peaks-loop-shared-channel": "0.0.37"
+    "peaks-loop-internal-runtime": "0.0.21",
+    "peaks-loop-shared-channel": "0.0.38",
+    "peaks-loop-shared": "0.0.70",
+    "peaks-loop-mut": "0.1.34"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/skills/bee/peaks-qa/SKILL.md

@@ -210,6 +210,8 @@ Do not own product scope or implementation. Do not modify runtime configuration.
 
 QA sub-agents (qa / qa-business / qa-perf / qa-security) follow the same G7 metadata-only + G8.6 share protocol as RD. Detailed: `skills/peaks-code/references/context-governance.md`.
 
+**Large tool output (> 2 KB) MUST NOT be dumped into the orchestrator's context** — use `--summary` (`peaks doctor --summary`, `peaks memory list --summary`, `peaks request list --summary`) or write to a file and `Read` selectively. Rationale (measured, session 2026-09-07-session-245530): full-envelope dumps cost ≈ 40K tokens of a 68%-full 1M window. `--summary` is an additive view — no information is removed. → `skills/peaks-code/references/context-governance.md` §G0.
+
 → see `references/qa-context-governance.md` for the full G7 / G8.6 / G9 protocol + QA sub-agent prompt template.
 
 ## References

package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md

@@ -59,6 +59,18 @@ What the sub-agent **MUST** still do:
 
 If `--type` is `docs` or `chore`, return `{"status":"skipped","reason":"type=<type>"}` and exit — there is no acceptance surface to plan tests for.
 
+## Final report cap (mandatory, slice 2026-09-10-context-audit-and-discipline)
+
+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
+- any blocker
+
+Do NOT paste file contents, full tool output, or logs into the report. **Rationale (measured, session 2026-09-07-session-245530):** 20 sub-agent final reports ≈ 60 KB ≈ 15K tokens of the orchestrator's window — the report is an index into the artifact, not a copy of it. This rule is also machine-injected into every dispatch prompt (`REPORT_CAP_BLOCK` in `src/services/context/build-dispatch-system-prompt.ts`); this doc and that constant MUST stay in lockstep.
+
 ## Test Tool Detection (mandatory)
 
 The dispatch CLI (`peaks sub-agent dispatch`) automatically prepends a Test Tool Detection block to every sub-agent prompt — telling the sub-agent to read `package.json#scripts.test` first and use the project-local runner (`./node_modules/.bin/<runner>` or `pnpm test -- <file>`). NEVER use `npx <runner>`. This rule is machine-injected, not a prompt ritual — every sub-agent gets it including rd/qa/ui/txt/sc.

package/skills/bee/peaks-rd/SKILL.md

@@ -239,6 +239,8 @@ The main RD loop MUST call `peaks job karpathy-cost-check` after every `peaks re
 
 RD sub-agent prompt template MUST include the G7 path convention + G8.6 share protocol. Detailed protocol: `skills/peaks-code/references/context-governance.md`.
 
+**Large tool output (> 2 KB) MUST NOT be dumped into the orchestrator's context** — use `--summary` (`peaks memory reindex --summary`, `peaks memory list --summary`, `peaks doctor --summary`, `peaks request list --summary`) or write to a file and `Read` selectively. Rationale (measured, session 2026-09-07-session-245530): 4 full `reindex --json` dumps ≈ 40K tokens of a 68%-full 1M window. `--summary` is an additive view — no information is removed. → `skills/peaks-code/references/context-governance.md` §G0.
+
 → see `references/rd-context-governance.md` for the full G7 / G8.6 / G9 protocol + RD sub-agent prompt template.
 
 ## Sub-stages (Plan 3 — strategic + tactical split)

package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md

@@ -113,6 +113,20 @@ Any RD/QA/SC sub-agent dispatched by `peaks sub-agent dispatch --from-dag` (or b
 
 ---
 
+## Final report cap (mandatory, slice 2026-09-10-context-audit-and-discipline)
+
+Your FINAL report to the parent MUST be **≤ 40 lines and ≤ 2 KB**. Write any longer detail into the artifact file you already own (registered via `--write-artifact`); 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
+- any blocker
+
+Do NOT paste file contents, full tool output, or logs into the report. **Rationale (measured, session 2026-09-07-session-245530):** 20 sub-agent final reports ≈ 60 KB ≈ 15K tokens of the orchestrator's window — the report is an index into the artifact, not a copy of it. This rule is also machine-injected into every dispatch prompt (`REPORT_CAP_BLOCK` in `src/services/context/build-dispatch-system-prompt.ts`); this doc and that constant MUST stay in lockstep.
+
+---
+
 ## Test Tool Detection (mandatory)
 
 The dispatch CLI (`peaks sub-agent dispatch`) automatically prepends a Test Tool Detection block to every sub-agent prompt — telling the sub-agent to read `package.json#scripts.test` first and use the project-local runner (`./node_modules/.bin/<runner>` or `pnpm test -- <file>`). NEVER use `npx <runner>`. This rule is machine-injected, not a prompt ritual — every sub-agent gets it including rd/qa/ui/txt/sc.

package/skills/bee/peaks-txt/SKILL.md

@@ -283,6 +283,8 @@ Reference: `references/context-capsule.md`.
 
 > peaks-txt is the TXT reducer; it sees the metadata-only view from G7 + the share entries from G8. The TXT handoff summarizes the slice at the slice-close gate. Detailed: `skills/peaks-code/references/context-governance.md`.
 
+**Large tool output (> 2 KB) MUST NOT be dumped into the orchestrator's context** — use `--summary` (`peaks request list --summary`, `peaks memory list --summary`, `peaks memory reindex --summary`) or write to a file and `Read` selectively. Rationale (measured, session 2026-09-07-session-245530): full-envelope dumps cost ≈ 40K tokens of a 68%-full 1M window. `--summary` is an additive view — no information is removed. → `skills/peaks-code/references/context-governance.md` §G0.
+
 ### G8 — TXT reducer sees share entries on completion
 
 When TXT reduces a batch, it consumes:

package/skills/bee/peaks-ui/SKILL.md

@@ -333,6 +333,8 @@ Do not own backend architecture, non-UI implementation, runtime hook installatio
 
 UI sub-agents follow the same G7 metadata-only + G8.6 share protocol. UI artifacts are large binary-ish; the 1MB artifact size limit (G7.3) applies. Detailed: `skills/peaks-code/references/context-governance.md`.
 
+**Large tool output (> 2 KB) MUST NOT be dumped into the orchestrator's context** — use `--summary` (`peaks request list --summary`, `peaks memory list --summary`) or write to a file and `Read` selectively. Rationale (measured, session 2026-09-07-session-245530): full-envelope dumps cost ≈ 40K tokens of a 68%-full 1M window. `--summary` is an additive view — no information is removed. → `skills/peaks-code/references/context-governance.md` §G0.
+
 ### G7 — UI sub-agent protocol
 
 1. Write design draft / component scaffold to `.peaks/_sub_agents/<sid>/artifacts/<rid>-ui-001.md` (size ≤ 1MB).

package/skills/peaks-code/SKILL.md

@@ -310,6 +310,14 @@ After final validation, refresh project-local standards via `peaks standards ini
 
 Main LLM reducer sees metadata-only view (~200 chars/sub-agent); on-demand `Read` for full content. Threshold table: 50% soft warn, 75% `CONTEXT_NEAR_LIMIT`, 80% hard reject (CLI + hook double-guard). → `references/context-governance.md`.
 
+## Large tool output discipline (BLOCKING — slice 2026-09-10-context-audit-and-discipline)
+
+> **Hard rule.** Any tool output larger than **2 KB** MUST NOT be dumped into the orchestrator's own context. Use `--summary` (bounded counts + names-of-first-N, ≤ 2 KB) when the command offers it — `peaks memory reindex --summary`, `peaks memory list --summary`, `peaks doctor --summary`, `peaks request list --summary` — otherwise write the output to a file and `Read` only the slice you need. The default envelopes are unchanged; `--summary` is strictly opt-in.
+>
+> **Why (measured, not cargo-cult).** In session `2026-09-07-session-245530` the orchestrator spent ~68% of a 1M window on its OWN context. Two offenders dominated: 4 × dumping a full `peaks memory reindex --json` unclassified array ≈ 160 KB ≈ 40K tokens, and 20 × sub-agent final reports ≈ 60 KB ≈ 15K tokens. Neither was dispatch boilerplate — both were the orchestrator reading things it did not need in full. `peaks code context-audit` now measures this per group (`{tool, key, bytes, pctOfTotal, count}`); run it when the window feels heavy.
+>
+> **Quality guard.** `--summary` removes no information — it is an additive view. Every path, name and count stays on disk and is re-readable by re-running the command without the flag. Never silently drop data; shrink the in-context copy instead.
+
 ## Sub-agent cross-batch signal — G8.4 share / shared-read / await
 
 Three CLI primitives: `peaks sub-agent share / shared-read / await` (last-write-wins, ≤ 1KB warn / ≥ 64KB reject). Channel gitignored under `.peaks/_sub_agents/<sessionId>/shared/`.

package/skills/peaks-code/references/context-governance.md

@@ -3,6 +3,35 @@
 > Slice #010 (G7 + G8 + G9 context-governance push).
 > See: `.peaks/memory/sub-agent-context-minimal-occupation.md` + `sub-agent-shared-channel-cross-completion.md` for the red lines.
 
+## G0 — orchestrator large-tool-output discipline (slice 2026-09-10-context-audit-and-discipline)
+
+### The measurement (session `2026-09-07-session-245530`, ~68% of a 1M window)
+
+The real token cost is the ORCHESTRATOR's own context — not dispatch boilerplate:
+
+| Offender | Volume | Cost |
+|---|---|---|
+| 4 × full `peaks memory reindex --json` unclassified array | ≈ 160 KB | ≈ 40K tokens |
+| 20 × sub-agent final reports | ≈ 60 KB | ≈ 15K tokens |
+| several `cat` of large docs | ≈ 15 KB | ≈ 4K tokens |
+
+`peaks code context-now` reports a RATIO only. `peaks code context-audit --project <root> --json` reports WHAT fills the window — top-N groups of `{tool, key, bytes, pctOfTotal, count}` — so the next session can name the offender instead of guessing. Read-only, fail-soft (`available: false` + reason; never blocks, never exits non-zero).
+
+### The rule (BLOCKING)
+
+- Tool output **> 2 KB** MUST NOT be dumped into the orchestrator's context.
+- Prefer the opt-in `--summary` flag, which emits counts + names-of-first-N (≤ 2 KB) instead of the full array:
+  - `peaks memory reindex --summary`
+  - `peaks memory list --summary`
+  - `peaks doctor --summary` (JSON envelope)
+  - `peaks request list --summary`
+- When a command has no `--summary`, write the output to a file and `Read` only the needed slice (offset/limit), or pipe through a filter before it reaches the orchestrator.
+- Default (no flag) envelopes are byte-identical to before — `--summary` is strictly opt-in, so back-compat is preserved.
+
+### Quality guard (binding)
+
+`--summary` is an ADDITIVE view. It removes no information: every path, name and count remains on disk and is re-readable by re-running the same command without the flag. Silently dropping data is forbidden; shrinking the in-context copy is the goal. The sub-agent FINAL report cap (≤ 40 lines / 2 KB, detail in the artifact the parent can `Read`) follows the same principle — see the dispatch prompt's `## Final report cap (mandatory)` block.
+
 ## G7 — sub-agent context minimal-occupation (metadata-only + 按需 Read)
 
 ### Path convention

package/skills/peaks-doctor/SKILL.md

@@ -47,6 +47,8 @@ If a doctor finding requires a code change, the workflow hands off to `peaks-rd`
 - `peaks openspec from-doctor` — L3.3 proposal generator
 - `peaks openspec validate` — gate a draft proposal
 
+**Large tool output (> 2 KB) MUST NOT be dumped into the orchestrator's context.** `peaks doctor` returns ~69 checks — use `peaks doctor --summary` (counts + names-of-first-N, ≤ 2 KB) and re-run without the flag only for the specific check you need to read. Rationale (measured, session 2026-09-07-session-245530): full-envelope dumps cost ≈ 40K tokens of a 68%-full 1M window; `--summary` is an additive view, so no information is removed.
+
 ## Boundaries
 
 - The doctor is read-only. It does NOT modify code, fix bugs, or clean up sessions.