bilmem 0.1.0 → 0.2.0

package/dist/mcp/index.js

@@ -1,6 +1,6 @@
 // src/mcp/server.ts
 import { McpApp, z } from "mcponce";
-import * as path8 from "path";
+import * as path9 from "path";
 
 // src/storage/canonical.ts
 import * as fs3 from "fs/promises";
@@ -1180,6 +1180,7 @@ function formatWhyHistory(knowledge) {
 // src/core/resolver.ts
 var RELATIVE_COSTS = {
   USE_KNOWLEDGE: 1,
+  REVALIDATE: 2,
   INSPECT_TEST: 2,
   INSPECT_FILE: 2,
   INSPECT_SYMBOL: 2.5,
@@ -1520,6 +1521,634 @@ async function resolveEpistemicQuery(options, storage, retriever) {
   };
 }
 
+// src/core/preflight.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import * as path4 from "path";
+import * as fs4 from "fs/promises";
+import YAML2 from "yaml";
+
+// src/core/dependencies.ts
+function normalizeSourceKey(source) {
+  return source.replace(/^(file|code|test|doc):/, "").trim().toLowerCase();
+}
+function checkKnowledgeStaleness(knowledge, changedSources) {
+  const normChanged = new Set(changedSources.map(normalizeSourceKey));
+  const allDeps = [
+    ...(knowledge.depends_on ?? []).map(normalizeSourceKey),
+    ...knowledge.evidence.map(normalizeSourceKey)
+  ];
+  const changed = [];
+  const unchanged = [];
+  for (const dep of allDeps) {
+    if (!dep) continue;
+    const isChanged = normChanged.has(dep) || Array.from(normChanged).some((c) => dep.includes(c) || c.includes(dep));
+    if (isChanged) {
+      changed.push(dep);
+    } else {
+      unchanged.push(dep);
+    }
+  }
+  if (changed.length > 0) {
+    const reason = `Supporting dependency changed: ${changed.join(", ")}. Unchanged evidence: ${unchanged.join(", ") || "none"}`;
+    return {
+      knowledgeId: knowledge.id,
+      affected: true,
+      status: "needs_revalidation",
+      changedSources: changed,
+      unchangedSources: unchanged,
+      reason
+    };
+  }
+  return {
+    knowledgeId: knowledge.id,
+    affected: false,
+    status: knowledge.status,
+    changedSources: [],
+    unchangedSources: allDeps
+  };
+}
+function markStaleKnowledge(knowledgeList, changedSources) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  let affectedCount = 0;
+  const updatedKnowledge = [];
+  for (const k of knowledgeList) {
+    if (k.status === "superseded" || k.status === "invalid" || k.status === "invalidated") {
+      updatedKnowledge.push(k);
+      continue;
+    }
+    const res = checkKnowledgeStaleness(k, changedSources);
+    if (res.affected) {
+      affectedCount++;
+      const history = k.history ?? [];
+      const updated = {
+        ...k,
+        status: "needs_revalidation",
+        updatedAt: now,
+        history: [
+          ...history,
+          {
+            timestamp: now,
+            status: "needs_revalidation",
+            action: "source_changed",
+            reason: res.reason
+          }
+        ]
+      };
+      updatedKnowledge.push(updated);
+    } else {
+      updatedKnowledge.push(k);
+    }
+  }
+  return { updatedKnowledge, affectedCount };
+}
+function checkKnowledgeListStaleness(knowledgeList, changedSources) {
+  const { updatedKnowledge, affectedCount } = markStaleKnowledge(knowledgeList, changedSources);
+  const affectedKnowledge = updatedKnowledge.filter((k) => k.status === "needs_revalidation");
+  return { affectedKnowledge, updatedKnowledge, affectedCount };
+}
+
+// src/core/preflight.ts
+var execFileAsync = promisify(execFile);
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "add",
+  "implement",
+  "create",
+  "support",
+  "with",
+  "the",
+  "a",
+  "an",
+  "for",
+  "in",
+  "to",
+  "and",
+  "of",
+  "on",
+  "from",
+  "using",
+  "via",
+  "into",
+  "by",
+  "our",
+  "new",
+  "use",
+  "make",
+  "allow",
+  "enable",
+  "provide",
+  "setup",
+  "set"
+]);
+var DOMAIN_KEYWORDS = {
+  authentication: ["auth", "oauth", "login", "logout", "session", "jwt", "token", "credential", "sso", "password"],
+  session: ["session", "cookie", "cookies", "expiry", "refresh", "token"],
+  "user-identity": ["user", "account", "profile", "identity", "member", "role", "permission"],
+  database: ["db", "database", "sql", "postgres", "sqlite", "migration", "schema", "table", "query"],
+  storage: ["storage", "s3", "bucket", "file", "upload", "disk", "blob"],
+  api: ["api", "endpoint", "http", "rest", "route", "controller", "middleware", "graphql"],
+  caching: ["cache", "redis", "memcached", "ttl", "invalidation"],
+  billing: ["payment", "stripe", "checkout", "billing", "subscription", "invoice", "credit"],
+  "data-processing": ["import", "export", "csv", "bulk", "batch", "stream", "pipeline"]
+};
+function tokenizeGoal(goal) {
+  return goal.toLowerCase().replace(/[^a-z0-9_-]/g, " ").split(/\s+/).filter((t) => t.length > 2 && !STOP_WORDS.has(t));
+}
+function inferLikelyDomains(tokens, knowledgeTags) {
+  const domains = /* @__PURE__ */ new Set();
+  for (const token of tokens) {
+    for (const [domain, keywords] of Object.entries(DOMAIN_KEYWORDS)) {
+      if (keywords.includes(token) || token.includes(domain)) {
+        domains.add(domain);
+      }
+    }
+  }
+  for (const tag of knowledgeTags) {
+    const norm = tag.toLowerCase().trim();
+    if (DOMAIN_KEYWORDS[norm]) {
+      domains.add(norm);
+    }
+  }
+  return Array.from(domains);
+}
+function classifyUnknown(unknown, goalTokens, domainCues) {
+  const text = `${unknown.id} ${unknown.statement || ""} ${unknown.question || unknown.next?.question || ""}`.toLowerCase();
+  if (unknown.blocking === true) {
+    const isDecision2 = /\b(should|whether|how to handle|what happens when|policy|strategy|linking|collision|merge|choice)\b/i.test(text);
+    return {
+      classification: "BLOCKING",
+      isDecision: isDecision2 || true,
+      reason: unknown.reason || "Blocking unknown identified for this goal"
+    };
+  }
+  if (unknown.blocking === false) {
+    const isDecision2 = /\b(should|whether|how to handle|what happens when|policy|strategy|choice)\b/i.test(text);
+    return {
+      classification: "NON_BLOCKING",
+      isDecision: isDecision2,
+      reason: "Operational or instrumentation detail not blocking core functionality"
+    };
+  }
+  const isNonBlocking = /\b(analytics|telemetry|metric|event name|logging level|log format|button color|styling|theme)\b/i.test(text);
+  if (isNonBlocking) {
+    return {
+      classification: "NON_BLOCKING",
+      isDecision: /\b(should|which name|choice)\b/i.test(text),
+      reason: "Operational or instrumentation detail not blocking core functionality"
+    };
+  }
+  const isDecision = /\b(should|whether|how to handle|what happens when|policy|strategy|linking|collision|merge)\b/i.test(text);
+  const isBlockingCandidate = /\b(link|linking|collision|duplicate|merge|security|permission|storage-engine|protocol|auth-flow|credentials)\b/i.test(text);
+  const overlapsGoal = goalTokens.some((t) => text.includes(t)) || domainCues.some((d) => text.includes(d));
+  if (isBlockingCandidate && (overlapsGoal || unknown.reason === "UNRESOLVABLE_LOCALLY")) {
+    return {
+      classification: "BLOCKING",
+      isDecision: true,
+      reason: "Unresolved architectural or behavioral decision critical to goal implementation"
+    };
+  }
+  return {
+    classification: "IMPORTANT",
+    isDecision,
+    reason: isDecision ? "Product or behavior decision requiring attention" : "Important implementation detail"
+  };
+}
+function prioritizeQuestions(rawQuestions, blockingUnknowns) {
+  const consolidated = /* @__PURE__ */ new Map();
+  for (const rq of rawQuestions) {
+    const qText = rq.question.trim();
+    if (!qText) continue;
+    const topic = rq.targetTopic || qText.toLowerCase().replace(/[^a-z0-9]/g, " ").slice(0, 30);
+    let expectedResolutionValue = 1;
+    if (rq.isBlocking) expectedResolutionValue += 2;
+    if (rq.outcomeScore && rq.outcomeScore > 0) expectedResolutionValue += 1;
+    if (rq.outcomeScore && rq.outcomeScore < 0) expectedResolutionValue -= 0.5;
+    const interactionCost = 1;
+    const priorityScore = Math.max(0.1, expectedResolutionValue) / interactionCost;
+    const existing = consolidated.get(topic);
+    if (!existing || priorityScore > (existing.priorityScore ?? 0)) {
+      consolidated.set(topic, {
+        question: qText,
+        reason: rq.reason,
+        targetTopic: rq.targetTopic,
+        expectedResolutionValue,
+        interactionCost,
+        priorityScore
+      });
+    }
+  }
+  return Array.from(consolidated.values()).sort((a, b) => (b.priorityScore ?? 0) - (a.priorityScore ?? 0));
+}
+async function executePreflight(options, storage, retriever, index) {
+  const goal = options.goal.trim();
+  const explicitPositive = (options.positive ?? []).map((p) => p.trim().toLowerCase());
+  const negative = (options.negative ?? []).map((n) => n.trim().toLowerCase());
+  const scope = options.scope ?? "project";
+  const goalTokens = tokenizeGoal(goal);
+  const allKnowledge = await storage.getAllKnowledge();
+  const allTags = allKnowledge.flatMap((k) => k.tags ?? []);
+  const likelyDomains = inferLikelyDomains(goalTokens, allTags);
+  const contextualPositive = Array.from(/* @__PURE__ */ new Set([...explicitPositive, ...likelyDomains, ...goalTokens]));
+  let candidatePool = [];
+  if (retriever) {
+    const jevCandidates = await retriever.lookup({
+      query: goal,
+      positive: contextualPositive,
+      negative,
+      scope,
+      limit: options.maxCandidates ?? 25,
+      includeRejected: true
+    });
+    for (const r of jevCandidates) {
+      if (r.knowledge) candidatePool.push(r.knowledge);
+    }
+  }
+  if (candidatePool.length === 0) {
+    candidatePool = allKnowledge.filter((k) => k.status !== "invalid" && k.status !== "superseded");
+  } else {
+    for (const k of allKnowledge) {
+      if (!candidatePool.some((c) => c.id === k.id) && k.status !== "invalid" && k.status !== "superseded") {
+        const matchesToken = goalTokens.some((t) => k.id.toLowerCase().includes(t) || k.statement.toLowerCase().includes(t));
+        const matchesCues = k.positive.some((p) => contextualPositive.includes(p));
+        if (matchesToken || matchesCues) {
+          candidatePool.push(k);
+        }
+      }
+    }
+  }
+  const jevResults = rerankCandidates(candidatePool, {
+    query: goal,
+    positive: contextualPositive,
+    negative,
+    scope
+  });
+  const matchingItems = [];
+  const rejectedItems = [];
+  for (const res of jevResults) {
+    if (res.status === "REJECT") {
+      const reason = res.explanation.negativeConflicts.length > 0 ? `Inapplicable: ${res.explanation.negativeConflicts.join(", ")} conflicts with current context` : res.explanation.reasons[0] || "Context mismatch";
+      rejectedItems.push({ id: res.knowledge.id, reason });
+    } else {
+      matchingItems.push(res.knowledge);
+    }
+  }
+  if (options.deep) {
+    try {
+      const { stdout: diffOutput } = await execFileAsync(
+        "git",
+        ["diff", "--name-only", "HEAD~1"],
+        { cwd: storage.getBaseDir() ? path4.dirname(storage.getBaseDir()) : process.cwd() }
+      );
+      const changedFiles = diffOutput.split("\n").map((f) => f.trim()).filter(Boolean);
+      if (changedFiles.length > 0) {
+        const staleness = checkKnowledgeListStaleness(matchingItems, changedFiles);
+        for (const affected of staleness.affectedKnowledge) {
+          const matchIdx = matchingItems.findIndex((m) => m.id === affected.id);
+          if (matchIdx >= 0) {
+            matchingItems[matchIdx] = affected;
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  const constraints = [];
+  const lessons = [];
+  const pastFailures = [];
+  const stale = [];
+  const known = [];
+  let conflictedCount = 0;
+  const CONSTRAINT_PATTERN = /\b(must|must not|never|only|cannot|require|required|boundary|strictly|prohibited|forbidden)\b/i;
+  const FAILURE_PATTERN = /(fail|bug|error|crash|duplicate write|race condition|pressure|leak|revert|timeout)/i;
+  const rootDir = storage.getBaseDir() ? path4.dirname(storage.getBaseDir()) : process.cwd();
+  for (const k of matchingItems) {
+    const matchesContradiction = k.status === "contradicted" || k.contradicts && k.contradicts.some((cid) => matchingItems.some((m) => m.id === cid));
+    if (matchesContradiction) {
+      conflictedCount++;
+    }
+    let isStale = k.status === "needs_revalidation" || k.status === "stale";
+    let staleReason = k.history?.[k.history.length - 1]?.reason || "Supporting source changed after last validation";
+    const changedDeps = [];
+    const candidateDeps = [...k.depends_on ?? [], ...k.evidence ?? []];
+    const timestampStr = k.updated_at ?? k.updatedAt ?? k.createdAt;
+    const knowledgeTime = new Date(timestampStr).getTime();
+    for (const dep of candidateDeps) {
+      const cleanPath = dep.replace(/^(file|code|test|doc):/, "").trim();
+      if (!cleanPath) continue;
+      const absPath = path4.isAbsolute(cleanPath) ? cleanPath : path4.resolve(rootDir, cleanPath);
+      try {
+        const stat4 = await fs4.stat(absPath);
+        if (stat4.mtimeMs > knowledgeTime + 500) {
+          isStale = true;
+          changedDeps.push(cleanPath);
+          staleReason = `Supporting source changed after last validation (${cleanPath})`;
+        }
+      } catch {
+      }
+    }
+    if (isStale) {
+      stale.push({
+        id: k.id,
+        statement: k.statement,
+        reason: staleReason,
+        changedSources: changedDeps.length > 0 ? changedDeps : k.depends_on
+      });
+      continue;
+    }
+    const isConstraint = k.type === "rule" || k.type === "decision" || k.type === "convention" || CONSTRAINT_PATTERN.test(k.statement);
+    if (isConstraint) {
+      constraints.push({
+        id: k.id,
+        statement: k.statement,
+        type: k.type,
+        confidence: k.confidence,
+        confidenceTier: k.confidenceTier,
+        source: k.evidence?.[0]
+      });
+      continue;
+    }
+    const isFailure = k.type === "failure" || k.statement.startsWith("[FAILURE]") || k.statement.startsWith("[REVERT]") || FAILURE_PATTERN.test(k.statement) || k.metrics.failed_outcomes > 0;
+    if (isFailure) {
+      pastFailures.push({
+        id: k.id,
+        statement: k.statement,
+        context: k.context || {
+          positive: k.positive,
+          negative: k.negative
+        },
+        failure: k.statement,
+        lesson: k.lesson || k.reasoning || k.resolves?.[0],
+        evidence: k.evidence
+      });
+      continue;
+    }
+    const isLesson = k.type === "lesson" && (k.id.includes("lesson") || k.tags?.includes("lesson") || k.statement.toLowerCase().includes("lesson")) || k.statement.toLowerCase().startsWith("lesson:") || k.statement.toLowerCase().includes("lesson:");
+    if (isLesson) {
+      lessons.push({
+        id: k.id,
+        statement: k.statement,
+        confidence: k.confidence,
+        domain: k.tags?.[0],
+        evidence: k.evidence
+      });
+      continue;
+    }
+    if (k.status === "active" || k.stage === "active" || k.stage === "probation" || !k.status) {
+      known.push({
+        id: k.id,
+        statement: k.statement,
+        confidence: k.confidence,
+        confidenceTier: k.confidenceTier,
+        stage: k.stage
+      });
+    }
+  }
+  const unknownsFromStorage = await storage.getAllUnknowns();
+  const unknownKnowledge = allKnowledge.filter((k) => k.type === "unknown");
+  const unifiedUnknowns = [];
+  const seenUnknownIds = /* @__PURE__ */ new Set();
+  for (const u of unknownsFromStorage) {
+    seenUnknownIds.add(u.id);
+    unifiedUnknowns.push({
+      id: u.id,
+      statement: u.statement || u.id,
+      reason: u.reason,
+      question: u.question || u.next?.question,
+      next: u.next,
+      blocking: u.blocking,
+      positive: u.positive,
+      negative: u.negative,
+      checked: u.checked
+    });
+  }
+  for (const k of unknownKnowledge) {
+    if (!seenUnknownIds.has(k.id)) {
+      seenUnknownIds.add(k.id);
+      unifiedUnknowns.push({
+        id: k.id,
+        statement: k.statement,
+        reason: k.history?.[0]?.reason,
+        question: k.question || (k.statement.includes("?") ? k.statement : void 0),
+        next: {
+          type: "ask",
+          target: k.id,
+          question: k.question || k.statement
+        },
+        blocking: k.blocking,
+        positive: k.positive,
+        negative: k.negative,
+        checked: k.depends_on || k.evidence
+      });
+    }
+  }
+  const unknowns = [];
+  const missing = [];
+  const rawQuestions = [];
+  for (const u of unifiedUnknowns) {
+    const text = `${u.id} ${u.statement || ""} ${u.question || ""}`.toLowerCase();
+    const overlaps = goalTokens.some((t) => text.includes(t)) || likelyDomains.some((d) => text.includes(d)) || u.positive && u.positive.some((p) => contextualPositive.includes(p));
+    if (u.negative && u.negative.some((n) => contextualPositive.includes(n))) {
+      continue;
+    }
+    if (overlaps) {
+      const { classification, isDecision, reason } = classifyUnknown(u, goalTokens, likelyDomains);
+      const isBlocking = classification === "BLOCKING";
+      unknowns.push({
+        id: u.id,
+        statement: u.statement,
+        question: u.question || u.statement,
+        classification,
+        blocking: isBlocking,
+        reason
+      });
+      if (isDecision) {
+        missing.push({
+          type: "decision",
+          subject: u.id,
+          question: u.question || u.statement,
+          reason
+        });
+      } else {
+        missing.push({
+          type: "evidence",
+          subject: u.id,
+          question: u.question || u.statement,
+          reason
+        });
+      }
+      const qText = u.question || (u.statement && u.statement.includes("?") ? u.statement : void 0);
+      if (qText) {
+        rawQuestions.push({
+          question: qText,
+          reason: `Unknown: ${u.id} (${reason})`,
+          targetTopic: u.id,
+          isBlocking
+        });
+      }
+    }
+  }
+  const questionKnowledge = allKnowledge.filter((k) => k.type === "question");
+  for (const qk of questionKnowledge) {
+    const matchesCues = qk.positive.some((p) => contextualPositive.includes(p));
+    const conflicts = qk.negative.some((n) => negative.includes(n));
+    if (matchesCues && !conflicts && qk.question) {
+      rawQuestions.push({
+        question: qk.question,
+        reason: `Learned question for [${qk.positive.join(", ")}] uncertainty`,
+        targetTopic: qk.resolves?.[0] || qk.id,
+        outcomeScore: (qk.metrics?.successful_outcomes ?? 0) - (qk.metrics?.failed_outcomes ?? 0)
+      });
+    }
+  }
+  const questions = prioritizeQuestions(rawQuestions, unknowns);
+  const receipts = await storage.getAllReceipts();
+  const alreadyInvestigated = [];
+  const investigatedSources = /* @__PURE__ */ new Set();
+  for (const r of receipts) {
+    const qTokens = r.question.toLowerCase().split(/\s+/).filter(Boolean);
+    const overlapsGoal = qTokens.some((t) => goalTokens.includes(t));
+    const overlapsCues = r.positive && r.positive.some((p) => contextualPositive.includes(p));
+    if (overlapsGoal || overlapsCues) {
+      for (const checked of r.checked) {
+        investigatedSources.add(checked.toLowerCase());
+        alreadyInvestigated.push({
+          source: checked,
+          result: r.findings[0] || r.rejected[0]?.reason || "Did not establish requested behavior",
+          nextSuggestion: "ASK_USER"
+        });
+      }
+    }
+  }
+  let readiness = "READY";
+  const totalRelevantKnowledge = known.length + constraints.length + lessons.length + pastFailures.length + stale.length;
+  const hasBlockingUnknown = unknowns.some((u) => u.blocking);
+  const hasMissingDecision = missing.some((m) => m.type === "decision");
+  if (totalRelevantKnowledge === 0 && unknowns.length === 0) {
+    readiness = "INSUFFICIENT_KNOWLEDGE";
+  } else if (conflictedCount > 0) {
+    readiness = "CONFLICTED";
+  } else if (hasBlockingUnknown || hasMissingDecision) {
+    readiness = "NEEDS_CLARIFICATION";
+  } else if (stale.length > 0) {
+    readiness = "NEEDS_REVALIDATION";
+  } else {
+    readiness = "READY";
+  }
+  const next = [];
+  for (const m of missing) {
+    if (m.type === "decision") {
+      next.push({
+        type: "ASK_USER",
+        target: m.subject,
+        reason: m.question || m.reason,
+        relativeCost: 1,
+        expectedInfoGain: 0.95
+      });
+    }
+  }
+  for (const s of stale) {
+    next.push({
+      type: "REVALIDATE",
+      target: s.id,
+      reason: s.reason,
+      relativeCost: 2,
+      expectedInfoGain: 0.85
+    });
+  }
+  for (const m of missing) {
+    if (m.type === "evidence") {
+      const wasChecked = investigatedSources.has(m.subject.toLowerCase()) || alreadyInvestigated.length > 0;
+      if (wasChecked) {
+        if (!next.some((n) => n.type === "ASK_USER")) {
+          next.push({
+            type: "ASK_USER",
+            target: m.subject,
+            reason: `Already investigated (${Array.from(investigatedSources).join(", ")}); did not establish requested behavior. Clarification required.`,
+            relativeCost: 1,
+            expectedInfoGain: 0.9
+          });
+        }
+      } else {
+        const isFilePath = m.subject.includes("/") || m.subject.includes(".");
+        next.push({
+          type: isFilePath ? "INSPECT_FILE" : "SEARCH_REPOSITORY",
+          target: m.subject,
+          reason: m.reason,
+          relativeCost: isFilePath ? 2 : 2.5,
+          expectedInfoGain: 0.8
+        });
+      }
+    }
+  }
+  if (alreadyInvestigated.length > 0 && !next.some((n) => n.type === "ASK_USER")) {
+    next.push({
+      type: "ASK_USER",
+      target: alreadyInvestigated[0].source,
+      reason: `Already investigated ${alreadyInvestigated[0].source}; clarification required`,
+      relativeCost: 1,
+      expectedInfoGain: 0.9
+    });
+  }
+  if (next.length === 0 && known.length > 0) {
+    next.push({
+      type: "USE_KNOWLEDGE",
+      target: known[0].id,
+      reason: "Proceed with implementation using verified knowledge and constraints",
+      relativeCost: 1,
+      expectedInfoGain: 1
+    });
+  }
+  const knowledgeImpact = {
+    relevantKnowledge: totalRelevantKnowledge,
+    validated: known.filter((k) => k.confidenceTier === "high").length + constraints.length,
+    needsRevalidation: stale.length,
+    conflicted: conflictedCount,
+    blockingUnknowns: unknowns.filter((u) => u.blocking).length,
+    relevantFailures: pastFailures.length
+  };
+  const similarWork = [];
+  for (const l of lessons) {
+    similarWork.push({
+      topic: l.domain || l.id,
+      lesson: l.statement
+    });
+  }
+  for (const f of pastFailures) {
+    similarWork.push({
+      topic: f.id,
+      failure: f.statement
+    });
+  }
+  await storage.appendMetricEvent({
+    type: "preflight",
+    goal,
+    readiness,
+    blockingUnknownsCount: knowledgeImpact.blockingUnknowns,
+    staleKnowledgeCount: stale.length,
+    pastFailuresCount: pastFailures.length,
+    questionsCount: questions.length,
+    repeatedChecksAvoidedCount: alreadyInvestigated.length,
+    timestamp: Date.now()
+  });
+  return {
+    goal,
+    readiness,
+    known,
+    constraints,
+    lessons,
+    past_failures: pastFailures,
+    unknowns,
+    stale,
+    missing,
+    questions,
+    likely_domains: likelyDomains,
+    similar_work: similarWork.length > 0 ? similarWork.slice(0, 5) : void 0,
+    already_investigated: alreadyInvestigated.length > 0 ? alreadyInvestigated : void 0,
+    knowledge_impact: knowledgeImpact,
+    next
+  };
+}
+
 // src/core/knowledge.ts
 import { createHash } from "crypto";
 
@@ -1666,7 +2295,7 @@ function createKnowledge(params) {
     type: params.type ?? "lesson",
     status,
     stage: initialStage,
-    statement: params.statement.trim(),
+    statement: (params.statement ?? params.question ?? params.id).trim(),
     positive: Array.from(new Set(params.positive?.map((p) => p.trim().toLowerCase()) ?? [])),
     negative: Array.from(new Set(params.negative?.map((n) => n.trim().toLowerCase()) ?? [])),
     relations: Array.from(new Set(params.relations?.map((r) => r.trim()) ?? [])),
@@ -1696,6 +2325,11 @@ function createKnowledge(params) {
     },
     history,
     value: 0,
+    lesson: params.lesson,
+    failure_details: params.failure_details,
+    context: params.context,
+    contradicts: params.contradicts ? Array.from(new Set(params.contradicts)) : void 0,
+    blocking: params.blocking,
     createdAt: now,
     updatedAt: now
   };
@@ -2474,7 +3108,7 @@ function processUserCorrection(params) {
 }
 
 // src/scanner/engine.ts
-import * as path7 from "path";
+import * as path8 from "path";
 
 // src/core/relations.ts
 var EvidenceGraph = class _EvidenceGraph {
@@ -2565,8 +3199,8 @@ var EvidenceGraph = class _EvidenceGraph {
 };
 
 // src/scanner/filesystem.ts
-import * as fs4 from "fs/promises";
-import * as path4 from "path";
+import * as fs5 from "fs/promises";
+import * as path5 from "path";
 var DEFAULT_IGNORED_DIRS = /* @__PURE__ */ new Set([
   ".git",
   ".bilmem",
@@ -2587,12 +3221,12 @@ var DEFAULT_IGNORED_DIRS = /* @__PURE__ */ new Set([
   "temp"
 ]);
 function normalizeRelPath(rel) {
-  return rel.split(path4.sep).join("/");
+  return rel.split(path5.sep).join("/");
 }
 async function loadGitignorePatterns(rootDir) {
   try {
-    const gitignorePath = path4.join(rootDir, ".gitignore");
-    const content = await fs4.readFile(gitignorePath, "utf-8");
+    const gitignorePath = path5.join(rootDir, ".gitignore");
+    const content = await fs5.readFile(gitignorePath, "utf-8");
     const regexes = [];
     for (const rawLine of content.split("\n")) {
       const line = rawLine.trim();
@@ -2640,7 +3274,7 @@ async function walkDirectory(dir, optionsOrRoot, legacyFileList) {
       return;
     }
     try {
-      const real = await fs4.realpath(currentDir);
+      const real = await fs5.realpath(currentDir);
       if (visitedRealPaths.has(real)) {
         return;
       }
@@ -2650,14 +3284,14 @@ async function walkDirectory(dir, optionsOrRoot, legacyFileList) {
     }
     let entries;
     try {
-      entries = await fs4.readdir(currentDir, { withFileTypes: true });
+      entries = await fs5.readdir(currentDir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
       if (fileList.length >= maxFiles) break;
-      const fullPath = path4.join(currentDir, entry.name);
-      const rawRelPath = path4.relative(root, fullPath);
+      const fullPath = path5.join(currentDir, entry.name);
+      const rawRelPath = path5.relative(root, fullPath);
       const relPath = normalizeRelPath(rawRelPath);
       const lowerName = entry.name.toLowerCase();
       if (gitignoreRules.some((rule) => rule.test(relPath))) {
@@ -2673,16 +3307,16 @@ async function walkDirectory(dir, optionsOrRoot, legacyFileList) {
         if (!includeHidden && entry.name.startsWith(".") && lowerName !== ".env.example") {
           continue;
         }
-        const ext = path4.extname(entry.name).toLowerCase();
+        const ext = path5.extname(entry.name).toLowerCase();
         try {
-          const stat3 = await fs4.stat(fullPath);
+          const stat4 = await fs5.stat(fullPath);
           const fileInfo = {
             path: fullPath,
             relativePath: relPath,
             name: entry.name,
             ext,
-            size: stat3.size,
-            mtimeMs: stat3.mtimeMs,
+            size: stat4.size,
+            mtimeMs: stat4.mtimeMs,
             isDirectory: false
           };
           if (!options.filter || options.filter(fileInfo)) {
@@ -2725,9 +3359,9 @@ var ProjectContext = class {
     if (this.textCache.has(key)) {
       return this.textCache.get(key);
     }
-    const fullPath = path4.resolve(this.rootDir, relativePath);
+    const fullPath = path5.resolve(this.rootDir, relativePath);
     try {
-      const handle = await fs4.open(fullPath, "r");
+      const handle = await fs5.open(fullPath, "r");
       const buffer = Buffer.alloc(maxBytes);
       const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
       await handle.close();
@@ -3153,12 +3787,12 @@ async function analyzeProjectStructure(files, rootDir, registry = defaultRegistr
 }
 
 // src/scanner/markdown.ts
-import * as fs5 from "fs/promises";
-import * as path5 from "path";
-import YAML2 from "yaml";
+import * as fs6 from "fs/promises";
+import * as path6 from "path";
+import YAML3 from "yaml";
 function parseMarkdownDocument(content, filePath, relativePath) {
   const lines = content.split("\n");
-  const baseName = path5.basename(relativePath, ".md").toLowerCase();
+  const baseName = path6.basename(relativePath, ".md").toLowerCase();
   let frontmatter = {};
   const headings = [];
   const alerts = [];
@@ -3187,7 +3821,7 @@ function parseMarkdownDocument(content, filePath, relativePath) {
         bodyStartIndex = i + 1;
         try {
           const yamlText = frontmatterLines.join("\n");
-          const parsed = YAML2.parse(yamlText);
+          const parsed = YAML3.parse(yamlText);
           if (parsed && typeof parsed === "object") {
             frontmatter = parsed;
           }
@@ -3575,8 +4209,8 @@ var BUILTIN_MARKDOWN_EXTRACTORS = [
         if (!target.startsWith("http://") && !target.startsWith("https://") && !target.startsWith("mailto:") && (target.startsWith(".") || target.includes("/") || /\.(md|ts|js|json|ya?ml|toml|rs|go|py)$/i.test(target))) {
           const rawTarget = target.split("#")[0].split("?")[0].trim();
           if (rawTarget) {
-            const dir = path5.dirname(doc.relativePath);
-            const resolved = dir === "." || path5.isAbsolute(rawTarget) ? rawTarget.replace(/^\.\//, "") : path5.normalize(path5.join(dir, rawTarget));
+            const dir = path6.dirname(doc.relativePath);
+            const resolved = dir === "." || path6.isAbsolute(rawTarget) ? rawTarget.replace(/^\.\//, "") : path6.normalize(path6.join(dir, rawTarget));
             relations.push({
               from: doc.relativePath,
               to: resolved,
@@ -3629,7 +4263,7 @@ for (const ext of BUILTIN_MARKDOWN_EXTRACTORS) {
 async function parseMarkdownFile(filePath, relativePath, registry = defaultMarkdownRegistry) {
   let content = "";
   try {
-    content = await fs5.readFile(filePath, "utf-8");
+    content = await fs6.readFile(filePath, "utf-8");
   } catch {
     return { observations: [], relations: [] };
   }
@@ -3638,11 +4272,11 @@ async function parseMarkdownFile(filePath, relativePath, registry = defaultMarkd
 }
 
 // src/scanner/git.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
 async function runGit(args, cwd) {
-  const { stdout } = await execFileAsync("git", args, {
+  const { stdout } = await execFileAsync2("git", args, {
     cwd,
     maxBuffer: 10 * 1024 * 1024
   });
@@ -3836,9 +4470,9 @@ async function scanGitHistory(cwd, options = {}) {
 }
 
 // src/scanner/source.ts
-import * as fs6 from "fs/promises";
+import * as fs7 from "fs/promises";
 import * as fsSync from "fs";
-import * as path6 from "path";
+import * as path7 from "path";
 import { createRequire } from "module";
 import Parser from "web-tree-sitter";
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
@@ -3892,7 +4526,7 @@ function getWasmDir() {
   try {
     const req = createRequire(import.meta.url);
     const pkgJson = req.resolve("tree-sitter-wasms/package.json");
-    const outDir = path6.join(path6.dirname(pkgJson), "out");
+    const outDir = path7.join(path7.dirname(pkgJson), "out");
     if (fsSync.existsSync(outDir)) {
       wasmBaseDir = outDir;
       return wasmBaseDir;
@@ -3900,8 +4534,8 @@ function getWasmDir() {
   } catch {
   }
   const candidateDirs = [
-    path6.resolve(process.cwd(), "node_modules/tree-sitter-wasms/out"),
-    path6.resolve(process.cwd(), "../node_modules/tree-sitter-wasms/out")
+    path7.resolve(process.cwd(), "node_modules/tree-sitter-wasms/out"),
+    path7.resolve(process.cwd(), "../node_modules/tree-sitter-wasms/out")
   ];
   for (const dir of candidateDirs) {
     if (fsSync.existsSync(dir)) {
@@ -3914,7 +4548,7 @@ function getWasmDir() {
 async function getParserForWasm(wasmName) {
   const wasmDir = getWasmDir();
   if (!wasmDir) return null;
-  const wasmPath = path6.join(wasmDir, wasmName);
+  const wasmPath = path7.join(wasmDir, wasmName);
   if (!fsSync.existsSync(wasmPath)) return null;
   try {
     if (!parserInitialized) {
@@ -4273,7 +4907,7 @@ async function analyzeSourceFile(filePath, relativePath) {
   const relations = [];
   let content = "";
   try {
-    content = await fs6.readFile(filePath, "utf-8");
+    content = await fs7.readFile(filePath, "utf-8");
   } catch {
     return { observations, relations };
   }
@@ -4281,8 +4915,8 @@ async function analyzeSourceFile(filePath, relativePath) {
     return { observations, relations };
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  const baseName = path6.basename(relativePath);
-  const ext = path6.extname(relativePath).toLowerCase();
+  const baseName = path7.basename(relativePath);
+  const ext = path7.extname(relativePath).toLowerCase();
   const wasmName = EXT_TO_WASM[ext];
   if (wasmName) {
     try {
@@ -4480,9 +5114,9 @@ async function scanRepository(rootDir = process.cwd(), options = {}) {
   const plannedActions = [];
   const config = dryRun ? await storage.isInitialized() ? await storage.getConfig() : {
     schemaVersion: 1,
-    projectName: path7.basename(rootDir),
+    projectName: path8.basename(rootDir),
     defaultScope: "project",
-    dataDir: path7.join(rootDir, ".bilmem")
+    dataDir: path8.join(rootDir, ".bilmem")
   } : await storage.init();
   const incremental = options.incremental ?? false;
   const lastScanCommit = incremental ? config.lastScanCommit : void 0;
@@ -4555,7 +5189,7 @@ async function scanRepository(rootDir = process.cwd(), options = {}) {
   ];
   for (const o of mdObs) {
     if (o.source.includes(":adr") || o.claim.startsWith("[WARNING]") || o.claim.startsWith("[CAUTION]")) {
-      const id = `decision.${path7.basename(o.provenance.path || "doc", ".md")}.${o.provenance.line || "adr"}`;
+      const id = `decision.${path8.basename(o.provenance.path || "doc", ".md")}.${o.provenance.line || "adr"}`;
       candidateLessons.push({
         id,
         type: "decision",
@@ -4789,8 +5423,34 @@ async function computeStats(storage, events, options) {
     }
   };
   const actions = {};
+  const preflight = {
+    runs: 0,
+    ready: 0,
+    needsClarification: 0,
+    needsRevalidation: 0,
+    conflicted: 0,
+    insufficientKnowledge: 0,
+    blockingUnknownsFound: 0,
+    staleKnowledgeFound: 0,
+    pastFailuresSurfaced: 0,
+    questionsSuggested: 0,
+    repeatedChecksAvoided: 0
+  };
   for (const e of events) {
     switch (e.type) {
+      case "preflight":
+        preflight.runs++;
+        if (e.readiness === "READY") preflight.ready++;
+        else if (e.readiness === "NEEDS_CLARIFICATION") preflight.needsClarification++;
+        else if (e.readiness === "NEEDS_REVALIDATION") preflight.needsRevalidation++;
+        else if (e.readiness === "CONFLICTED") preflight.conflicted++;
+        else if (e.readiness === "INSUFFICIENT_KNOWLEDGE") preflight.insufficientKnowledge++;
+        preflight.blockingUnknownsFound += e.blockingUnknownsCount || 0;
+        preflight.staleKnowledgeFound += e.staleKnowledgeCount || 0;
+        preflight.pastFailuresSurfaced += e.pastFailuresCount || 0;
+        preflight.questionsSuggested += e.questionsCount || 0;
+        preflight.repeatedChecksAvoided += e.repeatedChecksAvoidedCount || 0;
+        break;
       case "knowledge_created":
         learning.new++;
         break;
@@ -4961,7 +5621,8 @@ async function computeStats(storage, events, options) {
       questionResolutionRate,
       jevRejectionRate
     },
-    health
+    health,
+    preflight: preflight.runs > 0 ? preflight : void 0
   };
 }
 async function computeKnowledgeStats(storage, knowledgeId, events) {
@@ -5030,9 +5691,9 @@ async function computeKnowledgeStats(storage, knowledgeId, events) {
 }
 
 // src/stats/filter.ts
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-var execFileAsync2 = promisify2(execFile2);
+import { execFile as execFile3 } from "child_process";
+import { promisify as promisify3 } from "util";
+var execFileAsync3 = promisify3(execFile3);
 async function resolveSinceTimestamp(since, projectDir = process.cwd()) {
   const trimmed = since.trim();
   const durationMatch = trimmed.match(/^(\d+)\s*([smhdw])$/i);
@@ -5064,7 +5725,7 @@ async function resolveSinceTimestamp(since, projectDir = process.cwd()) {
     return parsedDate;
   }
   try {
-    const { stdout } = await execFileAsync2(
+    const { stdout } = await execFileAsync3(
       "git",
       ["log", "-1", "--format=%ct", trimmed],
       { cwd: projectDir }
@@ -5108,17 +5769,56 @@ async function runStats(options = {}) {
 
 // src/mcp/server.ts
 function createBilmemMcpApp(options = {}) {
-  const rootDir = options.rootDir ? path8.resolve(options.rootDir) : process.cwd();
-  const storage = new Storage(rootDir);
-  const index = new SearchIndex();
-  let initialized = false;
-  async function ensureInitialized() {
-    if (!initialized) {
-      await storage.init();
-      const all = await storage.getAllKnowledge();
-      await index.buildIndex(all);
-      initialized = true;
+  const contexts = /* @__PURE__ */ new Map();
+  let lastActiveDir = options.rootDir ? path9.resolve(options.rootDir) : null;
+  function isSystemRoot(dir) {
+    const resolved = path9.resolve(dir);
+    return resolved === "/" || path9.parse(resolved).root === resolved;
+  }
+  function resolveTargetDir(requestedPath) {
+    if (requestedPath && requestedPath.trim()) {
+      const resolved = path9.resolve(requestedPath.trim());
+      lastActiveDir = resolved;
+      return resolved;
+    }
+    if (lastActiveDir) {
+      return lastActiveDir;
+    }
+    if (process.env.BILMEM_PROJECT_DIR) {
+      const envDir = path9.resolve(process.env.BILMEM_PROJECT_DIR);
+      lastActiveDir = envDir;
+      return envDir;
+    }
+    const cwd = process.cwd();
+    if (cwd && !isSystemRoot(cwd)) {
+      lastActiveDir = cwd;
+      return cwd;
+    }
+    throw new Error(
+      `No project directory specified and the MCP server was started in system root ('/'). Please provide the 'path' parameter in your tool call (e.g. { path: "/path/to/project", ... }).`
+    );
+  }
+  async function getProjectContext(requestedPath) {
+    const targetDir = resolveTargetDir(requestedPath);
+    let ctx = contexts.get(targetDir);
+    if (!ctx) {
+      const storage = new Storage(targetDir);
+      const index = new SearchIndex();
+      ctx = {
+        rootDir: targetDir,
+        storage,
+        index,
+        initialized: false
+      };
+      contexts.set(targetDir, ctx);
+    }
+    if (!ctx.initialized) {
+      await ctx.storage.init();
+      const all = await ctx.storage.getAllKnowledge();
+      await ctx.index.buildIndex(all);
+      ctx.initialized = true;
     }
+    return ctx;
   }
   const app = new McpApp({
     name: options.name ?? "bilmem",
@@ -5128,6 +5828,7 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_resolve",
     description: "Determine if enough is known to answer or act, what contextually does not apply, what is missing, and the cheapest next step to resolve uncertainty.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       question: z.string().describe("The question, goal, or uncertainty to resolve"),
       positive: z.array(z.string()).optional().describe("Applicable context cues (e.g. server-session, node, postgres)"),
       negative: z.array(z.string()).optional().describe("Inapplicable context cues (e.g. stateless-jwt, browser, sqlite)"),
@@ -5135,8 +5836,8 @@ function createBilmemMcpApp(options = {}) {
       maxDepth: z.number().optional().describe("Max candidates to inspect (default: 5)")
     },
     handler: async (args) => {
-      await ensureInitialized();
-      const retriever = new Retriever(index, storage);
+      const ctx = await getProjectContext(args.path);
+      const retriever = new Retriever(ctx.index, ctx.storage);
       const res = await resolveEpistemicQuery(
         {
           question: args.question,
@@ -5145,7 +5846,7 @@ function createBilmemMcpApp(options = {}) {
           scope: args.scope,
           maxDepth: args.maxDepth
         },
-        storage,
+        ctx.storage,
         retriever
       );
       return {
@@ -5162,10 +5863,53 @@ function createBilmemMcpApp(options = {}) {
       };
     }
   });
+  app.tool({
+    name: "bilmem_preflight",
+    description: "Determine what must be known before beginning a proposed goal (surfaces constraints, relevant lessons, past failures, stale knowledge, and blocking unknowns).",
+    inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
+      goal: z.string().describe("The proposed goal, feature, or work to analyze before implementation"),
+      positive: z.array(z.string()).optional().describe("Applicable context cues (e.g. authentication, postgres)"),
+      negative: z.array(z.string()).optional().describe("Inapplicable context cues (e.g. browser, sqlite)"),
+      deep: z.boolean().optional().describe("Check targeted git diff / unindexed files for staleness")
+    },
+    handler: async (args) => {
+      const ctx = await getProjectContext(args.path);
+      const retriever = new Retriever(ctx.index, ctx.storage);
+      const res = await executePreflight(
+        {
+          goal: args.goal,
+          positive: args.positive,
+          negative: args.negative,
+          deep: args.deep
+        },
+        ctx.storage,
+        retriever,
+        ctx.index
+      );
+      return {
+        goal: res.goal,
+        readiness: res.readiness,
+        known: res.known.slice(0, 5).map((k) => k.statement),
+        constraints: res.constraints.map((c) => c.statement),
+        lessons: res.lessons.slice(0, 5).map((l) => l.statement),
+        pastFailures: res.past_failures.slice(0, 5).map((f) => f.statement),
+        blockingUnknowns: res.unknowns.filter((u) => u.blocking).map((u) => u.question || u.statement || u.id),
+        stale: res.stale.map((s) => s.id),
+        questions: res.questions.slice(0, 5).map((q) => q.question),
+        next: res.next.slice(0, 3).map((n) => ({
+          type: n.type,
+          target: n.target,
+          reason: n.reason
+        }))
+      };
+    }
+  });
   app.tool({
     name: "bilmem_lookup",
     description: "Lookup reusable knowledge, conventions, and lessons using JEV contextual reranking. Returns compact, highly applicable knowledge units.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       query: z.string().optional().describe("Query text, intent keywords, or problem description"),
       positive: z.array(z.string()).optional().describe("Contextual positive cues (e.g. node, esm, server-session)"),
       negative: z.array(z.string()).optional().describe("Contextual negative cues (e.g. commonjs, browser)"),
@@ -5173,8 +5917,8 @@ function createBilmemMcpApp(options = {}) {
       limit: z.number().optional().describe("Maximum number of results to return (default 5)")
     },
     handler: async (args) => {
-      await ensureInitialized();
-      const retriever = new Retriever(index, storage);
+      const ctx = await getProjectContext(args.path);
+      const retriever = new Retriever(ctx.index, ctx.storage);
       const results = await retriever.lookup({
         query: args.query,
         positive: args.positive,
@@ -5201,6 +5945,7 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_observe",
     description: "Record a new observation from code, git, test execution, or environment. Preserves provenance.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       claim: z.string().describe("What was observed"),
       source: z.string().describe("Source identifier (e.g. file:src/auth.ts#L42, git:commit:81ac23, user:correction)"),
       confidence: z.number().optional().describe("Confidence 0.0 - 1.0 (default: 0.85)"),
@@ -5209,7 +5954,7 @@ function createBilmemMcpApp(options = {}) {
       details: z.record(z.any()).optional().describe("Optional structured metadata")
     },
     handler: async (args) => {
-      await ensureInitialized();
+      const ctx = await getProjectContext(args.path);
       const obs = createObservation({
         source: args.source,
         claim: args.claim,
@@ -5223,10 +5968,10 @@ function createBilmemMcpApp(options = {}) {
         negative: args.negative,
         details: args.details
       });
-      await storage.saveObservation(obs);
+      await ctx.storage.saveObservation(obs);
       const evidence = createEvidence(obs, "supports");
-      await storage.saveEvidence(evidence);
-      const existing = await storage.getAllKnowledge();
+      await ctx.storage.saveEvidence(evidence);
+      const existing = await ctx.storage.getAllKnowledge();
       const rec = reconcileKnowledge(
         {
           statement: obs.claim,
@@ -5247,10 +5992,10 @@ function createBilmemMcpApp(options = {}) {
           evidence: [evidence.id, obs.source]
         },
         existing,
-        storage
+        ctx.storage
       );
-      await storage.saveKnowledge(updatedKnowledge);
-      await index.upsert(updatedKnowledge);
+      await ctx.storage.saveKnowledge(updatedKnowledge);
+      await ctx.index.upsert(updatedKnowledge);
       return {
         observationId: obs.id,
         evidenceId: evidence.id,
@@ -5264,6 +6009,7 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_learn",
     description: "Learn from a completed task trajectory or explicit user correction. Converts experiences into refined, reusable lessons.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       goal: z.string().describe("The task or goal that was pursued"),
       taskId: z.string().optional().describe("Task identifier"),
       outcome: z.enum(["success", "failure", "reverted", "neutral"]).describe("Outcome of the task"),
@@ -5279,16 +6025,16 @@ function createBilmemMcpApp(options = {}) {
       }).optional().describe("Explicit user correction, if any occurred")
     },
     handler: async (args) => {
-      await ensureInitialized();
+      const ctx = await getProjectContext(args.path);
       if (args.userCorrection) {
         const { observation, knowledge } = processUserCorrection(args.userCorrection);
-        await storage.saveObservation(observation);
-        await storage.saveEvidence(createEvidence(observation, "supports"));
-        const existing = await storage.getAllKnowledge();
+        await ctx.storage.saveObservation(observation);
+        await ctx.storage.saveEvidence(createEvidence(observation, "supports"));
+        const existing = await ctx.storage.getAllKnowledge();
         const rec = reconcileKnowledge(knowledge, existing);
-        const { updatedKnowledge } = applyReconciliation(rec, knowledge, existing, storage);
-        await storage.saveKnowledge(updatedKnowledge);
-        await index.upsert(updatedKnowledge);
+        const { updatedKnowledge } = applyReconciliation(rec, knowledge, existing, ctx.storage);
+        await ctx.storage.saveKnowledge(updatedKnowledge);
+        await ctx.index.upsert(updatedKnowledge);
         return {
           type: "user_correction",
           knowledgeId: updatedKnowledge.id,
@@ -5304,20 +6050,20 @@ function createBilmemMcpApp(options = {}) {
           startedAt: (/* @__PURE__ */ new Date()).toISOString(),
           finalOutcome: args.outcome
         };
-        const existing = await storage.getAllKnowledge();
+        const existing = await ctx.storage.getAllKnowledge();
         const learningResult = learnFromTrajectory(trajectory, existing);
         for (const obs of learningResult.observations) {
-          await storage.saveObservation(obs);
+          await ctx.storage.saveObservation(obs);
         }
         for (const ev of learningResult.evidence) {
-          await storage.saveEvidence(ev);
+          await ctx.storage.saveEvidence(ev);
         }
         let updatedKnowledge;
         let action = "NEW";
         for (const item of learningResult.reconciliations) {
           if (item.appliedKnowledge) {
-            await storage.saveKnowledge(item.appliedKnowledge);
-            await index.upsert(item.appliedKnowledge);
+            await ctx.storage.saveKnowledge(item.appliedKnowledge);
+            await ctx.index.upsert(item.appliedKnowledge);
             updatedKnowledge = item.appliedKnowledge;
             action = item.action;
           }
@@ -5329,9 +6075,9 @@ function createBilmemMcpApp(options = {}) {
             result: args.outcome,
             context: { positive: updatedKnowledge.positive, negative: updatedKnowledge.negative }
           });
-          await storage.appendOutcome(out);
+          await ctx.storage.appendOutcome(out);
           applyOutcomeToKnowledge(updatedKnowledge, out);
-          await storage.saveKnowledge(updatedKnowledge);
+          await ctx.storage.saveKnowledge(updatedKnowledge);
           return {
             type: "trajectory_lesson",
             action,
@@ -5353,12 +6099,13 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_explain",
     description: "Explain why a knowledge ID exists: statement, evidence provenance, confidence, support/contradiction history, and applicable context.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       id: z.string().describe("The knowledge ID to explain"),
       history: z.boolean().optional().describe("Whether to format lifecycle transition history (--history)")
     },
     handler: async (args) => {
-      await ensureInitialized();
-      const k = await storage.getKnowledge(args.id);
+      const ctx = await getProjectContext(args.path);
+      const k = await ctx.storage.getKnowledge(args.id);
       if (!k) {
         return { error: `Knowledge not found: "${args.id}"` };
       }
@@ -5392,6 +6139,7 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_unknown",
     description: "Query or record first-class unknowns (NOT_OBSERVED, INSUFFICIENT_EVIDENCE, CONFLICTING_EVIDENCE, UNRESOLVABLE_LOCALLY) to prevent repeating useless investigations.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       action: z.enum(["query", "check", "record", "resolve"]).describe("Action to perform"),
       id: z.string().optional().describe("Unknown ID or query subject"),
       reason: z.enum(["NOT_OBSERVED", "INSUFFICIENT_EVIDENCE", "CONFLICTING_EVIDENCE", "STALE", "UNRESOLVABLE_LOCALLY"]).optional(),
@@ -5400,16 +6148,16 @@ function createBilmemMcpApp(options = {}) {
       question: z.string().optional().describe("Clarifying question for the user or next agent")
     },
     handler: async (args) => {
-      await ensureInitialized();
+      const ctx = await getProjectContext(args.path);
       if (args.action === "query") {
-        const list = await storage.getAllUnknowns();
+        const list = await ctx.storage.getAllUnknowns();
         return {
           count: list.length,
           unknowns: list
         };
       }
       if (args.action === "check") {
-        const list = await storage.getAllUnknowns();
+        const list = await ctx.storage.getAllUnknowns();
         const checkResult = hasBeenInvestigated(list, args.id || "");
         return checkResult;
       }
@@ -5423,12 +6171,12 @@ function createBilmemMcpApp(options = {}) {
           checked: args.checked ?? [],
           next: args.question ? { type: "ask", question: args.question } : void 0
         });
-        await storage.saveUnknown(record);
+        await ctx.storage.saveUnknown(record);
         return { success: true, recorded: record };
       }
       if (args.action === "resolve") {
         if (!args.id) throw new Error("ID is required to resolve an unknown");
-        const deleted = await storage.deleteUnknown(args.id);
+        const deleted = await ctx.storage.deleteUnknown(args.id);
         return { success: deleted, resolvedId: args.id };
       }
       return { error: "Unknown action" };
@@ -5438,16 +6186,16 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_scan",
     description: "Trigger a language-independent scan of the repository filesystem, markdown documentation, and git history.",
     inputSchema: {
-      path: z.string().optional().describe("Root directory to scan (defaults to project root)"),
+      path: z.string().optional().describe("Project root directory to scan (defaults to active workspace or current working directory)"),
       incremental: z.boolean().optional().describe("Whether to scan incrementally from last scanned git commit")
     },
     handler: async (args) => {
-      const targetDir = args.path ? path8.resolve(args.path) : rootDir;
-      const report = await scanRepository(targetDir, {
+      const ctx = await getProjectContext(args.path);
+      const report = await scanRepository(ctx.rootDir, {
         incremental: args.incremental ?? false
       });
-      const all = await storage.getAllKnowledge();
-      await index.buildIndex(all);
+      const all = await ctx.storage.getAllKnowledge();
+      await ctx.index.buildIndex(all);
       return report;
     }
   });
@@ -5455,13 +6203,14 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_stats",
     description: "Inspect local-first statistics, knowledge health, and effectiveness metrics (measuring reuse, investigation avoidance, and JEV accuracy). Read-only.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       since: z.string().optional().describe("Time window (e.g. 24h, 7d, 30d) or Git revision (e.g. HEAD~20, commit-sha)"),
       knowledgeId: z.string().optional().describe("Specific knowledge ID to inspect single-item lifecycle and diagnostics")
     },
     handler: async (args) => {
-      await ensureInitialized();
+      const ctx = await getProjectContext(args.path);
       const res = await runStats({
-        rootDir,
+        rootDir: ctx.rootDir,
         since: args.since,
         knowledgeId: args.knowledgeId
       });