@hadooppei/hwcode 1.0.16 → 1.0.20

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

@@ -10,8 +10,9 @@ import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
 import { userRuntimePaths } from "../runtime/paths.ts";
 import { compactKnowledgeSummary, compactKnowledgeText, sanitizeKnowledgeText } from "./sanitize.ts";
 import type {
-  KnowledgeCandidate, KnowledgeCatalog, KnowledgeCatalogEntry, KnowledgeManifest, KnowledgeReviewCursor,
-  KnowledgeReviewTask, KnowledgeScope, KnowledgeSkipReason, KnowledgeSnapshot, KnowledgeTrack,
+  KnowledgeCandidate, KnowledgeCatalog, KnowledgeCatalogEntry, KnowledgeClaim, KnowledgeEpisodeDecision,
+  KnowledgeEvidence, KnowledgeManifest, KnowledgeReviewCursor, KnowledgeReviewTask, KnowledgeScope,
+  KnowledgeSkipReason, KnowledgeSnapshot, KnowledgeTrack,
   PersistKnowledgeResult,
 } from "./types.ts";
 
@@ -21,10 +22,6 @@ 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 {}
 
@@ -121,47 +118,8 @@ function normalizeSlug(value: string): string {
 }
 
 function normalizedFingerprint(candidate: KnowledgeCandidate): string {
-  return createHash("sha256").update(`${candidate.scope}\0${candidate.key.trim().toLowerCase()}`).digest("hex");
-}
-
-function comparisonTerms(value: string): Set<string> {
-  return new Set((value.normalize("NFKC").toLowerCase().match(/\p{Script=Han}+|[\p{L}\p{N}]+/gu) ?? [])
-    .filter((term) => term.length >= 2));
-}
-
-function containment(left: Set<string>, right: Set<string>): number {
-  const minimum = Math.min(left.size, right.size);
-  if (minimum === 0) return 0;
-  let shared = 0;
-  for (const term of left) if (right.has(term)) shared++;
-  return shared / minimum;
-}
-
-function semanticDuplicateScore(candidate: KnowledgeCandidate, entry: KnowledgeCatalogEntry): number {
-  if (candidate.scope !== entry.scope || candidate.storageHint !== entry.track) 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) 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 {
-  let bestIndex = -1;
-  let bestScore = 0;
-  for (const [index, entry] of catalog.items.entries()) {
-    const score = semanticDuplicateScore(candidate, entry);
-    if (score > bestScore) { bestIndex = index; bestScore = score; }
-  }
-  return bestIndex;
+  const identity = candidate.identityKey?.trim().toLowerCase() || candidate.key.trim().toLowerCase();
+  return createHash("sha256").update(`${candidate.scope}\0${candidate.storageHint}\0${identity}`).digest("hex");
 }
 
 interface UnsupportedOperation {
@@ -201,6 +159,72 @@ function asStringArray(value: unknown, maxItems: number): string[] {
     .map((item) => compactKnowledgeText(item, 240)).filter(Boolean))].slice(0, maxItems);
 }
 
+function asSafeReferenceArray(value: unknown, maxItems: number): string[] {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item): item is string => (
+    typeof item === "string" && /^[a-z0-9][a-z0-9-]{0,127}$/u.test(item)
+  )))].slice(0, maxItems);
+}
+
+function normalizedClaimKey(value: string): string {
+  return compactKnowledgeText(value, 160).toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ".").replace(/^\.+|\.+$/gu, "");
+}
+
+function parseClaims(value: unknown): KnowledgeClaim[] {
+  if (!Array.isArray(value)) return [];
+  const claims: KnowledgeClaim[] = [];
+  for (const raw of value.slice(0, 12)) {
+    if (!raw || typeof raw !== "object") continue;
+    const item = raw as Record<string, unknown>;
+    if (typeof item.text !== "string") continue;
+    const text = compactKnowledgeText(item.text, 500);
+    const key = typeof item.key === "string" ? normalizedClaimKey(item.key) : normalizedClaimKey(text);
+    const evidenceIds = asSafeReferenceArray(item.evidenceIds, 12);
+    if (key && text && evidenceIds.length > 0) claims.push({ key, text, evidenceIds });
+  }
+  return claims;
+}
+
+function evidenceMap(task: KnowledgeReviewTask): Map<string, KnowledgeEvidence> {
+  return new Map((task.evidence ?? []).map((item) => [item.id, item]));
+}
+
+const UNIVERSAL_CLAIM_RE = /(?:\b(?:all|always|any|every)\b|全部|所有|任何|始终|均需)/iu;
+const BROAD_REQUIRED_CLAIM_RE = /(?:\b(?:apis?|operations?|services?)\b|接口|操作|服务)[^\n]{0,80}(?:\b(?:must|require[sd]?)\b|必须)/iu;
+const TECHNICAL_TOKEN_RE = /\p{Script=Han}{2,}|[a-z][a-z0-9_.\/-]{2,}/giu;
+const CLAIM_COMMON_TERMS = new Set(["should", "must", "always", "before", "after", "使用", "必须", "应该", "需要", "首先"]);
+
+function claimTerms(value: string): Set<string> {
+  return new Set((value.toLowerCase().match(TECHNICAL_TOKEN_RE) ?? [])
+    .filter((term) => !CLAIM_COMMON_TERMS.has(term)));
+}
+
+function claimHasDirectSupport(claim: KnowledgeClaim, ledger: Map<string, KnowledgeEvidence>): boolean {
+  const terms = claimTerms(claim.text);
+  if (terms.size === 0) return false;
+  for (const id of claim.evidenceIds) {
+    const evidence = ledger.get(id);
+    if (!evidence || evidence.kind === "assistant-claim") continue;
+    const haystack = `${evidence.subject}\n${evidence.operation ?? ""}\n${evidence.excerpt}`.toLowerCase();
+    if ([...terms].some((term) => haystack.includes(term))) return true;
+  }
+  return false;
+}
+
+function claimIsOverbroad(claim: KnowledgeClaim, ledger: Map<string, KnowledgeEvidence>): boolean {
+  if (!UNIVERSAL_CLAIM_RE.test(claim.text) && !BROAD_REQUIRED_CLAIM_RE.test(claim.text)) return false;
+  const operations = new Set(claim.evidenceIds.map((id) => ledger.get(id)?.operation).filter(Boolean));
+  return operations.size <= 1;
+}
+
+function claimContradictsSuccess(claim: KnowledgeClaim, task: KnowledgeReviewTask): boolean {
+  if (!/(?:not supported|unsupported|不支持|不可用|必须.*\/v\d|must.*\/v\d)/iu.test(claim.text)) return false;
+  const claimLower = claim.text.toLowerCase();
+  return (task.evidence ?? []).some((item) => item.outcome === "success" && item.operation
+    && claimLower.includes(item.operation.split(/\s+/u).at(-1)!.toLowerCase().replace(/\/v\d$/u, ""))
+    && !item.operation.toLowerCase().match(/\/v\d$/u));
+}
+
 type CandidateNormalization = { candidate: KnowledgeCandidate } | { reason: KnowledgeSkipReason };
 
 function withoutLeadingTitle(body: string): string {
@@ -218,7 +242,7 @@ function containsVolatileDetail(body: string, projectRoot: string): boolean {
 }
 
 function normalizeCandidate(
-  value: unknown, projectKey: string, projectRoot: string, validationText: string,
+  value: unknown, task: KnowledgeReviewTask, validationText: string,
 ): CandidateNormalization {
   if (!value || typeof value !== "object") return { reason: "invalid-schema" };
   const raw = value as Record<string, unknown>;
@@ -229,27 +253,62 @@ function normalizeCandidate(
   if (raw.targetId !== undefined && raw.targetId !== null
     && (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 scope: KnowledgeScope = raw.scope === "global" && explicitUserDirective ? "global" : `project:${task.projectKey}`;
   const body = withoutLeadingTitle(compactKnowledgeText(raw.body, 20_000));
-  const evidence = asStringArray(raw.evidence, 8);
+  const ledger = evidenceMap(task);
+  const claims = parseClaims(raw.claims);
+  const episodeIds = asSafeReferenceArray(raw.episodeIds, 8);
+  const evidenceIds = [...new Set([
+    ...asSafeReferenceArray(raw.evidenceIds, 16),
+    ...claims.flatMap((claim) => claim.evidenceIds),
+  ])];
+  let evidence = asStringArray(raw.evidence, 8);
+  if (ledger.size > 0) {
+    if (typeof raw.identityKey !== "string" || !raw.identityKey.trim()) return { reason: "invalid-schema" };
+    if (claims.length === 0 || evidenceIds.length === 0) return { reason: "missing-body-or-evidence" };
+    if (evidenceIds.some((id) => !ledger.has(id))) return { reason: "unknown-evidence" };
+    if (episodeIds.length === 0 || episodeIds.some((id) => !(task.episodes ?? []).some((episode) => episode.id === id))) {
+      return { reason: "invalid-schema" };
+    }
+    const episodeEvidenceIds = new Set((task.episodes ?? [])
+      .filter((episode) => episodeIds.includes(episode.id)).flatMap((episode) => episode.evidenceIds));
+    if (evidenceIds.some((id) => !episodeEvidenceIds.has(id))) return { reason: "unknown-evidence" };
+    if (!explicitUserDirective && claims.some((claim) => !claimHasDirectSupport(claim, ledger))) {
+      return { reason: "unsupported-claim" };
+    }
+    if (!explicitUserDirective && claims.some((claim) => claimIsOverbroad(claim, ledger))) {
+      return { reason: "overbroad-claim" };
+    }
+    if (claims.some((claim) => claimContradictsSuccess(claim, task))) {
+      return { reason: "contradicts-verified-failure" };
+    }
+    evidence = evidenceIds.slice(0, 8).map((id) => {
+      const item = ledger.get(id)!;
+      return `${id}: ${compactKnowledgeText(`${item.subject}: ${item.excerpt}`, 220)}`;
+    });
+  }
   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 (containsVolatileDetail(body, task.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
     && body.split(/\n\s*\n/gu).length === 1
     && (explicitUserDirective || raw.confidence >= 0.9);
   const targetId = typeof raw.targetId === "string" && SAFE_ID_RE.test(raw.targetId) ? raw.targetId : undefined;
+  const action = raw.action === "reinforce" || raw.action === "extend" || raw.action === "correct"
+    || raw.action === "retire" ? raw.action : "add";
   return { candidate: {
-    key: compactKnowledgeText(raw.key, 160), targetId,
+    key: compactKnowledgeText(raw.key, 160),
+    identityKey: typeof raw.identityKey === "string" ? compactKnowledgeText(raw.identityKey, 240).toLowerCase() : undefined,
+    targetId,
     title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
     summary: compactKnowledgeSummary(raw.summary, STORAGE.maxSummaryChars),
     keywords: asStringArray(raw.keywords, STORAGE.maxKeywordCount).map((keyword) => keyword.toLowerCase()),
-    scope, body, evidence, confidence: Math.min(1, raw.confidence),
+    scope, body, evidence, evidenceIds, episodeIds, claims, confidence: Math.min(1, raw.confidence),
     storageHint: requestedTrack === "rule" && ruleEligible ? "rule" : "topic",
-    action: raw.action === "revise" ? "revise" : raw.action === "reinforce" ? "reinforce" : "add",
+    action,
     explicitUserDirective, durability: "stable",
   } };
 }
@@ -276,6 +335,17 @@ function renderKnowledgeFile(candidate: KnowledgeCandidate): string {
   ].join("\n");
 }
 
+function extendKnowledgeFile(content: string, candidate: KnowledgeCandidate): string {
+  const evidenceHeading = "\n## Evidence\n";
+  const index = content.indexOf(evidenceHeading);
+  const addition = candidate.body.trim();
+  const evidenceLines = candidate.evidence.map((item) => `- ${item}`).join("\n");
+  if (index < 0) return `${content.trim()}\n\n${addition}\n\n## Evidence\n\n${evidenceLines}\n`;
+  const before = content.slice(0, index).trim();
+  const after = content.slice(index + evidenceHeading.length).trim();
+  return `${before}\n\n${addition}\n\n## Evidence\n\n${after}${after ? "\n" : ""}${evidenceLines}\n`;
+}
+
 function applicable(entry: KnowledgeCatalogEntry, projectKey: string): boolean {
   return entry.scope === "global" || entry.scope === `project:${projectKey}`;
 }
@@ -340,11 +410,11 @@ function newGenerationId(): string {
 }
 
 function copyCurrentContent(manifest: KnowledgeManifest, target: string, home: string): void {
-  for (const name of ["rules", "topics", "pending"]) ensureDirectory(join(target, name));
+  for (const name of ["rules", "topics", "pending", "audits"]) ensureDirectory(join(target, name));
   if (!manifest.generationId) return;
   const source = generationDirectory(manifest.generationId, home);
   if (!source) return;
-  for (const name of ["rules", "topics", "pending"]) {
+  for (const name of ["rules", "topics", "pending", "audits"]) {
     const sourceDirectory = join(source, name);
     if (!existsSync(sourceDirectory)) continue;
     for (const entry of readdirSync(sourceDirectory, { withFileTypes: true })) {
@@ -371,9 +441,23 @@ function reviewCursor(task: KnowledgeReviewTask): KnowledgeReviewCursor {
   };
 }
 
+function validateEpisodeDecisions(task: KnowledgeReviewTask, decisions: KnowledgeEpisodeDecision[]): void {
+  const mandatory = (task.episodes ?? []).filter((episode) => (
+    episode.score >= KNOWLEDGE_RUNTIME_DEFAULTS.review.mandatoryEpisodeScore
+  ));
+  for (const episode of mandatory) {
+    const decision = decisions.find((item) => item.episodeId === episode.id);
+    if (!decision || typeof decision.reason !== "string" || !decision.reason.trim()) {
+      throw new Error(`Knowledge reviewer omitted mandatory episode ${episode.id}`);
+    }
+  }
+}
+
 export function commitKnowledgeReview(
   values: unknown[], task: KnowledgeReviewTask, leaderToken: string, home = homedir(),
+  decisions: KnowledgeEpisodeDecision[] = [],
 ): PersistKnowledgeResult {
+  validateEpisodeDecisions(task, decisions);
   ensureKnowledgeDirectories(home);
   const release = acquireCommitLock(leaderToken, home);
   const paths = userRuntimePaths(home);
@@ -392,7 +476,7 @@ export function commitKnowledgeReview(
     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.projectRoot, `${task.context ?? ""}\n${task.delta}`,
+        value, task, `${task.context ?? ""}\n${task.delta}`,
       );
       if (!("candidate" in normalized)) {
         recordSkip(result, normalized.reason);
@@ -412,20 +496,76 @@ export function commitKnowledgeReview(
       }
       let existingIndex = targetIndex >= 0
         ? targetIndex
-        : catalog.items.findIndex((item) => item.fingerprint === fingerprint);
-      let semanticReinforcement = false;
-      if (existingIndex < 0) {
-        existingIndex = semanticDuplicateIndex(candidate, catalog);
-        semanticReinforcement = existingIndex >= 0;
-      }
+        : catalog.items.findIndex((item) => item.fingerprint === fingerprint
+          || Boolean(candidate.identityKey && item.identityKey === candidate.identityKey && item.track === candidate.storageHint));
       const existing = existingIndex >= 0 ? catalog.items[existingIndex] : undefined;
-      if (existing && (existing.contentHash === hash || candidate.action === "reinforce" || semanticReinforcement)) {
+
+      if (candidate.action === "reinforce") {
+        const claimKeys = candidate.claims?.map((claim) => claim.key) ?? [];
+        const covered = claimKeys.length > 0 && claimKeys.every((key) => existing?.claimKeys?.includes(key));
+        if (!existing || (!covered && existing.contentHash !== hash)) {
+          recordSkip(result, "unsafe-reinforcement");
+          rejected.push({ reason: "unsafe-reinforcement", value });
+          continue;
+        }
+        existing.evidenceCount += candidate.evidence.length;
+        existing.updatedAt = new Date().toISOString();
+        result.updated++;
+        continue;
+      }
+
+      if (candidate.action === "retire") {
+        if (!existing || !candidate.targetId || (!candidate.explicitUserDirective && candidate.confidence < 0.98)) {
+          recordSkip(result, "unsafe-reinforcement");
+          rejected.push({ reason: "unsafe-reinforcement", value });
+          continue;
+        }
+        const existingPath = resolve(temporary, existing.file);
+        if (existingPath.startsWith(`${temporary}${sep}`)) rmSync(existingPath, { force: true });
+        catalog.items.splice(existingIndex, 1);
+        result.updated++;
+        continue;
+      }
+
+      if (candidate.action === "extend") {
+        if (!existing || !candidate.targetId || existing.track !== "topic") {
+          recordSkip(result, "unknown-target");
+          rejected.push({ reason: "unknown-target", value });
+          continue;
+        }
+        const newClaimKeys = (candidate.claims ?? []).map((claim) => claim.key)
+          .filter((key) => !existing.claimKeys?.includes(key));
+        if (newClaimKeys.length === 0 && existing.claimKeys?.length) {
+          existing.evidenceCount += candidate.evidence.length;
+          existing.updatedAt = new Date().toISOString();
+          result.updated++;
+          continue;
+        }
+        const existingPath = resolve(temporary, existing.file);
+        if (!existingPath.startsWith(`${temporary}${sep}`) || !existsSync(existingPath)) {
+          recordSkip(result, "unknown-target");
+          rejected.push({ reason: "unknown-target", value });
+          continue;
+        }
+        const content = extendKnowledgeFile(readFileSync(existingPath, "utf8"), candidate);
+        atomicWrite(existingPath, content);
+        existing.contentHash = createHash("sha256").update(content).digest("hex");
+        existing.keywords = [...new Set([...existing.keywords, ...candidate.keywords])].slice(0, STORAGE.maxKeywordCount);
+        existing.claimKeys = [...new Set([...(existing.claimKeys ?? []), ...newClaimKeys])];
         existing.evidenceCount += candidate.evidence.length;
         existing.updatedAt = new Date().toISOString();
         result.updated++;
         continue;
       }
-      if (existing && !(candidate.action === "revise" && (candidate.explicitUserDirective || candidate.confidence >= 0.92))) {
+
+      if (existing && candidate.action !== "correct") {
+        const name = `${Date.now()}-${normalizeSlug(candidate.title)}-${randomUUID().slice(0, 8)}.json`;
+        atomicWrite(join(temporary, "pending", name), `${JSON.stringify({ reason: "conflicting-or-ambiguous-update", candidate }, null, 2)}\n`);
+        result.pending++;
+        continue;
+      }
+      if (existing && candidate.action === "correct"
+        && (!candidate.targetId || (!candidate.explicitUserDirective && candidate.confidence < 0.92))) {
         const name = `${Date.now()}-${normalizeSlug(candidate.title)}-${randomUUID().slice(0, 8)}.json`;
         atomicWrite(join(temporary, "pending", name), `${JSON.stringify({ reason: "conflicting-or-ambiguous-update", candidate }, null, 2)}\n`);
         result.pending++;
@@ -446,21 +586,32 @@ export function commitKnowledgeReview(
         title: candidate.title, summary: candidate.summary,
         keywords: candidate.keywords, scope: existing?.scope ?? candidate.scope, track, file: relativeFile,
         evidenceCount: (existing?.evidenceCount ?? 0) + candidate.evidence.length,
+        identityKey: candidate.identityKey ?? existing?.identityKey,
+        claimKeys: candidate.claims?.map((claim) => claim.key) ?? existing?.claimKeys,
         createdAt: existing?.createdAt ?? now, updatedAt: now,
       };
       if (existingIndex >= 0) { catalog.items[existingIndex] = entry; result.updated++; }
       else { catalog.items.push(entry); result.saved++; }
     }
-    if (result.skipped > 0 && result.saved === 0 && result.updated === 0 && result.pending === 0) {
-      for (const item of rejected) writeRejectedPending(temporary, item.reason, item.value);
-      result.pending += rejected.length;
-    }
+    for (const item of rejected) writeRejectedPending(temporary, item.reason, item.value);
+    result.pending += rejected.length;
     catalog.updatedAt = new Date().toISOString();
     const manifest: KnowledgeManifest = {
       version: 3, generationId, createdAt: new Date().toISOString(), leaderToken, catalog,
       reviews: { ...current.reviews, [task.sessionKey]: reviewCursor(task) },
     };
     atomicWrite(join(temporary, "MEMORY.md"), generateMemory(catalog));
+    atomicWrite(join(temporary, "audits", `${task.reviewKey}.json`), `${JSON.stringify({
+      reviewKey: task.reviewKey,
+      sessionKey: task.sessionKey,
+      episodes: (task.episodes ?? []).map((episode) => ({
+        id: episode.id, title: episode.title, score: episode.score,
+        failureCount: episode.failureCount, successCount: episode.successCount,
+      })),
+      decisions,
+      result,
+      rejected: rejected.map((item) => ({ reason: item.reason })),
+    }, null, 2)}\n`);
     atomicWrite(join(temporary, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
     if (!validManifestAt(manifest, temporary)) throw new Error("Refusing to publish an incomplete knowledge generation");
     const finalDirectory = join(paths.knowledgeGenerations, generationId);

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

@@ -1,10 +1,56 @@
 export type KnowledgeTrack = "rule" | "topic";
 export type KnowledgeScope = "global" | `project:${string}`;
-export type KnowledgeAction = "add" | "reinforce" | "revise";
+export type KnowledgeAction = "add" | "reinforce" | "extend" | "correct" | "retire";
 export type KnowledgeDurability = "stable";
 
+export type KnowledgeEvidenceKind =
+  | "user-directive"
+  | "user-correction"
+  | "tool-success"
+  | "tool-failure"
+  | "verification"
+  | "assistant-claim";
+
+export interface KnowledgeEvidence {
+  id: string;
+  entryId: string;
+  timestamp: string;
+  kind: KnowledgeEvidenceKind;
+  subject: string;
+  operation?: string;
+  outcome: "success" | "failure" | "unknown";
+  excerpt: string;
+}
+
+export interface KnowledgeEpisode {
+  id: string;
+  title: string;
+  query: string;
+  evidenceIds: string[];
+  score: number;
+  failureCount: number;
+  successCount: number;
+  hypothesisReversalCount: number;
+  elapsedMs: number;
+  userSignal: boolean;
+}
+
+export interface KnowledgeClaim {
+  key: string;
+  text: string;
+  evidenceIds: string[];
+}
+
+export interface KnowledgeEpisodeDecision {
+  episodeId: string;
+  decision: "add" | "reinforce" | "extend" | "correct" | "retire" | "skip";
+  targetId?: string;
+  reason: string;
+}
+
 export interface KnowledgeCandidate {
   key: string;
+  identityKey?: string;
   targetId?: string;
   title: string;
   summary: string;
@@ -12,6 +58,9 @@ export interface KnowledgeCandidate {
   scope: KnowledgeScope;
   body: string;
   evidence: string[];
+  evidenceIds?: string[];
+  episodeIds?: string[];
+  claims?: KnowledgeClaim[];
   confidence: number;
   storageHint: KnowledgeTrack;
   action: KnowledgeAction;
@@ -30,6 +79,8 @@ export interface KnowledgeCatalogEntry {
   track: KnowledgeTrack;
   file: string;
   evidenceCount: number;
+  identityKey?: string;
+  claimKeys?: string[];
   createdAt: string;
   updatedAt: string;
 }
@@ -86,7 +137,11 @@ export type KnowledgeSkipReason =
   | "low-confidence"
   | "missing-body-or-evidence"
   | "contradicts-verified-failure"
-  | "unknown-target";
+  | "unknown-target"
+  | "unknown-evidence"
+  | "unsupported-claim"
+  | "overbroad-claim"
+  | "unsafe-reinforcement";
 
 export interface KnowledgeReviewTask {
   requestId: string;
@@ -102,6 +157,8 @@ export interface KnowledgeReviewTask {
   delta: string;
   recallQuery?: string;
   loadedKnowledgeIds?: string[];
+  evidence?: KnowledgeEvidence[];
+  episodes?: KnowledgeEpisode[];
   deltaDigest: string;
   fileSize: number;
   fileMtimeMs: number;

package/.pi/lib/knowledge/worker-protocol.ts

@@ -13,7 +13,7 @@ export type KnowledgeWorkerOutput =
   | { type: "review_request"; leaderToken: string; requestId: string; task: KnowledgeReviewTask }
   | { type: "review_cancel"; requestId: string; reason: string }
   | { type: "review_saved"; requestId: string; generationId?: string; result: PersistKnowledgeResult }
-  | { type: "review_failed"; requestId?: string; error: string }
+  | { type: "review_failed"; requestId?: string; error: string; terminal?: boolean }
   | { type: "generation_changed"; generationId: string };
 
 export interface CoordinatorBroadcast {

package/.pi/lib/runtime/defaults.ts

@@ -32,8 +32,14 @@ export const KNOWLEDGE_RUNTIME_DEFAULTS = Object.freeze({
     idleMs: 60_000,
     capabilityPollMs: 5_000,
     modelTimeoutMs: 180_000,
+    maxAttempts: 2,
+    maxFailureDetailChars: 4_000,
     maxDeltaChars: 12_000,
     maxPriorContextChars: 4_000,
+    maxNarrativeChars: 6_000,
+    maxEvidenceItems: 24,
+    maxEvidenceChars: 12_000,
+    mandatoryEpisodeScore: 45,
     maxExistingContextItems: 5,
     maxExistingBodyItems: 2,
     maxExistingBodyChars: 600,

package/.pi/lib/workflows/cloud/process.ts

@@ -18,6 +18,25 @@ export interface ProcessResult {
   spawnErrorCode?: string;
 }
 
+const BRACKETED_PROVIDER_ERROR_RE = /\[(?:USE|CLI|AUTH|HTTP|SERVER|SYSTEM|SDK)_ERROR\][^\r\n]*/iu;
+const STRUCTURED_PROVIDER_FAILURE_RE = /"kind"\s*:\s*"Status"[\s\S]{0,500}"status"\s*:\s*"(?:failure|failed|error)"/iu;
+const STRUCTURED_ERROR_CODE_RE = /"(?:errorCode|error_code|code)"\s*:\s*(?:"[^"\r\n]+"|\d+)/iu;
+
+/** Detect CLIs that report an API failure in output while incorrectly exiting with code 0. */
+export function cloudProviderFailureReason(stdout: string, stderr: string): string | undefined {
+  const output = `${stderr}\n${stdout}`.trim();
+  if (!output) return undefined;
+  const bracketed = BRACKETED_PROVIDER_ERROR_RE.exec(output)?.[0]?.trim();
+  if (bracketed) return bracketed.slice(0, 2_000);
+  if (STRUCTURED_PROVIDER_FAILURE_RE.test(output) && STRUCTURED_ERROR_CODE_RE.test(output)) {
+    const status = STRUCTURED_PROVIDER_FAILURE_RE.exec(output)?.[0];
+    const code = STRUCTURED_ERROR_CODE_RE.exec(output)?.[0];
+    const message = /"message"\s*:\s*"([^"\r\n]+)"/iu.exec(output)?.[1];
+    return [status, code, message].filter(Boolean).join("; ").slice(0, 2_000);
+  }
+  return undefined;
+}
+
 function captureOutput(current: string, chunk: Buffer): string {
   if (Buffer.byteLength(current, "utf8") >= MAX_CAPTURE_BYTES) return current;
   const remaining = MAX_CAPTURE_BYTES - Buffer.byteLength(current, "utf8");

package/package.json

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