kibi-cli 0.7.0 → 0.8.0

package/dist/commands/sync/staging.d.ts

@@ -8,11 +8,14 @@ interface StagingDeps {
     cwd: () => string;
     existsSync: typeof existsSync;
     fg: typeof fg;
+    isProcessAlive: (pid: number) => boolean;
     mkdirSync: typeof mkdirSync;
     moduleDir: string;
     renameSync: typeof renameSync;
     rmSync: typeof rmSync;
 }
+export declare function createUniqueStagingPath(currentBranch: string, rootDir: string, pid?: number, now?: number): string;
+export declare function cleanupAbandonedStagingDirectories(stagingPath: string, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function prepareStagingEnvironment(stagingPath: string, livePath: string, rebuild: boolean, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function atomicPublish(stagingPath: string, livePath: string, deps?: Partial<StagingDeps>): void;
 export declare function cleanupStaging(stagingPath: string, deps?: Partial<StagingDeps>): void;

package/dist/commands/sync/staging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CACvB;AAiBD,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAaf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CACvB;AA8BD,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,SAAc,EACjB,GAAG,SAAa,GACf,MAAM,CAOR;AAGD,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAkDf;AAED,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAaf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}

package/dist/commands/sync/staging.js

@@ -27,6 +27,17 @@ function resolveDeps(overrides) {
         cwd: () => process.cwd(),
         existsSync,
         fg,
+        isProcessAlive: (pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (error) {
+                return !(error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ESRCH");
+            }
+        },
         mkdirSync,
         moduleDir: import.meta.dirname,
         renameSync,
@@ -34,11 +45,54 @@ function resolveDeps(overrides) {
         ...overrides,
     };
 }
+// implements REQ-003
+export function createUniqueStagingPath(currentBranch, rootDir, pid = process.pid, now = Date.now()) {
+    return path.join(rootDir, ".kb", "branches", `${currentBranch}.staging.${pid}.${now}`);
+}
+// implements REQ-003
+export async function cleanupAbandonedStagingDirectories(stagingPath, deps) {
+    const resolved = resolveDeps(deps);
+    const stagingDir = path.dirname(stagingPath);
+    const stagingBase = path.basename(stagingPath);
+    const match = /^(?<branch>.+)\.staging\.(?<pid>\d+)\.(?<timestamp>\d+)$/.exec(stagingBase);
+    if (!match?.groups) {
+        return;
+    }
+    const branch = match.groups.branch;
+    if (!branch) {
+        return;
+    }
+    const candidates = await resolved.fg(`${branch}.staging.*`, {
+        cwd: stagingDir,
+        absolute: true,
+        onlyDirectories: true,
+        suppressErrors: true,
+    });
+    for (const candidate of candidates) {
+        if (candidate === stagingPath) {
+            continue;
+        }
+        const candidateBase = path.basename(candidate);
+        const candidateMatch = new RegExp(`^${escapeRegex(branch)}\\.staging\\.(\\d+)\\.(\\d+)$`).exec(candidateBase);
+        if (!candidateMatch) {
+            continue;
+        }
+        const candidatePidText = candidateMatch[1];
+        if (!candidatePidText) {
+            continue;
+        }
+        const candidatePid = Number.parseInt(candidatePidText, 10);
+        if (!Number.isFinite(candidatePid) || resolved.isProcessAlive(candidatePid)) {
+            continue;
+        }
+        cleanupStaging(candidate, resolved);
+    }
+}
 export async function prepareStagingEnvironment(
 // implements REQ-003
 stagingPath, livePath, rebuild, deps) {
     const resolved = resolveDeps(deps);
-    // Cleanup any existing staging directory
+    await cleanupAbandonedStagingDirectories(stagingPath, resolved);
     cleanupStaging(stagingPath, resolved);
     resolved.mkdirSync(stagingPath, { recursive: true });
     if (!rebuild && resolved.existsSync(livePath)) {
@@ -107,3 +161,6 @@ stagingPath, deps) {
         resolved.rmSync(stagingPath, { recursive: true, force: true });
     }
 }
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/commands/sync.d.ts

@@ -1,13 +1,30 @@
 import type { SyncSummary } from "../diagnostics.js";
+import { PrologProcess } from "../prolog.js";
 export declare class SyncError extends Error {
     constructor(message: string);
 }
 export interface SyncResult extends SyncSummary {
     exitCode?: number;
 }
+interface SyncCommandRuntimeContext {
+    currentBranch: string;
+    livePath: string;
+    rebuild: boolean;
+    stagingPath: string;
+    validateOnly: boolean;
+}
+interface SyncCommandRuntime {
+    afterAttach?: (context: SyncCommandRuntimeContext) => Promise<void> | void;
+    beforeSave?: (context: SyncCommandRuntimeContext & {
+        kbModified: boolean;
+    }) => Promise<void> | void;
+    createProlog?: (options: {
+        timeout: number;
+    }) => PrologProcess;
+}
 export declare function syncCommand(options?: {
     validateOnly?: boolean;
     rebuild?: boolean;
-}): Promise<SyncResult>;
+}, runtime?: SyncCommandRuntime): Promise<SyncResult>;
 export { normalizeMarkdownPath } from "./sync/discovery.js";
 //# sourceMappingURL=sync.d.ts.map

package/dist/commands/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0CjE,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,OAAO,CAAC,UAAU,CAAC,CAqarB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAejE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA4B7C,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CACZ,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;CAChE;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,EAC3D,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAmbrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/commands/sync.js

@@ -29,7 +29,7 @@ import { discoverSourceFiles, } from "./sync/discovery.js";
 import { processExtractions } from "./sync/extraction.js";
 import { refreshManifestCoordinates } from "./sync/manifest.js";
 import { persistEntities, persistRelationships } from "./sync/persistence.js";
-import { atomicPublish, cleanupStaging, prepareStagingEnvironment, } from "./sync/staging.js";
+import { atomicPublish, cleanupStaging, createUniqueStagingPath, prepareStagingEnvironment, } from "./sync/staging.js";
 export class SyncError extends Error {
     constructor(message) {
         super(message);
@@ -37,7 +37,7 @@ export class SyncError extends Error {
     }
 }
 // implements REQ-003, REQ-007
-export async function syncCommand(options = {}) {
+export async function syncCommand(options = {}, runtime = {}) {
     const validateOnly = options.validateOnly ?? false;
     const rebuild = options.rebuild ?? false;
     const startTime = Date.now();
@@ -45,6 +45,7 @@ export async function syncCommand(options = {}) {
     const entityCounts = {};
     let published = false;
     let currentBranch;
+    let stagingPath;
     const getCurrentCommit = () => {
         try {
             return execSync("git rev-parse HEAD", {
@@ -199,16 +200,25 @@ export async function syncCommand(options = {}) {
         if (!kbExists && !rebuild) {
             diagnostics.push(createKbMissingDiagnostic(currentBranch, livePath));
         }
-        const stagingPath = path.join(process.cwd(), `.kb/branches/${currentBranch}.staging`);
+        stagingPath = createUniqueStagingPath(currentBranch, process.cwd());
+        const runtimeContext = {
+            currentBranch,
+            livePath,
+            rebuild,
+            stagingPath,
+            validateOnly,
+        };
         await prepareStagingEnvironment(stagingPath, livePath, rebuild);
         try {
-            const prolog = new PrologProcess({ timeout: 120000 });
+            const prolog = runtime.createProlog?.({ timeout: 120000 }) ??
+                new PrologProcess({ timeout: 120000 });
             await prolog.start();
             const attachResult = await prolog.query(`kb_attach('${stagingPath}')`);
             if (!attachResult.success) {
                 await prolog.terminate();
                 throw new SyncError(`Failed to attach to staging KB: ${attachResult.error || "Unknown error"}`);
             }
+            await runtime.afterAttach?.(runtimeContext);
             const entityIds = new Set();
             for (const { entity } of results) {
                 entityCounts[entity.type] = (entityCounts[entity.type] || 0) + 1;
@@ -263,6 +273,7 @@ export async function syncCommand(options = {}) {
             if (kbModified) {
                 prolog.invalidateCache();
             }
+            await runtime.beforeSave?.({ ...runtimeContext, kbModified });
             const saveResult = await prolog.query("kb_save");
             if (!saveResult.success) {
                 throw new SyncError(`Failed to save staging KB: ${saveResult.error || "Unknown error"}`);
@@ -270,6 +281,7 @@ export async function syncCommand(options = {}) {
             await prolog.query("kb_detach");
             await prolog.terminate();
             atomicPublish(stagingPath, livePath);
+            cleanupStaging(stagingPath);
             const evictedHashes = {};
             const evictedSeenAt = {};
             for (const [key, hash] of Object.entries(nextHashes)) {
@@ -312,6 +324,9 @@ export async function syncCommand(options = {}) {
         }
     }
     catch (error) {
+        if (stagingPath) {
+            cleanupStaging(stagingPath);
+        }
         const errorMessage = error instanceof Error ? error.message : String(error);
         console.error(`Error: ${errorMessage}`);
         const commit = getCurrentCommit();

package/dist/public/operational-artifacts.d.ts

@@ -0,0 +1,2 @@
+export declare function isOperationalArtifactPath(pathLike: string): boolean;
+//# sourceMappingURL=operational-artifacts.d.ts.map

package/dist/public/operational-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operational-artifacts.d.ts","sourceRoot":"","sources":["../../src/public/operational-artifacts.ts"],"names":[],"mappings":"AAAA,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAInE"}

package/dist/public/operational-artifacts.js

@@ -0,0 +1,4 @@
+export function isOperationalArtifactPath(pathLike) {
+    const normalized = pathLike.replaceAll("\\", "/");
+    return /(^|\/)\.sisyphus\//.test(normalized);
+}

package/dist/search-ranking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-ranking.d.ts","sourceRoot":"","sources":["../src/search-ranking.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACnC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,EAAE,CAAC,CAyBxB;AA+FD,wBAAsB,gBAAgB,CAEpC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA6BxB"}
+{"version":3,"file":"search-ranking.d.ts","sourceRoot":"","sources":["../src/search-ranking.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAgDD,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACnC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,EAAE,CAAC,CA8BxB;AAmGD,wBAAsB,gBAAgB,CAEpC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA6BxB"}

package/dist/search-ranking.js

@@ -1,10 +1,47 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+const SEARCH_STOP_WORDS = new Set([
+    "to",
+    "in",
+    "out",
+    "log",
+    "logged",
+    "unable",
+    "the",
+    "a",
+    "an",
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "have",
+    "has",
+    "had",
+    "do",
+    "does",
+    "did",
+    "will",
+    "would",
+    "could",
+    "should",
+    "may",
+    "might",
+    "shall",
+    "can",
+    "not",
+]);
 // implements REQ-mcp-search-discovery, REQ-002, REQ-003
 export async function rankEntities(entities, query, workspaceRoot) {
+    const queryContext = buildSearchQueryContext(query);
+    if (!queryContext.rawTrimmedQuery || queryContext.signalTokens.length === 0) {
+        return [];
+    }
     const matches = [];
     for (const entity of entities) {
-        const match = await rankEntity(entity, query, workspaceRoot);
+        const match = await rankEntity(entity, queryContext, workspaceRoot);
         if (match) {
             matches.push(match);
         }
@@ -22,9 +59,8 @@ export async function rankEntities(entities, query, workspaceRoot) {
     });
     return matches;
 }
-async function rankEntity(entity, query, workspaceRoot) {
-    const normalizedQuery = normalize(query);
-    const tokens = normalizedQuery.split(/\s+/).filter(Boolean);
+// implements REQ-mcp-search-discovery
+async function rankEntity(entity, queryContext, workspaceRoot) {
     const reasons = [];
     let score = 0;
     const id = String(entity.id ?? "");
@@ -37,55 +73,56 @@ async function rankEntity(entity, query, workspaceRoot) {
     const tags = Array.isArray(entity.tags)
         ? entity.tags.map((tag) => String(tag))
         : [];
-    const normalizedTitle = normalize(title);
-    const normalizedId = normalize(id);
-    if (normalizedTitle === normalizedQuery) {
+    const titleForms = buildSearchTextForms(title);
+    const idForms = buildSearchTextForms(id);
+    if (isExactSearchMatch(titleForms, queryContext.phrase)) {
         score += 100;
         reasons.push("exact title match");
     }
-    else if (normalizedTitle.includes(normalizedQuery)) {
+    else if (isPhraseSearchMatch(titleForms, queryContext.phrase)) {
         score += 60;
         reasons.push("title phrase match");
     }
-    if (normalizedId === normalizedQuery) {
+    if (isExactSearchMatch(idForms, queryContext.phrase)) {
         score += 90;
         reasons.push("exact ID match");
     }
-    else if (normalizedId.includes(normalizedQuery)) {
+    else if (isPhraseSearchMatch(idForms, queryContext.phrase)) {
         score += 55;
         reasons.push("ID match");
     }
     const metadataFields = [type, source, owner, priority, severity];
-    const metadataMatched = metadataFields.some((field) => normalize(field).includes(normalizedQuery));
+    const metadataMatched = metadataFields.some((field) => isPhraseSearchMatch(buildSearchTextForms(field), queryContext.phrase));
     if (metadataMatched) {
         score += 20;
         reasons.push("metadata match");
     }
-    const matchingTags = tags.filter((tag) => normalize(tag).includes(normalizedQuery));
+    const matchingTags = tags.filter((tag) => isPhraseSearchMatch(buildSearchTextForms(tag), queryContext.phrase));
     if (matchingTags.length > 0) {
         score += 30;
         reasons.push("tag match");
     }
-    const titleTokenMatches = countTokenMatches(normalizedTitle, tokens);
+    const titleTokenMatches = countTokenMatches(titleForms, queryContext.signalTokens);
     if (titleTokenMatches > 0) {
         score += titleTokenMatches * 8;
         reasons.push("title token coverage");
     }
-    const bodyText = await loadMarkdownBody(source, workspaceRoot);
+    const bodyText = (await loadMarkdownBody(source, workspaceRoot)) ??
+        getInlineBodyText(entity);
     let snippet;
     if (bodyText) {
-        const normalizedBody = normalize(bodyText);
-        if (normalizedBody.includes(normalizedQuery)) {
+        const bodyForms = buildSearchTextForms(bodyText);
+        if (isPhraseSearchMatch(bodyForms, queryContext.phrase)) {
             score += 15;
             reasons.push("markdown body match");
-            snippet = buildSnippet(bodyText, query);
+            snippet = buildSnippet(bodyText, queryContext.phrase);
         }
         else {
-            const bodyTokenMatches = countTokenMatches(normalizedBody, tokens);
+            const bodyTokenMatches = countTokenMatches(bodyForms, queryContext.signalTokens);
             if (bodyTokenMatches > 0) {
                 score += bodyTokenMatches * 3;
                 reasons.push("markdown body token coverage");
-                snippet = buildSnippet(bodyText, query);
+                snippet = buildSnippet(bodyText, queryContext.phrase);
             }
         }
     }
@@ -126,6 +163,7 @@ source, workspaceRoot) {
         return null;
     }
 }
+// implements REQ-mcp-search-discovery
 function stripFrontmatter(content) {
     const trimmedContent = content.trimStart();
     if (!trimmedContent.startsWith("---")) {
@@ -143,19 +181,88 @@ function stripFrontmatter(content) {
     }
     return trimmedContent.slice(match.index + match[0].length);
 }
-function normalize(value) {
-    return value.trim().toLowerCase();
+// implements REQ-mcp-search-discovery
+function buildSearchQueryContext(query) {
+    return {
+        phrase: buildSearchTextForms(query),
+        signalTokens: tokenizeSignalTerms(query),
+        rawTrimmedQuery: query.trim(),
+    };
+}
+// implements REQ-mcp-search-discovery
+function buildSearchTextForms(value) {
+    const normalized = normalizeSearchText(value);
+    return {
+        normalized,
+        compact: normalized.replace(/\s+/g, ""),
+    };
+}
+// implements REQ-mcp-search-discovery
+function normalizeSearchText(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[-_]+/g, " ")
+        .replace(/[^a-z0-9\s]+/g, " ")
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map(singularizeSimplePlural)
+        .join(" ");
+}
+// implements REQ-mcp-search-discovery
+function tokenizeSignalTerms(value) {
+    return Array.from(new Set(normalizeSearchText(value)
+        .split(/\s+/)
+        .filter((token) => token && !SEARCH_STOP_WORDS.has(token))));
 }
+// implements REQ-mcp-search-discovery
+function singularizeSimplePlural(token) {
+    if (token.length <= 4 ||
+        !token.endsWith("s") ||
+        token.endsWith("ss") ||
+        token.endsWith("us") ||
+        token.endsWith("is")) {
+        return token;
+    }
+    return token.slice(0, -1);
+}
+// implements REQ-mcp-search-discovery
+function isExactSearchMatch(haystack, needle) {
+    return (haystack.normalized === needle.normalized ||
+        (needle.compact !== "" && haystack.compact === needle.compact));
+}
+// implements REQ-mcp-search-discovery
+function isPhraseSearchMatch(haystack, needle) {
+    return (haystack.normalized.includes(needle.normalized) ||
+        (needle.compact !== "" && haystack.compact.includes(needle.compact)));
+}
+// implements REQ-mcp-search-discovery
 function countTokenMatches(haystack, tokens) {
-    return tokens.filter((token) => haystack.includes(token)).length;
+    return tokens.filter((token) => haystack.normalized.includes(token) || haystack.compact.includes(token)).length;
+}
+// implements REQ-mcp-search-discovery
+function getInlineBodyText(entity) {
+    const candidates = [
+        entity.body,
+        entity.markdownBody,
+        entity.markdown_body,
+        entity.content,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate.trim() !== "") {
+            return candidate;
+        }
+    }
+    return null;
 }
-function buildSnippet(bodyText, query) {
+// implements REQ-mcp-search-discovery
+function buildSnippet(bodyText, queryForms) {
     const lines = bodyText
         .split(/\r?\n/)
         .map((line) => line.trim())
         .filter(Boolean);
-    const normalizedQuery = normalize(query);
-    const matchedLine = lines.find((line) => normalize(line).includes(normalizedQuery)) ?? lines[0];
+    const matchedLine = lines.find((line) => isPhraseSearchMatch(buildSearchTextForms(line), queryForms)) ?? lines[0];
     if (!matchedLine) {
         return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -78,6 +78,10 @@
     "./brief-config": {
       "types": "./dist/public/brief-config.d.ts",
       "default": "./dist/public/brief-config.js"
+    },
+    "./operational-artifacts": {
+      "types": "./dist/public/operational-artifacts.d.ts",
+      "default": "./dist/public/operational-artifacts.js"
     }
   },
   "types": "./dist/cli.d.ts",

package/src/public/operational-artifacts.ts

@@ -0,0 +1,5 @@
+export function isOperationalArtifactPath(pathLike: string): boolean { // implements REQ-001
+  const normalized = pathLike.replaceAll("\\", "/");
+
+  return /(^|\/)\.sisyphus\//.test(normalized);
+}