@hadooppei/hwcode 1.0.13 → 1.0.16

package/.pi/dist/lib/knowledge/extractor.js

@@ -8,12 +8,14 @@ Persist only knowledge that is likely to be useful in future sessions:
 - reusable architecture, testing, debugging, deployment, or operational knowledge.
 Do not persist task summaries, guesses, temporary IDs, credentials, secrets, private data, or facts recoverable by simply reading the repository.
 Do not persist mutable inventory such as current cloud resources, names, availability, status, timestamps, or account snapshots. Preserve the discovery method or selection rule instead. If useful procedure is mixed with volatile facts, remove the volatile facts.
+Do not persist hypotheses, suspected causes, or statements marked as possible, pending validation, or unconfirmed. Omit them until direct evidence verifies them.
 Treat failed, unsupported, invalid, or corrected operations as negative evidence. Never present an operation as valid when the supplied evidence says it failed; use only a verified alternative or record an explicit warning. Never invent commands or parameters absent from successful evidence.
 Use storageHint "rule" only for one short imperative instruction of at most 240 characters. A rule must not contain incident narration, example resource names, IDs, timestamps, or evidence details. Use "topic" for multi-step SOPs and detailed experience.
 Relevant existing knowledge may be supplied. If a candidate has the same intent as an existing item, do not add a translated, renamed, or reformatted duplicate. Set targetId to that exact existing ID and action to "reinforce" when the existing content remains correct, or "revise" only when the delta explicitly proves a correction. Use targetId null only for genuinely new knowledge.
 Scope may be "global" only for an explicit user directive intended across projects; otherwise use "project".
 The prior validation context is only for checking facts and contradictions; do not persist it again unless the new delta independently reinforces it. Prefer accumulated workflow successfulSteps and failedApproaches over assistant narration.
 Each summary must be one complete sentence of at most 160 characters. Keep each topic body under 2200 characters. Escape line breaks and quotes inside JSON strings. Set durability to "stable" only after removing facts likely to change or be cheaply rediscovered. Return at most 3 candidates.
+The body must not repeat the title as a Markdown H1. The storage renderer supplies the H1. Replace any necessary example resource value with an obvious placeholder instead of a real project, namespace, image, network, or resource name.
 Return: {"candidates":[{"key":"stable semantic key","targetId":"existing-id or null","title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body","evidence":["verified evidence"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|revise","explicitUserDirective":false,"durability":"stable"}]}
 Return {"candidates":[]} when nothing meets the threshold.`;
 export function buildKnowledgeExtractionPrompt(projectRoot, delta, context = "", existing = []) {

package/.pi/dist/lib/knowledge/session-scanner.js

@@ -1,14 +1,17 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFileSync, readdirSync, statSync } from "node:fs";
-import { resolve, sep } from "node:path";
+import { resolve } from "node:path";
 import { buildContextEntries, parseSessionEntries, } from "@earendil-works/pi-coding-agent";
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.js";
-import { findLatestWorkflowRoot } from "../working-directory.js";
+import { canonicalizeDirectory } from "../working-directory.js";
 import { knowledgeDeltaDigest } from "./extractor.js";
 import { sanitizeKnowledgeText } from "./sanitize.js";
 import { projectKnowledgeKey } from "./store.js";
 const FAILURE_EVIDENCE_RE = /(?:\b(?:error|failed|failure|invalid|unsupported|mistyp(?:e|ed)|typo)\b|not supported|失败|错误|不支持|无效)/iu;
 const INJECTED_SKILL_RE = /<skill\b[^>]*>[\s\S]*?<\/skill>/giu;
+const SAFE_KNOWLEDGE_ID_RE = /^[a-z0-9][a-z0-9-]{0,79}$/u;
+const MAX_RECALL_QUERY_CHARS = 4_000;
+const MAX_LOADED_KNOWLEDGE_IDS = 8;
 function hash(value, length = 64) {
     return createHash("sha256").update(value).digest("hex").slice(0, length);
 }
@@ -98,27 +101,117 @@ function buildValidationContext(entries) {
     return selected.sort((left, right) => left.index - right.index).map((piece) => piece.text).join("\n\n")
         .slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxPriorContextChars);
 }
-function projectRootForSession(header, branch) {
-    const sessionRoot = resolve(header.cwd);
-    const workflowRootValue = findLatestWorkflowRoot(branch);
-    const workflowRoot = workflowRootValue ? resolve(workflowRootValue) : undefined;
-    let workingDirectory = sessionRoot;
-    for (const entry of branch.slice().reverse()) {
-        if (entry.type !== "custom" || entry.customType !== "hwcode-working-directory"
-            || !entry.data || typeof entry.data !== "object")
+function messageRecord(entry) {
+    return entry.type === "message" && entry.message && typeof entry.message === "object"
+        ? entry.message
+        : undefined;
+}
+function loadedKnowledgeIds(entries) {
+    const ids = [];
+    for (const entry of entries) {
+        const content = messageRecord(entry)?.content;
+        if (!Array.isArray(content))
             continue;
-        const cwd = entry.data.cwd;
-        if (typeof cwd !== "string" || !cwd)
+        for (const item of content) {
+            if (!item || typeof item !== "object")
+                continue;
+            const call = item;
+            if (call.type !== "toolCall" || call.name !== "hwcode_knowledge_lookup"
+                || !call.arguments || typeof call.arguments !== "object")
+                continue;
+            const id = call.arguments.id;
+            if (typeof id !== "string" || !SAFE_KNOWLEDGE_ID_RE.test(id))
+                continue;
+            const existing = ids.indexOf(id);
+            if (existing >= 0)
+                ids.splice(existing, 1);
+            ids.push(id);
+        }
+    }
+    return ids.slice(-MAX_LOADED_KNOWLEDGE_IDS);
+}
+function compactRecallValue(value, maxChars = 600) {
+    return typeof value === "string" ? sanitizeKnowledgeText(value).replace(/\s+/gu, " ").trim().slice(0, maxChars) : "";
+}
+function workflowRecallLines(entry) {
+    if (entry.type !== "custom" || !entry.customType.startsWith("hwcode-workflow")
+        || !entry.data || typeof entry.data !== "object")
+        return [];
+    const data = entry.data;
+    const details = data.details && typeof data.details === "object" ? data.details : undefined;
+    const lines = [];
+    const request = compactRecallValue(details?.request ?? data.request, 800);
+    if (request)
+        lines.push(`Task objective: ${request}`);
+    const addSteps = (label, value, maxItems) => {
+        if (!Array.isArray(value))
+            return;
+        for (const raw of value.slice(-maxItems)) {
+            if (typeof raw === "string") {
+                const text = compactRecallValue(raw);
+                if (text)
+                    lines.push(`${label}: ${text}`);
+                continue;
+            }
+            if (!raw || typeof raw !== "object")
+                continue;
+            const step = raw;
+            const parts = [step.approach, step.intent, step.reason].map((item) => compactRecallValue(item, 320)).filter(Boolean);
+            if (typeof step.command === "string")
+                parts.push(step.command);
+            if (Array.isArray(step.args)) {
+                const operation = step.args.slice(0, 2).filter((item) => typeof item === "string")
+                    .map((item) => compactRecallValue(item, 100)).filter(Boolean).join(" ");
+                if (operation)
+                    parts.push(operation);
+            }
+            const text = [...new Set(parts)].join("; ");
+            if (text)
+                lines.push(`${label}: ${text}`);
+        }
+    };
+    addSteps("Verified success", details?.successfulSteps ?? data.successfulSteps, 12);
+    addSteps("Verified failure", details?.failedApproaches ?? data.failedApproaches, 8);
+    return lines;
+}
+function buildRecallQuery(entries, ids) {
+    const lines = [];
+    const workflows = entries.map(workflowRecallLines).filter((item) => item.length > 0);
+    const workflowLines = workflows.at(-1) ?? [];
+    lines.push(...workflowLines.filter((line) => line.startsWith("Task objective:")));
+    for (const entry of entries.slice().reverse()) {
+        const message = messageRecord(entry);
+        if (!message || message.role !== "user")
             continue;
-        workingDirectory = resolve(cwd);
-        break;
+        const text = compactRecallValue(textContent(message.content).replace(INJECTED_SKILL_RE, ""), 800);
+        if (text)
+            lines.push(`User request: ${text}`);
+        if (lines.filter((line) => line.startsWith("User request:")).length >= 2)
+            break;
+    }
+    for (const entry of entries.slice().reverse()) {
+        const message = messageRecord(entry);
+        if (!message || message.role !== "assistant")
+            continue;
+        const text = compactRecallValue(textContent(message.content), 1_000);
+        if (text) {
+            lines.push(`Latest conclusion: ${text}`);
+            break;
+        }
     }
-    if (workflowRoot && (workingDirectory === workflowRoot || workingDirectory.startsWith(`${workflowRoot}${sep}`))) {
-        return workflowRoot;
+    for (const id of ids)
+        lines.push(`Loaded knowledge: ${id}`);
+    lines.push(...workflowLines.filter((line) => line.startsWith("Verified failure:")));
+    lines.push(...workflowLines.filter((line) => line.startsWith("Verified success:")));
+    return lines.join("\n").slice(0, MAX_RECALL_QUERY_CHARS);
+}
+function projectRootForSession(header) {
+    try {
+        return canonicalizeDirectory(header.cwd);
+    }
+    catch {
+        return resolve(header.cwd);
     }
-    if (workingDirectory === sessionRoot || workingDirectory.startsWith(`${sessionRoot}${sep}`))
-        return sessionRoot;
-    return workingDirectory;
 }
 export function discoverSessionFiles(root) {
     const files = [];
@@ -176,18 +269,21 @@ export function readReviewTask(sessionFile, cursor, now = Date.now()) {
     if (pending.length === 0)
         return undefined;
     const delta = buildDelta(pending);
+    const loadedIds = loadedKnowledgeIds(pending);
+    const recallQuery = buildRecallQuery(pending, loadedIds);
     const context = cursorIndex >= 0 ? buildValidationContext(branch.slice(0, cursorIndex + 1)) : "";
     const firstEntryId = pending[0].id;
     const lastEntryId = pending[pending.length - 1].id;
-    const deltaDigest = knowledgeDeltaDigest(delta || `${firstEntryId}\0${lastEntryId}`);
+    const deltaDigest = knowledgeDeltaDigest(`${delta || `${firstEntryId}\0${lastEntryId}`}\0${recallQuery}\0${loadedIds.join("\0")}`);
     const sessionFileHash = hash(resolve(sessionFile), 16);
     const sessionKey = hash(header.id, 24);
     const reviewKey = hash(`${header.id}\0${firstEntryId}\0${lastEntryId}\0${deltaDigest}`);
-    const projectRoot = projectRootForSession(header, branch);
+    const projectRoot = projectRootForSession(header);
     return {
         requestId: randomUUID(), reviewKey, sessionId: header.id, sessionKey, sessionFileHash,
         projectRoot, projectKey: projectKnowledgeKey(projectRoot),
-        firstEntryId, lastEntryId, context, delta, deltaDigest, fileSize: stat.size, fileMtimeMs: stat.mtimeMs,
+        firstEntryId, lastEntryId, context, delta, recallQuery, loadedKnowledgeIds: loadedIds,
+        deltaDigest, fileSize: stat.size, fileMtimeMs: stat.mtimeMs,
     };
 }
 export function findNextReviewTask(sessionsRoot, reviews, now = Date.now()) {

package/.pi/dist/lib/knowledge/store.js

@@ -9,6 +9,12 @@ const STORAGE = KNOWLEDGE_RUNTIME_DEFAULTS.storage;
 const SAFE_ID_RE = /^[a-z0-9][a-z0-9-]{0,79}$/u;
 const SAFE_GENERATION_RE = /^[0-9TZ-]+-[a-f0-9]{12}$/u;
 const PROJECT_SCOPE_RE = /^project:[a-f0-9]{16}$/u;
+const UNVERIFIED_CLAIM_RE = /(?:待验证|尚未(?:验证|确认)|未经(?:验证|确认)|未(?:经)?证实|推测|猜测|疑似|可能是|可能由于|可能导致|或许|unverified|unconfirmed|speculat(?:e|ive|ion)|hypothes(?:is|ize)|suspect(?:ed|ion)?|possibly|probably)/iu;
+const VOLATILE_ARGUMENT_RE = /--(?:namespace|name|server_name|security_group_id|subnet_id|vpc_id|image_id|project_id)(?:\.\d+)?=(?!<[^>]+>|\$?\{)[^\s`"']+/iu;
+const DISTINCTIVE_COMMON_TERMS = new Set([
+    "cloud", "huawei", "huaweicloud", "hcloud", "topic", "rule", "sop", "project", "region", "create",
+    "deploy", "deployment", "service", "workflow", "cn", "south",
+]);
 export class KnowledgeCommitBusyError extends Error {
 }
 function emptyCatalog() {
@@ -120,9 +126,14 @@ function semanticDuplicateScore(candidate, entry) {
         return 0;
     const titleScore = containment(comparisonTerms(candidate.title), comparisonTerms(entry.title));
     const keywordScore = containment(comparisonTerms(candidate.keywords.join(" ")), comparisonTerms(entry.keywords.join(" ")));
-    if (titleScore < 0.8 || keywordScore < 0.5)
+    if (titleScore >= 0.8 && keywordScore >= 0.5)
+        return titleScore * 0.7 + keywordScore * 0.3;
+    const candidateTerms = comparisonTerms(`${candidate.title} ${candidate.keywords.join(" ")}`);
+    const entryTerms = comparisonTerms(`${entry.title} ${entry.keywords.join(" ")}`);
+    const distinctiveShared = [...candidateTerms].filter((term) => (entryTerms.has(term) && term.length >= 3 && !DISTINCTIVE_COMMON_TERMS.has(term))).length;
+    if (keywordScore < 0.5 || distinctiveShared < 3)
         return 0;
-    return titleScore * 0.7 + keywordScore * 0.3;
+    return keywordScore * 0.7 + Math.min(distinctiveShared / 6, 1) * 0.3;
 }
 function semanticDuplicateIndex(candidate, catalog) {
     let bestIndex = -1;
@@ -167,7 +178,19 @@ function asStringArray(value, maxItems) {
     return [...new Set(value.filter((item) => typeof item === "string")
             .map((item) => compactKnowledgeText(item, 240)).filter(Boolean))].slice(0, maxItems);
 }
-function normalizeCandidate(value, projectKey, validationText) {
+function withoutLeadingTitle(body) {
+    return body.replace(/^#\s+[^\n]*(?:\n+|$)/u, "").trim();
+}
+function containsVolatileDetail(body, projectRoot) {
+    const projectName = basename(resolve(projectRoot));
+    const escapedProjectName = projectName.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const namedProject = projectName.length >= 5
+        && new RegExp(`(?:项目|project)\\s*(?:[:：=]|is)?\\s*[\`'\"]?${escapedProjectName}(?![\\p{L}\\p{N}-])`, "iu").test(body);
+    return VOLATILE_ARGUMENT_RE.test(body)
+        || namedProject
+        || /\.hwcode\/cloud\/runs\//iu.test(body);
+}
+function normalizeCandidate(value, projectKey, projectRoot, validationText) {
     if (!value || typeof value !== "object")
         return { reason: "invalid-schema" };
     const raw = value;
@@ -183,10 +206,15 @@ function normalizeCandidate(value, projectKey, validationText) {
         return { reason: "unknown-target" };
     const explicitUserDirective = raw.explicitUserDirective === true;
     const scope = raw.scope === "global" && explicitUserDirective ? "global" : `project:${projectKey}`;
-    const body = compactKnowledgeText(raw.body, 20_000);
+    const body = withoutLeadingTitle(compactKnowledgeText(raw.body, 20_000));
     const evidence = asStringArray(raw.evidence, 8);
     if (!body || evidence.length === 0)
         return { reason: "missing-body-or-evidence" };
+    const candidateClaims = `${raw.title}\n${raw.summary}\n${body}`;
+    if (!explicitUserDirective && UNVERIFIED_CLAIM_RE.test(candidateClaims))
+        return { reason: "unverified-claim" };
+    if (containsVolatileDetail(body, projectRoot))
+        return { reason: "volatile-detail" };
     if (contradictsVerifiedFailures(body, validationText))
         return { reason: "contradicts-verified-failure" };
     const requestedTrack = raw.storageHint === "rule" ? "rule" : "topic";
@@ -352,7 +380,7 @@ export function commitKnowledgeReview(values, task, leaderToken, home = homedir(
         const result = { saved: 0, updated: 0, pending: 0, skipped: 0 };
         const rejected = [];
         for (const value of values.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates)) {
-            const normalized = normalizeCandidate(value, task.projectKey, `${task.context ?? ""}\n${task.delta}`);
+            const normalized = normalizeCandidate(value, task.projectKey, task.projectRoot, `${task.context ?? ""}\n${task.delta}`);
             if (!("candidate" in normalized)) {
                 recordSkip(result, normalized.reason);
                 rejected.push({ reason: normalized.reason, value });

package/.pi/dist/lib/working-directory.js

@@ -39,6 +39,10 @@ export function getWorkingDirectoryState(source) {
 export function getWorkingDirectory(source) {
     return getWorkingDirectoryState(source).cwd;
 }
+/** The immutable project root captured when the session was created. */
+export function getSessionProjectRoot(source) {
+    return canonicalizeDirectory(source.getCwd());
+}
 export function setWorkingDirectoryState(source, state) {
     workingDirectories.set(source.getSessionId(), state);
 }

package/.pi/extensions/knowledge.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
+import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Worker } from "node:worker_threads";
 
@@ -10,16 +10,17 @@ import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-
 import {
   buildKnowledgeExtractionPrompt, type ExistingKnowledgeContext, KNOWLEDGE_EXTRACTION_SYSTEM_PROMPT,
 } from "../lib/knowledge/extractor.ts";
-import { matchKnowledge } from "../lib/knowledge/matcher.ts";
+import { matchKnowledge, recallKnowledge } from "../lib/knowledge/matcher.ts";
 import { loadKnowledgeById, loadKnowledgeSnapshot, projectKnowledgeKey } from "../lib/knowledge/store.ts";
 import type { KnowledgeWorkerInput, KnowledgeWorkerOutput } from "../lib/knowledge/worker-protocol.ts";
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../lib/runtime/defaults.ts";
-import { findLatestWorkflowRoot, getWorkingDirectory } from "../lib/working-directory.ts";
+import { getSessionProjectRoot } from "../lib/working-directory.ts";
 
 interface ActiveReview {
   requestId: string;
   leaderToken: string;
   controller: AbortController;
+  abortReason?: string;
 }
 
 interface ProcessKnowledgeRuntime {
@@ -58,8 +59,17 @@ function updateCapability(): void {
   post({ type: "configure", modelAvailable: available, sessionsRoot: runtime.sessionsRoot });
 }
 
-function cancelActiveReview(): void {
-  runtime.activeReview?.controller.abort();
+function cancelActiveReview(reason: string): void {
+  const review = runtime.activeReview;
+  if (!review || review.controller.signal.aborted) return;
+  review.abortReason = reason;
+  review.controller.abort();
+}
+
+export function isExpectedReviewInterruption(reason: string): boolean {
+  return reason === "foreground-model-became-busy"
+    || reason === "session-shutdown"
+    || reason === "knowledge-worker-restarting";
 }
 
 function reportWorkerIssue(error: unknown): void {
@@ -95,6 +105,7 @@ function workerEntryUrl(): URL {
 
 async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review_request" }>): Promise<void> {
   let timeout: NodeJS.Timeout | undefined;
+  let review: ActiveReview | undefined;
   try {
     const ctx = runtime.context;
     if (!ctx?.model || !ctx.modelRegistry.hasConfiguredAuth(ctx.model)) throw new Error("no-configured-model");
@@ -108,8 +119,13 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
       return;
     }
     const controller = new AbortController();
-    runtime.activeReview = { requestId: message.requestId, leaderToken: message.leaderToken, controller };
-    timeout = setTimeout(() => controller.abort(), KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs);
+    review = { requestId: message.requestId, leaderToken: message.leaderToken, controller };
+    runtime.activeReview = review;
+    timeout = setTimeout(() => {
+      if (controller.signal.aborted) return;
+      review!.abortReason = "knowledge-review-model-timeout";
+      controller.abort();
+    }, KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs);
     timeout.unref();
     const snapshot = loadKnowledgeSnapshot(message.task.projectKey);
     const applicableCatalog = {
@@ -118,9 +134,10 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
         entry.scope === "global" || entry.scope === `project:${message.task.projectKey}`
       )),
     };
-    const related: ExistingKnowledgeContext[] = matchKnowledge(
-      message.task.delta,
+    const related: ExistingKnowledgeContext[] = recallKnowledge(
+      message.task.recallQuery || message.task.delta,
       applicableCatalog,
+      message.task.loadedKnowledgeIds ?? [],
       KNOWLEDGE_RUNTIME_DEFAULTS.review.maxExistingContextItems,
     ).map((entry, index) => {
       const reference: ExistingKnowledgeContext = {
@@ -155,13 +172,15 @@ async function runReview(message: Extract<KnowledgeWorkerOutput, { type: "review
       },
       { signal: controller.signal, reasoningEffort: "low", cacheRetention: "none", sessionId: randomUUID() },
     );
-    if (controller.signal.aborted) throw new Error("knowledge-review-aborted-or-timed-out");
+    if (controller.signal.aborted) throw new Error(review.abortReason ?? "knowledge-review-interrupted");
     const raw = response.content.filter((item): item is { type: "text"; text: string } => item.type === "text")
       .map((item) => item.text).join("\n");
     post({ type: "review_result", leaderToken: message.leaderToken, requestId: message.requestId, raw });
   } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    if (reason === "model-executor-is-busy") {
+    const reason = review?.controller.signal.aborted
+      ? review.abortReason ?? "knowledge-review-interrupted"
+      : error instanceof Error ? error.message : String(error);
+    if (reason === "model-executor-is-busy" || isExpectedReviewInterruption(reason)) {
       post({ type: "review_deferred", leaderToken: message.leaderToken, requestId: message.requestId, reason });
     } else {
       post({ type: "review_result", leaderToken: message.leaderToken, requestId: message.requestId, error: reason });
@@ -181,7 +200,7 @@ function handleWorkerMessage(message: KnowledgeWorkerOutput): void {
   }
   if (message.type === "review_request") { void runReview(message); return; }
   if (message.type === "review_cancel" && runtime.activeReview?.requestId === message.requestId) {
-    runtime.activeReview.controller.abort();
+    cancelActiveReview(message.reason);
     return;
   }
   if (message.type === "review_failed") reportWorkerIssue(message.error);
@@ -196,7 +215,7 @@ function ensureWorker(): Worker | undefined {
   worker.on("message", (message: KnowledgeWorkerOutput) => handleWorkerMessage(message));
   worker.on("error", (error) => {
     reportWorkerIssue(error);
-    cancelActiveReview();
+    cancelActiveReview("knowledge-worker-restarting");
     if (runtime.worker === worker) {
       runtime.worker = undefined;
       runtime.modelAvailable = undefined;
@@ -226,13 +245,7 @@ function configureForContext(ctx: ExtensionContext): void {
 }
 
 function currentProject(ctx: ExtensionContext): { root: string; key: string } {
-  const workingDirectory = resolve(getWorkingDirectory(ctx.sessionManager));
-  const workflowRootValue = findLatestWorkflowRoot(ctx.sessionManager.getEntries());
-  const workflowRoot = workflowRootValue ? resolve(workflowRootValue) : undefined;
-  const root = workflowRoot
-    && (workingDirectory === workflowRoot || workingDirectory.startsWith(`${workflowRoot}${sep}`))
-    ? workflowRoot
-    : workingDirectory;
+  const root = getSessionProjectRoot(ctx.sessionManager);
   return { root, key: projectKnowledgeKey(root) };
 }
 
@@ -292,14 +305,14 @@ export default function registerKnowledgeExtension(pi: ExtensionAPI): void {
 
   pi.on("input", (_event, ctx) => {
     runtime.context = ctx;
-    cancelActiveReview();
+    cancelActiveReview("foreground-model-became-busy");
     updateCapability();
     return undefined;
   });
 
   pi.on("agent_start", (_event, ctx) => {
     runtime.context = ctx;
-    cancelActiveReview();
+    cancelActiveReview("foreground-model-became-busy");
   });
 
   pi.on("agent_settled", (_event, ctx) => {
@@ -309,7 +322,7 @@ export default function registerKnowledgeExtension(pi: ExtensionAPI): void {
   });
 
   pi.on("session_shutdown", (event) => {
-    cancelActiveReview();
+    cancelActiveReview("session-shutdown");
     if (event.reason === "quit") {
       runtime.context = undefined;
       updateCapability();

package/.pi/extensions/workflows/cloud/activation.ts

@@ -9,7 +9,7 @@ import { modelConfigurationIssue } from "../../../lib/models/readiness.ts";
 import { CLOUD_RUNTIME_DEFAULTS } from "../../../lib/runtime/defaults.ts";
 import { remoteRunnerPaths, userRuntimePaths } from "../../../lib/runtime/paths.ts";
 import { canonicalizeWorkspaceRoot } from "../../../lib/workflow-guard.ts";
-import { getWorkingDirectory } from "../../../lib/working-directory.ts";
+import { getSessionProjectRoot } from "../../../lib/working-directory.ts";
 import { checkProviderCli, formatValidationFailure, validateCloudCredentials } from "../../../lib/workflows/cloud/adapters.ts";
 import { cloudTerraformTemplateSource, listCloudTerraformTemplates, materializeCloudTerraformTemplate, type CloudTerraformTemplate } from "../../../lib/workflows/cloud/bundles.ts";
 import { CLOUD_PROVIDERS, getCloudProvider, inaccessibleCloudCliMessage, missingCloudCliMessage, type CloudCredentials, type CloudVendorId } from "../../../lib/workflows/cloud/providers.ts";
@@ -126,7 +126,7 @@ export async function activateCloudWorkflow(runtime: CloudExtensionRuntime, args
   if (!ctx.isIdle()) { notify(ctx, "请等待当前响应完成后再启动 HWCode Cloud。", "warning"); return; }
   if (!(await ensureConversationModel(ctx))) return;
 
-  const root = canonicalizeWorkspaceRoot(getWorkingDirectory(ctx.sessionManager));
+  const root = canonicalizeWorkspaceRoot(getSessionProjectRoot(ctx.sessionManager));
   const currentWorkflow = activeWorkflow(ctx.sessionManager.getEntries());
   if (currentWorkflow && currentWorkflow.mode !== "cloud") {
     notify(ctx, `当前会话已有 ${currentWorkflow.mode} workflow。请新建 session 后再启动 HWCode Cloud。`, "warning");

package/.pi/extensions/workflows/sdd.ts

@@ -10,7 +10,7 @@ import { notify } from "../../lib/extension-ui.ts";
 import {
 	canonicalizeWorkspaceRoot,
 } from "../../lib/workflow-guard.ts";
-import { getWorkingDirectory } from "../../lib/working-directory.ts";
+import { getSessionProjectRoot } from "../../lib/working-directory.ts";
 import {
 	WORKFLOW_STATE_TYPE,
 	activeWorkflow,
@@ -94,7 +94,7 @@ export function registerSddWorkflow(pi: ExtensionAPI) {
 				return;
 			}
 
-			const root = canonicalizeWorkspaceRoot(getWorkingDirectory(ctx.sessionManager));
+			const root = canonicalizeWorkspaceRoot(getSessionProjectRoot(ctx.sessionManager));
 			const existing = activeWorkflow(ctx.sessionManager.getEntries());
 			if (existing) {
 				notify(

package/.pi/extensions/workflows/vibe.ts

@@ -6,7 +6,7 @@ import { notify } from "../../lib/extension-ui.ts";
 import {
 	canonicalizeWorkspaceRoot,
 } from "../../lib/workflow-guard.ts";
-import { getWorkingDirectory } from "../../lib/working-directory.ts";
+import { getSessionProjectRoot } from "../../lib/working-directory.ts";
 import {
 	WORKFLOW_STATE_TYPE,
 	activeWorkflow,
@@ -24,7 +24,7 @@ export function registerVibeWorkflow(pi: ExtensionAPI) {
 				return;
 			}
 
-			const root = canonicalizeWorkspaceRoot(getWorkingDirectory(ctx.sessionManager));
+			const root = canonicalizeWorkspaceRoot(getSessionProjectRoot(ctx.sessionManager));
 			const existing = activeWorkflow(ctx.sessionManager.getEntries());
 			if (existing) {
 				notify(

package/.pi/extensions/workflows/workspace-guard.ts

@@ -7,7 +7,7 @@ import { notify } from "../../lib/extension-ui.ts";
 import {
 	canonicalizeWorkspaceRoot,
 } from "../../lib/workflow-guard.ts";
-import { getWorkingDirectory } from "../../lib/working-directory.ts";
+import { getSessionProjectRoot } from "../../lib/working-directory.ts";
 import {
 	WORKFLOW_EXTERNAL_AUDIT_TYPE,
 	WORKFLOW_STATE_TYPE,
@@ -47,13 +47,13 @@ export function registerWorkspaceGuard(pi: ExtensionAPI) {
 			return;
 		}
 
-		const currentRoot = canonicalizeWorkspaceRoot(getWorkingDirectory(ctx.sessionManager));
+		const currentRoot = canonicalizeWorkspaceRoot(getSessionProjectRoot(ctx.sessionManager));
 		if (currentRoot !== restored.root) {
 			activeState = undefined;
 			pi.appendEntry<WorkflowState>(WORKFLOW_STATE_TYPE, updateWorkflowState(restored, {
 				status: "cancelled",
 				phase: "root-changed",
-				reason: "Stored workflow root no longer matches the current execution directory.",
+				reason: "Stored workflow root no longer matches the immutable session project root.",
 			}));
 			notify(ctx, "Stored HWCode workflow disabled because the current directory changed.", "warning");
 			return;

package/.pi/lib/knowledge/extractor.ts

@@ -19,12 +19,14 @@ Persist only knowledge that is likely to be useful in future sessions:
 - reusable architecture, testing, debugging, deployment, or operational knowledge.
 Do not persist task summaries, guesses, temporary IDs, credentials, secrets, private data, or facts recoverable by simply reading the repository.
 Do not persist mutable inventory such as current cloud resources, names, availability, status, timestamps, or account snapshots. Preserve the discovery method or selection rule instead. If useful procedure is mixed with volatile facts, remove the volatile facts.
+Do not persist hypotheses, suspected causes, or statements marked as possible, pending validation, or unconfirmed. Omit them until direct evidence verifies them.
 Treat failed, unsupported, invalid, or corrected operations as negative evidence. Never present an operation as valid when the supplied evidence says it failed; use only a verified alternative or record an explicit warning. Never invent commands or parameters absent from successful evidence.
 Use storageHint "rule" only for one short imperative instruction of at most 240 characters. A rule must not contain incident narration, example resource names, IDs, timestamps, or evidence details. Use "topic" for multi-step SOPs and detailed experience.
 Relevant existing knowledge may be supplied. If a candidate has the same intent as an existing item, do not add a translated, renamed, or reformatted duplicate. Set targetId to that exact existing ID and action to "reinforce" when the existing content remains correct, or "revise" only when the delta explicitly proves a correction. Use targetId null only for genuinely new knowledge.
 Scope may be "global" only for an explicit user directive intended across projects; otherwise use "project".
 The prior validation context is only for checking facts and contradictions; do not persist it again unless the new delta independently reinforces it. Prefer accumulated workflow successfulSteps and failedApproaches over assistant narration.
 Each summary must be one complete sentence of at most 160 characters. Keep each topic body under 2200 characters. Escape line breaks and quotes inside JSON strings. Set durability to "stable" only after removing facts likely to change or be cheaply rediscovered. Return at most 3 candidates.
+The body must not repeat the title as a Markdown H1. The storage renderer supplies the H1. Replace any necessary example resource value with an obvious placeholder instead of a real project, namespace, image, network, or resource name.
 Return: {"candidates":[{"key":"stable semantic key","targetId":"existing-id or null","title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body","evidence":["verified evidence"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|revise","explicitUserDirective":false,"durability":"stable"}]}
 Return {"candidates":[]} when nothing meets the threshold.`;
 

package/.pi/lib/knowledge/matcher.ts

@@ -80,7 +80,7 @@ function phraseScore(query: string, title: SearchField, summary: SearchField, ke
 export function matchKnowledge(
   query: string,
   catalog: KnowledgeCatalog,
-  limit = KNOWLEDGE_RUNTIME_DEFAULTS.storage.maxLookupResults,
+  limit: number = KNOWLEDGE_RUNTIME_DEFAULTS.storage.maxLookupResults,
 ): KnowledgeCatalogEntry[] {
   const normalizedQuery = normalizeSearchText(query);
   const compactQuery = normalizedQuery.replace(/\s+/gu, "");
@@ -120,3 +120,38 @@ export function matchKnowledge(
     .slice(0, limit)
     .map(({ item }) => item);
 }
+
+/** Keeps explicitly loaded knowledge in review context, then fills the remainder with cheap lexical recall. */
+export function recallKnowledge(
+  query: string,
+  catalog: KnowledgeCatalog,
+  preferredIds: string[],
+  limit: number = KNOWLEDGE_RUNTIME_DEFAULTS.storage.maxLookupResults,
+): KnowledgeCatalogEntry[] {
+  if (limit <= 0) return [];
+  const recalled: KnowledgeCatalogEntry[] = [];
+  const seen = new Set<string>();
+  const lexicalMatches = matchKnowledge(query, catalog, catalog.items.length);
+  const lexicalRank = new Map(lexicalMatches.map((entry, index) => [entry.id, index]));
+  const preferred = preferredIds.map((id, index) => ({
+    entry: catalog.items.find((item) => item.id === id), index,
+  })).filter((item): item is { entry: KnowledgeCatalogEntry; index: number } => Boolean(item.entry))
+    .sort((left, right) => (
+      (lexicalRank.get(left.entry.id) ?? Number.MAX_SAFE_INTEGER)
+      - (lexicalRank.get(right.entry.id) ?? Number.MAX_SAFE_INTEGER)
+      || left.index - right.index
+    ));
+  for (const { entry } of preferred) {
+    if (seen.has(entry.id)) continue;
+    recalled.push(entry);
+    seen.add(entry.id);
+    if (recalled.length >= limit) return recalled;
+  }
+  for (const entry of lexicalMatches) {
+    if (seen.has(entry.id)) continue;
+    recalled.push(entry);
+    seen.add(entry.id);
+    if (recalled.length >= limit) break;
+  }
+  return recalled;
+}

package/.pi/lib/knowledge/session-scanner.ts

@@ -1,13 +1,13 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFileSync, readdirSync, statSync } from "node:fs";
-import { resolve, sep } from "node:path";
+import { resolve } from "node:path";
 
 import {
   buildContextEntries, parseSessionEntries, type SessionEntry, type SessionHeader,
 } from "@earendil-works/pi-coding-agent";
 
 import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
-import { findLatestWorkflowRoot } from "../working-directory.ts";
+import { canonicalizeDirectory } from "../working-directory.ts";
 import { knowledgeDeltaDigest } from "./extractor.ts";
 import { sanitizeKnowledgeText } from "./sanitize.ts";
 import { projectKnowledgeKey } from "./store.ts";
@@ -22,6 +22,9 @@ interface ReviewPiece {
 
 const FAILURE_EVIDENCE_RE = /(?:\b(?:error|failed|failure|invalid|unsupported|mistyp(?:e|ed)|typo)\b|not supported|失败|错误|不支持|无效)/iu;
 const INJECTED_SKILL_RE = /<skill\b[^>]*>[\s\S]*?<\/skill>/giu;
+const SAFE_KNOWLEDGE_ID_RE = /^[a-z0-9][a-z0-9-]{0,79}$/u;
+const MAX_RECALL_QUERY_CHARS = 4_000;
+const MAX_LOADED_KNOWLEDGE_IDS = 8;
 
 function hash(value: string, length = 64): string {
   return createHash("sha256").update(value).digest("hex").slice(0, length);
@@ -105,24 +108,98 @@ function buildValidationContext(entries: SessionEntry[]): string {
     .slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxPriorContextChars);
 }
 
-function projectRootForSession(header: SessionHeader, branch: SessionEntry[]): string {
-  const sessionRoot = resolve(header.cwd);
-  const workflowRootValue = findLatestWorkflowRoot(branch);
-  const workflowRoot = workflowRootValue ? resolve(workflowRootValue) : undefined;
-  let workingDirectory = sessionRoot;
-  for (const entry of branch.slice().reverse()) {
-    if (entry.type !== "custom" || entry.customType !== "hwcode-working-directory"
-      || !entry.data || typeof entry.data !== "object") continue;
-    const cwd = (entry.data as Record<string, unknown>).cwd;
-    if (typeof cwd !== "string" || !cwd) continue;
-    workingDirectory = resolve(cwd);
-    break;
+function messageRecord(entry: SessionEntry): Record<string, unknown> | undefined {
+  return entry.type === "message" && entry.message && typeof entry.message === "object"
+    ? entry.message as unknown as Record<string, unknown>
+    : undefined;
+}
+
+function loadedKnowledgeIds(entries: SessionEntry[]): string[] {
+  const ids: string[] = [];
+  for (const entry of entries) {
+    const content = messageRecord(entry)?.content;
+    if (!Array.isArray(content)) continue;
+    for (const item of content) {
+      if (!item || typeof item !== "object") continue;
+      const call = item as Record<string, unknown>;
+      if (call.type !== "toolCall" || call.name !== "hwcode_knowledge_lookup"
+        || !call.arguments || typeof call.arguments !== "object") continue;
+      const id = (call.arguments as Record<string, unknown>).id;
+      if (typeof id !== "string" || !SAFE_KNOWLEDGE_ID_RE.test(id)) continue;
+      const existing = ids.indexOf(id);
+      if (existing >= 0) ids.splice(existing, 1);
+      ids.push(id);
+    }
+  }
+  return ids.slice(-MAX_LOADED_KNOWLEDGE_IDS);
+}
+
+function compactRecallValue(value: unknown, maxChars = 600): string {
+  return typeof value === "string" ? sanitizeKnowledgeText(value).replace(/\s+/gu, " ").trim().slice(0, maxChars) : "";
+}
+
+function workflowRecallLines(entry: SessionEntry): string[] {
+  if (entry.type !== "custom" || !entry.customType.startsWith("hwcode-workflow")
+    || !entry.data || typeof entry.data !== "object") return [];
+  const data = entry.data as Record<string, unknown>;
+  const details = data.details && typeof data.details === "object" ? data.details as Record<string, unknown> : undefined;
+  const lines: string[] = [];
+  const request = compactRecallValue(details?.request ?? data.request, 800);
+  if (request) lines.push(`Task objective: ${request}`);
+
+  const addSteps = (label: string, value: unknown, maxItems: number): void => {
+    if (!Array.isArray(value)) return;
+    for (const raw of value.slice(-maxItems)) {
+      if (typeof raw === "string") {
+        const text = compactRecallValue(raw);
+        if (text) lines.push(`${label}: ${text}`);
+        continue;
+      }
+      if (!raw || typeof raw !== "object") continue;
+      const step = raw as Record<string, unknown>;
+      const parts = [step.approach, step.intent, step.reason].map((item) => compactRecallValue(item, 320)).filter(Boolean);
+      if (typeof step.command === "string") parts.push(step.command);
+      if (Array.isArray(step.args)) {
+        const operation = step.args.slice(0, 2).filter((item): item is string => typeof item === "string")
+          .map((item) => compactRecallValue(item, 100)).filter(Boolean).join(" ");
+        if (operation) parts.push(operation);
+      }
+      const text = [...new Set(parts)].join("; ");
+      if (text) lines.push(`${label}: ${text}`);
+    }
+  };
+  addSteps("Verified success", details?.successfulSteps ?? data.successfulSteps, 12);
+  addSteps("Verified failure", details?.failedApproaches ?? data.failedApproaches, 8);
+  return lines;
+}
+
+function buildRecallQuery(entries: SessionEntry[], ids: string[]): string {
+  const lines: string[] = [];
+  const workflows = entries.map(workflowRecallLines).filter((item) => item.length > 0);
+  const workflowLines = workflows.at(-1) ?? [];
+  lines.push(...workflowLines.filter((line) => line.startsWith("Task objective:")));
+
+  for (const entry of entries.slice().reverse()) {
+    const message = messageRecord(entry);
+    if (!message || message.role !== "user") continue;
+    const text = compactRecallValue(textContent(message.content).replace(INJECTED_SKILL_RE, ""), 800);
+    if (text) lines.push(`User request: ${text}`);
+    if (lines.filter((line) => line.startsWith("User request:")).length >= 2) break;
   }
-  if (workflowRoot && (workingDirectory === workflowRoot || workingDirectory.startsWith(`${workflowRoot}${sep}`))) {
-    return workflowRoot;
+  for (const entry of entries.slice().reverse()) {
+    const message = messageRecord(entry);
+    if (!message || message.role !== "assistant") continue;
+    const text = compactRecallValue(textContent(message.content), 1_000);
+    if (text) { lines.push(`Latest conclusion: ${text}`); break; }
   }
-  if (workingDirectory === sessionRoot || workingDirectory.startsWith(`${sessionRoot}${sep}`)) return sessionRoot;
-  return workingDirectory;
+  for (const id of ids) lines.push(`Loaded knowledge: ${id}`);
+  lines.push(...workflowLines.filter((line) => line.startsWith("Verified failure:")));
+  lines.push(...workflowLines.filter((line) => line.startsWith("Verified success:")));
+  return lines.join("\n").slice(0, MAX_RECALL_QUERY_CHARS);
+}
+
+function projectRootForSession(header: SessionHeader): string {
+  try { return canonicalizeDirectory(header.cwd); } catch { return resolve(header.cwd); }
 }
 
 export function discoverSessionFiles(root: string): string[] {
@@ -164,18 +241,21 @@ export function readReviewTask(
   const pending = branch.slice(cursorIndex + 1);
   if (pending.length === 0) return undefined;
   const delta = buildDelta(pending);
+  const loadedIds = loadedKnowledgeIds(pending);
+  const recallQuery = buildRecallQuery(pending, loadedIds);
   const context = cursorIndex >= 0 ? buildValidationContext(branch.slice(0, cursorIndex + 1)) : "";
   const firstEntryId = pending[0].id;
   const lastEntryId = pending[pending.length - 1].id;
-  const deltaDigest = knowledgeDeltaDigest(delta || `${firstEntryId}\0${lastEntryId}`);
+  const deltaDigest = knowledgeDeltaDigest(`${delta || `${firstEntryId}\0${lastEntryId}`}\0${recallQuery}\0${loadedIds.join("\0")}`);
   const sessionFileHash = hash(resolve(sessionFile), 16);
   const sessionKey = hash(header.id, 24);
   const reviewKey = hash(`${header.id}\0${firstEntryId}\0${lastEntryId}\0${deltaDigest}`);
-  const projectRoot = projectRootForSession(header, branch);
+  const projectRoot = projectRootForSession(header);
   return {
     requestId: randomUUID(), reviewKey, sessionId: header.id, sessionKey, sessionFileHash,
     projectRoot, projectKey: projectKnowledgeKey(projectRoot),
-    firstEntryId, lastEntryId, context, delta, deltaDigest, fileSize: stat.size, fileMtimeMs: stat.mtimeMs,
+    firstEntryId, lastEntryId, context, delta, recallQuery, loadedKnowledgeIds: loadedIds,
+    deltaDigest, fileSize: stat.size, fileMtimeMs: stat.mtimeMs,
   };
 }
 

package/.pi/lib/knowledge/store.ts

@@ -19,6 +19,12 @@ const STORAGE = KNOWLEDGE_RUNTIME_DEFAULTS.storage;
 const SAFE_ID_RE = /^[a-z0-9][a-z0-9-]{0,79}$/u;
 const SAFE_GENERATION_RE = /^[0-9TZ-]+-[a-f0-9]{12}$/u;
 const PROJECT_SCOPE_RE = /^project:[a-f0-9]{16}$/u;
+const UNVERIFIED_CLAIM_RE = /(?:待验证|尚未(?:验证|确认)|未经(?:验证|确认)|未(?:经)?证实|推测|猜测|疑似|可能是|可能由于|可能导致|或许|unverified|unconfirmed|speculat(?:e|ive|ion)|hypothes(?:is|ize)|suspect(?:ed|ion)?|possibly|probably)/iu;
+const VOLATILE_ARGUMENT_RE = /--(?:namespace|name|server_name|security_group_id|subnet_id|vpc_id|image_id|project_id)(?:\.\d+)?=(?!<[^>]+>|\$?\{)[^\s`"']+/iu;
+const DISTINCTIVE_COMMON_TERMS = new Set([
+  "cloud", "huawei", "huaweicloud", "hcloud", "topic", "rule", "sop", "project", "region", "create",
+  "deploy", "deployment", "service", "workflow", "cn", "south",
+]);
 
 export class KnowledgeCommitBusyError extends Error {}
 
@@ -138,8 +144,14 @@ function semanticDuplicateScore(candidate: KnowledgeCandidate, entry: KnowledgeC
     comparisonTerms(candidate.keywords.join(" ")),
     comparisonTerms(entry.keywords.join(" ")),
   );
-  if (titleScore < 0.8 || keywordScore < 0.5) return 0;
-  return titleScore * 0.7 + keywordScore * 0.3;
+  if (titleScore >= 0.8 && keywordScore >= 0.5) return titleScore * 0.7 + keywordScore * 0.3;
+  const candidateTerms = comparisonTerms(`${candidate.title} ${candidate.keywords.join(" ")}`);
+  const entryTerms = comparisonTerms(`${entry.title} ${entry.keywords.join(" ")}`);
+  const distinctiveShared = [...candidateTerms].filter((term) => (
+    entryTerms.has(term) && term.length >= 3 && !DISTINCTIVE_COMMON_TERMS.has(term)
+  )).length;
+  if (keywordScore < 0.5 || distinctiveShared < 3) return 0;
+  return keywordScore * 0.7 + Math.min(distinctiveShared / 6, 1) * 0.3;
 }
 
 function semanticDuplicateIndex(candidate: KnowledgeCandidate, catalog: KnowledgeCatalog): number {
@@ -191,7 +203,23 @@ function asStringArray(value: unknown, maxItems: number): string[] {
 
 type CandidateNormalization = { candidate: KnowledgeCandidate } | { reason: KnowledgeSkipReason };
 
-function normalizeCandidate(value: unknown, projectKey: string, validationText: string): CandidateNormalization {
+function withoutLeadingTitle(body: string): string {
+  return body.replace(/^#\s+[^\n]*(?:\n+|$)/u, "").trim();
+}
+
+function containsVolatileDetail(body: string, projectRoot: string): boolean {
+  const projectName = basename(resolve(projectRoot));
+  const escapedProjectName = projectName.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const namedProject = projectName.length >= 5
+    && new RegExp(`(?:项目|project)\\s*(?:[:：=]|is)?\\s*[\`'\"]?${escapedProjectName}(?![\\p{L}\\p{N}-])`, "iu").test(body);
+  return VOLATILE_ARGUMENT_RE.test(body)
+    || namedProject
+    || /\.hwcode\/cloud\/runs\//iu.test(body);
+}
+
+function normalizeCandidate(
+  value: unknown, projectKey: string, projectRoot: string, validationText: string,
+): CandidateNormalization {
   if (!value || typeof value !== "object") return { reason: "invalid-schema" };
   const raw = value as Record<string, unknown>;
   if (typeof raw.key !== "string" || typeof raw.title !== "string" || typeof raw.summary !== "string"
@@ -202,9 +230,12 @@ function normalizeCandidate(value: unknown, projectKey: string, validationText:
     && (typeof raw.targetId !== "string" || !SAFE_ID_RE.test(raw.targetId))) return { reason: "unknown-target" };
   const explicitUserDirective = raw.explicitUserDirective === true;
   const scope: KnowledgeScope = raw.scope === "global" && explicitUserDirective ? "global" : `project:${projectKey}`;
-  const body = compactKnowledgeText(raw.body, 20_000);
+  const body = withoutLeadingTitle(compactKnowledgeText(raw.body, 20_000));
   const evidence = asStringArray(raw.evidence, 8);
   if (!body || evidence.length === 0) return { reason: "missing-body-or-evidence" };
+  const candidateClaims = `${raw.title}\n${raw.summary}\n${body}`;
+  if (!explicitUserDirective && UNVERIFIED_CLAIM_RE.test(candidateClaims)) return { reason: "unverified-claim" };
+  if (containsVolatileDetail(body, projectRoot)) return { reason: "volatile-detail" };
   if (contradictsVerifiedFailures(body, validationText)) return { reason: "contradicts-verified-failure" };
   const requestedTrack: KnowledgeTrack = raw.storageHint === "rule" ? "rule" : "topic";
   const ruleEligible = body.length <= STORAGE.maxRuleChars && body.split("\n").length <= STORAGE.maxRuleFileLines
@@ -360,7 +391,9 @@ export function commitKnowledgeReview(
     const result: PersistKnowledgeResult = { saved: 0, updated: 0, pending: 0, skipped: 0 };
     const rejected: Array<{ reason: KnowledgeSkipReason; value: unknown }> = [];
     for (const value of values.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates)) {
-      const normalized = normalizeCandidate(value, task.projectKey, `${task.context ?? ""}\n${task.delta}`);
+      const normalized = normalizeCandidate(
+        value, task.projectKey, task.projectRoot, `${task.context ?? ""}\n${task.delta}`,
+      );
       if (!("candidate" in normalized)) {
         recordSkip(result, normalized.reason);
         rejected.push({ reason: normalized.reason, value });

package/.pi/lib/knowledge/types.ts

@@ -81,6 +81,8 @@ export interface PersistKnowledgeResult {
 export type KnowledgeSkipReason =
   | "invalid-schema"
   | "unstable"
+  | "unverified-claim"
+  | "volatile-detail"
   | "low-confidence"
   | "missing-body-or-evidence"
   | "contradicts-verified-failure"
@@ -98,6 +100,8 @@ export interface KnowledgeReviewTask {
   lastEntryId: string;
   context?: string;
   delta: string;
+  recallQuery?: string;
+  loadedKnowledgeIds?: string[];
   deltaDigest: string;
   fileSize: number;
   fileMtimeMs: number;

package/.pi/lib/working-directory.ts

@@ -69,6 +69,11 @@ export function getWorkingDirectory(source: SessionDirectorySource): string {
 	return getWorkingDirectoryState(source).cwd;
 }
 
+/** The immutable project root captured when the session was created. */
+export function getSessionProjectRoot(source: Pick<SessionDirectorySource, "getCwd">): string {
+	return canonicalizeDirectory(source.getCwd());
+}
+
 export function setWorkingDirectoryState(
 	source: SessionDirectorySource,
 	state: WorkingDirectoryState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadooppei/hwcode",
-  "version": "1.0.13",
+  "version": "1.0.16",
   "description": "A customizable terminal coding agent with local-model support and HWCode workflows.",
   "type": "module",
   "bin": {