peaks-cli 1.2.7 → 1.2.9

package/dist/src/cli/commands/progress-watch-render.js

@@ -0,0 +1,308 @@
+/**
+ * In-place progress renderer for `peaks progress watch`.
+ *
+ * Goals (in order of importance):
+ *   1. **In-place overwrite.** Every tick the dynamic rows
+ *      (status line + progress bar) get rewritten, NOT
+ *      appended. We bypass `io.stdout` (which is
+ *      `console.log` and adds a trailing `\n` per call) and
+ *      write directly to `process.stdout`. The cursor-up
+ *      and erase-line escapes are the same ones terminal-kit
+ *      emits; we do not need a terminal-kit dependency for
+ *      them.
+ *   2. **Clear PEAKS-CLI branding.** A static 3-line header
+ *      with the brand bar, the project root, and the
+ *      progress-file path is painted once. The user always
+ *      sees what they are looking at, even after the
+ *      watch loop has overwritten the dynamic rows a
+ *      thousand times.
+ *   3. **Graceful degrade.** When stdout is not a TTY
+ *      (CI / pipe / `--json`), we fall back to a single
+ *      static snapshot per tick (no cursor moves, no
+ *      SGR colour) and a single newline. This keeps the
+ *      tool scriptable without dropping into a wall of
+ *      escape codes.
+ *
+ * Token-cost note: this module is rendered to the user's
+ * terminal, never into LLM context. The watch side has
+ * zero token cost.
+ */
+import chalk from 'chalk';
+// ─────────────────────────────────────────────────────────────────────
+// Raw byte writes. We do NOT go through `io.stdout` because the
+// default `io.stdout` is `console.log` and appends a trailing
+// newline, which would defeat in-place overwrite.
+// ─────────────────────────────────────────────────────────────────────
+function rawWrite(text) {
+    process.stdout.write(text);
+}
+/**
+ * Number of lines that the dynamic dashboard occupies. We
+ * rewrite exactly this many rows per tick via cursor-up +
+ * erase-line, so the static header above and the
+ * `press Ctrl-C` footer below stay put.
+ */
+const DYNAMIC_LINES = 2;
+/** ANSI: cursor up N rows. */
+const CURSOR_UP_N = (n) => `\x1b[${n}A`;
+/** ANSI: erase the current row from cursor to end-of-line. */
+const ERASE_LINE = '\x1b[2K';
+/** ANSI: reset all SGR attributes. */
+const RESET = '\x1b[0m';
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const PHASE_LABEL = {
+    starting: 'starting',
+    running: 'running',
+    verifying: 'verifying',
+    completing: 'completing',
+    finished: 'finished',
+    failed: 'failed',
+    idle: 'idle'
+};
+const PHASE_COLOR = {
+    starting: chalk.cyan,
+    running: chalk.cyan,
+    verifying: chalk.cyan,
+    completing: chalk.cyan,
+    finished: chalk.green,
+    failed: chalk.red,
+    idle: chalk.gray
+};
+function pickSpinnerFrame(tick) {
+    return SPINNER_FRAMES[Math.abs(tick) % SPINNER_FRAMES.length];
+}
+function formatElapsed(ms) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0) {
+        return `${hours}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
+    }
+    return `${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
+}
+/**
+ * `elapsedMs` based fake progress, 0..1, capped at 1 after
+ * 10 minutes. Visual cue that the watch is alive; NOT a real
+ * percent-complete.
+ */
+function computeFakeProgress(data) {
+    if (data === null)
+        return 0;
+    const startedAtMs = new Date(data.current.startedAt).getTime();
+    if (Number.isNaN(startedAtMs))
+        return 0;
+    const elapsedMs = Math.max(0, Date.now() - startedAtMs);
+    const upperBoundMs = 10 * 60 * 1000;
+    return Math.min(1, elapsedMs / upperBoundMs);
+}
+// ─────────────────────────────────────────────────────────────────────
+// ASCII art for the PEAKS-CLI brand bar. Kept in code (not a
+// dependency) so the user sees the brand even when terminal-kit
+// is unavailable.
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Three-row ASCII wordmark for PEAKS-CLI. Each letter is 5
+ * columns wide; P-E-A-K-S take 5 letters (25 cols), the
+ * dash takes 9 cols (with surrounding space), C-L-I take 3
+ * letters (15 cols). Total ≈ 49 cols, fits in 80-col
+ * terminals without wrapping.
+ *
+ * The block-character density (full blocks on the
+ * prominent rows) makes the brand visually dominant
+ * against the gray "sub-agent progress watch" tagline
+ * that sits below — so the user always knows whose
+ * dashboard they are looking at, even when the title
+ * bar is hidden.
+ */
+const PEAKS_CLI_ASCII = [
+    '█████  █████  █████  ██  ██  ██████         █████  ██      ███',
+    '█   █  █   █  █   █ ██  ██    ██             ██    ██      ██ ',
+    '█████  █████  █████  ██████    ██             ████  █████   ███'
+];
+/**
+ * Render the static header: the three-line big PEAKS-CLI
+ * wordmark, a separator, a small "sub-agent progress watch"
+ * tagline, and the project / file path. Painted ONCE at the
+ * top of the watch, then never touched again.
+ *
+ * Visual hierarchy (per user feedback):
+ *   1. PEAKS-CLI — 3-line big block art, bold cyan
+ *   2. separator
+ *   3. sub-agent progress watch — 1 line, smaller, gray
+ *   4. project / path — 1 line each, gray
+ */
+function renderHeader(projectRoot, progressFilePath, isTty) {
+    if (!isTty) {
+        // Non-TTY: emit a single header line, no colour. The
+        // dashboard still emits 2 dynamic lines per tick, so
+        // consumers that need to parse the output can rely on
+        // a known line count.
+        return [
+            `PEAKS-CLI · sub-agent progress watch · project=${projectRoot}`,
+            `path: ${progressFilePath}`
+        ].join('\n') + '\n';
+    }
+    // PEAKS-CLI block-art rows in bold cyan (the "big" brand).
+    const brandLines = PEAKS_CLI_ASCII.map((row) => chalk.bold.cyan(`  ${row}`));
+    // The tagline below the brand — small, gray, no big
+    // chrome. The user sees the brand first, the
+    // descriptor second.
+    const tagline = chalk.gray('  sub-agent progress watch');
+    const projLine = chalk.gray(`  project: ${projectRoot}`);
+    const pathLine = chalk.gray(`  path:    ${progressFilePath}`);
+    const separator = chalk.gray('  ' + '─'.repeat(60));
+    return [
+        brandLines[0] ?? '',
+        brandLines[1] ?? '',
+        brandLines[2] ?? '',
+        separator,
+        tagline,
+        projLine,
+        pathLine,
+        ''
+    ].join('\n');
+}
+/**
+ * Render the 2-line dynamic dashboard. Status row on top
+ * (spinner + phase + elapsed + step), progress bar on the
+ * bottom. When `data` is null (no progress file yet), we
+ * still show a live spinner + a "waiting…" message so the
+ * user knows the watch is alive.
+ */
+function renderDynamicRows(data, tick, width, isTty) {
+    const progressFraction = computeFakeProgress(data);
+    if (data === null) {
+        return {
+            status: isTty
+                ? `  ${chalk.gray(pickSpinnerFrame(tick))}  ${chalk.gray('idle')}    ${chalk.gray('(no progress file yet — sub-agent has not started)')}`
+                : `idle (no progress file yet)`,
+            bar: isTty ? renderBar(0, width, isTty) : ''
+        };
+    }
+    const startedAtMs = new Date(data.current.startedAt).getTime();
+    const elapsedMs = Number.isNaN(startedAtMs) ? 0 : Math.max(0, Date.now() - startedAtMs);
+    const phase = PHASE_LABEL[data.current.phase];
+    const step = data.current.step.length > 60 ? data.current.step.slice(0, 57) + '...' : data.current.step;
+    const verdict = data.current.verdict ? `  verdict=${data.current.verdict}` : '';
+    const role = data.role ? `  role=${data.role}` : '';
+    const spinner = pickSpinnerFrame(tick);
+    if (!isTty) {
+        return {
+            status: `${spinner} ${phase} ${formatElapsed(elapsedMs)} ${step}${role}${verdict}`,
+            bar: ''
+        };
+    }
+    const colorize = PHASE_COLOR[data.current.phase] ?? chalk.cyan;
+    const spinnerColor = phase === 'failed' ? chalk.red
+        : phase === 'finished' ? chalk.green
+            : chalk.cyan;
+    const statusLine = `  ${spinnerColor(spinner)}  ${colorize(phase.padEnd(11))}  ${chalk.yellow(formatElapsed(elapsedMs))}  ${step}${chalk.gray(role)}${verdict ? chalk.gray(verdict) : ''}`;
+    return {
+        status: statusLine,
+        bar: renderBar(progressFraction, width, isTty)
+    };
+}
+function renderBar(fraction, width, isTty) {
+    if (!isTty)
+        return '';
+    // 8ths-of-cell block characters: ░ (empty) U+2591, full blocks
+    // U+2588..U+258F for the partial last cell.
+    const barCells = Math.max(10, Math.min(50, Math.floor(width * 0.4)));
+    const filled = Math.round(barCells * Math.max(0, Math.min(1, fraction)) * 8);
+    const fullBlocks = Math.floor(filled / 8);
+    const fracBlock = filled % 8;
+    const emptyCells = barCells * 8 - filled;
+    const fullStr = '█'.repeat(fullBlocks);
+    const fracStr = fracBlock > 0 ? String.fromCharCode(0x2588 + (8 - fracBlock)) : '';
+    const emptyStr = '░'.repeat(Math.floor(emptyCells / 8));
+    const percent = String(Math.round(fraction * 100)).padStart(3, ' ');
+    return `  ${chalk.green(fullStr + fracStr + emptyStr)}  ${chalk.gray(`${percent}%`)}`;
+}
+export class WatchRenderer {
+    projectRoot;
+    progressFilePath;
+    width;
+    isTty;
+    hasRenderedDynamic = false;
+    constructor(options) {
+        this.projectRoot = options.projectRoot;
+        this.progressFilePath = options.progressFilePath;
+        this.width = (process.stdout.columns ?? 120) - 1;
+        this.isTty = process.stdout.isTTY === true;
+    }
+    /**
+     * Paint the static header once at the top of the watch
+     * (the PEAKS-CLI wordmark, separator, project, path). Then
+     * paint the dynamic rows for the first tick. From here on
+     * the dynamic rows are the only thing we touch.
+     */
+    start() {
+        rawWrite(renderHeader(this.projectRoot, this.progressFilePath, this.isTty));
+        this.paintDynamicOnce(null, 0);
+    }
+    /**
+     * Repaint the 2 dynamic rows in place. First call moves
+     * the cursor up N rows from the bottom of the previously
+     * painted block; subsequent calls do the same.
+     */
+    tick(data, tickCount) {
+        if (this.hasRenderedDynamic) {
+            // Move cursor up to the top of the previously-painted
+            // dynamic block.
+            rawWrite(CURSOR_UP_N(DYNAMIC_LINES));
+        }
+        this.paintDynamicOnce(data, tickCount);
+    }
+    paintDynamicOnce(data, tick) {
+        const { status, bar } = renderDynamicRows(data, tick, this.width, this.isTty);
+        // Erase-then-rewrite the status row.
+        rawWrite(ERASE_LINE + status + '\n');
+        // Erase-then-rewrite the bar row. (In non-TTY mode the
+        // bar is empty; we still emit a newline so the line
+        // count stays consistent.)
+        rawWrite(ERASE_LINE + bar + '\n');
+        this.hasRenderedDynamic = true;
+    }
+    /**
+     * Paint a final 2-line verdict + a farewell line below the
+     * dashboard, then return. The cursor stays at the bottom
+     * of the farewell so the user's shell prompt lands on the
+     * next row.
+     */
+    finalize(data) {
+        // Rewrite the dynamic block one last time so the user can
+        // read the verdict.
+        if (this.hasRenderedDynamic) {
+            rawWrite(CURSOR_UP_N(DYNAMIC_LINES));
+        }
+        this.paintDynamicOnce(data, Number.MAX_SAFE_INTEGER);
+        // Then emit the farewell BELOW the dashboard, in green.
+        const verdictSuffix = data.current.verdict !== undefined ? ` (verdict=${data.current.verdict})` : '';
+        const farewell = this.isTty
+            ? chalk.green(`✔ peaks progress watch: sub-agent reached phase=${data.current.phase}${verdictSuffix} at ${new Date().toISOString()}. Auto-closing watch window.`)
+            : `peaks progress watch: sub-agent reached phase=${data.current.phase}${verdictSuffix} at ${new Date().toISOString()}. Auto-closing watch window.`;
+        rawWrite(ERASE_LINE + farewell + '\n');
+    }
+    /**
+     * Force a non-ANSI snapshot of the current state, used by
+     * the `--once` mode and for fallback when stdout is not a
+     * TTY. Does NOT touch the cursor state — safe to call from
+     * any context.
+     */
+    static snapshot(data) {
+        return renderDynamicRows(data, 0, 80, false);
+    }
+}
+/**
+ * Strip ANSI escapes from a string. Used for visible-length
+ * accounting; not for re-painting.
+ */
+export function stripAnsi(input) {
+    // eslint-disable-next-line no-control-regex
+    return input.replace(/\x1b\[[0-9;]*m/g, '');
+}
+/** Reset terminal SGR — used on early-return error paths. */
+export function resetTerminal() {
+    rawWrite(RESET);
+}

package/dist/src/cli/commands/project-commands.js

@@ -123,7 +123,7 @@ export function registerProjectCommands(program, io) {
         .command('memories')
         .description('Read durable project memories (decisions, conventions, modules, rules) from .peaks/memory for LLM consumption')
         .requiredOption('--project <path>', 'target project root')
-        .option('--kind <kind>', 'filter by kind: project, rule, decision, reference, feedback, convention, module')).action((options) => {
+        .option('--kind <kind>', 'filter by kind: project, rule, decision, reference, feedback, convention, module, lesson')).action((options) => {
         try {
             const result = readProjectMemories(options.project);
             if (options.kind) {

package/dist/src/cli/commands/scan-commands.js

@@ -5,6 +5,7 @@ import { checkTypeSanity } from '../../services/scan/type-sanity-service.js';
 import { getAcceptanceCoverage, isAcceptanceCoverageError } from '../../services/scan/acceptance-coverage-service.js';
 import { getDiffVsScope, isDiffScopeError } from '../../services/scan/diff-scope-service.js';
 import { scanFileSize, DEFAULT_FILE_SIZE_THRESHOLD } from '../../services/scan/file-size-scan.js';
+import { scanLibraries } from '../../services/scan/libraries-service.js';
 import { isRequestType, VALID_REQUEST_TYPES } from '../../services/artifacts/artifact-prerequisites.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
@@ -221,4 +222,25 @@ export function registerScanCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(scan
+        .command('libraries')
+        .description('Enumerate every dependency + devDependency + peerDependency + optionalDependency in package.json with parsed major version (read-only). Output goes to ## Library versions in rd/project-scan.md.')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        try {
+            const report = await scanLibraries({ projectRoot: options.project });
+            const nextActions = [];
+            if (report.libraries.length === 0) {
+                nextActions.push('No dependencies found — verify package.json exists and is valid JSON.');
+            }
+            else {
+                nextActions.push('Paste the report under `## Library versions` in .peaks/<sid>/rd/project-scan.md.');
+                nextActions.push('peaks-rd preflight will cross-check diff imports against schemas/library-breaking-changes.data.json.');
+            }
+            printResult(io, ok('scan.libraries', report, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('scan.libraries', 'SCAN_LIBRARIES_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is readable']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

package/dist/src/cli/program.js

@@ -9,6 +9,8 @@ import { registerCapabilityWorkerConfigAndSCCommands } from './commands/capabili
 import { registerCodegraphCommands } from './commands/codegraph-commands.js';
 import { registerMcpCommands } from './commands/mcp-commands.js';
 import { registerOpenSpecCommands } from './commands/openspec-commands.js';
+import { registerPerfCommands } from './commands/perf-commands.js';
+import { registerProgressCommands } from './commands/progress-commands.js';
 import { registerProjectCommands } from './commands/project-commands.js';
 import { registerRequestCommands } from './commands/request-commands.js';
 import { registerScanCommands } from './commands/scan-commands.js';
@@ -79,6 +81,8 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerCodegraphCommands(program, io);
     registerMcpCommands(program, io);
     registerOpenSpecCommands(program, io);
+    registerPerfCommands(program, io);
+    registerProgressCommands(program, io);
     registerProjectCommands(program, io);
     registerRequestCommands(program, io);
     registerScanCommands(program, io);

package/dist/src/services/config/config-types.d.ts

@@ -58,6 +58,26 @@ export type PeaksConfig = {
     tokens: TokenConfig;
     providers: ModelProviderConfig;
     proxy: ProxyConfig;
+    /**
+     * Sub-agent progress surfacing knobs. The `peaks progress watch`
+     * CLI (intended to be run in a separate terminal tab while the
+     * LLM is working) reads `.peaks/<sid>/system/subagent-progress.json`
+     * and renders elapsed / spinner / sub-step in real time. The
+     * `enabled` flag is a kill-switch for users who find the watch
+     * distracting; the `heartbeatIntervalMs` lets power users tune
+     * the write cadence. Both default to sensible values so stock
+     * projects get the feature out of the box.
+     *
+     * Optional on the type level so older test fixtures / hand-
+     * written config files do not have to know about it; the
+     * `DEFAULT_CONFIG.progress` block supplies the runtime defaults
+     * and `config get` will surface a synthesised block when the
+     * field is absent.
+     */
+    progress?: {
+        enabled: boolean;
+        heartbeatIntervalMs: number;
+    };
 };
 export type ConfigLayer = 'user' | 'project';
 export type ConfigGetOptions = {

package/dist/src/services/config/config-types.js

@@ -11,5 +11,9 @@ export const DEFAULT_CONFIG = {
             model: 'minimax-2.7'
         }
     },
-    proxy: {}
+    proxy: {},
+    progress: {
+        enabled: true,
+        heartbeatIntervalMs: 60000
+    }
 };

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

@@ -1,4 +1,4 @@
-export type ProjectMemoryKind = 'project' | 'rule' | 'decision' | 'reference' | 'feedback' | 'convention' | 'module';
+export type ProjectMemoryKind = 'project' | 'rule' | 'decision' | 'reference' | 'feedback' | 'convention' | 'module' | 'lesson';
 export type ExtractedProjectMemory = {
     title: string;
     kind: ProjectMemoryKind;

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

@@ -3,13 +3,20 @@ import { dirname, basename, isAbsolute, join, relative, resolve } from 'node:pat
 import { isInsidePath, isWindowsAbsolutePath, normalizePath, resolveInputPath, stablePath, stableRealPath } from '../../shared/path-utils.js';
 import { containsSensitiveConfigValue, isSensitiveConfigPath } from '../config/config-service.js';
 // Hot kinds: full body kept in index for always-available context
-const HOT_KINDS = new Set(['feedback', 'decision', 'rule', 'convention', 'module']);
+const HOT_KINDS = new Set(['feedback', 'decision', 'rule', 'convention', 'module', 'lesson']);
 // ---------------------------------------------------------------------------
 // Internal helpers (kept from original, sorted by dependency order)
 // ---------------------------------------------------------------------------
 const START_MARKER = '<!-- peaks-memory:start -->';
 const END_MARKER = '<!-- peaks-memory:end -->';
-const VALID_MEMORY_KINDS = new Set(['project', 'rule', 'decision', 'reference', 'feedback', 'convention', 'module']);
+const VALID_MEMORY_KINDS = new Set(['project', 'rule', 'decision', 'reference', 'feedback', 'convention', 'module', 'lesson']);
+// Length bounds for index entry descriptions. The numbers were chosen when
+// summarizeMemoryBody was first introduced; locking them in as named
+// constants is a doc-as-code move so the truncation rule is no longer
+// "magic". Bump MAX_DESCRIPTION_LENGTH deliberately if downstream UIs grow.
+const MIN_BODY_SENTENCE_LENGTH = 20; // skip fragments shorter than this when picking a leading sentence
+const MAX_DESCRIPTION_LENGTH = 120; // hard cap on description length in the memory index entry
+const ELLIPSIS_RESERVE = 3; // length of the trailing "..." when truncating with an ellipsis
 function normalizeRoot(path) {
     return resolveInputPath(path);
 }
@@ -214,15 +221,15 @@ function summarizeMemoryBody(body) {
         .replace(/^\s*[-*+]\s+/gm, '')
         .replace(/\n+/g, ' ')
         .trim();
-    const sentences = cleaned.split(/(?<=[.!?])\s+/).filter((s) => s.length > 20 && !/^\[.+\]$/.test(s));
+    const sentences = cleaned.split(/(?<=[.!?])\s+/).filter((s) => s.length > MIN_BODY_SENTENCE_LENGTH && !/^\[.+\]$/.test(s));
     if (sentences.length === 0) {
-        return cleaned.slice(0, 120) || 'Project memory';
+        return cleaned.slice(0, MAX_DESCRIPTION_LENGTH) || 'Project memory';
     }
     const first = sentences[0];
-    if (first.length <= 120) {
+    if (first.length <= MAX_DESCRIPTION_LENGTH) {
         return first;
     }
-    return first.slice(0, 117) + '...';
+    return first.slice(0, MAX_DESCRIPTION_LENGTH - ELLIPSIS_RESERVE) + '...';
 }
 // ---------------------------------------------------------------------------
 // Session memory extraction (new extract path)
@@ -296,7 +303,7 @@ function readStoredMemoryNames(memoryDir) {
 function generateMemoryIndexFile(projectRoot, memoryDir, indexPath) {
     const memories = readProjectMemories(projectRoot);
     const hot = {
-        feedback: [], decision: [], rule: [], convention: [], module: []
+        feedback: [], decision: [], rule: [], convention: [], module: [], lesson: []
     };
     const warm = {
         project: [], reference: []
@@ -350,29 +357,49 @@ function readExistingIndex(indexPath) {
         return null;
     }
 }
+// Decide whether readMemoryIndex should rebuild the on-disk index.json.
+// The rule is: rebuild iff index.json is missing OR any memory.md has an
+// mtime strictly greater than index.json's mtime. Any statSync failure
+// falls back to "rebuild" — a safe default that matches the prior
+// always-rebuild behaviour and avoids serving a stale index from a
+// partially-corrupt dir.
+function shouldRegenerateIndex(indexPath, memoryFiles) {
+    let indexMtimeMs = 0;
+    try {
+        indexMtimeMs = statSync(indexPath).mtimeMs;
+    }
+    catch {
+        return true; // no index → must regenerate
+    }
+    for (const memoryPath of memoryFiles) {
+        try {
+            const memoryMtimeMs = statSync(memoryPath).mtimeMs;
+            if (memoryMtimeMs > indexMtimeMs)
+                return true;
+        }
+        catch {
+            return true; // unreadable file → safe default is regenerate
+        }
+    }
+    return false;
+}
 export function readMemoryIndex(projectRoot) {
     const normalizedRoot = normalizeRoot(projectRoot);
     const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
     const indexPath = join(memoryDir, 'index.json');
-    // Read-side bootstrap: if the memory dir is missing entirely, build a full
-    // empty index so downstream readers always see a well-formed result. We
-    // also fall through if the dir is present but the index is missing — the
-    // user may have nuked the index file, or never had one because no
-    // memory has ever been extracted in this project.
+    // Read-side bootstrap: if the memory dir is missing entirely, build it and
+    // return whatever index is on disk (likely null on a fresh project). We
+    // deliberately do NOT pre-write an empty index here: the mtime-based
+    // regeneration guard below is the sole authority on whether index.json
+    // gets materialised, and pre-writing an empty index would race the guard
+    // (giving it a current-time mtime that defeats "memory older than index"
+    // detection on the first read).
     if (!existsSync(memoryDir)) {
         ensureMemoryBootstrap(normalizedRoot);
         return readExistingIndex(indexPath);
     }
-    if (!existsSync(indexPath)) {
-        try {
-            writeFileSync(indexPath, renderEmptyIndex(), { mode: 0o644 });
-        }
-        catch {
-            // fall through — readExistingIndex will return null
-        }
-    }
     const files = listMarkdownFiles(memoryDir);
-    if (files.length > 0) {
+    if (files.length > 0 && shouldRegenerateIndex(indexPath, files)) {
         try {
             generateMemoryIndexFile(normalizedRoot, memoryDir, indexPath);
         }
@@ -659,7 +686,8 @@ function emptyByKind() {
         reference: [],
         feedback: [],
         convention: [],
-        module: []
+        module: [],
+        lesson: []
     };
 }
 function emptyIndex() {
@@ -676,7 +704,8 @@ function emptyIndex() {
             decision: [],
             rule: [],
             convention: [],
-            module: []
+            module: [],
+            lesson: []
         },
         warm: {
             project: [],

package/dist/src/services/perf/perf-baseline-service.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Performance baseline scaffolding for the RD stage.
+ *
+ * peaks-solo's RD stage runs before the QA stage. The user-facing pain is
+ * that performance tests (lighthouse / k6 / project-local benches / etc.)
+ * have historically only been run at QA Gate A4 — too late in the loop,
+ * because a slow regression discovered at QA triggers a return-to-rd
+ * cycle, the RD ships another "fix", QA re-runs, and the same cycle
+ * repeats up to 3 times before the slice ships.
+ *
+ * `peaks perf baseline` is the user-visible artifact of a deliberate
+ * compromise: keep the heavy performance measurement as something the
+ * RD runs themselves (lighthouse is project-shape dependent and we
+ * don't want to bake a lighthouse dependency into the CLI), but capture
+ * the result in a stable, scaffolded file under
+ * `.peaks/<sid>/rd/perf-baseline.md` so QA Gate A4 has a known-good
+ * reference to diff against. The CLI itself only writes the scaffold
+ * and records the path; the actual measurement is a project-local
+ * concern that lives in the README, not in peaks-cli.
+ *
+ * The four-grounds check (per the skill-primary-CLI-auxiliary dev
+ * preference):
+ *   1. hook/script/CI invokability  — yes, a hook can call this CLI
+ *                                     to scaffold the file on session
+ *                                     init, similar to session bootstrap.
+ *   2. JSON envelope that gates a downstream decision — yes,
+ *                                     peaks-rd reads the result and
+ *                                     attaches it to the handoff.
+ *   3. Destructive --apply side effect — yes, default dry-run.
+ *   4. Machine-enforced gate that prose cannot enforce — no, the
+ *                                     measurement still lives in
+ *                                     the LLM / project tools. We do
+ *                                     NOT add a lint gate here.
+ *
+ * Net: CLI is justified. The destructive --apply default is dry-run,
+ * matching the rest of peaks-cli's scaffolding pattern.
+ */
+export type PerfBaselineInitOptions = {
+    projectRoot: string;
+    apply?: boolean;
+    reason?: string;
+};
+export type PerfBaselinePlan = {
+    apply: boolean;
+    projectRoot: string;
+    sessionId: string | null;
+    perfBaselinePath: string | null;
+    plannedWrites: Array<{
+        path: string;
+        kind: 'directory' | 'file';
+        bytes: number;
+        content: string;
+    }>;
+    alreadyInitialized: boolean;
+    existingFiles: string[];
+};
+export type PerfBaselineResult = PerfBaselinePlan & {
+    writtenFiles: string[];
+    createdDirectories: string[];
+    reason?: string;
+};
+export declare function executePerfBaselineInit(options: PerfBaselineInitOptions): Promise<PerfBaselineResult>;
+/**
+ * Re-exported so the CLI command can fall back to a project-root
+ * resolution when the caller did not pass --project. The CLI does
+ * the same findProjectRoot walk that `workspace init` does; this
+ * helper exists for the command layer to import without reaching
+ * into config-safety directly.
+ */
+export declare function resolveProjectRootFromCwd(cwd: string): string;