peaks-loop 4.0.0-beta.6 → 4.0.0-beta.8

package/dist/src/services/memory/llm-reranker.js

@@ -1,284 +0,0 @@
-/**
- * Slice Z-A (2.8.0) — LLM rerank service (Y2 architecture, zero new deps).
- *
- * Receives a fuzzy top-N candidate list (from `searchMemory` /
- * `MemorySearchResult[]`) and asks an LLM to rerank them by relevance
- * to the query. Returns the top-K in descending relevance.
- *
- * Architecture note (locked decision — see
- * `.peaks/memory/2026-06-18-peaks-zvec-spike-proposal.md` §Y2):
- *
- *   - "Active IDE LLM" is a deliberate abstraction: peaks-loop itself
- *     has NO direct LLM API key. The chat call is performed by the
- *     active IDE (Claude Code / Trae / Cursor / Codex / ...) using
- *     its own authentication chain.
- *
- *   - The current `IdeAdapter` interface has no `chat()` method —
- *     `SubAgentDispatcher` returns IDE-private tool-call descriptors
- *     (sub-agent dispatch, not direct chat). This service therefore
- *     takes a `chat` function INJECTION at the call site. The default
- *     is a no-op that fails-open (returns the original fuzzy order).
- *
- *   - This is a SPIKE artifact for Z-A. The real chat wiring (either
- *     a new `IdeAdapter.chat()` method, or routing through
- *     `SubAgentDispatcher` with a "rerank" role) is a Z-B prerequisite
- *     and is tracked in the GO/NO-GO report at
- *     `.peaks/memory/memory-search-y2-rerank-2026-06-19-decision.md`.
- *
- * Why this is split from `memory-search-service.ts`:
- *
- *   - The fuzzy kernel is pure + synchronous + 100% testable today.
- *   - The rerank layer is async + IO-bound + 100% fallback. Keeping
- *     it separate means the existing 2800+ fuzzy tests are untouched
- *     and the new spike has its own test surface (per the Z-A
- *     proposal's "不重写 memory-search-service.ts" red line).
- *
- * Why 4-bytes-per-token:
- *
- *   - `headroom-client.ts:60` already uses `BYTES_PER_TOKEN = 4` as
- *     its rough English-text approximation. Reusing the same constant
- *     keeps token estimates comparable across the headroom + rerank
- *     pipelines in the AC-ZA-5 benchmark.
- *
- * Out of scope (YAGNI per Karpathy #2 Simplicity First):
- *
- *   - No cross-process cache (AC-ZA-6 deferred — only build if
- *     AC-ZA-5 shows a hot path).
- *   - No rerank-prompt optimization beyond the minimal JSON
- *     output format.
- *   - No integration with `memory-search-service.ts` (Z-A is a spike;
- *     the wiring into `peaks memory search` is Z-B).
- */
-// Approximate 1 token = 4 bytes for English text. Matches
-// `headroom-client.ts:60` so the AC-ZA-5 benchmark can compare
-// rerank input cost against headroom compressed cost directly.
-const BYTES_PER_TOKEN = 4;
-// Hard caps so a pathological query / 60-candidate list cannot blow
-// up the LLM prompt. These are conservative defaults; Z-B may tune.
-const DEFAULT_TOP_N = 10;
-const DEFAULT_TOP_K = 5;
-const MAX_CANDIDATES = 30;
-const MAX_DESCRIPTION_CHARS = 240;
-const DEFAULT_CHAT_TIMEOUT_MS = 5_000;
-/**
- * Estimate token count for a string. `1 token ≈ 4 bytes` for English
- * text — same approximation as `headroom-client.ts:60`.
- */
-export function estimateTokens(text) {
-    return Math.ceil(Buffer.byteLength(text, 'utf8') / BYTES_PER_TOKEN);
-}
-/**
- * Truncate a string to a maximum character count, appending an
- * ellipsis marker when truncated. Used to keep the rerank prompt
- * bounded when a candidate's description is unusually long.
- */
-function truncateForPrompt(text, maxChars) {
-    if (text.length <= maxChars)
-        return text;
-    return `${text.slice(0, Math.max(0, maxChars - 1))}…`;
-}
-/**
- * Build the rerank prompt. Pure function — no IO, no side effects.
- * Trivially testable.
- *
- * Format (locked for Z-A; Z-B may tune):
- *
- *   Query: "<query>"
- *
- *   Rank the following <N> candidate memories by relevance to the
- *   query. Return a JSON array of the candidate indices in
- *   descending relevance. Return only the JSON — no prose, no
- *   markdown.
- *
- *   Candidates:
- *   [0] name-a — description-a…
- *   [1] name-b — description-b…
- *   ...
- *
- * The LLM is expected to return e.g. `[3, 0, 4, 1, 2]`. The
- * output is parsed by `parseRerankResponse`.
- */
-export function renderRerankPrompt(query, candidates) {
-    const blocks = candidates.map((c, i) => {
-        const desc = truncateForPrompt(c.description, MAX_DESCRIPTION_CHARS);
-        return `[${i}] ${c.name} — ${desc}`;
-    });
-    return [
-        `Query: "${query}"`,
-        '',
-        `Rank the following ${candidates.length} candidate memories by relevance to the query. Return a JSON array of the candidate indices in descending relevance. Return only the JSON — no prose, no markdown.`,
-        '',
-        'Candidates:',
-        ...blocks,
-    ].join('\n');
-}
-/**
- * Parse the LLM's raw text response into an ordered list of
- * candidate indices. Tolerates:
- *
- *   - Pure JSON arrays: `[3, 0, 4, 1, 2]`
- *   - JSON wrapped in markdown code fences:
- *       ```json
- *       [3, 0, 4, 1, 2]
- *       ```
- *   - Whitespace and surrounding prose (best-effort: looks for the
- *     first `[...]` block)
- *
- * Returns `null` on parse failure (caller falls back to original
- * fuzzy order per AC-ZA-8 L3).
- */
-export function parseRerankResponse(raw) {
-    const trimmed = raw.trim();
-    if (trimmed === '')
-        return null;
-    // Strip markdown code fence if present.
-    let body = trimmed;
-    const fenceMatch = /^```(?:json)?\s*([\s\S]*?)\s*```$/.exec(trimmed);
-    if (fenceMatch !== null && fenceMatch[1] !== undefined) {
-        body = fenceMatch[1];
-    }
-    // Best-effort: locate the first JSON array in the body.
-    const arrayMatch = /\[[\s\S]*?\]/.exec(body);
-    const candidate = arrayMatch !== null ? arrayMatch[0] : body;
-    let parsed;
-    try {
-        parsed = JSON.parse(candidate);
-    }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
-    }
-    if (!Array.isArray(parsed))
-        return null;
-    const indices = [];
-    for (const item of parsed) {
-        if (typeof item !== 'number' || !Number.isInteger(item) || item < 0) {
-            return null;
-        }
-        indices.push(item);
-    }
-    return indices;
-}
-/**
- * Apply a parsed index ordering to a candidate list. Indices that
- * are out-of-range or duplicated are skipped (defensive). If the
- * ordering covers fewer candidates than `topK`, the remaining
- * slots are filled from the original fuzzy order.
- */
-export function applyRerankOrder(candidates, order, topK) {
-    const result = [];
-    const seen = new Set();
-    for (const idx of order) {
-        if (idx >= candidates.length)
-            continue;
-        if (seen.has(idx))
-            continue;
-        seen.add(idx);
-        const item = candidates[idx];
-        if (item === undefined)
-            continue;
-        result.push(item);
-        if (result.length >= topK)
-            return result;
-    }
-    for (let i = 0; i < candidates.length && result.length < topK; i += 1) {
-        if (seen.has(i))
-            continue;
-        const item = candidates[i];
-        if (item === undefined)
-            continue;
-        seen.add(i);
-        result.push(item);
-    }
-    return result;
-}
-/**
- * The no-op chat function. Used when no real chat injection is
- * available — the rerank layer fails-open and the caller gets
- * the original fuzzy order.
- */
-export const noopRerankChat = async () => {
-    throw new Error('NO_CHAT_FN: rerank chat function not provided (default fail-open)');
-};
-/**
- * Run the LLM rerank. Always returns a result — never throws.
- * The caller can use `topK` as a drop-in replacement for the
- * fuzzy top-K regardless of degradation mode.
- */
-export async function rerank(query, candidates, options = {}) {
-    const topN = Math.min(Math.max(options.topN ?? DEFAULT_TOP_N, 1), MAX_CANDIDATES);
-    const topK = Math.min(Math.max(options.topK ?? DEFAULT_TOP_K, 1), topN);
-    const chatTimeoutMs = options.chatTimeoutMs ?? DEFAULT_CHAT_TIMEOUT_MS;
-    const chat = options.chat ?? noopRerankChat;
-    // Edge case 1: empty input. Return empty result, no warning.
-    if (candidates.length === 0) {
-        return {
-            topK: [],
-            tokens: { promptTokens: 0, responseTokens: 0, total: 0 },
-            degradation: 'noop-empty-input',
-            warning: null,
-        };
-    }
-    // Edge case 2: input fits within topK already. Rerank would be
-    // a no-op — return as-is without paying the LLM cost.
-    if (candidates.length <= topK) {
-        return {
-            topK: candidates.slice(0, topK),
-            tokens: { promptTokens: 0, responseTokens: 0, total: 0 },
-            degradation: 'noop-empty-input',
-            warning: null,
-        };
-    }
-    // Slice to topN (fuzzy already returns in score-descending order).
-    const truncated = candidates.slice(0, topN);
-    const prompt = renderRerankPrompt(query, truncated);
-    const promptTokens = estimateTokens(prompt);
-    // Edge case 3: no chat function. Fail-open per AC-ZA-8 L1.
-    if (options.chat === undefined) {
-        return {
-            topK: truncated.slice(0, topK),
-            tokens: { promptTokens, responseTokens: 0, total: promptTokens },
-            degradation: 'skipped-no-chat-fn',
-            warning: 'No chat function provided; returning original fuzzy order.',
-        };
-    }
-    // Chat call with timeout (AbortController-based).
-    const controller = new AbortController();
-    const timeoutHandle = setTimeout(() => controller.abort(), chatTimeoutMs);
-    let raw = '';
-    try {
-        raw = await chat([{ role: 'user', content: prompt }], controller.signal);
-    }
-    catch (chatError) {
-        clearTimeout(timeoutHandle);
-        const message = chatError instanceof Error ? chatError.message : String(chatError);
-        const isTimeout = controller.signal.aborted && /abort/i.test(message);
-        return {
-            topK: truncated.slice(0, topK),
-            tokens: { promptTokens, responseTokens: 0, total: promptTokens },
-            degradation: isTimeout ? 'timeout-fallback' : 'chat-failed-fallback',
-            warning: isTimeout
-                ? `Chat timeout after ${chatTimeoutMs}ms; returning original fuzzy order.`
-                : `Chat failed: ${message}; returning original fuzzy order.`,
-        };
-    }
-    clearTimeout(timeoutHandle);
-    // Parse the response.
-    const order = parseRerankResponse(raw);
-    const responseTokens = estimateTokens(raw);
-    if (order === null) {
-        return {
-            topK: truncated.slice(0, topK),
-            tokens: { promptTokens, responseTokens, total: promptTokens + responseTokens },
-            degradation: 'parse-failed-fallback',
-            warning: 'LLM response was not a valid JSON index array; returning original fuzzy order.',
-        };
-    }
-    // Apply the order and return.
-    const topKResult = applyRerankOrder(truncated, order, topK);
-    return {
-        topK: topKResult,
-        tokens: { promptTokens, responseTokens, total: promptTokens + responseTokens },
-        degradation: 'reranked',
-        warning: null,
-    };
-}

package/dist/src/services/memory/memory-search-service.d.ts

@@ -1,93 +0,0 @@
-export type { ProjectMemoryKind } from './project-memory-service.js';
-import type { ProjectMemoryKind } from './project-memory-service.js';
-/**
- * One entry in `.peaks/memory/index.json` after the on-disk `hot[]` +
- * `cold[]` arrays are flattened. Mirrors the field shape that the
- * existing `project-memory-service.ts` writer emits.
- */
-export interface MemoryIndexEntry {
-    name: string;
-    kind: ProjectMemoryKind;
-    description: string;
-    sourcePath: string;
-    sourceArtifact: string | null;
-    updatedAt: string;
-}
-/**
- * The full snapshot of `.peaks/memory/index.json`.
- */
-export interface MemoryIndexSnapshot {
-    indexPath: string;
-    version: number;
-    updatedAt: string;
-    entries: MemoryIndexEntry[];
-}
-/**
- * Input to `searchMemory`. `projectRoot` defaults to the resolved
- * peaks project root (CLI resolves this before calling). `query` is
- * required and non-empty.
- */
-export interface MemorySearchInput {
-    query: string;
-    projectRoot?: string;
-    limit?: number;
-    kind?: ProjectMemoryKind;
-}
-/**
- * One hit returned by `searchMemory`. Mirrors the entry shape with a
- * normalized score in [0, 1] (top of batch = 1.0) and the char indices
- * in the searchable text that contributed to the match.
- */
-export interface MemorySearchResult {
-    name: string;
-    kind: ProjectMemoryKind;
-    description: string;
-    sourcePath: string;
-    score: number;
-    positions: number[];
-}
-/**
- * Read `.peaks/memory/index.json` and flatten the on-disk `hot[<kind>][]`
- * + `cold[]` shape into a single `entries[]` array. Throws structured
- * errors with stable `code` markers that the CLI converts to the
- * peaks envelope.
- */
-export declare function loadMemoryIndex(projectRoot: string): MemoryIndexSnapshot;
-/**
- * Run the generic fuzzy kernel against the on-disk memory index. The
- * searchable text is `name + " " + description` for each entry (per
- * spec §Component Details).
- */
-export declare function searchMemory(input: MemorySearchInput): MemorySearchResult[];
-/**
- * Envelope for the optional headroom-compressed version of the search
- * result text. The compressed text is intended for the LLM-side prompt
- * (it preserves the entry names + descriptions in a more token-efficient
- * form); the structured `matches` array is unchanged and remains the
- * machine-readable form. `null` when compression was not requested,
- * did not run, or failed (see `warning` for the reason).
- */
-export interface CompressedResultsEnvelope {
-    readonly mode: 'balanced' | 'aggressive' | 'conservative';
-    readonly originalSize: number;
-    readonly compressedSize: number;
-    readonly compressionRatio: number;
-    readonly compressedText: string;
-    readonly warning: string | null;
-}
-export interface MemorySearchWithResults {
-    readonly matches: MemorySearchResult[];
-    readonly compressedResults: CompressedResultsEnvelope | null;
-}
-export interface MemorySearchOptions {
-    /** When true, read preferences.headroom.perTouchpoint.memorySearch and
-     *  compress joined match text via headroom-ai. Falls back silently to
-     *  the structured `matches` array when compression is unavailable. */
-    readonly compressResults?: boolean;
-}
-/**
- * Run the search + optionally compress the joined match text via headroom.
- * The structured `matches` array is the canonical output. The
- * `compressedResults` is a derived view for LLM-side prompt assembly.
- */
-export declare function searchMemoryWithResults(input: MemorySearchInput, options?: MemorySearchOptions): Promise<MemorySearchWithResults>;

package/dist/src/services/memory/memory-search-service.js

@@ -1,117 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { fuzzyMatchWithKey } from '../fuzzy-matching/fuzzy-match-service.js';
-import { compressPrompt } from '../context/headroom-client.js';
-import { loadPreferences } from '../preferences/preferences-service.js';
-import { shouldCompressResults } from '../context/headroom-prefs.js';
-const DEFAULT_LIMIT = 6;
-/**
- * Read `.peaks/memory/index.json` and flatten the on-disk `hot[<kind>][]`
- * + `cold[]` shape into a single `entries[]` array. Throws structured
- * errors with stable `code` markers that the CLI converts to the
- * peaks envelope.
- */
-export function loadMemoryIndex(projectRoot) {
-    const indexPath = join(projectRoot, '.peaks', 'memory', 'index.json');
-    if (!existsSync(indexPath)) {
-        const err = new Error(`INDEX_MISSING: memory index not found at ${indexPath}`);
-        err.code = 'INDEX_MISSING';
-        throw err;
-    }
-    let raw;
-    try {
-        raw = readFileSync(indexPath, 'utf8');
-    }
-    catch (cause) {
-        const err = new Error(`INDEX_INVALID: failed to read memory index at ${indexPath}: ${cause.message}`);
-        err.code = 'INDEX_INVALID';
-        throw err;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (cause) {
-        const err = new Error(`INDEX_INVALID: malformed memory index at ${indexPath}: ${cause.message}`);
-        err.code = 'INDEX_INVALID';
-        throw err;
-    }
-    const index = parsed;
-    const hot = index.hot ?? {};
-    const flatFromHot = Object.values(hot).flat();
-    const flatFromCold = (index.cold ?? []);
-    const entries = [...flatFromHot, ...flatFromCold];
-    return {
-        indexPath,
-        version: index.version ?? 1,
-        updatedAt: index.updatedAt ?? '',
-        entries,
-    };
-}
-/**
- * Run the generic fuzzy kernel against the on-disk memory index. The
- * searchable text is `name + " " + description` for each entry (per
- * spec §Component Details).
- */
-export function searchMemory(input) {
-    if (input.query === '') {
-        const err = new Error('EMPTY_QUERY: searchMemory requires a non-empty query (use `peaks memory index` to list all)');
-        err.code = 'EMPTY_QUERY';
-        throw err;
-    }
-    const projectRoot = input.projectRoot ?? process.cwd();
-    const limit = input.limit ?? DEFAULT_LIMIT;
-    const snapshot = loadMemoryIndex(projectRoot);
-    let candidates = snapshot.entries;
-    if (input.kind !== undefined) {
-        candidates = candidates.filter((e) => e.kind === input.kind);
-    }
-    // Per spec: searchable text is name + " " + description.
-    // The keyFn is invoked once per item per call.
-    const matches = fuzzyMatchWithKey(input.query, candidates, { keyFn: (e) => `${e.name} ${e.description}`, limit, caseSensitive: false });
-    return matches.map((m) => {
-        const entry = m.item;
-        return {
-            name: entry.name,
-            kind: entry.kind,
-            description: entry.description,
-            sourcePath: entry.sourcePath,
-            score: m.score,
-            positions: m.positions,
-        };
-    });
-}
-/**
- * Run the search + optionally compress the joined match text via headroom.
- * The structured `matches` array is the canonical output. The
- * `compressedResults` is a derived view for LLM-side prompt assembly.
- */
-export async function searchMemoryWithResults(input, options = {}) {
-    const matches = searchMemory(input);
-    if (options.compressResults !== true) {
-        return { matches, compressedResults: null };
-    }
-    const projectRoot = input.projectRoot ?? process.cwd();
-    const prefs = loadPreferences(projectRoot).headroom;
-    const joinedText = matches.map((m) => `${m.name}: ${m.description}`).join('\n');
-    const joinedBytes = Buffer.byteLength(joinedText, 'utf8');
-    const decision = shouldCompressResults(prefs, joinedBytes, 'memorySearch');
-    if (!decision.compress) {
-        return { matches, compressedResults: null };
-    }
-    const result = await compressPrompt(joinedText, decision.mode);
-    if (result.warning !== null || result.compressedPrompt === null) {
-        return { matches, compressedResults: null };
-    }
-    return {
-        matches,
-        compressedResults: {
-            mode: decision.mode,
-            originalSize: result.originalSize,
-            compressedSize: result.compressedSize,
-            compressionRatio: result.compressionRatio,
-            compressedText: result.compressedPrompt,
-            warning: result.warning
-        }
-    };
-}

package/dist/src/services/memory/project-context-service.d.ts

@@ -1,11 +0,0 @@
-export type ProjectContextSection = {
-    heading: string;
-    body: string;
-};
-export declare function generateProjectContext(projectRoot: string): {
-    path: string;
-    content: string;
-    sessionCount: number;
-};
-export declare function readProjectContext(projectRoot: string): string | null;
-export declare function getProjectContextPath(projectRoot: string): string;

package/dist/src/services/memory/project-context-service.js

@@ -1,148 +0,0 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { listSessionMetas } from '../session/session-manager.js';
-import { getSessionDir } from '../session/getSessionDir.js';
-const PROJECT_CONTEXT_FILE = '.peaks/PROJECT.md';
-const CONTEXT_HEADER = `# Peaks Project Context
-
-> Auto-generated project memory. Peaks reads this at the start of each session to understand
-> the project's history, tech stack, conventions, and past decisions.
-> Last updated: `;
-const MANAGED_BLOCK_START = '<!-- peaks-managed:session-history-start -->';
-const MANAGED_BLOCK_END = '<!-- peaks-managed:session-history-end -->';
-function projectName(projectRoot) {
-    const pkgPath = join(projectRoot, 'package.json');
-    if (!existsSync(pkgPath))
-        return projectRoot.split(/[\\/]/).pop() ?? 'unknown';
-    try {
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-        return pkg.name ?? projectRoot.split(/[\\/]/).pop() ?? 'unknown';
-    }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return projectRoot.split(/[\\/]/).pop() ?? 'unknown';
-    }
-}
-function listMdFiles(dir, maxDepth = 3) {
-    const results = [];
-    if (!existsSync(dir) || maxDepth <= 0)
-        return results;
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return results;
-    }
-    for (const entry of entries) {
-        if (entry.name.startsWith('.'))
-            continue;
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            results.push(...listMdFiles(full, maxDepth - 1));
-        }
-        else if (entry.isFile() && entry.name.endsWith('.md')) {
-            results.push(full);
-        }
-    }
-    return results;
-}
-function extractOneLineSummary(sessionRoot) {
-    const artifacts = listMdFiles(sessionRoot, 4);
-    for (const artifact of artifacts.slice(0, 5)) {
-        try {
-            const content = readFileSync(artifact, 'utf8');
-            // Grab the first non-heading, non-empty line after the front section
-            const lines = content.split(/\r?\n/);
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('-') || trimmed.startsWith('`'))
-                    continue;
-                if (trimmed.length > 10 && trimmed.length < 200)
-                    return trimmed;
-                break;
-            }
-        }
-        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-            // skip unreadable
-        }
-    }
-    return null;
-}
-function buildSessionHistory(projectRoot) {
-    const metas = listSessionMetas(projectRoot);
-    if (metas.length === 0) {
-        return `${MANAGED_BLOCK_START}\n\n_No sessions recorded yet._\n\n${MANAGED_BLOCK_END}`;
-    }
-    const maxSessions = 15;
-    // Sort by createdAt descending (most recent first)
-    const sorted = [...metas].sort((a, b) => (b.createdAt || '').localeCompare(a.createdAt || ''));
-    const recent = sorted.slice(0, maxSessions);
-    let body = `${MANAGED_BLOCK_START}\n\n## Timeline (${metas.length} sessions`;
-    if (metas.length > maxSessions)
-        body += `, showing last ${maxSessions}`;
-    body += ')\n\n';
-    // Human-readable timeline: date | name | brief
-    body += `| Date | Directory | Title | What |\n`;
-    body += `|------|-----------|-------|------|\n`;
-    for (const meta of recent) {
-        const date = meta.createdAt ? meta.createdAt.slice(0, 10) : '?';
-        const dir = meta.sessionId;
-        const title = (meta.title ?? 'Untitled').slice(0, 40);
-        const skill = meta.skill ?? '-';
-        // Extract one-line summary from artifacts for the "What" column
-        const sessionRoot = getSessionDir(projectRoot, meta.sessionId);
-        const summary = extractOneLineSummary(sessionRoot);
-        const brief = summary ? summary.slice(0, 70) : skill;
-        body += `| ${date} | \`${dir}\` | ${title} | ${brief} |\n`;
-    }
-    body += `\n${MANAGED_BLOCK_END}`;
-    return body;
-}
-export function generateProjectContext(projectRoot) {
-    const peaksDir = join(projectRoot, '.peaks');
-    if (!existsSync(peaksDir)) {
-        mkdirSync(peaksDir, { recursive: true });
-    }
-    const contextPath = join(projectRoot, PROJECT_CONTEXT_FILE);
-    const name = projectName(projectRoot);
-    const now = new Date().toISOString();
-    const sessionHistory = buildSessionHistory(projectRoot);
-    const header = `${CONTEXT_HEADER}${now}\n\n## Project: ${name}\n`;
-    let content;
-    if (existsSync(contextPath)) {
-        const existing = readFileSync(contextPath, 'utf8');
-        const startIdx = existing.indexOf(MANAGED_BLOCK_START);
-        const endIdx = existing.indexOf(MANAGED_BLOCK_END);
-        // Update the Last-updated timestamp in the header
-        const updatedExisting = existing.replace(/Last updated: .*/, `Last updated: ${now}`);
-        if (startIdx >= 0 && endIdx > startIdx) {
-            // Replace managed block, preserve user content outside it
-            const before = updatedExisting.slice(0, startIdx);
-            const after = updatedExisting.slice(endIdx + MANAGED_BLOCK_END.length);
-            content = before + sessionHistory + after;
-        }
-        else {
-            // No managed block found — append
-            content = updatedExisting.trimEnd() + '\n\n' + sessionHistory + '\n';
-        }
-    }
-    else {
-        content = header + '\n' + sessionHistory + '\n';
-    }
-    writeFileSync(contextPath, content, 'utf8');
-    return { path: contextPath, content, sessionCount: listSessionMetas(projectRoot).length };
-}
-export function readProjectContext(projectRoot) {
-    const contextPath = join(projectRoot, PROJECT_CONTEXT_FILE);
-    if (!existsSync(contextPath))
-        return null;
-    try {
-        return readFileSync(contextPath, 'utf8');
-    }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
-    }
-}
-export function getProjectContextPath(projectRoot) {
-    return join(projectRoot, PROJECT_CONTEXT_FILE);
-}