@evo-dev/core 0.0.1-alpha.14 → 0.0.1-alpha.16

package/src/evolution/knowledge/index.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { resolveEvoDevPaths } from "../../config/paths.ts";
+import { readRuntimeInjectionSettings } from "../../config/settings.ts";
 import {
   canonicalizeProjectKey,
   listEquivalentProjectKeys,
@@ -21,6 +22,24 @@ import type {
   EvolutionKnowledgeRecord,
 } from "../schema.ts";
 import { REVIEW_STATES } from "../shared.ts";
+import {
+  type OkfKnowledgeChangeCandidateV1,
+  createOkfKnowledgeChangeCandidate,
+  readOkfKnowledgeChangeCandidate,
+  writeOkfKnowledgeChangeCandidate,
+} from "./change-store.ts";
+import {
+  type OkfKnowledgeChangeClassificationResult,
+  classifyOkfKnowledgeCandidate,
+  createOkfKnowledgeRevision,
+  createOkfKnowledgeRuntimeProjectionFromConcept,
+} from "./changes.ts";
+import {
+  type OkfKnowledgeFreshness,
+  type OkfKnowledgeVerificationSnapshotV1,
+  createOkfKnowledgeVerificationSnapshot,
+  deriveOkfKnowledgeFreshness,
+} from "./freshness.ts";
 
 export type OkfKnowledgeDecision =
   | "auto-accept"
@@ -28,7 +47,8 @@ export type OkfKnowledgeDecision =
   | "create"
   | "update"
   | "skip"
-  | "needs-human";
+  | "needs-human"
+  | "revoke";
 export type OkfKnowledgeTargetStore = "okf" | "repo-asset-proposal" | "evo-eval-set" | "none";
 export type OkfKnowledgeReviewState =
   | "auto-accepted"
@@ -221,6 +241,7 @@ export interface OkfKnowledgeActivationResult {
   overlayPaths: string[];
   skippedCandidates: string[];
   needsHumanCandidates: string[];
+  pendingChangeIds: string[];
   indexPaths: string[];
   derivedIndexPaths: string[];
   logPaths: string[];
@@ -258,6 +279,7 @@ export interface OkfKnowledgeConcept {
   reviewState: OkfKnowledgeReviewState;
   lifecycle: OkfKnowledgeLifecycle;
   lifecyclePersisted: boolean;
+  verificationSnapshot: OkfKnowledgeVerificationSnapshotV1 | null;
   title: string;
   description: string;
   tags: string[];
@@ -294,6 +316,8 @@ export interface OkfKnowledgeContextItem {
   score?: number;
   title: string;
   summary: string;
+  freshness: OkfKnowledgeFreshness;
+  runtimeExcerpt: string | null;
   matchReasons: string[];
 }
 
@@ -337,6 +361,20 @@ export interface ScopedKnowledgeContextPackItem {
   section: OkfKnowledgeContextSection;
   rank: number;
   title: string;
+  freshness: OkfKnowledgeFreshness;
+  loader:
+    | {
+        kind: "knowledge-show";
+        conceptId: string;
+      }
+    | {
+        kind: "none";
+        conceptId: null;
+      };
+  delivery: {
+    mode: "inline" | "reference";
+    excerpt: string | null;
+  };
   matchReasons: string[];
 }
 
@@ -478,6 +516,7 @@ const OKF_DECISIONS: readonly OkfKnowledgeDecision[] = [
   "update",
   "skip",
   "needs-human",
+  "revoke",
 ];
 const ACTIVE_OKF_DECISIONS: readonly OkfKnowledgeDecision[] = ["auto-accept", "create", "update"];
 const BEHAVIOR_CHANGE_KINDS = new Set([
@@ -642,7 +681,7 @@ export function finalizeCuratedKnowledgePlan(input: {
   };
   const candidates = input.plan.candidates.map((candidate) => {
     if (candidate.decision === "no_write" || candidate.decision === "skip") return candidate;
-    if (candidate.decision === "needs-human") return candidate;
+    if (candidate.decision === "needs-human" || candidate.decision === "revoke") return candidate;
     return decideOkfKnowledgeCandidate(
       {
         ...candidate,
@@ -773,7 +812,7 @@ export function parseKnowledgeDistillationOutput(
 
 export function validateOkfKnowledgePlanContract(
   plan: OkfKnowledgePlan,
-  _options: { homeDir?: string } = {},
+  options: { homeDir?: string; allowReviewedHighRisk?: boolean } = {},
 ): OkfKnowledgePlanValidationResult {
   const findings: OkfKnowledgePlanValidationFinding[] = [];
   const add = (
@@ -825,7 +864,9 @@ export function validateOkfKnowledgePlanContract(
     add("candidates", "plan.candidates", "Plan candidates must be an array.");
   } else {
     plan.candidates.forEach((candidate, index) =>
-      validateCandidateContract(candidate, `candidates[${index}]`, evalSetIds, add),
+      validateCandidateContract(candidate, `candidates[${index}]`, evalSetIds, add, {
+        allowReviewedHighRisk: options.allowReviewedHighRisk === true,
+      }),
     );
   }
 
@@ -877,7 +918,7 @@ export function validateOkfKnowledgePlanContract(
 
 export function assertOkfKnowledgePlanContract(
   plan: OkfKnowledgePlan,
-  options: { homeDir?: string } = {},
+  options: { homeDir?: string; allowReviewedHighRisk?: boolean } = {},
 ): void {
   const result = validateOkfKnowledgePlanContract(plan, options);
   if (!result.ok) {
@@ -948,6 +989,7 @@ function validateCandidateContract(
   path: string,
   evalSetIds: Set<string>,
   add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+  options: { allowReviewedHighRisk: boolean },
 ): void {
   if (!isRecord(candidate)) {
     add(path, "candidate.object", "Candidate must be an object.");
@@ -1035,7 +1077,7 @@ function validateCandidateContract(
         "Active writes require metadata-only evidence.",
       );
     }
-    if (hasHighRiskHumanReviewSignal(candidate)) {
+    if (hasHighRiskHumanReviewSignal(candidate) && !options.allowReviewedHighRisk) {
       add(
         path,
         "candidate.active.highRiskHumanReview",
@@ -1094,6 +1136,47 @@ function validateCandidateContract(
       );
     }
   }
+  if (decision === "revoke") {
+    if (candidate.targetStore !== "okf") {
+      add(
+        `${path}.targetStore`,
+        "candidate.revoke.targetStore",
+        "Knowledge revocation must target OKF.",
+      );
+    }
+    if (candidate.reviewState !== "needs-human") {
+      add(
+        `${path}.reviewState`,
+        "candidate.revoke.reviewState",
+        "Knowledge revocation must enter human review.",
+      );
+    }
+    if (candidate.metadataOnlyEvidence !== true) {
+      add(
+        `${path}.metadataOnlyEvidence`,
+        "candidate.revoke.metadataOnlyEvidence",
+        "Knowledge revocation requires metadata-only evidence.",
+      );
+    }
+    if (!Array.isArray(candidate.evidenceRefs) || candidate.evidenceRefs.length === 0) {
+      add(
+        `${path}.evidenceRefs`,
+        "candidate.revoke.evidenceRefs",
+        "Knowledge revocation requires evidenceRefs.",
+      );
+    }
+    const verification =
+      isRecord(candidate.bodySections) && Array.isArray(candidate.bodySections.verification)
+        ? candidate.bodySections.verification
+        : [];
+    if (verification.length === 0 && !isNonEmptyString(candidate.verificationNotApplicableReason)) {
+      add(
+        `${path}.bodySections.verification`,
+        "candidate.revoke.verification",
+        "Knowledge revocation requires verification or an explicit not-applicable reason.",
+      );
+    }
+  }
   if (noOp && (!isNonEmptyString(candidate.id) || !isNonEmptyString(candidate.decisionReason))) {
     add(path, "candidate.noop.metadata", "No-op candidates require safe skip metadata.");
   }
@@ -1638,9 +1721,8 @@ export function findCandidateConflictOrDuplicate(
   const targetPath = candidate.targetPath.replace(/^\/+/u, "");
   const duplicate = index.concepts.find(
     (concept) =>
-      concept.stableKey === candidate.stableKey ||
-      concept.targetPath === targetPath ||
-      concept.sourceLink === `/${targetPath}`,
+      concept.stableKey !== candidate.stableKey &&
+      (concept.targetPath === targetPath || concept.sourceLink === `/${targetPath}`),
   );
   if (duplicate !== undefined) {
     return {
@@ -1655,6 +1737,7 @@ export function findCandidateConflictOrDuplicate(
   );
   const semanticDuplicate = index.concepts.find(
     (concept) =>
+      concept.stableKey !== candidate.stableKey &&
       candidateFingerprint !== "" &&
       candidateFingerprint === concept.semanticFingerprint &&
       scopesOverlap(candidate.repoTags, concept.repoTags),
@@ -1808,12 +1891,22 @@ export function decideOkfKnowledgeCandidate(
   }
 
   if (highRiskRequiresHuman) {
+    const reviewEligible =
+      !originalUnsafe &&
+      hasReusableSemanticShape(sanitized) &&
+      localActiveTarget &&
+      sanitized.metadataOnlyEvidence &&
+      hasVerification &&
+      hasScopeTags &&
+      scores.privacyRisk <= 2;
     return {
       ...sanitized,
-      decision: "no_write",
+      decision: reviewEligible ? "needs-human" : "no_write",
       scores,
-      reviewState: "auto-stored/unreviewed",
-      decisionReason: "No write: high-risk knowledge is not eligible for automatic activation.",
+      reviewState: reviewEligible ? "needs-human" : "auto-stored/unreviewed",
+      decisionReason: reviewEligible
+        ? "Needs human review: the candidate changes a sensitive engineering domain."
+        : "No write: high-risk knowledge did not pass the privacy, verification, or scope gates.",
     };
   }
 
@@ -1849,19 +1942,103 @@ export function decideOkfKnowledgeCandidate(
   };
 }
 
+async function readAuthorizedReviewedKnowledgeChange(input: {
+  homeDir: string;
+  plan: OkfKnowledgePlan;
+  changeId: string;
+}): Promise<OkfKnowledgeChangeCandidateV1> {
+  const { change } = await readOkfKnowledgeChangeCandidate({
+    homeDir: input.homeDir,
+    changeId: input.changeId,
+  });
+  if (change.state !== "accepted" || change.decision?.state !== "accepted") {
+    throw new Error("Reviewed knowledge change must be accepted before activation.");
+  }
+  if (change.operation === "revoke") {
+    throw new Error("Reviewed knowledge revocation must use the lifecycle decision path.");
+  }
+  if (
+    input.plan.projectKey !== change.projectKey ||
+    input.plan.runId !== change.runId ||
+    input.plan.evidenceWindowId !== change.provenance.evidenceWindowId
+  ) {
+    throw new Error("Reviewed knowledge change identity does not match the activation plan.");
+  }
+  if (input.plan.candidates.length !== 1) {
+    throw new Error("Reviewed knowledge activation must contain exactly one candidate.");
+  }
+  const candidate = input.plan.candidates[0] as OkfKnowledgePlanCandidate;
+  const expectedCandidate: OkfKnowledgePlanCandidate = {
+    ...change.candidate.planCandidate,
+    decision: change.operation === "update" ? "update" : "create",
+    reviewState: "accepted",
+    targetPath:
+      change.operation === "update" && change.base !== null
+        ? change.base.sourceLink.replace(/^\/+/u, "")
+        : change.targetPath,
+  };
+  if (stableJsonStringify(candidate) !== stableJsonStringify(expectedCandidate)) {
+    throw new Error("Reviewed knowledge candidate does not match the accepted change.");
+  }
+  if (
+    stableJsonStringify(input.plan.evoEvalSets) !== stableJsonStringify(change.candidate.evalSets)
+  ) {
+    throw new Error("Reviewed knowledge eval sets do not match the accepted change.");
+  }
+  const expectedEvidenceRefs = change.provenance.evidenceRefs.map((id) => ({
+    id,
+    kind: "knowledge-change-evidence",
+    source: `knowledge-change:${change.id}`,
+    rawContentStored: false,
+    externalContentCopied: false,
+  }));
+  if (
+    stableJsonStringify(input.plan.evidenceRefs) !== stableJsonStringify(expectedEvidenceRefs) ||
+    stableJsonStringify(input.plan.privacyCheck) !==
+      stableJsonStringify(expectedCandidate.privacyCheck)
+  ) {
+    throw new Error("Reviewed knowledge provenance does not match the accepted change.");
+  }
+  return change;
+}
+
+function assertReviewedKnowledgeClassification(
+  change: OkfKnowledgeChangeCandidateV1,
+  classification: OkfKnowledgeChangeClassificationResult,
+): void {
+  if (
+    classification.classification !== change.operation ||
+    classification.baseRevision !== (change.base?.revision ?? null) ||
+    classification.candidateRevision !== change.candidate.revision
+  ) {
+    throw new Error("Reviewed knowledge classification changed before activation.");
+  }
+}
+
 export async function activateOkfKnowledgePlan(input: {
   homeDir: string;
   plan: OkfKnowledgePlan;
   overwrite?: boolean;
   evidenceWindowPath?: string | null;
+  reviewedChangeId?: string;
 }): Promise<OkfKnowledgeActivationResult> {
-  const validation = validateOkfKnowledgePlanContract(input.plan);
   const projectKey =
     isRecord(input.plan) && isNonEmptyString(input.plan.projectKey)
       ? input.plan.projectKey
       : "unknown";
   const runId =
     isRecord(input.plan) && isNonEmptyString(input.plan.runId) ? input.plan.runId : "unknown";
+  const reviewedChange =
+    input.reviewedChangeId === undefined
+      ? null
+      : await readAuthorizedReviewedKnowledgeChange({
+          homeDir: input.homeDir,
+          plan: input.plan,
+          changeId: input.reviewedChangeId,
+        });
+  const validation = validateOkfKnowledgePlanContract(input.plan, {
+    allowReviewedHighRisk: reviewedChange !== null,
+  });
   if (!validation.ok) {
     await writeFailedOkfKnowledgePlanArtifact({
       homeDir: input.homeDir,
@@ -1874,7 +2051,7 @@ export async function activateOkfKnowledgePlan(input: {
     });
     throw new Error("OKF knowledge plan contract validation failed.");
   }
-  validateOkfKnowledgePlan(input.plan);
+  validateOkfKnowledgePlan(input.plan, { allowReviewedHighRisk: reviewedChange !== null });
   const paths = resolveOkfKnowledgePaths(input.homeDir);
   const tmpRunDir = join(paths.tmpDir, `${input.plan.projectKey}-${input.plan.runId}`);
   const planPath = join(tmpRunDir, "knowledge-plan.json");
@@ -1891,24 +2068,146 @@ export async function activateOkfKnowledgePlan(input: {
   const overlayPaths: string[] = [];
   const skippedCandidates: string[] = [];
   const needsHumanCandidates: string[] = [];
+  const pendingChangeIds: string[] = [];
   const affectedDirectories = new Set<string>([paths.okfDir]);
 
   try {
-    const targetStates = await preflightOkfConceptTargets(paths.okfDir, input.plan.candidates);
+    const settings = await readRuntimeInjectionSettings(input.homeDir);
+    const existingConcepts = await listOkfKnowledgeConcepts({ homeDir: input.homeDir });
+    const existingByStableKey = new Map(
+      existingConcepts
+        .filter(
+          (concept) =>
+            isActiveOkfReviewState(concept.reviewState) && concept.lifecycle.status === "active",
+        )
+        .map((concept) => [concept.stableKey, concept]),
+    );
+    const writeCandidates: OkfKnowledgePlanCandidate[] = [];
+    const existingByCandidateId = new Map<string, OkfKnowledgeConcept>();
     for (const candidate of input.plan.candidates) {
       if (candidate.decision === "no_write" || candidate.decision === "skip") {
         skippedCandidates.push(candidate.id);
         continue;
       }
-      if (candidate.decision === "needs-human") {
-        needsHumanCandidates.push(candidate.id);
+      if (candidate.targetStore !== "okf") {
+        skippedCandidates.push(candidate.id);
         continue;
       }
-      if (candidate.targetStore !== "okf") {
+      const existing = existingByStableKey.get(candidate.stableKey) ?? null;
+      const classification = classifyOkfKnowledgeCandidate({
+        candidate,
+        existingConcept: existing,
+      });
+      if (reviewedChange !== null) {
+        assertReviewedKnowledgeClassification(reviewedChange, classification);
+      }
+      const needsReview =
+        reviewedChange === null &&
+        (candidate.decision === "needs-human" ||
+          classification.classification === "revoke" ||
+          classification.classification === "supersede" ||
+          (classification.classification === "update" && settings.reviewKnowledgeUpdates));
+      if (needsReview) {
+        const operation =
+          classification.classification === "supersede" ||
+          classification.classification === "revoke"
+            ? classification.classification
+            : existing === null
+              ? "create"
+              : "update";
+        const beforeFreshness =
+          existing === null ? null : deriveOkfKnowledgeFreshness({ concept: existing }).freshness;
+        const verificationSnapshot = createOkfKnowledgeVerificationSnapshot({
+          candidate,
+          verifiedAt: input.plan.createdAt,
+          projectKey: input.plan.projectKey,
+        });
+        const change = createOkfKnowledgeChangeCandidate({
+          projectKey: input.plan.projectKey,
+          runId: input.plan.runId,
+          operation,
+          stableKey: candidate.stableKey,
+          targetPath: candidate.targetPath,
+          base:
+            existing === null || classification.baseProjection === null
+              ? null
+              : {
+                  conceptId: existing.id,
+                  sourceLink: existing.sourceLink,
+                  revision:
+                    classification.baseRevision ??
+                    createOkfKnowledgeRevision(
+                      createOkfKnowledgeRuntimeProjectionFromConcept(existing),
+                    ),
+                  runtimeProjection: classification.baseProjection,
+                },
+          candidateRevision: classification.candidateRevision,
+          planCandidate: candidate,
+          evalSets: input.plan.evoEvalSets.filter((evalSet) =>
+            (candidate.evalSetRefs ?? []).includes(evalSet.id),
+          ),
+          diff: classification.diff,
+          freshness: {
+            before: beforeFreshness,
+            after:
+              classification.classification === "revoke"
+                ? "stale"
+                : verificationSnapshot === null
+                  ? "unknown"
+                  : "verified",
+            reason:
+              candidate.decision === "needs-human" || candidate.decision === "revoke"
+                ? candidate.decisionReason
+                : classification.reason,
+          },
+          evidenceWindowId: input.plan.evidenceWindowId,
+          evidenceRefs: candidate.evidenceRefs,
+          createdAt: input.plan.createdAt,
+        });
+        await writeOkfKnowledgeChangeCandidate({ homeDir: input.homeDir, change });
+        pendingChangeIds.push(change.id);
+        if (candidate.decision === "needs-human" || candidate.decision === "revoke") {
+          needsHumanCandidates.push(candidate.id);
+        }
+        continue;
+      }
+      if (classification.classification === "no_write") {
         skippedCandidates.push(candidate.id);
         continue;
       }
+      if (classification.classification === "supersede") {
+        writeCandidates.push({
+          ...candidate,
+          decision: "create",
+          reviewState: "accepted",
+        });
+        continue;
+      }
+      if (classification.classification === "revoke") {
+        throw new Error("Knowledge revocation must be applied through its reviewed change.");
+      }
+      if (
+        classification.classification === "update" ||
+        classification.classification === "refresh"
+      ) {
+        if (existing === null) {
+          throw new Error(`Knowledge ${classification.classification} requires an active concept.`);
+        }
+        const effectiveCandidate: OkfKnowledgePlanCandidate = {
+          ...candidate,
+          decision: "update",
+          targetPath: existing.sourceLink.replace(/^\/+/u, ""),
+          reviewState: candidate.reviewState === "auto-accepted" ? "auto-accepted" : "accepted",
+        };
+        writeCandidates.push(effectiveCandidate);
+        existingByCandidateId.set(effectiveCandidate.id, existing);
+        continue;
+      }
+      writeCandidates.push(candidate);
+    }
 
+    const targetStates = await preflightOkfConceptTargets(paths.okfDir, writeCandidates);
+    for (const candidate of writeCandidates) {
       const targetPath = resolveOkfTargetPath(paths.okfDir, candidate.targetPath);
       const targetState = targetStates.get(targetPath);
       if (targetState?.action === "skip-existing") {
@@ -1921,7 +2220,11 @@ export async function activateOkfKnowledgePlan(input: {
       }
 
       await mkdir(dirname(targetPath), { recursive: true });
-      await writeFile(targetPath, renderOkfConcept(candidate, input.plan), "utf8");
+      await writeFile(
+        targetPath,
+        renderOkfConcept(candidate, input.plan, existingByCandidateId.get(candidate.id)),
+        "utf8",
+      );
       conceptPaths.push(targetPath);
       affectedDirectories.add(dirname(targetPath));
 
@@ -1962,6 +2265,7 @@ export async function activateOkfKnowledgePlan(input: {
       overlayPaths,
       skippedCandidates,
       needsHumanCandidates,
+      pendingChangeIds,
       indexPaths,
       derivedIndexPaths,
       logPaths,
@@ -2500,17 +2804,26 @@ export async function queryOkfKnowledge(input: {
       return left.concept.id.localeCompare(right.concept.id);
     })
     .slice(0, limit)
-    .map<OkfKnowledgeContextItem>((candidate, index) => ({
-      id: candidate.concept.id,
-      sourceType: "okf",
-      sourceLink: candidate.concept.sourceLink,
-      section: candidate.section,
-      rank: index + 1,
-      score: candidate.score,
-      title: candidate.concept.title,
-      summary: candidate.concept.description || candidate.concept.title,
-      matchReasons: candidate.matchReasons.length === 0 ? ["generic"] : candidate.matchReasons,
-    }));
+    .map<OkfKnowledgeContextItem>((candidate, index) => {
+      const freshness = deriveOkfKnowledgeFreshness({
+        concept: candidate.concept,
+        now,
+      }).freshness;
+      return {
+        id: candidate.concept.id,
+        sourceType: "okf",
+        sourceLink: candidate.concept.sourceLink,
+        section: candidate.section,
+        rank: index + 1,
+        score: candidate.score,
+        title: candidate.concept.title,
+        summary: candidate.concept.description || candidate.concept.title,
+        freshness,
+        runtimeExcerpt:
+          freshness === "verified" ? createBoundedOkfRuntimeExcerpt(candidate.concept) : null,
+        matchReasons: candidate.matchReasons.length === 0 ? ["generic"] : candidate.matchReasons,
+      };
+    });
 
   return {
     projectKey: scope.projectKey,
@@ -2788,6 +3101,10 @@ export function mergeAcceptedEvosCasesIntoKnowledgeQuery(
         score: structuredScore + lexical.score,
         title: evosCase.title,
         summary: evosCase.expectedFutureBehavior || evosCase.result.summary || evosCase.title,
+        freshness: "verified",
+        runtimeExcerpt: sanitizeOkfText(
+          evosCase.expectedFutureBehavior || evosCase.result.summary || evosCase.title,
+        ).slice(0, 1_200),
         matchReasons:
           lexical.reasons.length === 0
             ? structuredReasons
@@ -2830,6 +3147,15 @@ export async function createScopedKnowledgeContextPack(input: {
     section: item.section,
     rank: item.rank,
     title: sanitizeOkfText(item.title),
+    freshness: item.freshness,
+    loader:
+      item.sourceType === "okf"
+        ? { kind: "knowledge-show", conceptId: item.id }
+        : { kind: "none", conceptId: null },
+    delivery: {
+      mode: item.runtimeExcerpt === null ? "reference" : "inline",
+      excerpt: item.runtimeExcerpt,
+    },
     matchReasons: uniqueStrings(item.matchReasons.map(sanitizeLexicalReason)),
   }));
   const okfIndexRevision = createKnowledgeContextRevision(items);
@@ -2843,7 +3169,9 @@ export async function createScopedKnowledgeContextPack(input: {
       sourceType: item.sourceType,
       sourceLink: item.sourceLink,
       section: item.section,
-      rank: item.rank,
+      freshness: item.freshness,
+      loader: item.loader,
+      delivery: item.delivery,
       matchReasons: item.matchReasons,
     })),
   });
@@ -2875,10 +3203,20 @@ export function formatScopedKnowledgePromptBlock(pack: ScopedKnowledgeContextPac
     ...(pack.queryText === undefined ? [] : [`Query: ${sanitizeOkfText(pack.queryText)}`]),
     `Paths: ${pack.scope.paths.length === 0 ? "all" : pack.scope.paths.join(", ")}`,
     "Raw content stored: false",
+    "Freshness is determined by EvoDev lifecycle and verification metadata; do not infer validity from timestamps.",
     "",
     "Applicable items:",
     ...pack.items.flatMap((item) => [
-      `- ${item.rank}. ${sanitizeOkfText(item.id)} (${item.section}; ${item.sourceType})`,
+      `- ${item.rank}. ${sanitizeOkfText(item.title)} (${item.section}; ${item.sourceType})`,
+      `  Identity: ${sanitizeOkfText(item.id)}`,
+      `  Freshness: ${item.freshness}`,
+      `  Delivery: ${item.delivery.mode}`,
+      ...(item.delivery.excerpt === null
+        ? ["  Guidance: load on demand; do not treat this reference as a standing constraint."]
+        : [`  Guidance: ${sanitizeOkfText(item.delivery.excerpt)}`]),
+      ...(item.loader.kind === "knowledge-show"
+        ? [`  Load: evodev knowledge show ${sanitizeOkfText(item.loader.conceptId)}`]
+        : []),
       `  Source: ${sanitizeOkfText(item.sourceLink)}`,
       `  Match: ${item.matchReasons.length === 0 ? "generic" : item.matchReasons.join(", ")}`,
     ]),
@@ -3293,7 +3631,7 @@ export function formatOkfKnowledgeQuery(result: OkfKnowledgeQueryResult): string
           ? ["- none"]
           : items.map(
               (item) =>
-                `- ${item.summary}\n  Source: ${item.sourceLink}\n  Match: ${item.matchReasons.join(", ")}\n  Rank: ${item.rank}`,
+                `- ${item.summary}\n  Freshness: ${item.freshness}\n  ${item.sourceType === "okf" ? `Load: evodev knowledge show ${item.id}\n  ` : ""}Source: ${item.sourceLink}\n  Match: ${item.matchReasons.join(", ")}\n  Rank: ${item.rank}`,
             )),
         "",
       ];
@@ -3699,6 +4037,19 @@ function extractSummarySection(body: string): string {
   return body.match(/(?:^|\n)# Summary\s*\n+([\s\S]*?)(?=\n# |$)/u)?.[1]?.trim() ?? "";
 }
 
+function createBoundedOkfRuntimeExcerpt(concept: OkfKnowledgeConcept): string {
+  const projection = createOkfKnowledgeRuntimeProjectionFromConcept(concept);
+  return sanitizeOkfText(
+    [
+      projection.summary || concept.description,
+      ...projection.guidance.map((item) => `- ${item}`),
+      ...projection.verification.map((item) => `Verification: ${item}`),
+    ]
+      .filter((item) => item.trim() !== "")
+      .join("\n"),
+  ).slice(0, 1_200);
+}
+
 function scopesOverlap(left: string[], right: string[]): boolean {
   if (left.length === 0 || right.length === 0) return true;
   return left.some((tag) => right.includes(tag));
@@ -3827,8 +4178,41 @@ async function ensureOverlayConcept(input: {
   );
 }
 
-function renderOkfConcept(candidate: OkfKnowledgePlanCandidate, plan: OkfKnowledgePlan): string {
+function renderOkfConcept(
+  candidate: OkfKnowledgePlanCandidate,
+  plan: OkfKnowledgePlan,
+  existing?: OkfKnowledgeConcept,
+): string {
   const scores = resolveCandidateScoresForWrite(candidate);
+  const reviewState = resolveCandidateReviewStateForWrite(candidate);
+  const nextLifecycle = createDefaultOkfLifecycle({
+    type: candidate.okfType,
+    path: candidate.targetPath,
+    tags: [
+      "evodev",
+      candidate.kind,
+      ...candidate.roleTags.map((tag) => `role:${tag}`),
+      ...candidate.repoTags.map((tag) => `repo:${tag}`),
+      ...candidate.workflowTags.map((tag) => `workflow:${tag}`),
+    ],
+    title: candidate.title,
+    reviewState,
+    createdAt: plan.createdAt,
+  });
+  const lifecycle =
+    existing === undefined
+      ? nextLifecycle
+      : {
+          ...nextLifecycle,
+          createdAt: existing.lifecycle.createdAt,
+          supersedes: existing.lifecycle.supersedes,
+          supersededBy: existing.lifecycle.supersededBy,
+        };
+  const verificationSnapshot = createOkfKnowledgeVerificationSnapshot({
+    candidate,
+    verifiedAt: plan.createdAt,
+    projectKey: plan.projectKey,
+  });
   return [
     "---",
     `type: ${yamlString(candidate.okfType)}`,
@@ -3847,24 +4231,9 @@ function renderOkfConcept(candidate: OkfKnowledgePlanCandidate, plan: OkfKnowled
     "evodev:",
     `  schema: ${yamlString("knowledge/v1")}`,
     `  stableKey: ${yamlString(candidate.stableKey)}`,
-    `  reviewState: ${yamlString(resolveCandidateReviewStateForWrite(candidate))}`,
-    renderLifecycleYaml(
-      "  ",
-      createDefaultOkfLifecycle({
-        type: candidate.okfType,
-        path: candidate.targetPath,
-        tags: [
-          "evodev",
-          candidate.kind,
-          ...candidate.roleTags.map((tag) => `role:${tag}`),
-          ...candidate.repoTags.map((tag) => `repo:${tag}`),
-          ...candidate.workflowTags.map((tag) => `workflow:${tag}`),
-        ],
-        title: candidate.title,
-        reviewState: resolveCandidateReviewStateForWrite(candidate),
-        createdAt: plan.createdAt,
-      }),
-    ),
+    `  reviewState: ${yamlString(reviewState)}`,
+    renderLifecycleYaml("  ", lifecycle),
+    renderVerificationSnapshotYaml("  ", verificationSnapshot),
     "  source:",
     `    kind: ${yamlString("trace-distillation")}`,
     `    projectKey: ${yamlString(plan.projectKey)}`,
@@ -3895,17 +4264,27 @@ function renderOkfConcept(candidate: OkfKnowledgePlanCandidate, plan: OkfKnowled
     "",
     candidate.bodySections.summary,
     "",
+    "# Claim",
+    "",
+    candidate.claim,
+    "",
     "# Applies When",
     "",
     renderMarkdownList(candidate.bodySections.appliesWhen),
     "",
+    "# How to Apply",
+    "",
+    candidate.howToApply,
+    "",
     "# Guidance",
     "",
     renderMarkdownList(candidate.bodySections.guidance),
     "",
     "# Anti-Criteria",
     "",
-    renderMarkdownList(candidate.bodySections.antiCriteria),
+    renderMarkdownList(
+      uniqueStrings([...candidate.antiCriteria, ...candidate.bodySections.antiCriteria]),
+    ),
     "",
     "# Verification",
     "",
@@ -4131,6 +4510,7 @@ function parseOkfConceptFile(
     reviewState,
     lifecycle: lifecycleParsed.lifecycle,
     lifecyclePersisted: lifecycleParsed.persisted,
+    verificationSnapshot: parseOkfVerificationSnapshot(frontmatter),
     title,
     description,
     tags,
@@ -4142,6 +4522,22 @@ function parseOkfConceptFile(
   };
 }
 
+function parseOkfVerificationSnapshot(
+  frontmatter: string,
+): OkfKnowledgeVerificationSnapshotV1 | null {
+  const block = extractNestedYamlBlock(frontmatter, "evodev", "verificationSnapshot");
+  if (block === null) return null;
+  const schemaVersion = readIndentedYamlScalar(block, "schemaVersion");
+  const verifiedAt = normalizeIsoDateString(readIndentedYamlScalar(block, "verifiedAt"));
+  if (schemaVersion !== "1" || verifiedAt === null) return null;
+  return {
+    schemaVersion: 1,
+    verifiedAt,
+    evidenceRefs: readYamlList(block, "evidenceRefs"),
+    repository: null,
+  };
+}
+
 function matchesConceptFilters(
   concept: OkfKnowledgeConcept,
   input: { projectKey?: string; roleId?: string; workflowId?: string; paths?: string[] },
@@ -4241,6 +4637,9 @@ function createKnowledgeContextRevision(items: ScopedKnowledgeContextPackItem[])
         sourceLink: item.sourceLink,
         section: item.section,
         title: item.title,
+        freshness: item.freshness,
+        loader: item.loader,
+        delivery: item.delivery,
         matchReasons: item.matchReasons,
       })),
     ),
@@ -4668,8 +5067,11 @@ function readIndentedYamlBoolean(frontmatter: string, key: string): boolean | nu
   return null;
 }
 
-function validateOkfKnowledgePlan(plan: OkfKnowledgePlan): void {
-  assertOkfKnowledgePlanContract(plan);
+function validateOkfKnowledgePlan(
+  plan: OkfKnowledgePlan,
+  options: { allowReviewedHighRisk?: boolean } = {},
+): void {
+  assertOkfKnowledgePlanContract(plan, options);
 }
 
 function validateFailedPlanArtifact(artifact: OkfKnowledgeFailedPlanArtifact): void {
@@ -4887,6 +5289,20 @@ function renderLifecycleYaml(indent: string, lifecycle: OkfKnowledgeLifecycle):
   ].join("\n");
 }
 
+function renderVerificationSnapshotYaml(
+  indent: string,
+  snapshot: OkfKnowledgeVerificationSnapshotV1 | null,
+): string {
+  if (snapshot === null) return `${indent}verificationSnapshot: null`;
+  return [
+    `${indent}verificationSnapshot:`,
+    `${indent}  schemaVersion: 1`,
+    `${indent}  verifiedAt: ${yamlString(snapshot.verifiedAt)}`,
+    renderYamlList(`${indent}  evidenceRefs`, snapshot.evidenceRefs),
+    `${indent}  repository: null`,
+  ].join("\n");
+}
+
 function lifecycleStatusFromReviewState(
   reviewState: OkfKnowledgeReviewState,
 ): OkfKnowledgeLifecycleStatus {