blun-king-cli 9.1.567 → 9.1.569

package/agent-spine-plugin/src/lib/source-roots.js

@@ -1,12 +1,16 @@
 import { createHash, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { lstat, mkdir, open, opendir, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
+import { lstat, mkdir, open, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { ancestorsBetween, canonicalPath, isInside, stateRoot } from "./paths.js";
 import { indexExplicitDocuments } from "./documents.js";
 import { isFileLockContention, replaceFileWithRetry } from "./filesystem-retry.js";
 import { purgeIndexedMemoryCache, resolveIndexedMemory } from "./indexed-memory.js";
+import { hookMemoryQuery, loadLessonRecallSelection, rememberLessonRecallSelection } from "./lesson-recall-session.js";
 import { catalogScanPolicy } from "./catalog.js";
+import {
+  SOURCE_SCAN_INCOMPLETE, boundedMarkdownTree, existingDirectory, existingRegular, sourceScanError
+} from "./source-tree-scan.js";
 
 export const SOURCE_REGISTRY_SCHEMA = "agentspine.source-roots/v1";
 const MAX_REGISTRY_BYTES = 1024 * 1024;
@@ -18,10 +22,8 @@ const MAX_DIRECTORY_ENTRIES = 4096;
 const MAX_PROJECT_DIRECTORY_ENTRIES = 8192;
 const SOURCE_RESOLUTION_MS = 2000;
 const SAFE_NAME = /^[A-Za-z0-9._-]{1,128}$/;
-const SKIP_EXTRA_DIRS = new Set([".git", ".hg", ".svn", ".claude", ".codex", "node_modules", "vendor", "dist", "build", "coverage"]);
 
 function digest(value) { return createHash("sha256").update(value).digest("hex"); }
-function sourceScanError(error) { error.agentSpineScan = true; return error; }
 function registryPath(env = process.env) { return join(stateRoot(env), "source-roots.json"); }
 function emptyRegistry() { return { schema: SOURCE_REGISTRY_SCHEMA, revision: 0, bindings: [], history: [] }; }
 
@@ -83,28 +85,6 @@ async function mutateRegistry(task, env = process.env) {
   }
 }
 
-async function existingRegular(path) {
-  try {
-    const metadata = await lstat(path);
-    if (metadata.isSymbolicLink() || !metadata.isFile()) return null;
-    return realpath(path);
-  } catch (error) {
-    if (error.code === "ENOENT") return null;
-    throw sourceScanError(error);
-  }
-}
-
-async function existingDirectory(path) {
-  try {
-    const metadata = await lstat(path);
-    if (metadata.isSymbolicLink() || !metadata.isDirectory()) return null;
-    return realpath(path);
-  } catch (error) {
-    if (error.code === "ENOENT") return null;
-    throw sourceScanError(error);
-  }
-}
-
 function expandHome(value, home) {
   if (value === "~") return home;
   if (value.startsWith("~/") || value.startsWith("~\\")) return join(home, value.slice(2));
@@ -177,100 +157,6 @@ async function findRoot(cwd, markers) {
   }
 }
 
-function skippedExtraDirectory(name) {
-  const lower = name.toLowerCase();
-  return SKIP_EXTRA_DIRS.has(name) || SKIP_EXTRA_DIRS.has(lower)
-    || lower.includes("dropbox") || lower === "onedrive" || lower.startsWith("onedrive - ");
-}
-
-function skippableTraversalError(error) {
-  return ["EPERM", "EACCES", "ENOENT"].includes(error?.code);
-}
-
-function recordSkippedPath(skipped, path, error, operation) {
-  skipped.push({ path, code: error.code, operation });
-}
-
-async function containsProjectMarker(directory) {
-  try {
-    await lstat(join(directory, ".git"));
-    return true;
-  } catch (error) {
-    if (error.code === "ENOENT") return false;
-    throw error;
-  }
-}
-
-async function containsEmbeddedHostProfile(directory) {
-  return Boolean(
-    await existingDirectory(join(directory, ".runtime-private"))
-    && await existingRegular(join(directory, "config.toml"))
-  );
-}
-
-async function boundedMarkdownTree(directory, prefix, host, scope, precedenceStart, deadline, {
-  projectBoundary = false,
-  maxFiles = MAX_RULE_FILES,
-  maxDirectoryEntries = MAX_DIRECTORY_ENTRIES,
-  skipped = []
-} = {}) {
-  let root;
-  try {
-    root = await existingDirectory(directory);
-  } catch (error) {
-    if (!skippableTraversalError(error)) throw sourceScanError(error);
-    recordSkippedPath(skipped, directory, error, "inspect-directory");
-    return [];
-  }
-  if (!root) return [];
-  const output = [];
-  let visitedEntries = 0;
-  async function walk(current) {
-    if (Date.now() > deadline) throw new Error(`host-native source resolution exceeded ${SOURCE_RESOLUTION_MS} ms`);
-    try {
-      if (projectBoundary && current !== root
-        && (await containsProjectMarker(current) || await containsEmbeddedHostProfile(current))) return;
-    } catch (error) {
-      if (!skippableTraversalError(error)) throw sourceScanError(error);
-      recordSkippedPath(skipped, current, error, "inspect-directory-boundary");
-      return;
-    }
-    const entries = [];
-    let stream;
-    try {
-      stream = await opendir(current);
-    } catch (error) {
-      if (!skippableTraversalError(error)) throw sourceScanError(error);
-      recordSkippedPath(skipped, error.path || current, error, "opendir");
-      return;
-    }
-    try {
-      for await (const entry of stream) {
-        visitedEntries += 1;
-        if (visitedEntries > maxDirectoryEntries) throw new Error(`host-native source tree exceeds ${maxDirectoryEntries} entries`);
-        entries.push(entry);
-      }
-    } catch (error) {
-      if (!skippableTraversalError(error)) throw sourceScanError(error);
-      recordSkippedPath(skipped, current, error, "readdir");
-      return;
-    }
-    entries.sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
-      if (output.length >= maxFiles) throw new Error(`host-native rule tree exceeds ${maxFiles} files`);
-      if (entry.isSymbolicLink()) continue;
-      const path = join(current, entry.name);
-      if (entry.isDirectory() && !entry.name.startsWith(".") && !skippedExtraDirectory(entry.name)) await walk(path);
-      else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
-        output.push({ path, id: `${prefix}/${relative(root, path).replaceAll("\\", "/")}`, host, scope,
-          binding: "host-native-rule-tree", precedence: precedenceStart + output.length });
-      }
-    }
-  }
-  await walk(root);
-  return output;
-}
-
 async function addFile(output, path, metadata) {
   const file = await existingRegular(path);
   if (file) output.push({ path: file, ...metadata });
@@ -349,7 +235,8 @@ async function claudeSources({ cwd, projectRoot, configDir, input, env, registry
   const sources = [];
   const skipped = [];
   await addFile(sources, join(configDir, "CLAUDE.md"), { id: "claude:user/CLAUDE.md", host: "claude", scope: "user", binding: "CLAUDE_CONFIG_DIR", precedence: 100 });
-  sources.push(...await boundedMarkdownTree(join(configDir, "rules"), "claude:user/rules", "claude", "user", 110, deadline, { skipped }));
+  sources.push(...await boundedMarkdownTree(join(configDir, "rules"), "claude:user/rules", "claude", "user", 110, deadline,
+    { maxFiles: MAX_RULE_FILES, maxDirectoryEntries: MAX_DIRECTORY_ENTRIES, skipped, timeoutMs: SOURCE_RESOLUTION_MS }));
   let precedence = 1000;
   for (const directory of ancestorsBetween(projectRoot, cwd)) {
     for (const name of ["CLAUDE.md", "CLAUDE.local.md"]) {
@@ -359,7 +246,8 @@ async function claudeSources({ cwd, projectRoot, configDir, input, env, registry
     await addFile(sources, join(directory, ".claude", "CLAUDE.md"), { id: `claude:project/${relative(projectRoot, join(directory, ".claude", "CLAUDE.md")).replaceAll("\\", "/")}`,
       host: "claude", scope: "project", binding: "native-project-chain", precedence: precedence++ });
   }
-  sources.push(...await boundedMarkdownTree(join(projectRoot, ".claude", "rules"), "claude:project/.claude/rules", "claude", "project", precedence, deadline, { skipped }));
+  sources.push(...await boundedMarkdownTree(join(projectRoot, ".claude", "rules"), "claude:project/.claude/rules", "claude", "project", precedence, deadline,
+    { maxFiles: MAX_RULE_FILES, maxDirectoryEntries: MAX_DIRECTORY_ENTRIES, skipped, timeoutMs: SOURCE_RESOLUTION_MS }));
 
   let memoryRoot = null;
   let memoryProvenance = null;
@@ -396,6 +284,12 @@ async function claudeSources({ cwd, projectRoot, configDir, input, env, registry
   if (memoryRoot) {
     const supplied = input.agent_spine_scope && typeof input.agent_spine_scope === "object"
       ? input.agent_spine_scope : input;
+    let recall = { status: "empty", paths: [], authority: "context-only" };
+    try {
+      recall = await loadLessonRecallSelection({ root: projectRoot, input, now: input.timestamp || new Date() });
+    } catch (error) {
+      recall = { status: "degraded", paths: [], reason: error.message, authority: "context-only" };
+    }
     const resolved = await resolveIndexedMemory({
       root: memoryRoot, env, hooks: memoryHooks, deadline,
       scope: {
@@ -403,10 +297,21 @@ async function claudeSources({ cwd, projectRoot, configDir, input, env, registry
         groupId: supplied.group_id ?? supplied.groupId ?? null,
         projectId: supplied.project_id ?? supplied.projectId ?? null,
         currentTaskId: supplied.task_id ?? supplied.currentTaskId ?? null,
-        prompt: input.prompt ?? input.user_prompt ?? input.message ?? input.input ?? null
+        prompt: hookMemoryQuery(input),
+        pinnedPaths: recall.paths
       }
     });
-    memoryDiagnostics = resolved.diagnostics;
+    let recorded = { status: "not-recorded", paths: [], authority: "context-only" };
+    try {
+      recorded = await rememberLessonRecallSelection({ root: projectRoot, input,
+        sources: resolved.sources, now: input.timestamp || new Date() });
+    } catch (error) {
+      recorded = { status: "degraded", paths: [], reason: error.message, authority: "context-only" };
+    }
+    memoryDiagnostics = { ...resolved.diagnostics, recall: {
+      restored: recall.paths.length, loadStatus: recall.status, recordStatus: recorded.status,
+      recorded: recorded.paths.length, authority: "context-only"
+    } };
     for (const item of resolved.sources) {
       sources.push({
         path: item.path, id: `claude:memory/${item.relativePath}`, host: "claude", scope: "project-memory",
@@ -442,7 +347,7 @@ async function codexSources({ cwd, projectRoot, codexHome, config }) {
 }
 
 export async function resolveHostSourceCatalog({ host, cwd = process.cwd(), input = {}, env = process.env, memoryHooks = {} } = {}) {
-  if (!["claude", "codex"].includes(host)) throw new Error(`host-native source resolution requires claude or codex, received ${host}`);
+  if (!["claude", "codex", "generic"].includes(host)) throw new Error(`unsupported source host: ${host}`);
   const canonicalCwd = await canonicalPath(cwd);
   const deadline = Date.now() + SOURCE_RESOLUTION_MS;
   const { registry } = await readRegistry(env);
@@ -460,7 +365,7 @@ export async function resolveHostSourceCatalog({ host, cwd = process.cwd(), inpu
     else ({ root: projectRoot, resolution: rootResolution } = await findRoot(canonicalCwd, config.rootMarkers));
     sources = await codexSources({ cwd: canonicalCwd, projectRoot, codexHome: hostHome, config });
     hostDetails = { rootMarkers: config.rootMarkers, fallbackNames: config.fallbackNames };
-  } else {
+  } else if (host === "claude") {
     hostHome = await existingDirectory(resolve(env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude")))
       || resolve(env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"));
     if (env.AGENTSPINE_ROOT) projectRoot = await canonicalPath(env.AGENTSPINE_ROOT);
@@ -470,23 +375,43 @@ export async function resolveHostSourceCatalog({ host, cwd = process.cwd(), inpu
     skipped = result.skipped;
     hostDetails = { memoryRoot: result.memoryRoot, memoryProvenance: result.memoryProvenance,
       memoryDiagnostics: result.memoryDiagnostics };
+  } else {
+    // Generic hosts get project sources, never another provider's profile.
+    hostHome = await canonicalPath(homedir());
+    if (env.AGENTSPINE_ROOT) projectRoot = await canonicalPath(env.AGENTSPINE_ROOT);
+    else ({ root: projectRoot, resolution: rootResolution } = await findRoot(canonicalCwd, [".git"]));
+    sources = [];
+    for (const directory of ancestorsBetween(projectRoot, canonicalCwd)) {
+      for (const name of ["AGENTS.md", "SOUL.md", "MEMORY.md"]) {
+        await addFile(sources, join(directory, name), {
+          id: `generic:project/${relative(projectRoot, join(directory, name)).replaceAll("\\", "/")}`,
+          host, scope: "project", binding: "native-project-chain", precedence: 1000 + sources.length
+        });
+      }
+    }
   }
+  sources = [...new Map(sources.map((item) => [item.path, item])).values()];
+  if (sources.length > MAX_SOURCES) throw new Error(`host-native required source set exceeds ${MAX_SOURCES} files`);
+  const nativeNames = new Set(host === "codex"
+    ? ["AGENTS.override.md", "AGENTS.md", ...(hostDetails.fallbackNames || [])]
+    : host === "claude" ? ["CLAUDE.md", "CLAUDE.local.md"] : ["AGENTS.md", "SOUL.md", "MEMORY.md"]);
   const knownHomeRoots = await homeRoots(env);
   const skippedHomeTree = knownHomeRoots.some((root) => samePath(root, projectRoot));
   const skippedProfileTree = samePath(hostHome, projectRoot);
   const skippedFallbackHomeTree = skippedHomeTree && rootResolution === "cwd-fallback";
   if (!skippedHomeTree && !skippedProfileTree) {
+    const optionalBudget = Math.min(MAX_PROJECT_FILES, MAX_SOURCES - sources.length);
     sources.push(...await boundedMarkdownTree(projectRoot, "agentspine:project", host, "project", 3000, deadline,
-      { projectBoundary: true, maxFiles: MAX_PROJECT_FILES, maxDirectoryEntries: MAX_PROJECT_DIRECTORY_ENTRIES, skipped }));
+      { projectBoundary: true, maxFiles: optionalBudget, maxDirectoryEntries: MAX_PROJECT_DIRECTORY_ENTRIES,
+        skipped, truncateOnLimit: true, excludedNames: nativeNames, label: "project Markdown",
+        timeoutMs: SOURCE_RESOLUTION_MS }));
   }
-  const nativeNames = new Set(host === "codex"
-    ? ["AGENTS.override.md", "AGENTS.md", ...(hostDetails.fallbackNames || [])]
-    : ["CLAUDE.md", "CLAUDE.local.md"]);
-  sources = sources.filter((item) => item.binding !== "host-native-rule-tree"
-    || !item.id.startsWith("agentspine:project/") || !nativeNames.has(basename(item.path)));
   sources = [...new Map(sources.map((item) => [item.path, item])).values()];
   if (sources.length > MAX_SOURCES) throw new Error(`host-native source set exceeds ${MAX_SOURCES} files`);
-  if (Date.now() > deadline) throw new Error(`host-native source resolution exceeded ${SOURCE_RESOLUTION_MS} ms`);
+  const projectScanIncomplete = skipped.some((item) => item.code === SOURCE_SCAN_INCOMPLETE);
+  if (Date.now() > deadline && !projectScanIncomplete) {
+    throw new Error(`host-native source resolution exceeded ${SOURCE_RESOLUTION_MS} ms`);
+  }
   let documents;
   try {
     documents = await indexExplicitDocuments(sources);
@@ -494,10 +419,14 @@ export async function resolveHostSourceCatalog({ host, cwd = process.cwd(), inpu
     if (typeof error?.code === "string" && (error.path || error.syscall)) throw sourceScanError(error);
     throw error;
   }
-  if (Date.now() > deadline) throw new Error(`host-native source resolution exceeded ${SOURCE_RESOLUTION_MS} ms`);
+  if (Date.now() > deadline && !projectScanIncomplete) {
+    throw new Error(`host-native source resolution exceeded ${SOURCE_RESOLUTION_MS} ms`);
+  }
   const totalBytes = documents.reduce((sum, document) => sum + document.bytes, 0);
   if (totalBytes > MAX_TOTAL_SOURCE_BYTES) throw new Error("host-native source set exceeds 8 MiB");
   const activeUserState = activeBinding(registry, host, hostHome, projectRoot, "state-user");
+  const orderedSkipped = skipped.sort((a, b) => a.path.localeCompare(b.path) || a.operation.localeCompare(b.operation));
+  const warnings = orderedSkipped.filter((item) => item.code === SOURCE_SCAN_INCOMPLETE);
   const diagnostics = {
     schema: SOURCE_REGISTRY_SCHEMA, host, status: documents.length ? "loaded" : "empty", projectRoot,
     hostHomeDigest: digest(hostHome).slice(0, 16), checked: ["host-profile", "project-chain", ...(host === "claude" ? ["project-memory"] : [])],
@@ -505,15 +434,19 @@ export async function resolveHostSourceCatalog({ host, cwd = process.cwd(), inpu
     reason: documents.length ? null : "No regular, non-symlink host-native Markdown source exists in the checked scope.",
     personalContinuityLoaded: documents.some((item) => item.sourceScope === "user") || Boolean(activeUserState),
     broadHomeScan: false, projectTreeScan: skippedFallbackHomeTree ? "skipped-unmarked-home"
-      : skippedHomeTree ? "skipped-home-root" : skippedProfileTree ? "skipped-profile-root" : "bounded",
-    skipped: skipped.sort((a, b) => a.path.localeCompare(b.path) || a.operation.localeCompare(b.operation)),
+      : skippedHomeTree ? "skipped-home-root" : skippedProfileTree ? "skipped-profile-root"
+        : warnings.length ? "bounded-truncated" : "bounded",
+    incomplete: warnings.length > 0,
+    warning: warnings[0]?.message || null,
+    warnings,
+    skipped: orderedSkipped,
     rootResolution, registryRevision: registry.revision,
     ...(host === "claude" ? {
       memoryBound: Boolean(hostDetails.memoryRoot),
       memoryRootDigest: hostDetails.memoryRoot ? digest(hostDetails.memoryRoot).slice(0, 16) : null,
       memoryProvenance: hostDetails.memoryProvenance,
       memory: hostDetails.memoryDiagnostics || {
-        indexed: 0, relevant: 0, loaded: 0, cacheHits: 0, cacheMisses: 0, missing: 0,
+        indexed: 0, relevant: 0, selected: 0, omittedRelevant: 0, loaded: 0, cacheHits: 0, cacheMisses: 0, missing: 0,
         rejected: { scope: 0, path: 0, symlink: 0, race: 0, size: 0 }, directoryEnumeration: 0
       }
     } : hostDetails)

package/agent-spine-plugin/src/lib/source-tree-scan.js

@@ -0,0 +1,178 @@
+import { lstat, opendir, realpath } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+export const SOURCE_SCAN_INCOMPLETE = "AGENTSPINE_SCAN_INCOMPLETE";
+
+const SKIP_EXTRA_DIRS = new Set([
+  ".git", ".hg", ".svn", ".claude", ".codex", "node_modules", "vendor", "dist", "build", "coverage"
+]);
+
+export function sourceScanError(error) {
+  error.agentSpineScan = true;
+  return error;
+}
+
+export async function existingRegular(path) {
+  try {
+    const metadata = await lstat(path);
+    if (metadata.isSymbolicLink() || !metadata.isFile()) return null;
+    return realpath(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw sourceScanError(error);
+  }
+}
+
+export async function existingDirectory(path) {
+  try {
+    const metadata = await lstat(path);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()) return null;
+    return realpath(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw sourceScanError(error);
+  }
+}
+
+function skippedExtraDirectory(name) {
+  const lower = name.toLowerCase();
+  return SKIP_EXTRA_DIRS.has(name) || SKIP_EXTRA_DIRS.has(lower)
+    || lower.includes("dropbox") || lower === "onedrive" || lower.startsWith("onedrive - ");
+}
+
+export function skippableTraversalError(error) {
+  return ["EPERM", "EACCES", "ENOENT", "ENOTDIR"].includes(error?.code);
+}
+
+function recordSkippedPath(skipped, path, error, operation) {
+  skipped.push({ path, code: error.code, operation });
+}
+
+function recordIncomplete(skipped, { path, operation, message, limit, retained }) {
+  skipped.push({
+    path, code: SOURCE_SCAN_INCOMPLETE, operation, message, limit, retained,
+    authority: "diagnostic-only"
+  });
+}
+
+async function containsProjectMarker(directory) {
+  try {
+    await lstat(join(directory, ".git"));
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function containsEmbeddedHostProfile(directory) {
+  return Boolean(
+    await existingDirectory(join(directory, ".runtime-private"))
+    && await existingRegular(join(directory, "config.toml"))
+  );
+}
+
+function limitMessage(label, detail) {
+  return `Host-native ${label} context is incomplete: ${detail}; remaining files were skipped.`;
+}
+
+export async function boundedMarkdownTree(directory, prefix, host, scope, precedenceStart, deadline, {
+  projectBoundary = false,
+  maxFiles,
+  maxDirectoryEntries,
+  skipped = [],
+  truncateOnLimit = false,
+  excludedNames = new Set(),
+  label = "rule-tree",
+  timeoutMs
+} = {}) {
+  let root;
+  try {
+    root = await existingDirectory(directory);
+  } catch (error) {
+    if (!skippableTraversalError(error)) throw sourceScanError(error);
+    recordSkippedPath(skipped, directory, error, "inspect-directory");
+    return [];
+  }
+  if (!root) return [];
+  const output = [];
+  let visitedEntries = 0;
+
+  function stopForLimit(path, operation, message, limit) {
+    if (!truncateOnLimit) throw new Error(message);
+    recordIncomplete(skipped, { path, operation,
+      message: limitMessage(label, message), limit, retained: output.length });
+    return false;
+  }
+
+  function checkDeadline(path) {
+    if (Date.now() <= deadline) return true;
+    const message = `source resolution exceeded ${timeoutMs} ms`;
+    if (!truncateOnLimit) throw new Error(`host-native ${message}`);
+    recordIncomplete(skipped, { path, operation: "deadline",
+      message: limitMessage(label, message), limit: timeoutMs, retained: output.length });
+    return false;
+  }
+
+  async function walk(current) {
+    if (!checkDeadline(current)) return false;
+    try {
+      if (projectBoundary && current !== root
+        && (await containsProjectMarker(current) || await containsEmbeddedHostProfile(current))) return true;
+    } catch (error) {
+      if (!skippableTraversalError(error)) throw sourceScanError(error);
+      recordSkippedPath(skipped, current, error, "inspect-directory-boundary");
+      return true;
+    }
+    const entries = [];
+    let stream;
+    try {
+      stream = await opendir(current);
+    } catch (error) {
+      if (!skippableTraversalError(error)) throw sourceScanError(error);
+      recordSkippedPath(skipped, error.path || current, error, "opendir");
+      return true;
+    }
+    let stopAfterDirectory = false;
+    try {
+      for await (const entry of stream) {
+        if (truncateOnLimit && !checkDeadline(current)) return false;
+        visitedEntries += 1;
+        if (visitedEntries > maxDirectoryEntries) {
+          const message = `source tree exceeds ${maxDirectoryEntries} directory entries`;
+          if (!truncateOnLimit) throw new Error(`host-native ${message}`);
+          recordIncomplete(skipped, { path: current, operation: "directory-entry-limit",
+            message: limitMessage(label, message), limit: maxDirectoryEntries, retained: output.length });
+          stopAfterDirectory = true;
+          break;
+        }
+        entries.push(entry);
+      }
+    } catch (error) {
+      if (!skippableTraversalError(error)) throw sourceScanError(error);
+      recordSkippedPath(skipped, current, error, "readdir");
+      return true;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (truncateOnLimit && !checkDeadline(current)) return false;
+      if (entry.isSymbolicLink()) continue;
+      const path = join(current, entry.name);
+      if (entry.isDirectory() && !stopAfterDirectory && !entry.name.startsWith(".")
+        && !skippedExtraDirectory(entry.name)) {
+        if (!await walk(path)) return false;
+      } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")
+        && !excludedNames.has(entry.name)) {
+        if (output.length >= maxFiles) {
+          return stopForLimit(root, "file-limit", `rule tree exceeds ${maxFiles} files`, maxFiles);
+        }
+        output.push({ path, id: `${prefix}/${relative(root, path).replaceAll("\\", "/")}`, host, scope,
+          binding: "host-native-rule-tree", precedence: precedenceStart + output.length });
+      }
+    }
+    return !stopAfterDirectory;
+  }
+
+  await walk(root);
+  return output;
+}

package/agent-spine-plugin/src/lib/task-knowledge-context.js

@@ -0,0 +1,78 @@
+const MAX_ITEMS = 6;
+const STOP_WORDS = new Set([
+  "and", "are", "das", "der", "die", "eine", "einer", "for", "from", "für", "ist",
+  "mit", "soll", "that", "the", "this", "und", "von", "was", "with"
+]);
+const KIND_WEIGHT = {
+  "error-lesson": 40,
+  decision: 30,
+  "user-preference": 20,
+  fact: 10
+};
+
+function terms(value) {
+  return [...new Set(String(value).normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase()
+    .match(/[\p{L}\p{N}]+/gu)?.filter((item) => item.length >= 3 && !STOP_WORDS.has(item)) || [])]
+    .slice(0, 64);
+}
+
+function taskText(task) {
+  return [task.objective, task.nextStep?.summary,
+    ...task.openQuestions.map((item) => item.question)].filter(Boolean).join(" ");
+}
+
+function entryText(entry) {
+  return [entry.subjectId, entry.predicate, JSON.stringify(entry.value), entry.rationale]
+    .filter(Boolean).join(" ").slice(0, 12_288);
+}
+
+function empty(taskId, status) {
+  return {
+    schema: "agentspine.task-knowledge-context/v1",
+    taskId,
+    status,
+    items: [],
+    omitted: 0,
+    authority: "context-only"
+  };
+}
+
+export function taskKnowledgeContext(entries, { taskId = null, continuation, maxItems = MAX_ITEMS } = {}) {
+  if (!taskId) return empty(null, "not-requested");
+  const task = continuation.tasks.find((item) => item.taskId === taskId);
+  if (!task) {
+    const terminal = continuation.terminal.some((item) => item.taskId === taskId);
+    return empty(taskId, terminal ? "terminal" : "unavailable");
+  }
+  const queryTerms = terms(taskText(task));
+  if (!queryTerms.length) return empty(taskId, "no-query");
+  const querySet = new Set(queryTerms);
+  const minimumMatches = Math.min(2, queryTerms.length);
+  const seen = new Set();
+  const ranked = [];
+  for (const entry of entries) {
+    if (entry.status !== "confirmed" || !(entry.kind in KIND_WEIGHT)) continue;
+    const matchedTerms = terms(entryText(entry)).filter((item) => querySet.has(item));
+    if (matchedTerms.length < minimumMatches) continue;
+    const key = `${entry.kind}\0${entry.subjectId}\0${entry.predicate}\0${JSON.stringify(entry.value)}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    ranked.push({ entry, matchedTerms,
+      score: matchedTerms.length * 100 + KIND_WEIGHT[entry.kind] });
+  }
+  ranked.sort((left, right) => right.score - left.score
+    || right.entry.observedAt.localeCompare(left.entry.observedAt)
+    || left.entry.id.localeCompare(right.entry.id));
+  const limit = Math.min(MAX_ITEMS, Math.max(1, maxItems));
+  return {
+    schema: "agentspine.task-knowledge-context/v1",
+    taskId,
+    status: ranked.length ? "available" : "no-match",
+    items: ranked.slice(0, limit).map(({ entry, matchedTerms }) => ({
+      ...structuredClone(entry),
+      relevance: { matchedTerms, authority: "context-only" }
+    })),
+    omitted: Math.max(0, ranked.length - limit),
+    authority: "context-only"
+  };
+}