peaks-loop 4.0.34 → 4.0.36

package/dist/services/memory/project-memory-service/types.d.ts

@@ -1,4 +1,34 @@
-export type ProjectMemoryKind = 'project' | 'rule' | 'decision' | 'reference' | 'feedback' | 'convention' | 'module' | 'lesson';
+/**
+ * Canonical memory-kind vocabulary — the single source of truth.
+ *
+ * The union type, the accepted-kind set in the frontmatter parser, the
+ * hot/warm tier map below, `KIND_ORDER` in the reindex view, and the CLI
+ * `--kind` help text all derive from this tuple. Adding a kind here is the
+ * only edit required; TypeScript then forces `MEMORY_KIND_TIER` to cover it.
+ *
+ * Slice 2026-09-10-memory-vocab-and-rotate (E): the original 8 kinds are
+ * unchanged. The 13 appended kinds were observed on disk with real values
+ * that the index schema rejected (`peaks memory reindex` reported them as
+ * `unrecognized kind value`). Accepting them moves those files into the
+ * index; files with no kind field at all stay reported as unclassified.
+ */
+export declare const PROJECT_MEMORY_KINDS: readonly ["project", "rule", "decision", "reference", "feedback", "convention", "module", "lesson", "bug", "investigation", "technical-pattern", "project-rule", "design", "handoff", "session-handoff", "project-todo", "publish-closure", "project-closure", "slice-closure", "slice-pilot-findings", "sediment"];
+export type ProjectMemoryKind = (typeof PROJECT_MEMORY_KINDS)[number];
+/** Hot kinds keep their body in the always-available index; warm kinds are
+ *  indexed with the same entry shape but read on demand. */
+export type MemoryKindTier = 'hot' | 'warm';
+/**
+ * Hot/warm tier per kind. Insertion order IS the deterministic section order
+ * used by the generated `MEMORY.md` (`KIND_ORDER` in `index/reindex.ts`),
+ * so this object's key order is load-bearing — append new kinds at the end
+ * of their tier block rather than reshuffling existing entries.
+ *
+ * The `Record<ProjectMemoryKind, MemoryKindTier>` annotation makes a missing
+ * tier a compile error whenever `PROJECT_MEMORY_KINDS` grows.
+ */
+export declare const MEMORY_KIND_TIER: Record<ProjectMemoryKind, MemoryKindTier>;
+export declare const HOT_MEMORY_KINDS: readonly ProjectMemoryKind[];
+export declare const WARM_MEMORY_KINDS: readonly ProjectMemoryKind[];
 export type ExtractedProjectMemory = {
     title: string;
     kind: ProjectMemoryKind;

package/dist/services/memory/project-memory-service/types.js

@@ -6,4 +6,79 @@
 // from here, and the top-level `index.ts` re-exports them for back-compat
 // with downstream callers (CLI commands, audit writers, presence service).
 // ---------------------------------------------------------------------------
-export {};
+/**
+ * Canonical memory-kind vocabulary — the single source of truth.
+ *
+ * The union type, the accepted-kind set in the frontmatter parser, the
+ * hot/warm tier map below, `KIND_ORDER` in the reindex view, and the CLI
+ * `--kind` help text all derive from this tuple. Adding a kind here is the
+ * only edit required; TypeScript then forces `MEMORY_KIND_TIER` to cover it.
+ *
+ * Slice 2026-09-10-memory-vocab-and-rotate (E): the original 8 kinds are
+ * unchanged. The 13 appended kinds were observed on disk with real values
+ * that the index schema rejected (`peaks memory reindex` reported them as
+ * `unrecognized kind value`). Accepting them moves those files into the
+ * index; files with no kind field at all stay reported as unclassified.
+ */
+export const PROJECT_MEMORY_KINDS = [
+    // Original 8 (pre-2026-09-10).
+    'project',
+    'rule',
+    'decision',
+    'reference',
+    'feedback',
+    'convention',
+    'module',
+    'lesson',
+    // Slice E expansion — observed on-disk values, hot tier.
+    'bug',
+    'investigation',
+    'technical-pattern',
+    'project-rule',
+    // Slice E expansion — observed on-disk values, warm tier.
+    'design',
+    'handoff',
+    'session-handoff',
+    'project-todo',
+    'publish-closure',
+    'project-closure',
+    'slice-closure',
+    'slice-pilot-findings',
+    'sediment'
+];
+/**
+ * Hot/warm tier per kind. Insertion order IS the deterministic section order
+ * used by the generated `MEMORY.md` (`KIND_ORDER` in `index/reindex.ts`),
+ * so this object's key order is load-bearing — append new kinds at the end
+ * of their tier block rather than reshuffling existing entries.
+ *
+ * The `Record<ProjectMemoryKind, MemoryKindTier>` annotation makes a missing
+ * tier a compile error whenever `PROJECT_MEMORY_KINDS` grows.
+ */
+export const MEMORY_KIND_TIER = {
+    // hot — full body kept in the index
+    feedback: 'hot',
+    decision: 'hot',
+    rule: 'hot',
+    convention: 'hot',
+    module: 'hot',
+    lesson: 'hot',
+    bug: 'hot',
+    investigation: 'hot',
+    'technical-pattern': 'hot',
+    'project-rule': 'hot',
+    // warm — same entry shape, read on demand
+    project: 'warm',
+    reference: 'warm',
+    design: 'warm',
+    handoff: 'warm',
+    'session-handoff': 'warm',
+    'project-todo': 'warm',
+    'publish-closure': 'warm',
+    'project-closure': 'warm',
+    'slice-closure': 'warm',
+    'slice-pilot-findings': 'warm',
+    sediment: 'warm'
+};
+export const HOT_MEMORY_KINDS = PROJECT_MEMORY_KINDS.filter((kind) => MEMORY_KIND_TIER[kind] === 'hot');
+export const WARM_MEMORY_KINDS = PROJECT_MEMORY_KINDS.filter((kind) => MEMORY_KIND_TIER[kind] === 'warm');

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

@@ -127,9 +127,23 @@ export interface ProjectPreferences {
      */
     readonly memoryPreflight?: {
         readonly enabled?: boolean;
+        /** Back-compat token cap; converted to bytes as `maxTokens * 4`. */
         readonly maxTokens?: number;
+        /** Back-compat hot item cap; `hotItemCap` overrides it when set. */
         readonly listCap?: number;
         readonly contentCacheBytes?: number;
+        /** Slice 2026-09-09-memory-retrieval: hard byte cap on the block. */
+        readonly maxBytes?: number;
+        /** Slice 2026-09-09-memory-retrieval: max hot items (default 10). */
+        readonly hotItemCap?: number;
+        /** Slice 2026-09-09-memory-retrieval: max warm items (default 4; 0 disables). */
+        readonly warmItemCap?: number;
+        /** Slice 2026-09-09-memory-retrieval: min task-token hits for warm eligibility. */
+        readonly warmMinTokenHits?: number;
+        /** Slice 2026-09-09-memory-retrieval: soft selection wall-clock budget (ms). */
+        readonly selectionTimeBudgetMs?: number;
+        /** Slice 2026-09-09-memory-retrieval: inline memo bodies (default false). */
+        readonly includeBodies?: boolean;
     };
 }
 export type FanoutMode = 'fan-out';

package/dist/services/preferences/preferences-types.js

@@ -48,5 +48,13 @@ export const DEFAULT_PREFERENCES = {
         maxTokens: 1200,
         listCap: 12,
         contentCacheBytes: 6000,
+        // Slice 2026-09-09-memory-retrieval tiered budget (see
+        // memory-preflight-config.ts::DEFAULTS).
+        maxBytes: 4800,
+        hotItemCap: 10,
+        warmItemCap: 4,
+        warmMinTokenHits: 1,
+        selectionTimeBudgetMs: 200,
+        includeBodies: false,
     },
 };

package/dist/services/share/run-state-contract.d.ts

@@ -64,8 +64,8 @@ export declare const RunStateContractSchema: z.ZodObject<{
     status: z.ZodEnum<{
         blocked: "blocked";
         failed: "failed";
-        running: "running";
         done: "done";
+        running: "running";
         paused: "paused";
     }>;
     current_step: z.ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.34",
+  "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.19",
-    "peaks-loop-shared": "0.0.68",
-    "peaks-loop-shared-channel": "0.0.36",
-    "peaks-loop-mut": "0.1.32"
+    "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

@@ -296,7 +296,7 @@ After final validation, refresh project-local standards via `peaks standards ini
 
 ## Peaks-Loop Step 11: Memory sediment (BLOCKING on workflow complete)
 
-> **Hard rule.** Code MUST NOT declare a workflow complete until Step 11 has produced ≥ 1 file in `.peaks/memory/` OR the user has explicitly approved a no-sediment outcome via AskUserQuestion. Canonical CLI: `peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json` (the artifact-scoped extract; the batch-scoped sibling `peaks project memories:extract` is for non-handoff flows only). Substeps 11a/11b/11c/11d (Gate A/B/C), D-010 fix root cause check → `references/step-11-memory-sediment.md` + `references/runbook.md` §Step 11.
+> **Hard rule.** Code MUST NOT declare a workflow complete until Step 11 has produced ≥ 1 file in `.peaks/memory/` OR the user has explicitly approved a no-sediment outcome via AskUserQuestion. Canonical CLI: `peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json` (the artifact-scoped extract; the batch-scoped sibling `peaks project memories:extract` is for non-handoff flows only). **Single authority:** inside a peaks-code workflow, sedimenting memory writes to `.peaks/memory/`; the IDE-side memory dir (`~/.claude/projects/<hash>/memory/`) is a session note, not the authority and is read-only for peaks — pull any session note in with `peaks memory ingest --apply`, and keep the index in sync with `peaks memory reindex --apply`. Substeps 11a/11b/11c/11d (Gate A/B/C), 11e (index hygiene), 11f (IDE-side ingest), D-010 fix root cause check → `references/step-11-memory-sediment.md` + `references/runbook.md` §Step 11.
 
 ## Peaks-Loop External references and lifecycle
 
@@ -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-code/references/runbook.md

@@ -215,6 +215,12 @@ peaks memory extract --project <repo> --artifact .peaks/_runtime/<id>/txt/handof
 #      --apply is REQUIRED to write .peaks/memory/; without it the command only
 #      previews. The extract regenerates index.json in the same call.
 
+# 10d. Index hygiene (single authority: .peaks/memory/ is peaks-owned):
+peaks memory reindex --project <repo> --json          # drift report (unclassified / orphans both ways)
+peaks memory reindex --project <repo> --apply --json  # rebuild index.json + regenerate MEMORY.md
+peaks memory ingest  --project <repo> --json          # preview IDE-side session notes
+peaks memory ingest  --project <repo> --apply --json  # import them into .peaks/memory (IDE side stays read-only)
+
 # 11. Peaks-Loop Final snapshot
 peaks project dashboard --project <repo> --json
 peaks skill doctor --json

package/skills/peaks-code/references/step-11-memory-sediment.md

@@ -6,6 +6,15 @@ Companion to `SKILL.md` §"Peaks-Loop Step 11". This file holds the substep-by-s
 
 Code MUST NOT declare a workflow complete until Step 11 has produced ≥ 1 file in `.peaks/memory/` OR the user has explicitly approved a no-sediment outcome via AskUserQuestion. Applies to **all modes** including `assisted` and `strict`.
 
+## Single authority (2026-09-09)
+
+**Inside a peaks-code workflow, sedimenting memory writes to `.peaks/memory/`. The IDE-side memory dir is a session note, not the authority.**
+
+- `.peaks/memory/` is peaks-owned and authoritative. Every sediment action ends there.
+- Claude Code's per-project memory dir (`~/.claude/projects/<project-hash>/memory/*.md`) is the IDE's own scratch memory. It is **read-only** for peaks — never write there (same rule as `~/.claude/agents/`).
+- If a session note was written to the IDE-side dir instead of `.peaks/memory/`, pull it in with `peaks memory ingest --apply` (LLM-run; read-only on the IDE side, normalizes frontmatter to `metadata.type`, idempotent by filename stem). Conflicts leave both copies in place — resolve by hand.
+- Never let a memory exist only in the IDE-side dir when the workflow claims the memory was sedimented.
+
 ## Substeps
 
 ### 11a — Gate A (txt/ inventory)
@@ -42,6 +51,32 @@ If `extractedCount === 0` after 11c, fire AskUserQuestion:
 
 > **D-010 fix root cause check:** When firing 11d, first inspect whether the block has the YAML frontmatter (`title:` + `kind:` + `---`). If the `<!-- peaks-memory:start -->` exists but no `title:` line follows, fix the block format and re-run 11c — don't ask the user yet. Default option = (a). Code MUST NOT silently accept (b) without user pick.
 
+### 11e — Index hygiene (run after any sediment)
+
+```bash
+peaks memory reindex --project <repo> --json          # drift report (dry run)
+peaks memory reindex --project <repo> --apply --json  # rebuild index.json + MEMORY.md
+```
+
+`reindex` re-scans **every** `.peaks/memory/*.md` (including `archived/`), resolves each file's kind as `metadata.type` → top-level `kind:` → top-level `type:`, rebuilds `index.json` deterministically, and regenerates `MEMORY.md` (generated banner; do not hand-edit). It reports, never silently drops:
+
+- `unclassified[]` — files with no resolvable kind (add `metadata.type` to fix);
+- `orphanIndex[]` — index entries whose `sourcePath` no longer exists;
+- `orphanDisk[]` — files on disk the rebuilt index does not contain.
+
+Run it whenever Step 11 wrote or imported memories, so the machine index and `MEMORY.md` never drift apart again.
+
+### 11f — Pull in IDE-side session notes (only when needed)
+
+If a memory was written to Claude Code's own memory dir during the session instead of `.peaks/memory/`:
+
+```bash
+peaks memory ingest --project <repo> --json          # preview
+peaks memory ingest --project <repo> --apply --json  # write into .peaks/memory
+```
+
+Source defaults to `~/.claude/projects/<project-hash>/memory/` (read-only). Import is idempotent by filename stem; differing destinations are reported as conflicts and both copies are left in place. Files whose kind cannot be resolved are reported as needing classification — never invented.
+
 ## Why Step 11 exists
 
 Audit 2026-07-03 confirmed 2 consecutive sessions produced zero `.peaks/memory/` files despite completing RD + QA + handoff artifacts; `assisted` mode silently skipped runbook Step 10 (no STOP condition).

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.