peaks-loop 4.0.34 → 4.0.35

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

@@ -12,22 +12,18 @@
 //      are stored as standard YAML frontmatter (name / description /
 //      metadata.type / metadata.sourceArtifact) followed by the body.
 //
-// Both parsers share the 8-kind `VALID_MEMORY_KINDS` allow-list and the
+// Both parsers share the `VALID_MEMORY_KINDS` allow-list (derived from the
+// canonical `PROJECT_MEMORY_KINDS` tuple in `../types.ts`) and the
 // `slugify` helper used to derive filenames from titles.
 // ---------------------------------------------------------------------------
-export const VALID_MEMORY_KINDS = new Set([
-    'project',
-    'rule',
-    'decision',
-    'reference',
-    'feedback',
-    'convention',
-    'module',
-    'lesson'
-]);
-/** Exported for guard tests + tooling that needs to enumerate the valid
- *  set without duplicating the literal. Single source of truth. */
-export const VALID_PROJECT_MEMORY_KINDS = Array.from(VALID_MEMORY_KINDS);
+import { basename } from 'node:path';
+import { PROJECT_MEMORY_KINDS } from '../types.js';
+/** Accepted-kind set, derived from the canonical `PROJECT_MEMORY_KINDS`
+ *  tuple so the parser cannot drift from the union type / tier map. */
+export const VALID_MEMORY_KINDS = new Set(PROJECT_MEMORY_KINDS);
+/** Exported for guard tests + tooling that needs to enumerate the accepted
+ *  set (CLI help text, `--kind` validation) without duplicating the literal. */
+export const VALID_PROJECT_MEMORY_KINDS = PROJECT_MEMORY_KINDS;
 export function slugify(title) {
     const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
     return slug.length > 0 ? slug : 'project-memory';
@@ -69,36 +65,129 @@ export function renderMemoryFile(memory) {
         ''
     ].join('\n');
 }
-export function parseStoredMemoryFile(content, filePath) {
+/**
+ * Resolve the peaks memory kind from a stored memory file's frontmatter.
+ *
+ * Resolution order (first *valid* kind wins):
+ *   1. nested `metadata.type`   — the canonical peaks contract
+ *   2. top-level `kind:`        — the legacy alias (was silently dropped before)
+ *   3. top-level `type:`        — tolerated by the pre-existing trim-based reader
+ *   4. `none`                   — reported as unclassified; never invented
+ *
+ * Slice 2026-09-09-memory-system-overhaul (B): before this helper, files
+ * using a top-level `kind:` were silently dropped by the reader (defect
+ * #2). Falling through to `kind:` / `type:` is a strict superset of the
+ * old behaviour — no previously-indexed file changes kind.
+ */
+export function resolveMemoryKind(content) {
+    const parsed = parseMemoryFrontmatter(content);
+    return parsed.kind;
+}
+/**
+ * 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.
+ */
+export function parseMemoryFrontmatter(content) {
     const normalized = content.replace(/\r\n/g, '\n');
-    if (!normalized.startsWith('---\n'))
-        return null;
+    if (!normalized.startsWith('---\n')) {
+        return { hasFrontmatter: false, kind: { kind: null, source: 'none', rawKind: null }, frontmatter: '', body: normalized.trim() };
+    }
     const endIndex = normalized.indexOf('\n---\n', 4);
-    if (endIndex < 0)
-        return null;
+    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();
     let name;
+    let titleField;
     let description;
-    let kind;
     let sourceArtifact;
+    let nestedType;
+    let topType;
+    let kindField;
+    let inMetadata = false;
     for (const rawLine of frontmatter.split('\n')) {
+        const indented = /^\s/.test(rawLine);
         const line = rawLine.trim();
+        if (!indented) {
+            inMetadata = line === 'metadata:';
+        }
         if (line.startsWith('name:'))
             name = line.slice('name:'.length).trim();
+        else if (line.startsWith('title:')) {
+            if (!indented)
+                titleField = line.slice('title:'.length).trim();
+        }
         else if (line.startsWith('description:'))
             description = line.slice('description:'.length).trim();
-        else if (line.startsWith('type:'))
-            kind = line.slice('type:'.length).trim();
+        else if (line.startsWith('type:')) {
+            const value = line.slice('type:'.length).trim();
+            if (indented || inMetadata)
+                nestedType ??= value;
+            else
+                topType ??= value;
+        }
+        else if (line.startsWith('kind:'))
+            kindField ??= line.slice('kind:'.length).trim();
         else if (line.startsWith('sourceArtifact:'))
             sourceArtifact = line.slice('sourceArtifact:'.length).trim();
     }
-    if (!name || !kind || !VALID_MEMORY_KINDS.has(kind) || body.length === 0)
+    const candidates = [
+        ['metadata.type', nestedType],
+        ['kind', kindField],
+        ['type', topType]
+    ];
+    let kind = { kind: null, source: 'none', rawKind: null };
+    for (const [source, raw] of candidates) {
+        if (raw === undefined || raw === '')
+            continue;
+        if (kind.rawKind === null)
+            kind = { kind: null, source: 'none', rawKind: raw };
+        if (VALID_MEMORY_KINDS.has(raw)) {
+            kind = { kind: raw, source, rawKind: raw };
+            break;
+        }
+    }
+    return { hasFrontmatter: true, frontmatter, ...(name !== undefined ? { name } : {}), ...(titleField !== undefined ? { title: titleField } : {}), ...(description !== undefined ? { description } : {}), ...(sourceArtifact !== undefined ? { sourceArtifact } : {}), kind, body };
+}
+/**
+ * Deterministic name fallback chain for the read path:
+ *
+ *   1. `name:`            — the canonical field written by `renderMemoryFile`
+ *   2. `title:`           — hand-written / legacy files (the 5 on-disk files
+ *                           this slice fixes carried only `title:` + `kind:`)
+ *   3. filename stem      — last resort, so a well-formed memory with a valid
+ *                           kind is never dropped just for missing a name
+ *
+ * Empty values are skipped rather than accepted: a `name:` of `''` still
+ * falls through, and a file whose stem is also empty resolves to null so the
+ * caller's validation is preserved (never invents a name).
+ */
+export function resolveMemoryName(parsed, filePath) {
+    if (parsed.name !== undefined && parsed.name.length > 0)
+        return { name: parsed.name, source: 'name' };
+    if (parsed.title !== undefined && parsed.title.length > 0)
+        return { name: parsed.title, source: 'title' };
+    const stem = basename(filePath, '.md');
+    if (stem.length > 0)
+        return { name: stem, source: 'stem' };
+    return { name: null, source: 'none' };
+}
+export function parseStoredMemoryFile(content, filePath) {
+    const parsed = parseMemoryFrontmatter(content);
+    if (!parsed.hasFrontmatter)
+        return null;
+    const { description, sourceArtifact, body } = parsed;
+    const kind = parsed.kind.kind;
+    const { name } = resolveMemoryName(parsed, filePath);
+    if (name === null || kind === null || body.length === 0)
         return null;
     return {
         name,
         title: description ?? name,
-        kind: kind,
+        kind,
         sourceArtifact: sourceArtifact && sourceArtifact !== 'undefined' ? sourceArtifact : null,
         body,
         filePath

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.35",
   "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.20",
+    "peaks-loop-mut": "0.1.33",
+    "peaks-loop-shared": "0.0.69",
+    "peaks-loop-shared-channel": "0.0.37"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

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
 

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).