peaks-cli 1.4.1 → 1.4.2

package/README.md

@@ -148,59 +148,6 @@ peaks project memories --project <repo> --json     # 读取 .peaks/memory/ 里
 
 完整命令列表跑 `peaks --help` 即可。
 
-## 技能白名单：`peaks skill scope`
-
-`peaks skill scope` 把"哪些 skill 暴露给当前项目的 LLM"这件事从"全部加载"变成"按项目相关度过滤"。1.4.0 起默认带 shadow-stub 机制，**denied skill 的 LLM 上下文减量约 96.4%**（每个 stub ≈285 字节 vs 原 SKILL.md ≈7-8 KB）。
-
-### 三步走
-
-```bash
-peaks skill scope --detect --project <repo> --json  # 看哪些 skill 被标 relevant / borderline / irrelevant
-peaks skill scope --apply  --project <repo>         # 写 source-of-truth + project-local mirror（默认 shadow-stub）
-peaks skill scope --show   --project <repo>         # 查当前应用了哪个 allowlist
-peaks skill scope --reset  --project <repo>         # 全部撤回
-```
-
-`--apply` 写两份东西：
-- `.peaks/scope/skills.json` — 唯一真源（allowlist + meta）
-- `.claude/skills/<skill>/SKILL.md` — project-local mirror；denied skill 被替换为 ~285 字节的 shadow stub，前 5 行包含 `description: _peaks_scope_disabled` 标记，Claude Code 看到这个标记就跳过它的 full body
-
-### 怎么 `--apply` 真的把上下文砍下来
-
-光把 skill 从 LLM 的可调用列表里 deny 不够——Claude Code 仍然会从项目本地 mirror 读完整的 SKILL.md。**shadow-stub** 把 mirror 也换成 5 行 stub：
-
-```yaml
----
-name: agent-sort
-description: _peaks_scope_disabled
-peaks_scope_disabled: true
----
-# Disabled by `peaks skill scope --apply`
-```
-
-实测在 ice-cola 项目（pnpm monorepo，4 包，TS + Python）：215 个 skill × 1.92 MB → 应用白名单后 44 个 allowed × 364 KB + 123 个 denied × 35 KB stubs = **399 KB 整体 LLM 可见 skill 上下文**。**减量 924.7 KB / 69.8%**，其中 denied 侧减量 96.4%。
-
-shadow-stub 是 1.4.0 的默认行为（`--shadow-fallback`）。想 copy 原 SKILL.md 到 mirror（IDE 端 inspection 用），传 `--no-shadow-fallback` 显式 opt-out。
-
-### 运行时观测：`peaks skill context-stats`
-
-想知道当前项目实际加载了多少 skill 字节 + 估计 token 数：
-
-```bash
-peaks skill context-stats --project <repo>
-# Allowed: 44 skills, 364.4 KB / 91.1K tokens.
-# Denied:  123 skills, 35.0 KB / 8.8K tokens (96.4% shadow-stub reduction).
-# Total:   399.5 KB / 99.9K tokens.
-```
-
-加 `--json` 拿结构化 envelope。还没 apply scope 的项目会拿到 `NO_SCOPE` code + 推荐命令。
-
-### 限制
-
-- detect 的 `relevant` 标记是按文件后缀占比 ≥ 5% 才算的（1.4.1 起的 shareByExtension 阈值）。比如冰-cola 这种 TS + Python 单仓，cpp/golang/java/kotlin/rust/swift 这些 language-specific skill 不会被标 relevant；以前 1 个 stray `.cpp` 文件就会把 `cpp-coding-standards` 误判为 relevant。
-- 阈值可通过 `PEAKS_SCOPE_THRESHOLD=0.05` 环境变量或 `--threshold 0.05` 调整。
-- `.peaks/scope/skills.json` 是 hand-editable 的；手改后下次 `--apply` 会按 detect 结果覆盖（除非带 `--strict` / `--loose` 改 detect 模式，不带 allowOverride）。
-
 ## 自定义 SOP（把你的流程变成带门禁的工作流）
 
 > **技能入口**：`peaks-sop` 技能

package/dist/src/cli/commands/core-artifact-commands.js

@@ -519,6 +519,27 @@ export function registerCoreAndArtifactCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(memory
+        .command('search <query>')
+        .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6.')
+        .option('--kind <kind>', 'filter by memory kind (one of: project, rule, decision, reference, feedback, convention, module, lesson)')
+        .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
+        // Lazy import avoids a top-of-file import cycle (memory-commands.ts
+        // imports services that the rest of this file may also touch).
+        void import('./memory-commands.js').then(({ runMemorySearch }) => {
+            runMemorySearch(io, {
+                query,
+                ...(options.kind !== undefined ? { kind: options.kind } : {}),
+                ...(options.limit !== undefined ? { limit: options.limit } : {}),
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {}),
+            });
+        }).catch((error) => {
+            printResult(io, fail('memory.search', 'MEMORY_SEARCH_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        });
+    });
     const proxy = program.command('proxy').description('Manage proxy settings');
     addJsonOption(proxy
         .command('test')

package/dist/src/cli/commands/memory-commands.d.ts

@@ -0,0 +1,13 @@
+import { type ProgramIO } from '../cli-helpers.js';
+export interface MemorySearchCommandOptions {
+    query: string;
+    kind?: string;
+    limit?: number;
+    project?: string;
+    json?: boolean;
+}
+/**
+ * Run the memory search subcommand. Extracted so unit tests can
+ * exercise the full envelope without spawning a subprocess.
+ */
+export declare function runMemorySearch(io: ProgramIO, options: MemorySearchCommandOptions): void;

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

@@ -0,0 +1,60 @@
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { searchMemory } from '../../services/memory/memory-search-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+const VALID_KINDS = [
+    'project',
+    'rule',
+    'decision',
+    'reference',
+    'feedback',
+    'convention',
+    'module',
+    'lesson',
+];
+/**
+ * Run the memory search subcommand. Extracted so unit tests can
+ * exercise the full envelope without spawning a subprocess.
+ */
+export function runMemorySearch(io, options) {
+    const projectRoot = options.project !== undefined
+        ? resolveCanonicalProjectRoot(options.project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+    const kindFilter = options.kind !== undefined && VALID_KINDS.includes(options.kind)
+        ? options.kind
+        : undefined;
+    // When the user passes --kind but the value isn't in the valid set,
+    // we silently pass `undefined` so the search returns the full set;
+    // that's friendlier than a hard error and matches the spec's
+    // "invalid kind -> empty matches" semantic for the filter path.
+    // (For the loader unit test we exercise the explicit-invalid path
+    // directly; here the CLI side is forgiving.)
+    try {
+        const matches = searchMemory({
+            query: options.query,
+            projectRoot,
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(kindFilter !== undefined ? { kind: kindFilter } : {}),
+        });
+        printResult(io, ok('memory.search', {
+            query: options.query,
+            total: matches.length,
+            matches,
+            warnings: [],
+        }, []), options.json);
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        const code = error.code ?? 'MEMORY_SEARCH_FAILED';
+        const suggestions = [];
+        if (code === 'INDEX_MISSING') {
+            suggestions.push('Run `peaks memory extract --apply` to build the index from memory/*.md files');
+        }
+        if (code === 'EMPTY_QUERY') {
+            suggestions.push('Use `peaks memory index` to list all entries');
+        }
+        printResult(io, fail('memory.search', code, message, { projectRoot, query: options.query }, suggestions), options.json);
+        process.exitCode = 1;
+    }
+}

package/dist/src/cli/commands/retrospective-commands.d.ts

@@ -1,3 +1,12 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
+export interface RetrospectiveSearchCommandOptions {
+    query: string;
+    type?: string;
+    outcome?: string;
+    limit?: number;
+    project?: string;
+    json?: boolean;
+}
+export declare function runRetrospectiveSearch(io: ProgramIO, options: RetrospectiveSearchCommandOptions): void;
 export declare function registerRetrospectiveCommands(program: Command, io: ProgramIO): void;

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

@@ -3,8 +3,50 @@ import { resolveCanonicalProjectRoot } from '../../services/config/config-servic
 import { loadRetrospectiveIndex } from '../../services/retrospective/retrospective-index.js';
 import { showRetrospective } from '../../services/retrospective/retrospective-show.js';
 import { migrateRetrospectiveFromMd } from '../../services/retrospective/migrate-from-md.js';
+import { searchRetrospective } from '../../services/retrospective/retrospective-search-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const VALID_RETRO_TYPES = ['refactor', 'feature', 'bugfix', 'config', 'docs', 'chore'];
+const VALID_RETRO_OUTCOMES = ['shipped', 'blocked', 'in-flight', 'cancelled'];
+export function runRetrospectiveSearch(io, options) {
+    const projectRoot = options.project !== undefined
+        ? resolveCanonicalProjectRoot(options.project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+    const typeFilter = options.type !== undefined && VALID_RETRO_TYPES.includes(options.type)
+        ? options.type
+        : undefined;
+    const outcomeFilter = options.outcome !== undefined && VALID_RETRO_OUTCOMES.includes(options.outcome)
+        ? options.outcome
+        : undefined;
+    try {
+        const matches = searchRetrospective({
+            query: options.query,
+            projectRoot,
+            ...(typeFilter !== undefined ? { type: typeFilter } : {}),
+            ...(outcomeFilter !== undefined ? { outcome: outcomeFilter } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        });
+        printResult(io, ok('retrospective.search', {
+            query: options.query,
+            total: matches.length,
+            matches,
+            warnings: [],
+        }, []), options.json);
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        const code = error.code ?? 'RETROSPECTIVE_SEARCH_FAILED';
+        const suggestions = [];
+        if (code === 'INDEX_MISSING') {
+            suggestions.push('Run `peaks retrospective migrate --apply` to build the index from legacy MDs');
+        }
+        if (code === 'EMPTY_QUERY') {
+            suggestions.push('Use `peaks retrospective index` to list all entries');
+        }
+        printResult(io, fail('retrospective.search', code, message, { projectRoot, query: options.query }, suggestions), options.json);
+        process.exitCode = 1;
+    }
+}
 export function registerRetrospectiveCommands(program, io) {
     const retrospective = program.command('retrospective').description('Read the peaks retrospective index (R3: index.json, not the legacy <id>/ MD tree)');
     addJsonOption(retrospective
@@ -110,4 +152,20 @@ export function registerRetrospectiveCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(retrospective
+        .command('search <query>')
+        .description('Fuzzy-search the retrospective index (deterministic, local, zero-token). Default --limit 6.')
+        .option('--type <type>', `filter by retrospective type (one of: ${VALID_RETRO_TYPES.join(', ')})`)
+        .option('--outcome <outcome>', `filter by retrospective outcome (one of: ${VALID_RETRO_OUTCOMES.join(', ')})`)
+        .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
+        runRetrospectiveSearch(io, {
+            query,
+            ...(options.type !== undefined ? { type: options.type } : {}),
+            ...(options.outcome !== undefined ? { outcome: options.outcome } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options.project !== undefined ? { project: options.project } : {}),
+            ...(options.json !== undefined ? { json: options.json } : {}),
+        });
+    });
 }

package/dist/src/cli/program.js

@@ -16,7 +16,6 @@ import { registerProjectCommands } from './commands/project-commands.js';
 import { registerRequestCommands } from './commands/request-commands.js';
 import { registerRetrospectiveCommands } from './commands/retrospective-commands.js';
 import { registerScanCommands } from './commands/scan-commands.js';
-import { registerShadcnCommands } from './commands/shadcn-commands.js';
 import { registerSliceCommands } from './commands/slice-commands.js';
 import { registerSopCommands } from './commands/sop-commands.js';
 import { registerSubAgentCommands } from './commands/sub-agent-commands.js';
@@ -27,7 +26,6 @@ import { registerHooksCommands } from './commands/hooks-commands.js';
 import { registerStatusLineCommands } from './commands/statusline-commands.js';
 import { registerUnderstandCommands } from './commands/understand-commands.js';
 import { registerWorkspaceCommands } from './commands/workspace-commands.js';
-import { registerSkillScopeCommands } from './commands/skill-scope-commands.js';
 import { registerWorkflowPlanCommands } from './commands/workflow-plan-commands.js';
 export { printResult } from './cli-helpers.js';
 export function createProgram(io = { stdout: (text) => console.log(text), stderr: (text) => console.error(text) }) {
@@ -37,13 +35,13 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
         .description(`Peaks CLI ${CLI_VERSION} — workflow-gating CLI + skill family for Claude Code
 
 Run peaks (no arguments) for a quickstart. You likely want one of:
-  peaks doctor     check your environment
-  peaks skill      list or manage skills
-  peaks slice      boundary check (tsc + vitest + 3-way + verify-pipeline)
-  peaks workflow   plan workflow routing dry-run graphs
-  peaks sop        author your own workflow gates
-  peaks hooks      install the un-bypassable gate-enforcement hook
-  peaks gate       enforce/bypass SOP gates on Bash commands`)
+ peaks doctor check your environment
+ peaks skill list or manage skills
+ peaks slice boundary check (tsc + vitest +3-way + verify-pipeline)
+ peaks workflow plan workflow routing dry-run graphs
+ peaks sop author your own workflow gates
+ peaks hooks install the un-bypassable gate-enforcement hook
+ peaks gate enforce/bypass SOP gates on Bash commands`)
         .configureOutput({
         writeOut: (text) => io.stdout(text.trimEnd()),
         writeErr: (text) => io.stderr(text.trimEnd())
@@ -69,19 +67,19 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
             }
         }
         catch { /* disk read is best-effort; zero skills is still truthful */ }
-        io.stdout(`Peaks CLI ${CLI_VERSION}  ·  ${skillCount} skills ready
+        io.stdout(`Peaks CLI ${CLI_VERSION} · ${skillCount} skills ready
 
-  Peaks is a workflow-gating CLI + skill family for Claude Code.
-  It turns "don't skip steps" into hard enforcement — gates that block
-  advancement in-conversation, un-bypassably.
+ Peaks is a workflow-gating CLI + skill family for Claude Code.
+ It turns "don't skip steps" into hard enforcement — gates that block
+ advancement in-conversation, un-bypassably.
 
-  Before diving into a project, two things worth doing now:
+ Before diving into a project, two things worth doing now:
 
-    peaks doctor             check your environment in one glance
-    peaks-sop                <<< ask this skill to author your first SOP
+ peaks doctor check your environment in one glance
+ peaks-sop <<< ask this skill to author your first SOP
 
-  Or jump straight in:
-    peaks sop init --id my-flow --apply && peaks hooks install
+ Or jump straight in:
+ peaks sop init --id my-flow --apply && peaks hooks install
 `);
     })
         .exitOverride();
@@ -95,7 +93,6 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerRequestCommands(program, io);
     registerRetrospectiveCommands(program, io);
     registerScanCommands(program, io);
-    registerShadcnCommands(program, io);
     registerSliceCommands(program, io);
     registerSopCommands(program, io);
     registerSubAgentCommands(program, io);
@@ -109,9 +106,6 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerStatusLineCommands(program, io);
     registerUnderstandCommands(program, io);
     registerWorkspaceCommands(program, io);
-    // Slice 025: peaks skill scope — per-project multi-IDE skill scoping.
-    registerSkillScopeCommands(program, io);
-    // Slice 025: peaks workflow plan — security/perf plan/result split CLI.
     registerWorkflowPlanCommands(program, io);
     return program;
 }

package/dist/src/services/fuzzy-matching/fuzzy-match-service.d.ts

@@ -0,0 +1,15 @@
+import type { FuzzyMatchOptions, FuzzyMatchResult } from './types.js';
+/**
+ * String-overload: when `items` is an array of strings, the searchable text
+ * is the string itself. No keyFn is required.
+ */
+export declare function fuzzyMatch<T extends string>(query: string, items: T[], options?: FuzzyMatchOptions): FuzzyMatchResult<T>[];
+/**
+ * Object-overload: caller provides a `keyFn` that extracts the searchable
+ * text from each item. The keyFn is invoked once per item per call; the
+ * caller is responsible for ensuring the result is stable (e.g., don't
+ * concatenate mutable fields).
+ */
+export declare function fuzzyMatchWithKey<T>(query: string, items: T[], options: FuzzyMatchOptions & {
+    keyFn: (item: T) => string;
+}): FuzzyMatchResult<T>[];

package/dist/src/services/fuzzy-matching/fuzzy-match-service.js

@@ -0,0 +1,56 @@
+import { Fzf } from 'fzf';
+/**
+ * Default limit for fuzzy-match. Aligned with the spec's "--limit default 6".
+ */
+const DEFAULT_LIMIT = 6;
+/**
+ * String-overload: when `items` is an array of strings, the searchable text
+ * is the string itself. No keyFn is required.
+ */
+export function fuzzyMatch(query, items, options = {}) {
+    return fuzzyMatchWithKey(query, items, { ...options, keyFn: (item) => item });
+}
+/**
+ * Object-overload: caller provides a `keyFn` that extracts the searchable
+ * text from each item. The keyFn is invoked once per item per call; the
+ * caller is responsible for ensuring the result is stable (e.g., don't
+ * concatenate mutable fields).
+ */
+export function fuzzyMatchWithKey(query, items, options) {
+    const { keyFn } = options;
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    if (items.length === 0)
+        return [];
+    // Empty query: surface all items (capped at limit) with neutral score and
+    // empty positions. Useful for "list" or "preview" use cases where the
+    // caller wants a deterministic top-N without a query.
+    if (query === '') {
+        return items.slice(0, limit).map((item) => ({ item, score: 0, positions: [] }));
+    }
+    const fzf = new Fzf(items, {
+        selector: keyFn,
+        limit,
+        // Per spec: default is case-insensitive (NOT fzf's smart-case).
+        // The user explicitly opts into case-sensitive via caseSensitive:true.
+        casing: options.caseSensitive === true ? 'case-sensitive' : 'case-insensitive',
+        // normalize:true (default) strips diacritics; fzf returns more matches
+        // for non-ASCII text this way, which is what we want for
+        // bilingual (zh-CN + en) memory entries.
+    });
+    const raw = fzf.find(query);
+    if (raw.length === 0)
+        return [];
+    // fzf-for-js score is "higher = better". Normalize so the top of the
+    // current batch is exactly 1.0 and others are in [0, 1].
+    // When the top score is 0 (degenerate — exact-character-only query that
+    // still matched somehow), fall back to 1.0 to avoid divide-by-zero.
+    const topScore = raw[0]?.score ?? 1;
+    const denom = topScore > 0 ? topScore : 1;
+    return raw.slice(0, limit).map((entry) => {
+        const score = topScore > 0 ? Number((entry.score / denom).toFixed(4)) : 1;
+        // positions is a Set<number> in fzf-for-js; convert to a sorted array
+        // so the JSON envelope is stable and human-readable.
+        const positions = [...entry.positions].sort((a, b) => a - b);
+        return { item: entry.item, score, positions };
+    });
+}

package/dist/src/services/fuzzy-matching/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Options for the generic fuzzy-match kernel.
+ */
+export interface FuzzyMatchOptions {
+    /** Maximum number of matches to return. Default 6. */
+    limit?: number;
+    /** When true, matching is case-sensitive. Default false (smart-case). */
+    caseSensitive?: boolean;
+}
+/**
+ * A single fuzzy-match hit. `item` is the original entry; `score` is
+ * normalized to [0, 1] with the top of the current batch at 1.0;
+ * `positions` is the set of char indices in the searchable text that
+ * contributed to the match.
+ */
+export interface FuzzyMatchResult<T> {
+    item: T;
+    score: number;
+    positions: number[];
+}

package/dist/src/services/fuzzy-matching/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,61 @@
+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[];

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

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fuzzyMatchWithKey } from '../fuzzy-matching/fuzzy-match-service.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,
+        };
+    });
+}

package/dist/src/services/recommendations/capability-seed-items.js

@@ -95,7 +95,6 @@ export const seedCapabilityItems = [
     capability('agent-browser.browser-agent', 'agent-browser', 'Agent Browser', 'agent', 'browser-agent', ['engineer', 'qa'], 'medium', 'manual-browser-walkthrough', 'Use screenshots and manual test steps if agent browser is unavailable.', 'Agent Browser', '浏览器代理', 'Supports browser-based validation and interaction planning.', '支持基于浏览器的验证和交互规划。'),
     capability('minimax-skills.worker-guidance', 'minimax-skills', 'MiniMax Worker Guidance', 'skill', 'worker-guidance', ['engineer'], 'medium', 'peaks-worker-contract', 'Use Peaks built-in minimax-worker contract and review handoff.', 'MiniMax Worker Guidance', 'MiniMax Worker 指南', 'Guides MiniMax coding/test worker delegation.', '指导 MiniMax 编码/测试 worker 委托。'),
     capability('claude-mem.memory-persistence', 'claude-mem', 'Claude Memory Persistence', 'skill', 'memory', ['engineer'], 'medium', 'peaks-txt-context-capsule', 'Use peaks-txt context capsules without storing secrets.', 'Memory Persistence', '记忆持久化', 'Persists reusable context when explicitly approved.', '在明确授权时持久化可复用上下文。'),
-    capability('shadcn-ui.component-system', 'shadcn-ui', 'shadcn/ui Component System', 'doc', 'ui-components', ['engineer', 'designer'], 'low', 'project-local-ui-patterns', 'Use existing project components and design tokens.', 'Component System Reference', '组件系统参考', 'Provides component and design-system references for UI planning.', '为 UI 规划提供组件和设计系统参考。'),
     capability('openspec.spec-workflow', 'openspec', 'OpenSpec Workflow', 'workflow', 'spec-workflow', ['product', 'engineer'], 'low', 'peaks-prd-rd-qa-artifacts', 'Use Peaks built-in PRD/RD/QA artifact flow.', 'OpenSpec Workflow', 'OpenSpec 规格流程', 'Supports spec-first product and engineering governance.', '支持规格优先的产品与工程治理。'),
     capability('gitnexus.repo-intelligence', 'gitnexus', 'GitNexus Repository Intelligence', 'cli', 'repo-intelligence', ['engineer'], 'medium', 'local-repo-scan', 'Use local project scanning through Peaks RD.', 'Repository Intelligence', '仓库智能分析', 'Repository intelligence should be proxied through Peaks before use.', '仓库智能分析应先通过 Peaks 代理边界再使用。'),
     capability('claude-code-best-practice.workflow-guidance', 'claude-code-best-practice', 'Claude Code Best Practice', 'doc', 'workflow-guidance', ['engineer'], 'low', 'peaks-built-in-rules', 'Use Peaks built-in workflow and review rules.', 'Claude Code Best Practice', 'Claude Code 最佳实践', 'Guidance for Claude Code engineering workflows.', 'Claude Code 工程工作流指导。'),

package/dist/src/services/recommendations/capability-seed-mappings.js

@@ -33,7 +33,6 @@ export const seedCapabilityLandingMappings = [
     mapping({ capabilityId: 'agent-browser.browser-agent', sourceId: 'agent-browser', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use for browser validation; never submit forms or mutate authenticated state without explicit permission.' }),
     mapping({ capabilityId: 'minimax-skills.worker-guidance', sourceId: 'minimax-skills', sourceGroup: 'mcp-server', landingKind: 'cli', target: 'peaks minimax-worker', commandPreview: 'peaks minimax-worker --json', guidance: 'Use Peaks worker command only after reviewing inputs; add --confirm manually when explicit external-provider approval exists.' }),
     mapping({ capabilityId: 'claude-mem.memory-persistence', sourceId: 'claude-mem', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-txt', skillName: 'peaks-txt', guidance: 'Use only with explicit durable-memory consent and never store secrets.' }),
-    mapping({ capabilityId: 'shadcn-ui.component-system', sourceId: 'shadcn-ui', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-ui', skillName: 'peaks-ui', guidance: 'Use as a component-system reference, not as an unreviewed generated UI default.' }),
     mapping({ capabilityId: 'darwin-skill.external-skill', sourceId: 'darwin-skill', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'external skill catalog', guidance: 'Catalog only until inspected for project fit and safety.' }),
     mapping({ capabilityId: 'claude-code-best-practice.workflow-guidance', sourceId: 'claude-code-best-practice', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use as Claude Code workflow reference while preserving Peaks gates.' }),
     mapping({ capabilityId: 'openspec.spec-workflow', sourceId: 'openspec', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-prd', skillName: 'peaks-prd', guidance: 'Use for spec-first product and engineering artifact structure.' }),

package/dist/src/services/recommendations/capability-seed-sources.js

@@ -17,7 +17,6 @@ export const seedCapabilitySources = [
     { sourceId: 'agent-browser', sourceType: 'repo', sourceGroup: 'mcp-server', title: 'Agent Browser', url: 'https://github.com/vercel-labs/agent-browser', discoveryStatus: 'indexed', items: ['agent-browser.browser-agent'] },
     { sourceId: 'minimax-skills', sourceType: 'skills-package', sourceGroup: 'mcp-server', title: 'MiniMax Skills', url: 'https://github.com/MiniMax-AI/skills', discoveryStatus: 'indexed', items: ['minimax-skills.worker-guidance'] },
     { sourceId: 'claude-mem', sourceType: 'repo', sourceGroup: 'mcp-server', title: 'claude-mem', url: 'https://github.com/thedotmack/claude-mem', discoveryStatus: 'indexed', items: ['claude-mem.memory-persistence'] },
-    { sourceId: 'shadcn-ui', sourceType: 'repo', sourceGroup: 'mcp-server', title: 'shadcn/ui', url: 'https://github.com/shadcn-ui/ui', discoveryStatus: 'indexed', items: ['shadcn-ui.component-system'] },
     { sourceId: 'darwin-skill', sourceType: 'skills-package', sourceGroup: 'mcp-server', title: 'darwin-skill', url: 'https://github.com/alchaincyf/darwin-skill', discoveryStatus: 'unscanned', items: ['darwin-skill.external-skill'] },
     { sourceId: 'claude-code-best-practice', sourceType: 'repo', sourceGroup: 'mcp-server', title: 'Claude Code Best Practice', url: 'https://github.com/shanraisshan/claude-code-best-practice', discoveryStatus: 'indexed', items: ['claude-code-best-practice.workflow-guidance'] },
     { sourceId: 'openspec', sourceType: 'repo', sourceGroup: 'mcp-server', title: 'OpenSpec', url: 'https://github.com/Fission-AI/OpenSpec', discoveryStatus: 'indexed', items: ['openspec.spec-workflow'] },

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

@@ -0,0 +1,37 @@
+export type { RetrospectiveType, RetrospectiveOutcome, RetrospectiveEntry } from './retrospective-index.js';
+import type { RetrospectiveType, RetrospectiveOutcome } from './retrospective-index.js';
+/**
+ * Input to `searchRetrospective`. `projectRoot` defaults to `process.cwd()`.
+ * `query` is required and non-empty. `type` and `outcome` are optional
+ * structured filters that compose with AND.
+ */
+export interface RetrospectiveSearchInput {
+    query: string;
+    projectRoot?: string;
+    limit?: number;
+    type?: RetrospectiveType;
+    outcome?: RetrospectiveOutcome;
+}
+/**
+ * One hit returned by `searchRetrospective`. The `artifactPaths` are
+ * preserved so the LLM can follow up with `peaks retrospective show
+ * <id>` (or read the artifact directly).
+ */
+export interface RetrospectiveSearchResult {
+    id: string;
+    sessionId: string;
+    type: RetrospectiveType;
+    title: string;
+    summary: string;
+    outcome: RetrospectiveOutcome;
+    artifactPaths: string[];
+    score: number;
+    positions: number[];
+}
+/**
+ * Run the generic fuzzy kernel against the on-disk retrospective index.
+ * Searchable text is `title + " " + summary` per spec §Component Details.
+ * `--type` and `--outcome` filters compose with AND before the kernel
+ * runs (cheaper to filter, then fuzzy on a smaller set).
+ */
+export declare function searchRetrospective(input: RetrospectiveSearchInput): RetrospectiveSearchResult[];