fluffy-context 0.1.0 → 0.3.0

package/dist/src/integrations/claude-code.d.ts

@@ -0,0 +1,19 @@
+export interface ClaudeIntegrationStatus {
+    projectRoot: string;
+    initialized: boolean;
+    settingsPath: string;
+    mcpPath: string;
+    settingsExists: boolean;
+    mcpExists: boolean;
+    sessionStartInstalled: boolean;
+    userPromptInstalled: boolean;
+    mcpInstalled: boolean;
+    mcpConflict: boolean;
+    installationNeeded: boolean;
+}
+export interface ClaudeIntegrationInstallResult extends ClaudeIntegrationStatus {
+    applied: boolean;
+    targetFiles: string[];
+}
+export declare function inspectClaudeIntegration(startPath: string | undefined): Promise<ClaudeIntegrationStatus>;
+export declare function installClaudeIntegration(startPath: string | undefined, apply: boolean): Promise<ClaudeIntegrationInstallResult>;

package/dist/src/integrations/claude-code.js

@@ -0,0 +1,122 @@
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { atomicWriteJson } from '../storage/atomic-write.js';
+import { isRecord, readJson } from '../storage/json-store.js';
+import { manifestPath } from '../storage/layout.js';
+const HOOK_COMMANDS = {
+    sessionStart: 'ctx hook claude-code session-start',
+    userPrompt: 'ctx hook claude-code user-prompt',
+};
+const MCP_SERVER = { command: 'ctx', args: ['agent', 'serve'] };
+function object(value) {
+    return isRecord(value) ? { ...value } : {};
+}
+function hookInstalled(value, command) {
+    if (!Array.isArray(value))
+        return false;
+    return value.some((group) => isRecord(group)
+        && Array.isArray(group.hooks)
+        && group.hooks.some((hook) => isRecord(hook) && hook.type === 'command' && hook.command === command));
+}
+function addHook(value, command) {
+    const groups = Array.isArray(value) ? value.filter(isRecord).map((group) => ({ ...group })) : [];
+    if (hookInstalled(groups, command))
+        return groups;
+    return [...groups, { hooks: [{ type: 'command', command }] }];
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadObject(filePath) {
+    if (!await exists(filePath))
+        return {};
+    return readJson(filePath, isRecord);
+}
+function validateConfig(settings, mcp) {
+    if (settings.hooks !== undefined && !isRecord(settings.hooks))
+        throw new Error('Claude Code settings hooks must be an object');
+    const hooks = object(settings.hooks);
+    for (const event of ['SessionStart', 'UserPromptSubmit']) {
+        if (hooks[event] !== undefined && !Array.isArray(hooks[event]))
+            throw new Error(`Claude Code ${event} hooks must be an array`);
+    }
+    if (mcp.mcpServers !== undefined && !isRecord(mcp.mcpServers))
+        throw new Error('Claude Code MCP servers must be an object');
+}
+function status(projectRoot, settingsPath, mcpPath, settings, mcp, settingsExists, mcpExists, initialized) {
+    const hooks = object(settings.hooks);
+    const sessionStartInstalled = hookInstalled(hooks.SessionStart, HOOK_COMMANDS.sessionStart);
+    const userPromptInstalled = hookInstalled(hooks.UserPromptSubmit, HOOK_COMMANDS.userPrompt);
+    const mcpServers = object(mcp.mcpServers);
+    const configuredMcp = mcpServers['fluffy-context'];
+    const mcpInstalled = isRecord(configuredMcp)
+        && configuredMcp.command === MCP_SERVER.command
+        && Array.isArray(configuredMcp.args)
+        && configuredMcp.args.length === MCP_SERVER.args.length
+        && configuredMcp.args.every((value, index) => value === MCP_SERVER.args[index]);
+    const mcpConflict = configuredMcp !== undefined && !mcpInstalled;
+    return {
+        projectRoot,
+        initialized,
+        settingsPath,
+        mcpPath,
+        settingsExists,
+        mcpExists,
+        sessionStartInstalled,
+        userPromptInstalled,
+        mcpInstalled,
+        mcpConflict,
+        installationNeeded: !sessionStartInstalled || !userPromptInstalled || !mcpInstalled,
+    };
+}
+async function inspect(projectRoot) {
+    const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+    const mcpPath = path.join(projectRoot, '.mcp.json');
+    const [settingsExists, mcpExists, initialized] = await Promise.all([
+        exists(settingsPath),
+        exists(mcpPath),
+        exists(manifestPath(projectRoot)),
+    ]);
+    const [settings, mcp] = await Promise.all([loadObject(settingsPath), loadObject(mcpPath)]);
+    validateConfig(settings, mcp);
+    return { status: status(projectRoot, settingsPath, mcpPath, settings, mcp, settingsExists, mcpExists, initialized), settings, mcp };
+}
+export async function inspectClaudeIntegration(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    return (await inspect(projectRoot)).status;
+}
+export async function installClaudeIntegration(startPath, apply) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const inspected = await inspect(projectRoot);
+    const targetFiles = [inspected.status.settingsPath, inspected.status.mcpPath];
+    if (!apply || !inspected.status.installationNeeded)
+        return { ...inspected.status, applied: false, targetFiles };
+    if (inspected.status.mcpConflict)
+        throw new Error('existing fluffy-context MCP server configuration conflicts with the generated integration');
+    const settingsHooks = object(inspected.settings.hooks);
+    const settings = {
+        ...inspected.settings,
+        hooks: {
+            ...settingsHooks,
+            SessionStart: addHook(settingsHooks.SessionStart, HOOK_COMMANDS.sessionStart),
+            UserPromptSubmit: addHook(settingsHooks.UserPromptSubmit, HOOK_COMMANDS.userPrompt),
+        },
+    };
+    const mcpServers = object(inspected.mcp.mcpServers);
+    const mcp = {
+        ...inspected.mcp,
+        mcpServers: { ...mcpServers, 'fluffy-context': MCP_SERVER },
+    };
+    await Promise.all([
+        atomicWriteJson(inspected.status.settingsPath, settings),
+        atomicWriteJson(inspected.status.mcpPath, mcp),
+    ]);
+    return { ...(await inspect(projectRoot)).status, applied: true, targetFiles };
+}

package/dist/src/mcp/main.d.ts

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

package/dist/src/mcp/main.js

@@ -0,0 +1,5 @@
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { createMcpServer } from './server.js';
+serveStdio(createMcpServer, {
+    onerror: (error) => process.stderr.write(`MCP server error: ${error.message}\n`),
+});

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/server';
+export declare function createMcpServer(): McpServer;

package/dist/src/mcp/server.js

@@ -0,0 +1,40 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+import { contextOrient } from '../agent/api.js';
+import { VERSION } from '../version.js';
+const orientInput = z.object({
+    path: z.string().optional(),
+    contextId: z.string().optional(),
+    query: z.string().optional(),
+    scope: z.string().optional(),
+    maxChars: z.int().nonnegative().optional(),
+    knowledgeLimit: z.int().nonnegative().optional(),
+    deadendLimit: z.int().nonnegative().optional(),
+    noteLimit: z.int().nonnegative().optional(),
+});
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function createMcpServer() {
+    const server = new McpServer({ name: 'fluffy-context', version: VERSION });
+    server.registerTool('context_orient', {
+        title: 'Orient context',
+        description: 'Load bounded, read-only task context with verified consensus and open notes.',
+        inputSchema: orientInput,
+    }, async ({ path, ...options }) => {
+        try {
+            const result = await contextOrient(path, options);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `context_orient failed: ${errorMessage(error)}` }],
+            };
+        }
+    });
+    return server;
+}

package/dist/src/project/project-resolver.d.ts

@@ -0,0 +1 @@
+export declare function resolveProjectRoot(startPath?: string): Promise<string>;

package/dist/src/runtime/diagnostics.d.ts

@@ -0,0 +1,6 @@
+export declare function status(startPath?: string): Promise<Record<string, unknown>>;
+export declare function doctor(startPath?: string): Promise<{
+    healthy: boolean;
+    projectRoot: string;
+    checks: string[];
+}>;

package/dist/src/runtime/diagnostics.js

@@ -1,8 +1,10 @@
 import { access, readdir } from 'node:fs/promises';
 import { resolveProjectRoot } from '../project/project-resolver.js';
 import { readJson } from '../storage/json-store.js';
-import { contextRoot, contextMetadataPath, contextsRoot, indexPath, manifestPath, snapshotPath } from '../storage/layout.js';
-import { rebuildIndex } from './runtime.js';
+import { contextRoot, contextMetadataPath, contextsRoot, indexPath, manifestPath, notesPath, snapshotPath } from '../storage/layout.js';
+import { rebuildIndex, rebuildSnapshot } from './runtime.js';
+import { isValidNote } from './notes.js';
+import { filterPaths } from '../capture/context-filter.js';
 export async function status(startPath) {
     const projectRoot = await resolveProjectRoot(startPath);
     try {
@@ -50,15 +52,42 @@ export async function doctor(startPath) {
         const entries = await readdir(contextsRoot(projectRoot));
         for (const contextId of entries) {
             const context = await readJson(contextMetadataPath(projectRoot, contextId));
-            if (context.id !== contextId || context.schemaVersion !== 1)
+            if (context.id !== contextId || context.schemaVersion !== 1 || typeof context.title !== 'string' || typeof context.projectRoot !== 'string' || typeof context.updatedAt !== 'string') {
                 throw new Error(`invalid context ${contextId}`);
-            if (context.currentSnapshotId)
+            }
+            if (context.currentSnapshotId) {
                 await access(snapshotPath(projectRoot, contextId, context.currentSnapshotId));
+                await rebuildSnapshot(projectRoot, contextId, context.currentSnapshotId);
+            }
+        }
+    });
+    await check('notes', async () => {
+        try {
+            const notes = await readJson(notesPath(projectRoot));
+            if (notes.schemaVersion !== 1 || !Array.isArray(notes.items) || notes.items.some((note) => !isValidNote(note)))
+                throw new Error('invalid notes');
+            const ids = new Set(notes.items.map((note) => note.noteId));
+            if (ids.size !== notes.items.length)
+                throw new Error('duplicate note id');
+            const contextIds = new Set((await readdir(contextsRoot(projectRoot))).filter((entry) => entry.startsWith('ctx-')));
+            for (const note of notes.items) {
+                if (note.contextId && !contextIds.has(note.contextId))
+                    throw new Error(`note ${note.noteId} references missing context`);
+                if (note.relatedFiles.length !== (await filterPaths(projectRoot, note.relatedFiles)).length)
+                    throw new Error(`note ${note.noteId} contains filtered paths`);
+                if (note.snapshotId && note.contextId)
+                    await access(snapshotPath(projectRoot, note.contextId, note.snapshotId));
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return;
+            throw error;
         }
     });
     await check('index rebuild', async () => {
         const stored = await readJson(indexPath(projectRoot));
-        const rebuilt = await rebuildIndex(projectRoot);
+        const rebuilt = await rebuildIndex(projectRoot, false);
         const rebuiltIds = new Set(rebuilt.contexts.map((entry) => entry.contextId));
         const storedIds = new Set(stored.contexts.map((entry) => entry.contextId));
         if (rebuiltIds.size !== rebuilt.contexts.length || storedIds.size !== stored.contexts.length)

package/dist/src/runtime/init.d.ts

@@ -0,0 +1,7 @@
+import type { Manifest } from './types.js';
+export interface InitResult {
+    projectRoot: string;
+    alreadyInitialized: boolean;
+}
+export declare function initProject(startPath?: string): Promise<InitResult>;
+export declare function loadManifest(projectRoot: string): Promise<Manifest>;

package/dist/src/runtime/knowledge.d.ts

@@ -0,0 +1,9 @@
+import type { Deadend, DeadendDiscoverOptions, DeadendDiscoveryResult, DeadendInput, Knowledge, KnowledgeDiscoverOptions, KnowledgeDiscoveryResult, KnowledgeInput } from './types.js';
+export declare function learnKnowledge(startPath: string | undefined, statement: string, scopeOrInput?: string | KnowledgeInput): Promise<Knowledge>;
+export declare function listKnowledge(startPath?: string, includeUnverified?: boolean): Promise<Knowledge[]>;
+export declare function discoverKnowledge(startPath: string | undefined, query: string, options?: KnowledgeDiscoverOptions): Promise<KnowledgeDiscoveryResult>;
+export declare function verifyKnowledge(startPath: string | undefined, knowledgeId: string): Promise<Knowledge>;
+export declare function recordDeadend(startPath: string | undefined, attempt: string, reason: string, scopeOrInput?: string | DeadendInput): Promise<Deadend>;
+export declare function listDeadends(startPath?: string, includeUnverified?: boolean): Promise<Deadend[]>;
+export declare function discoverDeadends(startPath: string | undefined, query: string, options?: DeadendDiscoverOptions): Promise<DeadendDiscoveryResult>;
+export declare function verifyDeadend(startPath: string | undefined, deadendId: string): Promise<Deadend>;

package/dist/src/runtime/knowledge.js

@@ -1,30 +1,73 @@
 import crypto from 'node:crypto';
-import { access } from 'node:fs/promises';
 import { resolveProjectRoot } from '../project/project-resolver.js';
 import { atomicWriteJson } from '../storage/atomic-write.js';
 import { isRecord, readJson } from '../storage/json-store.js';
 import { withLock } from '../storage/lock.js';
 import { contextMetadataPath, deadendsPath, knowledgePath, locksDirectory, snapshotPath } from '../storage/layout.js';
+import { rebuildSnapshot } from './runtime.js';
 function id(prefix) {
     return `${prefix}-${Date.now().toString(36)}-${crypto.randomBytes(4).toString('hex')}`;
 }
 function isNotFound(error) {
     return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }
+function isKnowledge(value) {
+    return isRecord(value)
+        && typeof value.knowledgeId === 'string'
+        && typeof value.kind === 'string' && value.kind.trim().length > 0
+        && typeof value.statement === 'string' && value.statement.trim().length > 0
+        && typeof value.scope === 'string' && value.scope.trim().length > 0
+        && typeof value.confidence === 'number' && value.confidence >= 0 && value.confidence <= 1
+        && ['candidate', 'verified', 'deprecated', 'rejected'].includes(value.status)
+        && Array.isArray(value.sourceContextIds) && value.sourceContextIds.every((item) => typeof item === 'string')
+        && Array.isArray(value.sourceSnapshotIds) && value.sourceSnapshotIds.every((item) => typeof item === 'string')
+        && Array.isArray(value.supportingEvidence) && value.supportingEvidence.every((item) => typeof item === 'string')
+        && typeof value.createdAt === 'string'
+        && typeof value.updatedAt === 'string';
+}
 function isKnowledgeFile(value) {
-    return isRecord(value) && value.schemaVersion === 1 && Array.isArray(value.items);
+    if (!isRecord(value) || value.schemaVersion !== 1 || !Array.isArray(value.items) || !value.items.every(isKnowledge))
+        return false;
+    const ids = value.items.map((item) => item.knowledgeId);
+    return new Set(ids).size === ids.length;
+}
+function cleanList(values) {
+    return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
+}
+function normalized(value) {
+    return value.trim().toLocaleLowerCase();
+}
+function isDeadend(value) {
+    return isRecord(value)
+        && typeof value.deadendId === 'string'
+        && typeof value.attempt === 'string'
+        && typeof value.reason === 'string'
+        && Array.isArray(value.observedEvidence) && value.observedEvidence.every((item) => typeof item === 'string')
+        && typeof value.scope === 'string'
+        && ['candidate', 'verified', 'obsolete', 'rejected'].includes(value.status)
+        && (typeof value.sourceContextId === 'string' || value.sourceContextId === null)
+        && (typeof value.sourceSnapshotId === 'string' || value.sourceSnapshotId === null)
+        && typeof value.createdAt === 'string'
+        && typeof value.updatedAt === 'string';
 }
 function isDeadendFile(value) {
-    return isRecord(value) && value.schemaVersion === 1 && Array.isArray(value.items);
+    if (!isRecord(value) || value.schemaVersion !== 1 || !Array.isArray(value.items) || !value.items.every(isDeadend))
+        return false;
+    const ids = value.items.map((item) => item.deadendId);
+    return new Set(ids).size === ids.length;
 }
 async function validateSource(projectRoot, contextId, snapshotId) {
     if (!contextId && snapshotId)
         throw new Error('source snapshot requires source context');
     if (!contextId)
         return;
-    await access(contextMetadataPath(projectRoot, contextId));
-    if (snapshotId)
-        await access(snapshotPath(projectRoot, contextId, snapshotId));
+    const context = await readJson(contextMetadataPath(projectRoot, contextId), (value) => isRecord(value) && value.id === contextId && value.schemaVersion === 1);
+    if (snapshotId) {
+        const snapshot = await readJson(snapshotPath(projectRoot, contextId, snapshotId), (value) => isRecord(value) && value.snapshotId === snapshotId && value.contextId === contextId && value.schemaVersion === 1);
+        await rebuildSnapshot(projectRoot, contextId, snapshot.snapshotId);
+    }
+    if (context.projectRoot !== projectRoot)
+        throw new Error(`source context belongs to another project: ${contextId}`);
 }
 async function loadKnowledge(projectRoot) {
     try {
@@ -49,20 +92,29 @@ async function loadDeadends(projectRoot) {
 export async function learnKnowledge(startPath, statement, scopeOrInput = 'project') {
     const projectRoot = await resolveProjectRoot(startPath);
     const input = typeof scopeOrInput === 'string' ? { scope: scopeOrInput } : scopeOrInput;
+    const cleanStatement = statement.trim();
+    const cleanScope = (input.scope ?? 'project').trim();
+    const cleanKind = (input.kind ?? 'fact').trim();
+    if (!cleanStatement)
+        throw new Error('knowledge statement must not be empty');
+    if (!cleanScope)
+        throw new Error('knowledge scope must not be empty');
+    if (!cleanKind)
+        throw new Error('knowledge kind must not be empty');
     await validateSource(projectRoot, input.sourceContextId, input.sourceSnapshotId);
     return withLock(`${locksDirectory(projectRoot)}/knowledge.lock`, async () => {
         const file = await loadKnowledge(projectRoot);
         const now = new Date().toISOString();
         const item = {
             knowledgeId: id('know'),
-            kind: 'fact',
-            statement,
-            scope: input.scope ?? 'project',
+            kind: cleanKind,
+            statement: cleanStatement,
+            scope: cleanScope,
             confidence: 0.5,
             status: 'candidate',
-            sourceContextIds: input.sourceContextId ? [input.sourceContextId] : [],
-            sourceSnapshotIds: input.sourceSnapshotId ? [input.sourceSnapshotId] : [],
-            supportingEvidence: input.evidence ?? [],
+            sourceContextIds: cleanList(input.sourceContextId ? [input.sourceContextId] : []),
+            sourceSnapshotIds: cleanList(input.sourceSnapshotId ? [input.sourceSnapshotId] : []),
+            supportingEvidence: cleanList(input.evidence),
             createdAt: now,
             updatedAt: now,
         };
@@ -75,6 +127,78 @@ export async function listKnowledge(startPath, includeUnverified = false) {
     const file = await loadKnowledge(projectRoot);
     return includeUnverified ? file.items : file.items.filter((item) => item.status === 'verified');
 }
+const aliasGroups = [
+    ['投保人认证', '投保人身份认证', '身份核验', '实名认证', 'applicant authentication', 'identity verification'],
+    ['短信验证码', '验证码', 'sms verification', 'otp'],
+    ['证件ocr', '证件识别', 'identity ocr', 'document ocr'],
+    ['人脸识别', '人脸认证', 'face recognition', 'facial verification'],
+];
+function queryTerms(query) {
+    const normalizedQuery = normalized(query);
+    const terms = new Set(normalizedQuery.split(/\s+/).filter(Boolean));
+    for (const group of aliasGroups) {
+        if (group.some((alias) => normalizedQuery.includes(normalized(alias)))) {
+            for (const alias of group)
+                terms.add(normalized(alias));
+        }
+    }
+    return [...terms];
+}
+function matchedFields(knowledge, terms) {
+    const values = { statement: normalized(knowledge.statement), kind: normalized(knowledge.kind), scope: normalized(knowledge.scope) };
+    const fields = new Set();
+    const matched = new Set();
+    let score = 0;
+    const normalizedQuery = terms.join(' ');
+    if (values.statement.includes(normalizedQuery))
+        score += 20;
+    for (const term of terms) {
+        let matchedTerm = false;
+        for (const [field, value] of Object.entries(values)) {
+            if (value.includes(term)) {
+                fields.add(field);
+                matchedTerm = true;
+                score += field === 'statement' ? 5 : field === 'scope' ? 4 : 3;
+            }
+        }
+        if (matchedTerm)
+            matched.add(term);
+    }
+    if (values.scope === normalizedQuery)
+        score += 10;
+    return { fields: [...fields], matchedTerms: [...matched], score };
+}
+function limitedKnowledge(knowledge, maxChars) {
+    const statement = knowledge.statement.length <= maxChars ? knowledge.statement : `${knowledge.statement.slice(0, Math.max(0, maxChars - 1))}…`;
+    return { ...knowledge, statement, supportingEvidence: knowledge.supportingEvidence.map((item) => item.length <= maxChars ? item : `${item.slice(0, Math.max(0, maxChars - 1))}…`) };
+}
+export async function discoverKnowledge(startPath, query, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const cleanQuery = query.trim();
+    if (!cleanQuery)
+        throw new Error('knowledge discovery query must not be empty');
+    const file = await loadKnowledge(projectRoot);
+    const statuses = options.statuses ?? ['verified'];
+    const terms = queryTerms(cleanQuery);
+    const matches = file.items
+        .filter((item) => statuses.includes(item.status))
+        .filter((item) => !options.scope || normalized(item.scope) === normalized(options.scope))
+        .map((knowledge) => ({ knowledge, ...matchedFields(knowledge, terms) }))
+        .filter((item) => item.matchedTerms.length > 0)
+        .sort((left, right) => right.score - left.score || Number(right.knowledge.status === 'verified') - Number(left.knowledge.status === 'verified') || right.knowledge.confidence - left.knowledge.confidence || right.knowledge.updatedAt.localeCompare(left.knowledge.updatedAt) || left.knowledge.knowledgeId.localeCompare(right.knowledge.knowledgeId));
+    const duplicateMap = new Map();
+    for (const item of file.items) {
+        const key = `${normalized(item.kind)}|${normalized(item.scope)}|${normalized(item.statement)}`;
+        duplicateMap.set(key, [...(duplicateMap.get(key) ?? []), item.knowledgeId]);
+    }
+    const duplicateIds = [...duplicateMap.values()].filter((ids) => ids.length > 1);
+    const possibleConflicts = file.items.flatMap((left, index) => file.items.slice(index + 1).filter((right) => normalized(left.scope) === normalized(right.scope) && normalized(left.statement) !== normalized(right.statement) && queryTerms(left.statement).some((term) => normalized(right.statement).includes(term))).map((right) => ({ scope: left.scope, knowledgeIds: [left.knowledgeId, right.knowledgeId], statements: [left.statement, right.statement] })));
+    const limit = options.limit ?? 10;
+    const selected = matches.slice(0, limit);
+    const maxChars = options.maxChars ?? 4000;
+    const hits = selected.map((item) => ({ knowledge: limitedKnowledge(item.knowledge, maxChars), score: item.score, matchedTerms: item.matchedTerms, matchedFields: item.fields, why: item.fields.map((field) => `matched ${field}`) }));
+    return { query: cleanQuery, total: matches.length, truncated: matches.length > selected.length, hits, duplicateIds, possibleConflicts };
+}
 export async function verifyKnowledge(startPath, knowledgeId) {
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/knowledge.lock`, async () => {
@@ -117,6 +241,49 @@ export async function listDeadends(startPath, includeUnverified = false) {
     const file = await loadDeadends(projectRoot);
     return includeUnverified ? file.items : file.items.filter((item) => item.status === 'verified');
 }
+function limitedDeadend(deadend, maxChars) {
+    const limit = (value) => value.length <= maxChars ? value : `${value.slice(0, Math.max(0, maxChars - 1))}…`;
+    return { ...deadend, attempt: limit(deadend.attempt), reason: limit(deadend.reason), observedEvidence: deadend.observedEvidence.map(limit) };
+}
+export async function discoverDeadends(startPath, query, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const cleanQuery = query.trim();
+    if (!cleanQuery)
+        throw new Error('deadend discovery query must not be empty');
+    const terms = normalized(cleanQuery).split(/\s+/).filter(Boolean);
+    const statuses = options.statuses ?? ['verified'];
+    const file = await loadDeadends(projectRoot);
+    const matches = file.items
+        .filter((item) => statuses.includes(item.status))
+        .filter((item) => !options.scope || normalized(item.scope) === normalized(options.scope))
+        .map((deadend) => {
+        const values = { attempt: normalized(deadend.attempt), reason: normalized(deadend.reason), scope: normalized(deadend.scope) };
+        const fields = new Set();
+        const matchedTerms = new Set();
+        let score = 0;
+        for (const term of terms) {
+            for (const [field, value] of Object.entries(values)) {
+                if (value.includes(term)) {
+                    fields.add(field);
+                    matchedTerms.add(term);
+                    score += field === 'attempt' ? 5 : field === 'reason' ? 4 : 3;
+                }
+            }
+        }
+        return { deadend, score, matchedTerms: [...matchedTerms], matchedFields: [...fields] };
+    })
+        .filter((item) => item.matchedTerms.length > 0)
+        .sort((left, right) => right.score - left.score || right.deadend.updatedAt.localeCompare(left.deadend.updatedAt) || left.deadend.deadendId.localeCompare(right.deadend.deadendId));
+    const limit = options.limit ?? 10;
+    const selected = matches.slice(0, limit);
+    const maxChars = options.maxChars ?? 4000;
+    return {
+        query: cleanQuery,
+        total: matches.length,
+        truncated: matches.length > selected.length,
+        hits: selected.map((item) => ({ ...item, deadend: limitedDeadend(item.deadend, maxChars) })),
+    };
+}
 export async function verifyDeadend(startPath, deadendId) {
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/deadends.lock`, async () => {

package/dist/src/runtime/notes.d.ts

@@ -0,0 +1,6 @@
+import type { ActivityQuery, ActivityResult, Note, NoteInput, NoteQuery } from './types.js';
+export declare function addNote(startPath: string | undefined, message: string, input?: NoteInput): Promise<Note>;
+export declare function listNotes(startPath: string | undefined, query?: NoteQuery): Promise<Note[]>;
+export declare function listActivity(startPath: string | undefined, query?: ActivityQuery): Promise<ActivityResult>;
+export declare function absorbNotes(startPath: string | undefined, contextId: string, snapshotId: string): Promise<number>;
+export declare function isValidNote(value: unknown): value is Note;