peaks-loop 4.0.35 → 4.0.37

package/dist/services/workspace/claude-settings-template.js

@@ -14,10 +14,12 @@
  * the in-memory template byte-for-byte.
  *
  * One matcher is emitted:
- *   1. `Write|Edit|MultiEdit` — a node one-liner that path-matches
- *      `.peaks/_runtime/` and `.peaks/_runtime/<sessionId>/`. Exits 0 (allow)
- *      for those paths, non-zero (deny → fall through to gate) for
- *      everything else.
+ *   1. `Write|Edit|MultiEdit` — a `node <script>` handler that runs the
+ *      path gate shipped at `src/services/hooks/write-gate.js`. Exits 0
+ *      (allow) for the paths the gate skips, exit 1 (deny → fall through to
+ *      gate) for everything else. TEMPLATE_VERSION 1.6.0 moved the decision
+ *      out of an inlined `node -e "<js>"` one-liner, whose escaping was
+ *      bash-specific and therefore could not take a platform `shell` pin.
  *
  * The previous `Bash` matcher (which whitelisted a fixed `peaks
  * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
@@ -31,6 +33,9 @@
  * consumer project's `.claude/settings.json` and which exits 0
  * silently for any command not guarded by a registered SOP gate.
  */
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveHookShell, resolveHookSpec } from '../skills/hooks-codegate-superpowers.js';
 export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
 /**
  * Informational version of the offline template shape. Bumped when the
@@ -55,8 +60,26 @@ export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
  *           gate). The existing Write|Edit|MultiEdit matcher is
  *           preserved. The new matcher's exit code is the load-bearing
  *           signal: 0 = allow, 2 = block (with stderr BLOCKED reason).
+ *   1.4.0 — added the `peaks gate enforce` `Bash` PreToolUse entry. It
+ *           lives here (machine-local, gitignored file) rather than in
+ *           the committed `.claude/settings.json` because its `shell`
+ *           is machine-specific: on Windows the default Git-Bash shell
+ *           force-allocates a console window on every Bash tool call.
+ *           This template is the second writer of that file, so it must
+ *           emit the entry too — otherwise `peaks workspace init` would
+ *           overwrite whatever `peaks hooks install` put there.
+ *   1.5.0 — pinned the same platform `shell` on the `peaks code
+ *           gate-step-08` handler. It runs on the same `Bash` matcher,
+ *           so leaving it un-pinned left the console-window defect in
+ *           place for half of every Bash tool call.
+ *   1.6.0 — the `Write|Edit|MultiEdit` handler no longer inlines its
+ *           JavaScript as `node -e "<js>"`. It invokes the shipped script
+ *           `src/services/hooks/write-gate.js` instead, so the command
+ *           string carries no shell-escaped payload at all and the handler
+ *           can take the same platform `shell` pin as its siblings. The
+ *           decision itself is a verbatim relocation — see that file.
  */
-export const TEMPLATE_VERSION = '1.3.0';
+export const TEMPLATE_VERSION = '1.6.0';
 /**
  * Compare two serialized template strings for semantic equivalence.
  *
@@ -124,70 +147,70 @@ function sameHooksArray(a, b) {
     for (let i = 0; i < a.length; i += 1) {
         const ha = a[i];
         const hb = b[i];
-        if (ha.type !== hb.type || ha.command !== hb.command) {
+        // `shell` participates in the comparison: it is machine-specific (see
+        // `resolveHookShell`), so a file written on one platform must be
+        // recognized as drifted on the other instead of silently kept.
+        if (ha.type !== hb.type || ha.command !== hb.command || ha.shell !== hb.shell) {
             return false;
         }
     }
     return true;
 }
 /**
- * Wrap an inner JavaScript payload as a shell-evaluable `node -e "..."`
- * one-liner. The returned string is what Claude Code writes verbatim
- * into `.claude/settings.local.json` under the `command` field. Per
- * Node.js docs (https://nodejs.org/api/process.html#processargv), when
- * using `-e` there is no script-file slot, so `process.argv[1]` is the
- * first user-passed extra argument. This is consistent across Windows,
- * macOS, and Linux.
+ * This module's own directory — `<root>/src/services/workspace` in the
+ * source tree, `<root>/dist/services/workspace` in a build.
  *
- * Every `"` character in the inner JS must be JSON-escaped as `\\"`
- * so that the surrounding wrapper `node -e "..."` parses correctly:
- * the shell sees the escape and passes a literal `"` to Node. A
- * single missed escape closes the wrapper early and the entire hook
- * regresses to the bash-syntax-error class of bug.
+ * Anchored on the running module rather than on `process.argv[1]`: the
+ * same reason `daemon-supervisor.ts` documents — `argv[1]` is a different
+ * file in each way the CLI is entered (`bin/peaks.js`, `src/cli/index.ts`
+ * under tsx, `dist/cli/index.js` when invoked directly), whereas the
+ * module's own location is the one fact that is always true.
+ */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+/**
+ * Absolute path of the shipped Write|Edit|MultiEdit gate script.
+ *
+ * `write-gate.js` is a plain `.js` (not a compiled `.ts`) precisely so this
+ * single relative filename resolves in BOTH trees: `src/services/hooks/` for
+ * `tsx` / vitest, `dist/services/hooks/` for an installed consumer (copied by
+ * `scripts/copy-templates.mjs`; the `dist/**` `*.js` glob in
+ * `package.json#files` already ships it).
  *
- * @param js Inner JavaScript payload. Must be a single statement or a
- *           sequence of statements joined with `;`. The wrapper does
- *           not insert any `;` between the payload and the closing
- *           `"` because Node accepts a trailing expression with `;`
- *           already terminated by the payload itself.
+ * Separators are normalized to `/` so the emitted command contains no
+ * backslash at all. That is what makes the handler shell-agnostic: bash
+ * reduces `\X` inside `"..."` and PowerShell escapes with a backtick, so any
+ * backslash in the string is one dialect's problem waiting to happen.
  */
-function wrapAsNodeOneLiner(js) {
-    // Only `"` needs JSON-escaping: the wrapper uses double quotes, so an
-    // unescaped inner `"` would close the wrapper prematurely. Backslashes
-    // do NOT need escaping here — bash inside a `"..."` wrapper reduces
-    // `\\` to `\`, so any `\X` in the inner JS reaches Node as `\X`,
-    // which is what regex literals like `/\.peaks\//` need. Adding a
-    // second `\\` → `\\` pass would double-escape backslashes and break
-    // every regex literal the inner JS contains.
-    const escaped = js.replace(/"/g, '\\"');
-    return `node -e "${escaped}"`;
+export function writeGateScriptPath() {
+    return resolve(MODULE_DIR, '..', 'hooks', 'write-gate.js').replaceAll('\\', '/');
 }
 /**
- * Build the Write|Edit|MultiEdit matcher command. The command reads
- * the candidate file path from argv[2] and exits 0 iff the path
- * contains `.peaks/_runtime/` or `.peaks/_runtime/<sessionId>/` (the change-id
- * segment is the next path component after `.peaks/`). All other
- * paths exit 1 so the gate fires normally.
+ * Build the Write|Edit|MultiEdit matcher command.
  *
- * The matcher is intentionally narrow: it only fires for tools that
- * take a `file_path` (Write/Edit/MultiEdit) and for the Bash
- * subcommand allow-list. It does NOT silently allow arbitrary paths
- * under `.peaks/_runtime/<sessionId>/` — only those matching the documented
- * pattern. Future slice work can broaden the allow-list if the
- * peaks-code workflow needs more paths.
+ * TEMPLATE_VERSION 1.6.0: `node "<script>"` with NO inline payload. The
+ * decision lives in `src/services/hooks/write-gate.js` and was relocated
+ * there verbatim. Because there is nothing left to escape, this handler is
+ * shell-dialect-independent and can carry the same platform `shell` pin as
+ * its Bash siblings (see `resolveHookShell`).
  */
 function buildWriteHookCommand() {
-    // Path-matching: allow when the path contains `.peaks/_runtime/`
-    // OR when the second `.peaks/` segment starts with anything that
-    // looks like a change-id (kebab-case slug). Exit 0 for allow, exit
-    // 1 for deny. The candidate path arrives on `process.argv[1]` per
-    // Node.js argv layout under `-e` (cross-platform consistent).
-    const js = 'const p=process.argv[1]||"";' +
-        'if(p.includes(".peaks/_runtime/"))process.exit(0);' +
-        'const m=p.match(/\\.peaks\\/([a-z0-9][a-z0-9.-]*)\\//);' +
-        'if(m&&m[1]&&m[1]!=="_runtime"&&m[1]!=="_dogfood"&&m[1]!=="_sub_agents"&&m[1]!=="memory"&&m[1]!=="sops"&&m[1]!=="retrospective"&&m[1]!=="project-scan"&&m[1]!=="perf-baseline")process.exit(0);' +
-        'process.exit(1)';
-    return wrapAsNodeOneLiner(js);
+    return `node "${writeGateScriptPath()}"`;
+}
+/**
+ * TEMPLATE_VERSION 1.4.0 — the SOP gate-enforce handler, read from the same
+ * canonical hook spec `peaks hooks install` uses. Deriving it here (rather
+ * than re-typing the literal) is what keeps the two writers of this file
+ * byte-compatible: `templateContentMatches` compares the `command` string,
+ * so any drift would make every `peaks workspace init` rewrite the file and
+ * drop whatever `peaks hooks install` had merged in.
+ */
+function buildGateEnforceHandler() {
+    const spec = resolveHookSpec('claude-code');
+    return {
+        type: 'command',
+        command: spec.hookEnforceCommand,
+        ...(spec.hookEnforceShell !== undefined ? { shell: spec.hookEnforceShell } : {})
+    };
 }
 /**
  * Build the full template object. The shape is the subset of Claude
@@ -202,6 +225,14 @@ function buildWriteHookCommand() {
  * `.claude/settings.json` (not `.claude/settings.local.json`).
  */
 export function buildClaudeSettingsLocalJson() {
+    // TEMPLATE_VERSION 1.6.0 — the write handler can now be shell-pinned for the
+    // same Windows reason as the two Bash handlers below: a shell-form command is
+    // executed by Git Bash / MSYS2, which force-allocates a console window on
+    // every matching tool call. It could NOT take the pin while its payload was
+    // inlined JavaScript, because PowerShell does not perform bash's backslash
+    // reduction and would have corrupted the payload. `undefined` on POSIX omits
+    // the key entirely.
+    const writeShell = resolveHookShell();
     return {
         hooks: {
             PreToolUse: [
@@ -210,7 +241,8 @@ export function buildClaudeSettingsLocalJson() {
                     hooks: [
                         {
                             type: 'command',
-                            command: buildWriteHookCommand()
+                            command: buildWriteHookCommand(),
+                            ...(writeShell !== undefined ? { shell: writeShell } : {})
                         }
                     ]
                 },
@@ -223,12 +255,22 @@ export function buildClaudeSettingsLocalJson() {
                     // 2 = block (stderr contains the BLOCKED: ... reason).
                     // The existing Write|Edit|MultiEdit matcher is preserved.
                     matcher: 'Bash',
-                    hooks: [
-                        {
-                            type: 'command',
-                            command: buildBashGateStep08Command()
-                        }
-                    ]
+                    hooks: [buildBashGateStep08Handler()]
+                },
+                {
+                    // TEMPLATE_VERSION 1.4.0 — SOP gate enforcement. Lives in this
+                    // machine-local file (not the committed settings.json) because
+                    // `shell` is machine-specific; see the version history above and
+                    // `resolveHookShell`.
+                    //
+                    // It sits in its own matcher group on purpose: a group counts as
+                    // peaks-managed only when EVERY handler in it carries a peaks
+                    // sentinel, and the `peaks code gate-step-08` handler above does
+                    // not. Sharing a group with it would make the whole group
+                    // unmanaged, so `peaks hooks install` would append a second Bash
+                    // group and the gate would run twice per Bash call.
+                    matcher: 'Bash',
+                    hooks: [buildGateEnforceHandler()]
                 }
             ]
         }
@@ -244,11 +286,21 @@ export function buildClaudeSettingsLocalJson() {
  * re-running `peaks workspace init` on a project that already has the
  * Bash hook is a no-op (already-current).
  */
-function buildBashGateStep08Command() {
+function buildBashGateStep08Handler() {
     // The hook receives the tool call on stdin. We ignore stdin and
     // delegate entirely to `peaks code gate-step-08`, which reads
     // .peaks/_runtime/<sessionId>/job-shape.json and last-prompt.txt.
     // `${CLAUDE_PROJECT_DIR}` resolves to the consumer project's root
     // (Claude Code's standard convention).
-    return 'peaks code gate-step-08 --project "${CLAUDE_PROJECT_DIR}"';
+    //
+    // TEMPLATE_VERSION 1.5.0 — shell-pinned on Windows for the same reason
+    // as the gate-enforce handler below: this runs on the same `Bash`
+    // matcher, so a shell-form command is executed by Git Bash / MSYS2,
+    // which force-allocates a console window on every Bash tool call.
+    const shell = resolveHookShell();
+    return {
+        type: 'command',
+        command: 'peaks code gate-step-08 --project "${CLAUDE_PROJECT_DIR}"',
+        ...(shell !== undefined ? { shell } : {})
+    };
 }

package/dist/services/workspace/workspace-claude-settings-materializer.js

@@ -89,7 +89,11 @@ export async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks)
         try {
             const { readFile } = await import('node:fs/promises');
             const existing = await readFile(settingsPath, 'utf8');
-            if (existing === serialized) {
+            // Structural comparison (not a byte comparison): `peaks hooks
+            // install` also writes this file, through a different serializer, so
+            // an equal hooks tree must be recognized as current or every init
+            // would rewrite the file and drop the installer's entries.
+            if (templateContentMatches(serialized, existing)) {
                 action = 'already-current';
             }
             else {

package/dist/services/workspace/workspace-service.js

@@ -3,7 +3,31 @@ import { existsSync, lstatSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { isDirectory } from 'peaks-loop-shared/fs';
 import { getSessionIdCanonical, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
+import { updateCallerBindingSessionId } from '../session/caller-binding-service.js';
+import { resolveCallerProjection } from '../session/resolve-caller-id.js';
 import { normalizePath } from '../../shared/path-utils.js';
+/**
+ * Slice 2026-09-10 (rid=rebind-must-update-caller-binding): repoint the
+ * calling process's own per-caller binding at the session id this init just
+ * bound. `getSessionIdCanonical` reads `callers/<callerId>.json` FIRST, so a
+ * binding left behind by an earlier session shadows every explicit rebind.
+ *
+ * Best-effort: an unresolvable callerId (`PEAKS_CALLER_NOT_RESOLVED`, e.g. a
+ * stock shell with no IDE adapter) means there is no binding file to
+ * repoint, and `session.json` alone answers both resolvers.
+ *
+ * @returns `true` when a binding file existed and was repointed.
+ */
+function rebindCurrentCallerBinding(projectRoot, sessionId) {
+    let callerId;
+    try {
+        callerId = resolveCallerProjection({ projectRoot, env: process.env }).callerId;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return false;
+    }
+    return updateCallerBindingSessionId(projectRoot, callerId, sessionId);
+}
 /**
  * Slice 2026-06-29-change-id-root-removal: list the immediate children of
  * `.peaks/` so the legacy sibling-dir guard can enumerate date-stamped
@@ -299,6 +323,15 @@ export async function initWorkspace(options) {
         // Either: existing session dir is empty (true leftover, no user data),
         // or the caller explicitly authorised a rebind. Overwrite.
         setCurrentSessionBinding(options.projectRoot, options.sessionId);
+        // Slice 2026-09-10 (rid=rebind-must-update-caller-binding): an
+        // explicit rebind must ALSO repoint this caller's per-caller binding.
+        // `getSessionIdCanonical` prefers `callers/<callerId>.json`, so leaving
+        // it untouched shadowed the rebind for every command resolving through
+        // it (session checkpoint / 24h-mode wrote into the stale session dir)
+        // while `getCurrentSessionId` (session.json) reported the new one.
+        // Only THIS caller's binding is repointed — a second caller keeps its
+        // own session by design.
+        rebindCurrentCallerBinding(options.projectRoot, options.sessionId);
         bound = true;
     }
     // Slice 2026-06-16-peaks-code-auto-scaffold (RD#7):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.35",
+  "version": "4.0.37",
   "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-mut": "0.1.35",
+    "peaks-loop-internal-runtime": "0.0.22",
+    "peaks-loop-shared-channel": "0.0.39",
+    "peaks-loop-shared": "0.0.71"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/scripts/copy-templates.mjs

@@ -60,6 +60,18 @@ const targets = [
     src: join(packageRoot, 'src/services/skillhub/migrations'),
     dest: join(packageRoot, 'dist/services/skillhub/migrations'),
     extensions: ['.sql']
+  },
+  {
+    // Slice c5-write-hook-exec-form: the Write|Edit|MultiEdit PreToolUse gate
+    // emitted by `peaks workspace init` is invoked as `node <path>`, and the
+    // path is resolved relative to this module — `dist/services/hooks/` in an
+    // installed consumer, `src/services/hooks/` under tsx. A plain `.js` asset
+    // (not a `.ts` compiled by tsc) is what lets ONE relative filename be valid
+    // in both trees. Without this copy the hook would be a broken path in every
+    // installed consumer while every test in this repo still passed.
+    src: join(packageRoot, 'src/services/hooks'),
+    dest: join(packageRoot, 'dist/services/hooks'),
+    extensions: ['.js']
   }
 ];
 

package/scripts/sync-version.mjs

@@ -18,6 +18,26 @@ writeFileSync(
   `export const CLI_VERSION = ${JSON.stringify(version)};\n`,
 );
 
+// Slice 2026-09-11 (runtime-version-lockstep) — sync RUNTIME_VERSION.
+// `packages/peaks-loop-internal-runtime/src/index.ts` declares
+// `RUNTIME_VERSION` under a comment stating it tracks the peaks-loop root
+// version, but nothing wrote it: v4.0.37 was tagged with the constant still
+// at 4.0.36 and publish.yml's gate-cli-version step aborted before npm
+// publish. The literal is replaced in place, single-quoted — the exact
+// shape the gate greps — because the file also holds the package's public
+// exports and must never be regenerated wholesale. A literal we cannot
+// find throws instead of no-op'ing: that silence is how the drift reached CI.
+const runtimeIndexPath = resolve('packages/peaks-loop-internal-runtime/src/index.ts');
+const runtimeIndex = readFileSync(runtimeIndexPath, 'utf8');
+const runtimeDecl = /(export const RUNTIME_VERSION = ')[^']*(';)/;
+if (!runtimeDecl.test(runtimeIndex)) {
+  throw new Error(`${runtimeIndexPath}: could not find "export const RUNTIME_VERSION = '...';"`);
+}
+const syncedRuntimeIndex = runtimeIndex.replace(runtimeDecl, `$1${version}$2`);
+if (syncedRuntimeIndex !== runtimeIndex) {
+  writeFileSync(runtimeIndexPath, syncedRuntimeIndex);
+}
+
 // 2026-07-23 follow-up (peaks-publish-stale fix, AC6): the shared
 // bump used to live here, gated on `PEAKS_AUTO_BUMP_SHARED === '1'`.
 // That gate was the Layer 2 root cause: publish.yml set the env on

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

@@ -235,6 +235,16 @@ triggered for this intent.
 5. LLM picks one recommendation (★ marker) with reasoning block.
 6. **Mandatory ⚠️ catch gate** — user explicitly acks / picks alt / rejects + reason.
 
+**When the scan cannot be performed, the sub-step is SKIPPED — never fabricated.** The lookups behind
+this scan are stubs in the current build: they return synthetic fragments marked internally as
+synthetic. When the scan runs on a synthetic result it **refuses** — `ok:false`,
+`BEST_PRACTICE_SCAN_SYNTHETIC_LOOKUP`, exit 1 — and prints no recommendation, no comparison table and
+no ⚠️ catch gate, because there is nothing real for the user to judge. Record the sub-step as
+**skipped with reason `synthetic-lookup`** and carry on; do not synthesise a recommendation to satisfy
+the gate. `--intent <text>` is required (the business goal, not the project path) — omitting it is
+`BEST_PRACTICE_SCAN_INTENT_REQUIRED`, also exit 1. A real scan renders the full table and the gate
+normally; wiring the real Context7 / WebSearch lookup is a future slice.
+
 **Out of scope for this sub-step:**
 - ❌ No changes to RD dispatch Karpathy prose (Step 3 unchanged)
 - ❌ No changes to QA / SC / TXT skills
@@ -310,6 +320,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/browser-workflow.md

@@ -105,7 +105,7 @@ If the page redirects to a login challenge:
 
 ## Sensitive data sanitization
 
-Never persist any of the following in `.peaks/_runtime/<session-id>/**` artifacts:
+**Default: never persist.** Never persist any of the following in `.peaks/_runtime/<session-id>/**` artifacts:
 
 - Login URLs, redirect URLs, OAuth callback URLs containing tokens or state.
 - Cookies, request or response headers, session tokens, storage state, QR payloads.
@@ -113,6 +113,15 @@ Never persist any of the following in `.peaks/_runtime/<session-id>/**` artifact
 - Raw browser state, browser traces.
 - Screenshots or logs containing PII, SSO challenge content, or MFA material.
 
+**The one exception, and it is narrow.** `peaks web login --profile <name>` persists a Playwright `storageState.json` to `~/.peaks/web-profiles/<name>/`. It is allowed only when the user explicitly asks for a persistent login. An LLM must never choose it on its own initiative, and it is never part of a default workflow. That name at that path is the whole of the exception: **no other artifact may hold these values, anywhere** — not under `.peaks/_runtime/`, not elsewhere in the project tree, not elsewhere under the user's home. This file is written outside the project tree and outside git; that is a property of this one path, not a licence to persist these values wherever the project tree happens to end.
+
+**Two named carve-outs, so the rule above can be read literally.**
+
+1. **The staging file.** The state is published atomically, which means writing it to a staging file **in the same profile directory** (`0600`) and renaming it into place. The staging name is **per-run** (`storageState.json.<pid>.staging`) so two concurrent logins cannot overwrite each other's in-flight bytes — the rule sanctions *a* staging file, and that is the only form it takes. It is sanctioned **only** while a publish is in flight: it must be deleted on every failure path, must never outlive the command that created it, and nothing may ever read it as a profile. A single non-atomic write is **not** an acceptable alternative — it truncates the previous session before writing the new one, so a failed write destroys a working login and the caller is told nothing happened.
+2. **The browser's own profile directory.** A headed Chromium writes its live session cookies to an **ephemeral profile directory the browser manages itself** (under the OS temp directory for the duration of the session, normally removed on close). This is not something a login flow can prevent and it is not what this rule is about — but it is a place those values are held, so it is named here rather than left implied. Launching a headed browser to log in is therefore **never zero-exposure**, and anyone weighing the exception above should weigh that too.
+
+**The risk, stated plainly.** That file holds live session cookies and tokens for the sites that were logged into. Any process running as this user can read it. It does not expire with the browser session, and it survives until it is deleted. Deleting `~/.peaks/web-profiles/<name>/` removes what the tool stored — it does not revoke the session at the site, so log out there as well if the account matters. Only persist a login for an account that may safely stay logged in on this machine.
+
 Redact sensitive values before retention. Store evidence as sanitized observations (e.g., "user reached settings page; first 3 list items had a missing-image regression") rather than raw captures.
 
 ## Fallback when Playwright MCP is not installed

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.