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

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

@@ -0,0 +1,284 @@
+/**
+ * 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/services/memory/memory-search-service.d.ts

@@ -0,0 +1,93 @@
+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/services/memory/memory-search-service.js

@@ -0,0 +1,117 @@
+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/services/memory/project-context-service.d.ts

@@ -0,0 +1,21 @@
+import { type BootstrapProjectScanEnvelope } from '../prd/project-scan-bootstrap-service.js';
+export type ProjectContextSection = {
+    heading: string;
+    body: string;
+};
+/**
+ * Slice 2026-07-15-project-scan-bootstrap (G1 + G2):
+ * generateProjectContext now also bootstraps the project-level
+ * `.peaks/project-scan/` artifact set. The envelope is returned
+ * alongside the context so `peaks project context` can surface
+ * `templatesBooted` / `templatesSkipped` / `durationMs` in its JSON.
+ */
+export type ProjectContextEnvelope = {
+    path: string;
+    content: string;
+    sessionCount: number;
+    projectScan: BootstrapProjectScanEnvelope;
+};
+export declare function generateProjectContext(projectRoot: string): Promise<ProjectContextEnvelope>;
+export declare function readProjectContext(projectRoot: string): string | null;
+export declare function getProjectContextPath(projectRoot: string): string;

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

@@ -0,0 +1,161 @@
+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';
+import { bootstrapProjectScan } from '../prd/project-scan-bootstrap-service.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 async 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');
+    // Slice 2026-07-15-project-scan-bootstrap (G1 + G2):
+    // After writing PROJECT.md, also bootstrap `.peaks/project-scan/`
+    // (project-scan.md + 4 bundled audit/business templates). Idempotent
+    // — re-running this call does not overwrite existing files (unless
+    // the caller passes `force` / `forceTemplates`, which we do NOT do
+    // here; peaks workspace init owns the force variants).
+    const projectScan = await bootstrapProjectScan({ projectRoot });
+    return {
+        path: contextPath,
+        content,
+        sessionCount: listSessionMetas(projectRoot).length,
+        projectScan
+    };
+}
+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);
+}