kibi-cursor 0.6.0 → 1.0.0

package/dist/bin/launch-kibi-mcp.mjs

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+
+/**
+ * Consumer-side entrypoint for Cursor's MCP process launcher.
+ */
+
+/**
+ * Launch the kibi-mcp package installed by the consumer project.
+ *
+ * Cursor starts plugin MCP commands with the plugin directory as their cwd.
+ * This adapter deliberately knows nothing about the Kibi source tree: it only
+ * resolves a consumer workspace, finds that workspace's kibi-mcp package, and
+ * runs its declared bin with the consumer as both cwd and KIBI_WORKSPACE.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_NAME = "kibi-mcp";
+const PLACEHOLDER_PATTERN = /\$\{[^}]+\}/;
+const SIGNAL_EXIT_CODES = {
+  SIGHUP: 129,
+  SIGINT: 130,
+  SIGTERM: 143,
+  SIGBREAK: 148,
+};
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isPlaceholder(value) {
+  return PLACEHOLDER_PATTERN.test(value.trim());
+}
+
+function normalizeWorkspacePath(value, baseDirectory) {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  if (!trimmed || isPlaceholder(trimmed)) return null;
+  const candidate = isAbsolute(trimmed)
+    ? trimmed
+    : resolve(baseDirectory, trimmed);
+  return isDirectory(candidate) ? resolve(candidate) : null;
+}
+
+/**
+ * Cursor has used both a platform-delimited string and a JSON-like list for
+ * workspace-folder environment values. Accept both without treating a
+ * literal unresolved placeholder as a path relative to the plugin directory.
+ */
+export function parseWorkspaceFolderPaths(value) {
+  if (typeof value !== "string" || !value.trim()) return [];
+  const trimmed = value.trim();
+  if (trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) {
+        return parsed.filter((item) => typeof item === "string");
+      }
+    } catch {
+      // Fall through to the platform-delimited form.
+    }
+  }
+
+  const separator = process.platform === "win32" ? ";" : ":";
+  const separated = trimmed.split(separator);
+  const values =
+    separated.length === 1 && trimmed.includes(",")
+      ? trimmed.split(",")
+      : separated;
+  return values
+    .flatMap((item) =>
+      process.platform === "win32" ? item.split(",") : [item],
+    )
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function packageJsonForResolvedFile(startPath) {
+  let current = resolve(startPath);
+  try {
+    if (!statSync(current).isDirectory()) current = dirname(current);
+  } catch {
+    current = dirname(current);
+  }
+
+  while (true) {
+    const packageJsonPath = join(current, "package.json");
+    if (existsSync(packageJsonPath)) {
+      try {
+        const packageJson = readJson(packageJsonPath);
+        if (packageJson.name === PACKAGE_NAME) {
+          return { packageJsonPath, packageRoot: current, packageJson };
+        }
+      } catch {
+        // Keep walking if a parent package manifest is malformed.
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function isWithinRoot(rootPath, candidatePath) {
+  const relativePath = relative(resolve(rootPath), resolve(candidatePath));
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !isAbsolute(relativePath))
+  );
+}
+
+function hasConsumerNodeModulesLink(workspaceRoot, packageRoot) {
+  try {
+    const linkPath = join(workspaceRoot, "node_modules", PACKAGE_NAME);
+    const linkedRoot = realpathSync(linkPath);
+    return (
+      isWithinRoot(linkedRoot, packageRoot) ||
+      isWithinRoot(packageRoot, linkedRoot)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isProjectScopedPackage(workspaceRoot, packageRoot) {
+  if (isWithinRoot(workspaceRoot, packageRoot)) return true;
+
+  // pnpm can expose a package through a symlink whose realpath is outside the
+  // workspace. Require that the consumer's node_modules entry points to it;
+  // this rejects arbitrary NODE_PATH/global packages while retaining that
+  // package-manager layout. Yarn PnP has no node_modules entry, so only its
+  // active resolver hook may authorize an out-of-tree package.
+  return (
+    hasConsumerNodeModulesLink(workspaceRoot, packageRoot) ||
+    Boolean(process.versions.pnp)
+  );
+}
+
+/**
+ * Resolve the consumer's package through Node's project-scoped resolver. This
+ * works with npm, pnpm, Yarn, and Bun layouts, unlike a hard-coded .bin path.
+ */
+export function resolveProjectLocalMcp(workspaceRoot) {
+  const root = resolve(workspaceRoot);
+  const consumerRequire = createRequire(join(root, "package.json"));
+  let packageInfo;
+
+  try {
+    packageInfo = packageJsonForResolvedFile(
+      consumerRequire.resolve(`${PACKAGE_NAME}/package.json`),
+    );
+  } catch {
+    try {
+      packageInfo = packageJsonForResolvedFile(
+        consumerRequire.resolve(PACKAGE_NAME),
+      );
+    } catch {
+      packageInfo = null;
+    }
+  }
+
+  if (!packageInfo) {
+    throw new Error(
+      `[KIBI-CURSOR] No project-local ${PACKAGE_NAME} package was found for ${root}. ` +
+        `Install it in that workspace (for example: npm install --save-dev ${PACKAGE_NAME}) and reload Cursor.`,
+    );
+  }
+
+  if (!isProjectScopedPackage(root, packageInfo.packageRoot)) {
+    throw new Error(
+      `[KIBI-CURSOR] Resolved ${PACKAGE_NAME} outside the consumer workspace: ${packageInfo.packageRoot}. Install it in ${root}; global, plugin-local, and ambient NODE_PATH packages are not supported.`,
+    );
+  }
+
+  const declaredBin = packageInfo.packageJson.bin;
+  const binEntry =
+    typeof declaredBin === "string"
+      ? declaredBin
+      : declaredBin && typeof declaredBin === "object"
+        ? declaredBin[PACKAGE_NAME]
+        : undefined;
+  if (typeof binEntry !== "string" || !binEntry) {
+    throw new Error(
+      `[KIBI-CURSOR] Project-local ${PACKAGE_NAME} does not declare a ${PACKAGE_NAME} executable.`,
+    );
+  }
+
+  const binPath = resolve(packageInfo.packageRoot, binEntry);
+  if (!existsSync(binPath)) {
+    throw new Error(
+      `[KIBI-CURSOR] Project-local ${PACKAGE_NAME} declares a missing executable: ${binPath}. Reinstall the workspace dependency and reload Cursor.`,
+    );
+  }
+
+  return {
+    packageRoot: packageInfo.packageRoot,
+    packageJsonPath: packageInfo.packageJsonPath,
+    packageJson: packageInfo.packageJson,
+    binPath,
+  };
+}
+
+function hasDeclaredProjectDependency(workspaceRoot) {
+  const packageJsonPath = join(workspaceRoot, "package.json");
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const packageJson = readJson(packageJsonPath);
+    return [
+      packageJson.dependencies,
+      packageJson.devDependencies,
+      packageJson.optionalDependencies,
+      packageJson.peerDependencies,
+    ].some((dependencies) =>
+      Boolean(
+        dependencies &&
+          typeof dependencies === "object" &&
+          dependencies[PACKAGE_NAME],
+      ),
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isDemonstrablyProjectWorkspace(workspaceRoot) {
+  return (
+    existsSync(join(workspaceRoot, ".git")) ||
+    existsSync(join(workspaceRoot, ".kb")) ||
+    hasDeclaredProjectDependency(workspaceRoot)
+  );
+}
+
+function usableWorkspaceCandidates(values, baseDirectory) {
+  return values
+    .map((value) => normalizeWorkspacePath(value, baseDirectory))
+    .filter((value, index, all) => value && all.indexOf(value) === index)
+    .filter((value) => {
+      try {
+        resolveProjectLocalMcp(value);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+}
+
+function chooseSingleWorkspace(candidates, source) {
+  if (candidates.length > 1) {
+    throw new Error(
+      `[KIBI-CURSOR] ${source} names multiple workspaces with project-local ${PACKAGE_NAME}: ${candidates.join(", ")}. Open a single-root workspace or set KIBI_WORKSPACE to one root.`,
+    );
+  }
+  return candidates[0];
+}
+
+/** Resolve the consumer workspace without ever defaulting to the plugin root. */
+export function resolveWorkspaceRoot(explicitWorkspace, options = {}) {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const env = options.env ?? process.env;
+
+  if (typeof explicitWorkspace === "string" && explicitWorkspace.trim()) {
+    const explicit = normalizeWorkspacePath(explicitWorkspace, cwd);
+    // Cursor can leave ${workspaceFolder} unresolved. It is invalid, so allow
+    // the environment fallbacks below rather than resolving it under cwd.
+    if (explicit) return explicit;
+  }
+
+  const folderCandidates = chooseSingleWorkspace(
+    usableWorkspaceCandidates(
+      parseWorkspaceFolderPaths(env.WORKSPACE_FOLDER_PATHS),
+      cwd,
+    ),
+    "WORKSPACE_FOLDER_PATHS",
+  );
+  if (folderCandidates) return folderCandidates;
+
+  for (const name of ["KIBI_WORKSPACE", "CURSOR_WORKSPACE"]) {
+    const candidate = chooseSingleWorkspace(
+      usableWorkspaceCandidates([env[name]], cwd),
+      name,
+    );
+    if (candidate) return candidate;
+  }
+
+  // A plugin installation is commonly the current cwd. Only use it when
+  // project markers make it demonstrably a consumer project and its local
+  // package can be resolved; never use an ambient/plugin-local package merely
+  // because it happens to be on disk.
+  if (isDemonstrablyProjectWorkspace(cwd)) {
+    try {
+      resolveProjectLocalMcp(cwd);
+      return cwd;
+    } catch {
+      // Continue to the actionable error below.
+    }
+  }
+
+  throw new Error(
+    `[KIBI-CURSOR] Unable to determine a consumer workspace. Cursor must provide \${workspaceFolder}, WORKSPACE_FOLDER_PATHS, KIBI_WORKSPACE, or CURSOR_WORKSPACE; the selected workspace must contain project-local ${PACKAGE_NAME}.`,
+  );
+}
+
+function signalExitCode(signal) {
+  return SIGNAL_EXIT_CODES[signal] ?? 1;
+}
+
+/** Spawn the project-local MCP server and mirror its transport and exit state. */
+export function launchKibiMcp(argv = process.argv.slice(2), env = process.env) {
+  const [explicitWorkspace, ...childArgs] = argv;
+  let workspaceRoot;
+  let projectLocal;
+  try {
+    workspaceRoot = resolveWorkspaceRoot(explicitWorkspace, {
+      cwd: process.cwd(),
+      env,
+    });
+    projectLocal = resolveProjectLocalMcp(workspaceRoot);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    return Promise.resolve(1);
+  }
+
+  const child = spawn(process.execPath, [projectLocal.binPath, ...childArgs], {
+    cwd: workspaceRoot,
+    env: { ...env, KIBI_WORKSPACE: workspaceRoot },
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+
+  return new Promise((resolveExit) => {
+    let finished = false;
+    const signalHandlers = new Map();
+    const finish = (exitCode) => {
+      if (finished) return;
+      finished = true;
+      for (const [signal, handler] of signalHandlers) {
+        process.removeListener(signal, handler);
+      }
+      resolveExit(exitCode);
+    };
+
+    for (const signal of ["SIGHUP", "SIGINT", "SIGTERM", "SIGBREAK"]) {
+      if (process.platform === "win32" && signal !== "SIGBREAK") continue;
+      const handler = () => {
+        if (!child.killed) child.kill(signal);
+      };
+      signalHandlers.set(signal, handler);
+      process.once(signal, handler);
+    }
+
+    child.once("error", (error) => {
+      process.stderr.write(
+        `[KIBI-CURSOR] Failed to start project-local ${PACKAGE_NAME}: ${error.message}\n`,
+      );
+      finish(1);
+    });
+    child.once("close", (code, signal) => {
+      finish(signal ? signalExitCode(signal) : (code ?? 1));
+    });
+  });
+}
+
+const entrypoint = process.argv[1] ? resolve(process.argv[1]) : undefined;
+if (entrypoint === resolve(fileURLToPath(import.meta.url))) {
+  const exitCode = await launchKibiMcp(process.argv.slice(2));
+  process.exitCode = exitCode;
+}

package/dist/commands/kibi-bootstrap.md

@@ -0,0 +1,19 @@
+---
+name: kibi-bootstrap
+description: Bootstrap Kibi knowledge for an existing repository
+---
+
+# Kibi bootstrap
+
+Route an explicit bootstrap request to the canonical `kibi-bootstrap` skill.
+
+## Route
+
+Inspect `kb_status.bootstrap` and follow its typed `nextAction`. If Kibi
+infrastructure is missing, run `kibi init` first. Then use the canonical
+planner and pass its unchanged returned `structuredContent.plan` to
+`kb_apply_plan` only after explicit approval.
+
+Questions come only from a `needs_context` planner result. Inspect typed apply
+`nextActions`, finish with `kb_check` and `kb_status`, and never read or edit
+`.kb` directly.

package/dist/hook-input.d.ts

@@ -1,4 +1,5 @@
 export type HookEvent = "sessionStart" | "preToolUse" | "postToolUse" | "beforeReadFile" | "stop";
+export type HookStopStatus = "completed" | "aborted" | "error";
 export type HookInput = {
     event: string;
     cwd?: string;
@@ -7,6 +8,7 @@ export type HookInput = {
     toolInput?: unknown;
     conversationId?: string;
     filePath?: string;
+    status?: HookStopStatus;
 };
 export declare function parseHookInput(input: unknown): HookInput;
 export declare function readStdin(): Promise<string>;

package/dist/hook-input.js

@@ -30,6 +30,12 @@ function normalizeEventName(event) {
     }
     return trimmed.charAt(0).toLowerCase() + trimmed.slice(1);
 }
+function parseStopStatus(value) {
+    if (value === "completed" || value === "aborted" || value === "error") {
+        return value;
+    }
+    return undefined;
+}
 export function parseHookInput(input) {
     if (!isRecord(input)) {
         return { event: "" };
@@ -58,6 +64,7 @@ export function parseHookInput(input) {
         "conversationId",
     ]);
     const filePath = readString(input, ["file_path", "filePath", "path"]);
+    const status = parseStopStatus(readString(input, ["status"]));
     const parsed = { event };
     if (cwd !== undefined) {
         parsed.cwd = cwd;
@@ -77,6 +84,9 @@ export function parseHookInput(input) {
     if (filePath !== undefined) {
         parsed.filePath = filePath;
     }
+    if (status !== undefined) {
+        parsed.status = status;
+    }
     return parsed;
 }
 export async function readStdin() {

package/dist/hook-runner.js

@@ -1,22 +1,24 @@
 #!/usr/bin/env node
-// implements REQ-cursor-kibi-plugin-v1
+// implements REQ-cursor-kibi-plugin-v1, REQ-cursor-stop-job-vs-plan
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { readGuidance, writeGuidance } from "./guidance.js";
 import { parseHookInput, parseStdinJson, readStdin } from "./hook-input.js";
-import { addDirtyPaths, clearSessionHookState, hasGuidedPath, loadHookState, recordKbMcpTool, rememberGuidedPath, resolveStateDir, } from "./hook-state.js";
+import { addDirtyPaths, clearSessionHookState, hasGuidedPath, loadHookState, recordKbMcpTool, recordPlanDelivered, rememberGuidedPath, resolveStateDir, } from "./hook-state.js";
 import { extractKbMcpToolCall } from "./kb-mcp-tools.js";
 import { BOOTSTRAP_REMINDER, DIRECT_KB_EDIT_WARNING, interfaceAdvisory, stopFollowupMessage, } from "./messages.js";
-import { extractExplicitPathFields, isDirectKbPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
+import { extractExplicitPathFields, isDirectKbPath, isKbFreshnessRelevantPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
 const editableTools = new Set([
     "Edit",
     "MultiEdit",
     "Write",
     "StrReplace",
     "apply_patch",
+    "EditNotebook",
 ]);
 const readTools = new Set(["Read", "TabRead"]);
+const planDeliveryTools = new Set(["CreatePlan", "create_plan", "createPlan"]);
 function emptyResult() {
     return {};
 }
@@ -24,11 +26,17 @@ function hasKibiConfig(cwd) {
     if (!cwd) {
         return false;
     }
-    return fs.existsSync(path.join(cwd, ".kb", "config.json"));
+    return fs.existsSync(path.join(cwd, ".kb", "manifest.json"));
 }
 function isEditLikeTool(toolName) {
     return toolName === undefined || editableTools.has(toolName);
 }
+function isKnownEditableTool(toolName) {
+    return toolName !== undefined && editableTools.has(toolName);
+}
+function isPlanDeliveryTool(toolName) {
+    return toolName !== undefined && planDeliveryTools.has(toolName);
+}
 function isReadLikeTool(toolName) {
     return toolName === undefined || readTools.has(toolName);
 }
@@ -108,12 +116,18 @@ export async function runHook(rawInput, environment = {}) {
                     sourceFiles: kbToolCall.sourceFiles,
                 });
             }
+            if (isPlanDeliveryTool(input.toolName)) {
+                recordPlanDelivered(stateDir);
+            }
             const explicitPaths = extractExplicitPathFields(input.toolInput);
-            const dirtyPaths = explicitPaths
-                .map((candidate) => toRepoRelativePath(candidate, cwd))
-                .filter(isMeaningfulTrackedPath);
-            if (dirtyPaths.length > 0) {
-                addDirtyPaths(stateDir, dirtyPaths);
+            if (isKnownEditableTool(input.toolName)) {
+                const dirtyPaths = explicitPaths
+                    .map((candidate) => toRepoRelativePath(candidate, cwd))
+                    .filter((candidate) => isMeaningfulTrackedPath(candidate) ||
+                    isKbFreshnessRelevantPath(candidate));
+                if (dirtyPaths.length > 0) {
+                    addDirtyPaths(stateDir, dirtyPaths);
+                }
             }
             const primaryPath = resolvePrimaryPath(input);
             if (!primaryPath || !kibiReady) {
@@ -157,14 +171,22 @@ export async function runHook(rawInput, environment = {}) {
         }
         case "stop": {
             const state = loadHookState(stateDir);
+            const shouldClearSession = state.dirtyPaths.length > 0 ||
+                state.kbMutationTools.length > 0 ||
+                state.kbCheckRun ||
+                state.planDelivered;
+            if (input.status === "aborted" || input.status === "error") {
+                if (shouldClearSession) {
+                    clearSessionHookState(stateDir);
+                }
+                return emptyResult();
+            }
             const followupMessage = stopFollowupMessage(state);
             if (followupMessage) {
                 clearSessionHookState(stateDir);
                 return { followup_message: followupMessage };
             }
-            if (state.dirtyPaths.length > 0 ||
-                state.kbMutationTools.length > 0 ||
-                state.kbCheckRun) {
+            if (shouldClearSession) {
                 clearSessionHookState(stateDir);
             }
             return emptyResult();

package/dist/hook-state-storage.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+// implements REQ-cursor-kibi-plugin-v1, REQ-cursor-stop-job-vs-plan
 const stateFileName = "hook-state.json";
 const lockFileName = "hook-state.lock";
 export const maxDirtyPaths = 50;
@@ -46,6 +47,7 @@ export function emptyHookState() {
         kbCheckRun: false,
         impactCheckRun: false,
         impactCheckedPaths: [],
+        planDelivered: false,
     };
 }
 function acquireLock(pluginData) {
@@ -130,6 +132,7 @@ function coerceHookState(value) {
         kbCheckRun: value.kbCheckRun === true,
         impactCheckRun: value.impactCheckRun === true,
         impactCheckedPaths: [...new Set(impactCheckedPaths)].slice(-maxGuidedPaths),
+        planDelivered: value.planDelivered === true,
     };
 }
 export function resolveStateDir(pluginData, conversationId) {

package/dist/hook-state.d.ts

@@ -9,10 +9,12 @@ export type HookState = {
     kbCheckRun: boolean;
     impactCheckRun: boolean;
     impactCheckedPaths: string[];
+    planDelivered: boolean;
 };
 export declare function addDirtyPaths(stateDir: string | undefined, dirtyPaths: readonly string[]): HookState;
 export declare function rememberGuidedPath(stateDir: string | undefined, kind: "read" | "write", guidedPath: string): HookState;
 export declare function hasGuidedPath(state: HookState, kind: "read" | "write", guidedPath: string): boolean;
+export declare function recordPlanDelivered(stateDir: string | undefined): HookState;
 export declare function recordKbMcpTool(stateDir: string | undefined, toolName: string, options?: {
     impactCheckRun?: boolean;
     sourceFiles?: readonly string[];

package/dist/hook-state.js

@@ -29,6 +29,9 @@ export function hasGuidedPath(state, kind, guidedPath) {
     const bucket = kind === "read" ? state.guidedReadPaths : state.guidedWritePaths;
     return bucket.includes(normalized);
 }
+export function recordPlanDelivered(stateDir) {
+    return updateHookState(stateDir, (state) => state.planDelivered ? state : { ...state, planDelivered: true });
+}
 export function recordKbMcpTool(stateDir, toolName, options = {}) {
     const normalized = toolName.trim();
     if (normalized.length === 0) {

package/dist/mcp.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "kibi": {
-      "command": "npx",
-      "args": ["--no-install", "kibi-mcp"]
+      "command": "node",
+      "args": ["bin/launch-kibi-mcp.mjs", "${workspaceFolder}"]
     }
   }
 }

package/dist/messages.js

@@ -20,13 +20,18 @@ export function stopFollowupMessage(state) {
     }
     const sourceImpactPaths = state.dirtyPaths.filter(isSourceImpactRelevantPath);
     const uncheckedSourcePaths = sourceImpactPaths.filter((sourcePath) => !state.impactCheckedPaths.includes(sourcePath));
+    const freshnessPaths = state.dirtyPaths.filter(isKbFreshnessRelevantPath);
+    const hasFollowupWork = uncheckedSourcePaths.length > 0 ||
+        (freshnessPaths.length > 0 && !state.kbCheckRun);
+    if (state.planDelivered && !hasFollowupWork) {
+        return undefined;
+    }
     if (uncheckedSourcePaths.length > 0 && !state.impactCheckRun) {
         return impactCheckFollowup(uncheckedSourcePaths);
     }
     if (uncheckedSourcePaths.length > 0) {
         return impactCheckFollowup(uncheckedSourcePaths);
     }
-    const freshnessPaths = state.dirtyPaths.filter(isKbFreshnessRelevantPath);
     if (freshnessPaths.length === 0 || state.kbCheckRun) {
         return undefined;
     }

package/dist/path-policy.js

@@ -41,6 +41,30 @@ const sourceExtensions = new Set([
     ".vue",
 ]);
 const documentationExtensions = new Set([".md", ".mdx", ".rst", ".txt"]);
+const CANONICAL_KB_KNOWLEDGE_LANES = new Set([
+    "requirements",
+    "scenarios",
+    "tests",
+    "facts",
+    "adr",
+    "flags",
+    "events",
+]);
+const CANONICAL_KB_KNOWLEDGE_FILES = new Set([
+    "symbols.yaml",
+    "symbol-coordinates.yaml",
+]);
+function isCanonicalKbKnowledgePath(segments) {
+    if (segments[0] !== ".kb") {
+        return false;
+    }
+    const lane = segments[1];
+    if (lane === undefined) {
+        return false;
+    }
+    return (CANONICAL_KB_KNOWLEDGE_FILES.has(lane) ||
+        CANONICAL_KB_KNOWLEDGE_LANES.has(lane));
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -93,9 +117,12 @@ export function isDirectKbPath(candidate) {
 export function isMeaningfulTrackedPath(candidate) {
     const normalized = normalizePath(candidate);
     const segments = pathSegments(normalized);
-    if (segments.includes(".kb") || segments.includes("dist")) {
+    if (segments.includes("dist")) {
         return false;
     }
+    if (segments.includes(".kb")) {
+        return isCanonicalKbKnowledgePath(segments);
+    }
     const basename = segments.at(-1) ?? "";
     const extension = basename.includes(".")
         ? `.${basename.split(".").at(-1) ?? ""}`
@@ -116,6 +143,21 @@ export function isMeaningfulTrackedPath(candidate) {
 /** Paths whose edits should trigger a KB freshness stop follow-up. */
 export function isKbFreshnessRelevantPath(candidate) {
     const segments = pathSegments(normalizePath(candidate));
+    if (segments[0] === ".kb") {
+        const lane = segments[1];
+        if (lane === "requirements" ||
+            lane === "scenarios" ||
+            lane === "tests" ||
+            lane === "facts" ||
+            lane === "adr" ||
+            lane === "flags" ||
+            lane === "events" ||
+            lane === "symbols.yaml" ||
+            lane === "symbol-coordinates.yaml") {
+            return true;
+        }
+    }
+    // Legacy layout during migration
     if (segments.includes("documentation")) {
         return true;
     }