@evo-dev/core 0.0.1-alpha.1 → 0.0.1-alpha.3

package/src/knowledge/index.ts

@@ -0,0 +1,4784 @@
+import { createHash } from "node:crypto";
+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 {
+  type EvolutionDistillationBatch,
+  type EvolutionEvosCase,
+  type EvolutionKnowledgeRecord,
+  listEvolutionEvosCases,
+} from "../evolution/index.ts";
+
+export type OkfKnowledgeDecision =
+  | "auto-accept"
+  | "no_write"
+  | "create"
+  | "update"
+  | "skip"
+  | "needs-human";
+export type OkfKnowledgeTargetStore = "okf" | "repo-asset-proposal" | "evo-eval-set" | "none";
+export type OkfKnowledgeReviewState =
+  | "auto-accepted"
+  | "accepted"
+  | "needs-human"
+  | "rejected"
+  | "deferred"
+  | "stale"
+  | "deprecated"
+  | "revoked"
+  | "superseded"
+  | "auto-stored/unreviewed";
+
+export type OkfKnowledgeLifecycleStatus =
+  | "active"
+  | "stale"
+  | "deprecated"
+  | "revoked"
+  | "superseded";
+
+export interface OkfKnowledgeLifecycle {
+  status: OkfKnowledgeLifecycleStatus;
+  createdAt: string;
+  lastVerifiedAt: string;
+  reviewAfter: string;
+  staleAfter: string;
+  supersedes: string[];
+  supersededBy: string | null;
+  revokedAt: string | null;
+  revokedReason: string | null;
+}
+
+export interface OkfKnowledgeCandidateScores {
+  evidenceStrength: number;
+  reuseValue: number;
+  actionability: number;
+  stability: number;
+  privacyRisk: number;
+  duplicationRisk: number;
+}
+
+export interface OkfKnowledgePrivacyCheck {
+  rawPromptsStored: false;
+  rawLogsStored: false;
+  sourceDumpsStored: false;
+  rawCommandOutputStored: false;
+  secretsStored: false;
+  internalLinksStored: false;
+}
+
+export interface OkfKnowledgeOverlayUpdate {
+  targetPath: string;
+  operation: "append-link";
+  link: string;
+}
+
+export interface OkfKnowledgeEvidenceRef {
+  id: string;
+  kind: string;
+  source: string;
+  rawContentStored: false;
+  externalContentCopied: false;
+}
+
+export interface OkfKnowledgeEvalSet {
+  id: string;
+  target: {
+    kind: string;
+    id: string;
+  };
+  purpose: string;
+  roleTags: string[];
+  cases: Array<{
+    id: string;
+    inputRefs: string[];
+    assertions: string[];
+    expectedReviewState: OkfKnowledgeReviewState;
+  }>;
+  privacy: {
+    usesRawPrompt: false;
+    usesSourceDump: false;
+    usesRawCommandOutput: false;
+  };
+  decision: "create" | "needs-human" | "no_write" | "skip";
+}
+
+export interface OkfKnowledgePlanCandidate {
+  id: string;
+  decision: OkfKnowledgeDecision;
+  kind: string;
+  okfType: string;
+  targetStore: OkfKnowledgeTargetStore;
+  targetPath: string;
+  stableKey: string;
+  confidence: "low" | "medium" | "high";
+  title: string;
+  description: string;
+  claim: string;
+  basis: "direct" | "inferred";
+  metadataOnlyEvidence: boolean;
+  howToApply: string;
+  antiCriteria: string[];
+  roleTags: string[];
+  repoTags: string[];
+  workflowTags: string[];
+  pathScopes: string[];
+  relatedConceptLinks: string[];
+  overlayUpdates: OkfKnowledgeOverlayUpdate[];
+  scores: OkfKnowledgeCandidateScores;
+  decisionReason: string;
+  evidenceRefs: string[];
+  reviewState: OkfKnowledgeReviewState;
+  verificationNotApplicableReason?: string;
+  evalSetRefs?: string[];
+  evalNotApplicableReason?: string;
+  bodySections: {
+    summary: string;
+    appliesWhen: string[];
+    guidance: string[];
+    antiCriteria: string[];
+    verification: string[];
+    citations: string[];
+  };
+  privacyCheck: OkfKnowledgePrivacyCheck;
+}
+
+export interface OkfKnowledgePlan {
+  schemaVersion: 1;
+  kind: "evodev-knowledge-plan";
+  projectKey: string;
+  runId: string;
+  createdAt: string;
+  evidenceWindowId: string;
+  summary: string;
+  evidenceRefs: OkfKnowledgeEvidenceRef[];
+  evoEvalSets: OkfKnowledgeEvalSet[];
+  candidates: OkfKnowledgePlanCandidate[];
+  droppedSignals: Array<{ evidenceRef: string; reason: string }>;
+  conflicts: Array<{ candidateId: string; reason: string }>;
+  privacyCheck: OkfKnowledgePrivacyCheck;
+}
+
+export interface KnowledgeDistillationOutputV1 {
+  schemaVersion: 1;
+  kind: "knowledge-distillation-output";
+  projectKey: string;
+  runId: string;
+  createdAt: string;
+  evidenceWindowId: string;
+  summary?: string;
+  evidenceRefs?: OkfKnowledgeEvidenceRef[];
+  evoEvalSets?: OkfKnowledgeEvalSet[];
+  knowledgeCandidates: Array<Omit<OkfKnowledgePlanCandidate, "decision"> & { decision: string }>;
+  droppedSignals?: Array<{ evidenceRef: string; reason: string }>;
+  conflicts?: Array<{ candidateId: string; reason: string }>;
+  privacyCheck: OkfKnowledgePrivacyCheck;
+}
+
+export interface OkfKnowledgePlanValidationFinding {
+  path: string;
+  code: string;
+  severity: "error" | "warning";
+  message: string;
+}
+
+export interface OkfKnowledgePlanValidationResult {
+  ok: boolean;
+  findings: OkfKnowledgePlanValidationFinding[];
+}
+
+export interface OkfKnowledgeFailedPlanArtifact {
+  schemaVersion: 1;
+  kind: "okf-knowledge-failed-plan";
+  failureKind: "validation" | "organizer";
+  projectKey: string;
+  runId: string;
+  createdAt: string;
+  resumable: boolean;
+  redactedPlan?: unknown;
+  plan?: OkfKnowledgePlan;
+  findings: OkfKnowledgePlanValidationFinding[];
+  error: string;
+}
+
+export interface OkfKnowledgeActivationResult {
+  planPath: string;
+  failedPlanPath: string;
+  evidenceWindowPath: string | null;
+  conceptPaths: string[];
+  overlayPaths: string[];
+  skippedCandidates: string[];
+  needsHumanCandidates: string[];
+  indexPaths: string[];
+  derivedIndexPaths: string[];
+  logPaths: string[];
+}
+
+export interface OkfKnowledgeLifecycleMutationResult {
+  conceptPaths: string[];
+  logPaths: string[];
+  indexPaths: string[];
+}
+
+export interface OkfKnowledgeConcept {
+  id: string;
+  path: string;
+  sourceLink: string;
+  type: string;
+  stableKey: string;
+  reviewState: OkfKnowledgeReviewState;
+  lifecycle: OkfKnowledgeLifecycle;
+  lifecyclePersisted: boolean;
+  title: string;
+  description: string;
+  tags: string[];
+  repoTags: string[];
+  roleTags: string[];
+  workflowTags: string[];
+  pathScopes: string[];
+  body: string;
+}
+
+export interface OkfKnowledgeLintResult {
+  ok: boolean;
+  errors: string[];
+  warnings: string[];
+  conceptCount: number;
+}
+
+export type OkfKnowledgeContextSection =
+  | "applicable-knowledge"
+  | "role-attention"
+  | "repo-attention"
+  | "workflow-attention"
+  | "verification"
+  | "accepted-evos-cases";
+
+export type OkfKnowledgeContextSourceType = "okf" | "evos-case";
+
+export interface OkfKnowledgeContextItem {
+  id: string;
+  sourceType: OkfKnowledgeContextSourceType;
+  sourceLink: string;
+  section: OkfKnowledgeContextSection;
+  rank: number;
+  score?: number;
+  title: string;
+  summary: string;
+  matchReasons: string[];
+}
+
+export interface OkfKnowledgeQueryResult {
+  projectKey?: string;
+  roleId?: string;
+  workflowId?: string;
+  queryText?: string;
+  paths: string[];
+  items: OkfKnowledgeContextItem[];
+  warnings: string[];
+}
+
+export interface LexicalKnowledgeDocument {
+  id: string;
+  sourceType: OkfKnowledgeContextSourceType;
+  sourceLink: string;
+  section: OkfKnowledgeContextSection;
+  title: string;
+  description: string;
+  tags: string[];
+  repoTags: string[];
+  roleTags: string[];
+  workflowTags: string[];
+  pathScopes: string[];
+  stableKey: string;
+  headings: string[];
+  bodySummary: string;
+  safeTokens: string[];
+}
+
+export interface LexicalKnowledgeScore {
+  score: number;
+  reasons: string[];
+}
+
+export interface ScopedKnowledgeContextPackItem {
+  id: string;
+  sourceType: OkfKnowledgeContextSourceType;
+  sourceLink: string;
+  section: OkfKnowledgeContextSection;
+  rank: number;
+  title: string;
+  matchReasons: string[];
+}
+
+export interface ScopedKnowledgeContextPackScope {
+  projectKey?: string;
+  roleId?: string;
+  workflowId?: string;
+  paths: string[];
+}
+
+export interface ScopedKnowledgeContextPack {
+  version: 1;
+  kind: "evodev-scoped-knowledge-context-pack";
+  id: string;
+  okfIndexRevision: string;
+  scope: ScopedKnowledgeContextPackScope;
+  queryText?: string;
+  items: ScopedKnowledgeContextPackItem[];
+  warnings: string[];
+  rawContentStored: false;
+}
+
+export type ContextInjectionTrigger = "team-startup" | "hook-safe-point";
+
+export interface ContextInjectionReceipt {
+  version: 1;
+  contextPackId: string;
+  okfIndexRevision: string;
+  scope: ScopedKnowledgeContextPackScope;
+  itemIds: string[];
+  injectedAt: string;
+  hookEventId: string | null;
+  trigger: ContextInjectionTrigger;
+  rawContentStored: false;
+}
+
+interface OkfPaths {
+  knowledgeDir: string;
+  okfDir: string;
+  indexesDir: string;
+  tmpDir: string;
+}
+
+interface KnowledgeQueryScope {
+  projectKey?: string;
+  roleId?: string;
+  workflowId?: string;
+  paths: string[];
+  hasPathFilter: boolean;
+}
+
+interface OkfContextMatch {
+  reasons: string[];
+  exactMatches: number;
+  overlayMatch: boolean;
+  pathMatch: boolean;
+}
+
+interface RankedOkfContextCandidate {
+  concept: OkfKnowledgeConcept;
+  section: OkfKnowledgeContextSection;
+  score: number;
+  matchReasons: string[];
+}
+
+export interface OkfActiveKnowledgeIndex {
+  concepts: Array<{
+    id: string;
+    sourceLink: string;
+    stableKey: string;
+    reviewState: OkfKnowledgeReviewState;
+    title: string;
+    description: string;
+    type: string;
+    repoTags: string[];
+    roleTags: string[];
+    workflowTags: string[];
+    targetPath: string;
+  }>;
+}
+
+export interface OkfCandidateConflictOrDuplicate {
+  kind: "conflict" | "duplicate";
+  conceptId: string;
+  reason: string;
+}
+
+export interface OkfKnowledgePlanContext {
+  batch: EvolutionDistillationBatch;
+  activeIndex: OkfActiveKnowledgeIndex;
+}
+
+const RESERVED_OKF_FILENAMES = new Set(["index.md", "log.md"]);
+const FORBIDDEN_OKF_TEXT =
+  /\b(secret|token|password|passwd|api[_-]?key|apikey|credential|credentials|secret[\s_-]*token(?:[\s_-]*repro)?|raw[\s_-]*(?:log|logs|output|source|prompt)(?:[\s_-]*repro)?|shell[\s_-]*history|command[\s_-]*history)\b/i;
+const FORBIDDEN_OKF_FIELD =
+  /^\s*(?:commandHistory|commandOutput|credential|credentials|env|memoryBody|password|privateKey|prompt|promptBody|promptText|rawCommand|rawCommandOutput|rawLog|rawLogs|rawOutput|rawPayload|rawPrompt|secret|secretValue|sourceBody|sourceCode|sourceContent|sourceText|stderr|stdout|token|transcript|transcriptBody|transcriptText)\s*:/im;
+const PRIVATE_OR_INTERNAL_URL =
+  /https?:\/\/\S*(?:internal|private|corp|localhost|127\.0\.0\.1)\S*/i;
+const HUMAN_REVIEW_DOMAIN_PATTERN =
+  /(^|[^a-z0-9])(?:security|privacy|release|architecture|cross[\s_-]*(?:repo|repository)|model[\s_-]*reflection|reflection[\s_-]*based)([^a-z0-9]|$)/i;
+const OKF_PRIVACY_FLAG_KEYS = [
+  "rawPromptsStored",
+  "rawLogsStored",
+  "sourceDumpsStored",
+  "rawCommandOutputStored",
+  "secretsStored",
+  "internalLinksStored",
+] as const;
+const OKF_QUERY_PRIVACY_FLAG_KEYS = [
+  ...OKF_PRIVACY_FLAG_KEYS,
+  "rawOutputStored",
+  "sourceContentStored",
+] as const;
+const ACTIVE_OKF_REVIEW_STATES: readonly OkfKnowledgeReviewState[] = ["accepted", "auto-accepted"];
+const OKF_REVIEW_STATES: readonly OkfKnowledgeReviewState[] = [
+  "auto-accepted",
+  "accepted",
+  "needs-human",
+  "rejected",
+  "deferred",
+  "stale",
+  "deprecated",
+  "revoked",
+  "superseded",
+  "auto-stored/unreviewed",
+];
+const OKF_LIFECYCLE_STATUSES: readonly OkfKnowledgeLifecycleStatus[] = [
+  "active",
+  "stale",
+  "deprecated",
+  "revoked",
+  "superseded",
+];
+const OKF_DECISIONS: readonly OkfKnowledgeDecision[] = [
+  "auto-accept",
+  "no_write",
+  "create",
+  "update",
+  "skip",
+  "needs-human",
+];
+const ACTIVE_OKF_DECISIONS: readonly OkfKnowledgeDecision[] = ["auto-accept", "create", "update"];
+const BEHAVIOR_CHANGE_KINDS = new Set([
+  "skill-improvement",
+  "role-agent-suggestion",
+  "team-suggestion",
+  "workflow-improvement",
+  "task-split-improvement",
+  "tool-use-improvement",
+  "repo-asset-suggestion",
+]);
+const DEFAULT_OKF_CANDIDATE_SCORES: OkfKnowledgeCandidateScores = {
+  evidenceStrength: 1,
+  reuseValue: 1,
+  actionability: 1,
+  stability: 1,
+  privacyRisk: 5,
+  duplicationRisk: 1,
+};
+
+export function resolveOkfKnowledgePaths(homeDir: string): OkfPaths {
+  const paths = resolveEvoDevPaths(homeDir);
+  return {
+    knowledgeDir: paths.knowledgeDir,
+    okfDir: join(paths.knowledgeDir, "okf"),
+    indexesDir: join(paths.knowledgeDir, "indexes"),
+    tmpDir: join(paths.knowledgeDir, "tmp"),
+  };
+}
+
+export async function ensureOkfKnowledgeBase(homeDir: string): Promise<void> {
+  const paths = resolveOkfKnowledgePaths(homeDir);
+  await ensureLocalKnowledgeGitRepository(paths.knowledgeDir);
+  await mkdir(paths.indexesDir, { recursive: true });
+  await mkdir(paths.tmpDir, { recursive: true });
+
+  const directories = [
+    {
+      path: "",
+      title: "EvoDev Knowledge",
+      description: "User-local active engineering knowledge.",
+    },
+    { path: "concepts", title: "Core Concepts", description: "Canonical core knowledge." },
+    { path: "concepts/rules", title: "Rules", description: "Normative engineering rules." },
+    {
+      path: "concepts/decisions",
+      title: "Decisions",
+      description: "Durable engineering decisions.",
+    },
+    { path: "concepts/patterns", title: "Patterns", description: "Reusable engineering patterns." },
+    { path: "concepts/warnings", title: "Warnings", description: "Risks and anti-patterns." },
+    { path: "concepts/checklists", title: "Checklists", description: "Verification checklists." },
+    {
+      path: "concepts/verification",
+      title: "Verification",
+      description: "Repeatable verification patterns.",
+    },
+    { path: "concepts/evos", title: "Evolution Cases", description: "Reviewed evolution cases." },
+    { path: "concepts/glossary", title: "Glossary", description: "Terms and taxonomy notes." },
+    { path: "repos", title: "Repositories", description: "Repository attention overlays." },
+    { path: "roles", title: "Roles", description: "Role attention overlays." },
+    { path: "workflows", title: "Workflows", description: "Workflow attention overlays." },
+    { path: "references", title: "References", description: "Cited references." },
+  ];
+
+  for (const directory of directories) {
+    await ensureOkfDirectory(paths.okfDir, directory.path, directory.title, directory.description);
+  }
+  await rebuildOkfKnowledgeIndexes({ homeDir });
+}
+
+export function createOkfKnowledgePlanFromDistillationBatch(
+  batch: EvolutionDistillationBatch,
+  options: { homeDir?: string } = {},
+): OkfKnowledgePlan {
+  const activeIndex =
+    options.homeDir === undefined
+      ? { concepts: [] }
+      : loadActiveOkfKnowledgeIndex({ homeDir: options.homeDir });
+  const planContext: OkfKnowledgePlanContext = { batch, activeIndex };
+  const knowledgeCandidates = batch.knowledgeRecords.map((record) =>
+    decideOkfKnowledgeCandidate(createCandidateFromKnowledgeRecord(record, batch), planContext),
+  );
+  const evosCandidates = batch.evosCases.map((evosCase) =>
+    decideOkfKnowledgeCandidate(createCandidateFromEvosCase(evosCase), planContext),
+  );
+  const rawCandidates = [...knowledgeCandidates, ...evosCandidates];
+  const { candidates, evoEvalSets } = attachGeneratedEvalSetsForBehaviorChanges(
+    rawCandidates,
+    batch,
+  );
+  const evidenceRefs = batch.evidenceWindow.sourceRefs.map<OkfKnowledgeEvidenceRef>(
+    (sourceRef) => ({
+      id: sourceRef.id,
+      kind: sourceRef.kind,
+      source: sourceRef.path,
+      rawContentStored: false,
+      externalContentCopied: sourceRef.externalContentCopied,
+    }),
+  );
+  return {
+    schemaVersion: 1,
+    kind: "evodev-knowledge-plan",
+    projectKey: sanitizeSlug(batch.projectKey),
+    runId: sanitizeSlug(batch.runId),
+    createdAt: batch.createdAt,
+    evidenceWindowId: batch.evidenceWindow.id,
+    summary:
+      candidates.length === 0
+        ? "No reusable OKF knowledge candidate was selected from this evidence window."
+        : `Selected ${candidates.length} reusable OKF knowledge candidate(s).`,
+    evidenceRefs,
+    evoEvalSets,
+    candidates,
+    droppedSignals: batch.evidenceWindow.events.slice(0, 20).map((event) => ({
+      evidenceRef: event.id,
+      reason:
+        candidates.length === 0
+          ? "No reusable verified knowledge candidate met the activation threshold."
+          : "Routine metadata retained only as evidence signal.",
+    })),
+    conflicts: candidates.flatMap((candidate) =>
+      /conflict|duplicate/i.test(candidate.decisionReason)
+        ? [{ candidateId: candidate.id, reason: candidate.decisionReason }]
+        : [],
+    ),
+    privacyCheck: createOkfPrivacyCheck(),
+  };
+}
+
+function attachGeneratedEvalSetsForBehaviorChanges(
+  candidates: OkfKnowledgePlanCandidate[],
+  batch: EvolutionDistillationBatch,
+): { candidates: OkfKnowledgePlanCandidate[]; evoEvalSets: OkfKnowledgeEvalSet[] } {
+  const evoEvalSets: OkfKnowledgeEvalSet[] = [];
+  const updatedCandidates = candidates.map((candidate) => {
+    if (
+      !ACTIVE_OKF_DECISIONS.includes(candidate.decision) ||
+      !isBehaviorChangeCandidate(candidate)
+    ) {
+      return candidate;
+    }
+    const evalSet = createGeneratedBehaviorChangeEvalSet(candidate, batch);
+    evoEvalSets.push(evalSet);
+    return {
+      ...candidate,
+      evalSetRefs: [...new Set([...(candidate.evalSetRefs ?? []), evalSet.id])],
+    };
+  });
+  return { candidates: updatedCandidates, evoEvalSets };
+}
+
+function createGeneratedBehaviorChangeEvalSet(
+  candidate: OkfKnowledgePlanCandidate,
+  batch: EvolutionDistillationBatch,
+): OkfKnowledgeEvalSet {
+  const evalId = `eval-${sanitizeSlug(candidate.id).replace(/[._/-]+/gu, "-")}`;
+  const inputRefs =
+    candidate.evidenceRefs.length > 0
+      ? candidate.evidenceRefs
+      : batch.evidenceWindow.sourceRefs.map((sourceRef) => sourceRef.id);
+  return {
+    id: evalId,
+    target: {
+      kind: candidate.kind,
+      id: candidate.id,
+    },
+    purpose: `Guard behavior-changing active OKF write for ${candidate.id}.`,
+    roleTags: candidate.roleTags,
+    cases: [
+      {
+        id: `${evalId}-case-1`,
+        inputRefs,
+        assertions: [
+          "Candidate uses metadata-only evidence.",
+          "Candidate remains scoped and review-state gated before runtime use.",
+        ],
+        expectedReviewState: candidate.reviewState,
+      },
+    ],
+    privacy: {
+      usesRawPrompt: false,
+      usesSourceDump: false,
+      usesRawCommandOutput: false,
+    },
+    decision: "create",
+  };
+}
+
+export function parseKnowledgeDistillationOutput(
+  value: unknown,
+  options: { homeDir?: string } = {},
+): OkfKnowledgePlan {
+  const output = assertRecordValue(value, "output") as Partial<KnowledgeDistillationOutputV1>;
+  if (output.schemaVersion !== 1) {
+    throw new Error("Knowledge distillation output schemaVersion must be 1.");
+  }
+  if (output.kind !== "knowledge-distillation-output") {
+    throw new Error("Knowledge distillation output kind is invalid.");
+  }
+  if (!Array.isArray(output.knowledgeCandidates)) {
+    throw new Error("Knowledge distillation output knowledgeCandidates must be an array.");
+  }
+
+  const plan: OkfKnowledgePlan = {
+    schemaVersion: 1,
+    kind: "evodev-knowledge-plan",
+    projectKey: readRequiredString(output.projectKey, "projectKey"),
+    runId: readRequiredString(output.runId, "runId"),
+    createdAt: readRequiredString(output.createdAt, "createdAt"),
+    evidenceWindowId: readRequiredString(output.evidenceWindowId, "evidenceWindowId"),
+    summary:
+      typeof output.summary === "string"
+        ? sanitizeOkfText(output.summary)
+        : `Parsed ${output.knowledgeCandidates.length} knowledge candidate(s).`,
+    evidenceRefs: normalizeEvidenceRefs(output.evidenceRefs ?? []),
+    evoEvalSets: normalizeEvalSets(output.evoEvalSets ?? []),
+    candidates: output.knowledgeCandidates.map((candidate, index) =>
+      normalizePlanCandidate(candidate, `knowledgeCandidates[${index}]`),
+    ),
+    droppedSignals: normalizeDroppedSignals(output.droppedSignals ?? []),
+    conflicts: normalizeConflicts(output.conflicts ?? []),
+    privacyCheck: normalizePrivacyCheck(output.privacyCheck, "privacyCheck"),
+  };
+  assertOkfKnowledgePlanContract(plan, { homeDir: options.homeDir });
+  return plan;
+}
+
+export function validateOkfKnowledgePlanContract(
+  plan: OkfKnowledgePlan,
+  _options: { homeDir?: string } = {},
+): OkfKnowledgePlanValidationResult {
+  const findings: OkfKnowledgePlanValidationFinding[] = [];
+  const add = (
+    path: string,
+    code: string,
+    message: string,
+    severity: "error" | "warning" = "error",
+  ) => {
+    findings.push({ path, code, severity, message });
+  };
+
+  if (!isRecord(plan)) {
+    add("$", "plan.object", "Plan must be an object.");
+    return { ok: false, findings };
+  }
+  if (plan.schemaVersion !== 1)
+    add("schemaVersion", "plan.schemaVersion", "Plan schemaVersion must be 1.");
+  if (plan.kind !== "evodev-knowledge-plan") add("kind", "plan.kind", "Plan kind is invalid.");
+  if (!isNonEmptyString(plan.projectKey))
+    add("projectKey", "plan.projectKey", "Project key is required.");
+  if (!isNonEmptyString(plan.runId)) add("runId", "plan.runId", "Run id is required.");
+  if (!isNonEmptyString(plan.createdAt))
+    add("createdAt", "plan.createdAt", "Created timestamp is required.");
+  if (!isNonEmptyString(plan.evidenceWindowId)) {
+    add("evidenceWindowId", "plan.evidenceWindowId", "Evidence window id is required.");
+  }
+  validatePrivacyCheckValue(plan.privacyCheck, "privacyCheck", add);
+
+  if (!Array.isArray(plan.evidenceRefs)) {
+    add("evidenceRefs", "plan.evidenceRefs", "Plan evidenceRefs must be an array.");
+  } else {
+    plan.evidenceRefs.forEach((evidenceRef, index) =>
+      validateEvidenceRefValue(evidenceRef, `evidenceRefs[${index}]`, add),
+    );
+  }
+
+  if (!Array.isArray(plan.evoEvalSets)) {
+    add("evoEvalSets", "plan.evoEvalSets", "Plan evoEvalSets must be an array.");
+  } else {
+    plan.evoEvalSets.forEach((evalSet, index) =>
+      validateEvalSetValue(evalSet, `evoEvalSets[${index}]`, add),
+    );
+  }
+  const evalSetIds = new Set(
+    (Array.isArray(plan.evoEvalSets) ? plan.evoEvalSets : []).map((evalSet) => evalSet.id),
+  );
+
+  if (!Array.isArray(plan.candidates)) {
+    add("candidates", "plan.candidates", "Plan candidates must be an array.");
+  } else {
+    plan.candidates.forEach((candidate, index) =>
+      validateCandidateContract(candidate, `candidates[${index}]`, evalSetIds, add),
+    );
+  }
+
+  if (Array.isArray(plan.droppedSignals)) {
+    plan.droppedSignals.forEach((signal, index) => {
+      if (!isRecord(signal))
+        add(`droppedSignals[${index}]`, "signal.object", "Dropped signal must be an object.");
+      if (!isNonEmptyString(signal?.evidenceRef)) {
+        add(
+          `droppedSignals[${index}].evidenceRef`,
+          "signal.evidenceRef",
+          "Dropped signal evidenceRef is required.",
+        );
+      }
+      if (!isNonEmptyString(signal?.reason))
+        add(
+          `droppedSignals[${index}].reason`,
+          "signal.reason",
+          "Dropped signal reason is required.",
+        );
+    });
+  } else {
+    add("droppedSignals", "plan.droppedSignals", "Plan droppedSignals must be an array.");
+  }
+
+  if (Array.isArray(plan.conflicts)) {
+    plan.conflicts.forEach((conflict, index) => {
+      if (!isRecord(conflict))
+        add(`conflicts[${index}]`, "conflict.object", "Conflict must be an object.");
+      if (!isNonEmptyString(conflict?.candidateId)) {
+        add(
+          `conflicts[${index}].candidateId`,
+          "conflict.candidateId",
+          "Conflict candidateId is required.",
+        );
+      }
+      if (!isNonEmptyString(conflict?.reason))
+        add(`conflicts[${index}].reason`, "conflict.reason", "Conflict reason is required.");
+    });
+  } else {
+    add("conflicts", "plan.conflicts", "Plan conflicts must be an array.");
+  }
+
+  return {
+    ok: findings.every((finding) => finding.severity !== "error"),
+    findings,
+  };
+}
+
+export function assertOkfKnowledgePlanContract(
+  plan: OkfKnowledgePlan,
+  options: { homeDir?: string } = {},
+): void {
+  const result = validateOkfKnowledgePlanContract(plan, options);
+  if (!result.ok) {
+    const errorCount = result.findings.filter((finding) => finding.severity === "error").length;
+    throw new Error(`OKF knowledge plan contract validation failed with ${errorCount} error(s).`);
+  }
+}
+
+function normalizePlanCandidate(value: unknown, path: string): OkfKnowledgePlanCandidate {
+  const input = assertRecordValue(value, path) as Record<string, unknown>;
+  const decision = normalizeDecision(readRequiredString(input.decision, `${path}.decision`));
+  const candidate: OkfKnowledgePlanCandidate = {
+    id: sanitizeOkfText(readRequiredString(input.id, `${path}.id`)),
+    decision,
+    kind: sanitizeOkfText(readRequiredString(input.kind, `${path}.kind`)),
+    okfType: sanitizeOkfText(readRequiredString(input.okfType, `${path}.okfType`)),
+    targetStore: normalizeTargetStore(readRequiredString(input.targetStore, `${path}.targetStore`)),
+    targetPath: sanitizeOkfText(readRequiredString(input.targetPath, `${path}.targetPath`)),
+    stableKey: sanitizeOkfText(readRequiredString(input.stableKey, `${path}.stableKey`)),
+    confidence: normalizeConfidence(readRequiredString(input.confidence, `${path}.confidence`)),
+    title: sanitizeOkfText(readRequiredString(input.title, `${path}.title`)),
+    description: sanitizeOkfText(readRequiredString(input.description, `${path}.description`)),
+    claim: sanitizeOkfText(readRequiredString(input.claim, `${path}.claim`)),
+    basis: normalizeBasis(readRequiredString(input.basis, `${path}.basis`)),
+    metadataOnlyEvidence: readRequiredBoolean(
+      input.metadataOnlyEvidence,
+      `${path}.metadataOnlyEvidence`,
+    ),
+    howToApply: sanitizeOkfText(readRequiredString(input.howToApply, `${path}.howToApply`)),
+    antiCriteria: readStringArray(input.antiCriteria, `${path}.antiCriteria`).map(sanitizeOkfText),
+    roleTags: readStringArray(input.roleTags, `${path}.roleTags`).map(sanitizeOkfText),
+    repoTags: readStringArray(input.repoTags, `${path}.repoTags`).map(sanitizeOkfText),
+    workflowTags: readStringArray(input.workflowTags, `${path}.workflowTags`).map(sanitizeOkfText),
+    pathScopes: readStringArray(input.pathScopes, `${path}.pathScopes`).map(sanitizeOkfText),
+    relatedConceptLinks: readStringArray(
+      input.relatedConceptLinks,
+      `${path}.relatedConceptLinks`,
+    ).map(sanitizeOkfText),
+    overlayUpdates: readOverlayUpdates(input.overlayUpdates, `${path}.overlayUpdates`),
+    scores: normalizeScores(input.scores, `${path}.scores`),
+    decisionReason: sanitizeOkfText(
+      readRequiredString(input.decisionReason, `${path}.decisionReason`),
+    ),
+    evidenceRefs: readStringArray(input.evidenceRefs, `${path}.evidenceRefs`).map(sanitizeOkfText),
+    reviewState: parseOkfReviewState(readRequiredString(input.reviewState, `${path}.reviewState`)),
+    verificationNotApplicableReason:
+      typeof input.verificationNotApplicableReason === "string"
+        ? sanitizeOkfText(input.verificationNotApplicableReason)
+        : undefined,
+    evalSetRefs:
+      input.evalSetRefs === undefined
+        ? undefined
+        : readStringArray(input.evalSetRefs, `${path}.evalSetRefs`).map(sanitizeOkfText),
+    evalNotApplicableReason:
+      typeof input.evalNotApplicableReason === "string"
+        ? sanitizeOkfText(input.evalNotApplicableReason)
+        : undefined,
+    bodySections: normalizeBodySections(input.bodySections, `${path}.bodySections`),
+    privacyCheck: normalizePrivacyCheck(input.privacyCheck, `${path}.privacyCheck`),
+  };
+  return candidate;
+}
+
+function validateCandidateContract(
+  candidate: unknown,
+  path: string,
+  evalSetIds: Set<string>,
+  add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+): void {
+  if (!isRecord(candidate)) {
+    add(path, "candidate.object", "Candidate must be an object.");
+    return;
+  }
+  const decision = candidate.decision;
+  const activeWrite =
+    typeof decision === "string" && ACTIVE_OKF_DECISIONS.includes(decision as OkfKnowledgeDecision);
+  const noOp = decision === "no_write" || decision === "skip";
+
+  for (const key of [
+    "id",
+    "kind",
+    "okfType",
+    "targetStore",
+    "targetPath",
+    "stableKey",
+    "confidence",
+    "title",
+    "description",
+    "claim",
+    "basis",
+    "howToApply",
+    "decisionReason",
+    "reviewState",
+  ]) {
+    if (!isNonEmptyString(candidate[key]))
+      add(`${path}.${key}`, `candidate.${key}`, `Candidate ${key} is required.`);
+  }
+  if (!OKF_DECISIONS.includes(decision as OkfKnowledgeDecision)) {
+    add(`${path}.decision`, "candidate.decision", "Candidate decision is invalid.");
+  }
+  if (
+    !["okf", "repo-asset-proposal", "evo-eval-set", "none"].includes(String(candidate.targetStore))
+  ) {
+    add(`${path}.targetStore`, "candidate.targetStore", "Candidate targetStore is invalid.");
+  }
+  if (!["low", "medium", "high"].includes(String(candidate.confidence))) {
+    add(`${path}.confidence`, "candidate.confidence", "Candidate confidence is invalid.");
+  }
+  if (candidate.basis !== "direct" && candidate.basis !== "inferred") {
+    add(`${path}.basis`, "candidate.basis", "Candidate basis is invalid.");
+  }
+  if (typeof candidate.metadataOnlyEvidence !== "boolean") {
+    add(
+      `${path}.metadataOnlyEvidence`,
+      "candidate.metadataOnlyEvidence",
+      "Candidate metadataOnlyEvidence must be boolean.",
+    );
+  }
+  validateStringArrayValue(candidate.antiCriteria, `${path}.antiCriteria`, add);
+  validateStringArrayValue(candidate.roleTags, `${path}.roleTags`, add);
+  validateStringArrayValue(candidate.repoTags, `${path}.repoTags`, add);
+  validateStringArrayValue(candidate.workflowTags, `${path}.workflowTags`, add);
+  validateStringArrayValue(candidate.pathScopes, `${path}.pathScopes`, add);
+  validateStringArrayValue(candidate.relatedConceptLinks, `${path}.relatedConceptLinks`, add);
+  validateStringArrayValue(candidate.evidenceRefs, `${path}.evidenceRefs`, add);
+  validateOverlayUpdatesValue(candidate.overlayUpdates, `${path}.overlayUpdates`, add);
+  validateScoresValue(candidate.scores, `${path}.scores`, add);
+  validatePrivacyCheckValue(candidate.privacyCheck, `${path}.privacyCheck`, add);
+  validateBodySectionsValue(candidate.bodySections, `${path}.bodySections`, add);
+  validateTargetPathValue(candidate.targetPath, `${path}.targetPath`, activeWrite, add);
+
+  if (
+    candidate.reviewState !== undefined &&
+    !OKF_REVIEW_STATES.includes(candidate.reviewState as OkfKnowledgeReviewState)
+  ) {
+    add(`${path}.reviewState`, "candidate.reviewState", "Candidate reviewState is invalid.");
+  }
+  if (activeWrite) {
+    if (candidate.targetStore !== "okf") {
+      add(`${path}.targetStore`, "candidate.active.targetStore", "Active writes must target OKF.");
+    }
+    if (candidate.reviewState !== "accepted" && candidate.reviewState !== "auto-accepted") {
+      add(
+        `${path}.reviewState`,
+        "candidate.active.reviewState",
+        "Active writes require an active-compatible reviewState.",
+      );
+    }
+    if (candidate.metadataOnlyEvidence !== true) {
+      add(
+        `${path}.metadataOnlyEvidence`,
+        "candidate.active.metadataOnlyEvidence",
+        "Active writes require metadata-only evidence.",
+      );
+    }
+    if (hasHighRiskHumanReviewSignal(candidate)) {
+      add(
+        path,
+        "candidate.active.highRiskHumanReview",
+        "High-risk active writes require human review before OKF writes.",
+      );
+    }
+    if (!Array.isArray(candidate.evidenceRefs) || candidate.evidenceRefs.length === 0) {
+      add(
+        `${path}.evidenceRefs`,
+        "candidate.active.evidenceRefs",
+        "Active writes require 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.active.verification",
+        "Active writes require verification or an explicit not-applicable reason.",
+      );
+    }
+    if (isBehaviorChangeCandidate(candidate)) {
+      const evalRefs = Array.isArray(candidate.evalSetRefs) ? candidate.evalSetRefs : [];
+      if (evalRefs.length === 0) {
+        add(
+          `${path}.evalSetRefs`,
+          "candidate.active.evalSetRefs",
+          "Behavior-change active writes require evalSetRefs.",
+        );
+      }
+      for (const evalRef of evalRefs) {
+        if (typeof evalRef !== "string" || !evalSetIds.has(evalRef)) {
+          add(
+            `${path}.evalSetRefs`,
+            "candidate.active.evalSetRefs.missing",
+            "Behavior-change evalSetRef must point to a provided eval set.",
+          );
+        }
+      }
+    }
+  }
+
+  if (decision === "needs-human") {
+    if (
+      !isNonEmptyString(candidate.id) ||
+      !isNonEmptyString(candidate.title) ||
+      !isNonEmptyString(candidate.decisionReason)
+    ) {
+      add(
+        path,
+        "candidate.needsHuman.metadata",
+        "Needs-human candidates require safe queue metadata.",
+      );
+    }
+  }
+  if (noOp && (!isNonEmptyString(candidate.id) || !isNonEmptyString(candidate.decisionReason))) {
+    add(path, "candidate.noop.metadata", "No-op candidates require safe skip metadata.");
+  }
+  if (hasUnsafeCandidateContent(candidate as unknown as OkfKnowledgePlanCandidate)) {
+    add(path, "candidate.privacy.unsafe", "Candidate contains unsafe raw or sensitive content.");
+  }
+}
+
+function normalizeEvidenceRefs(values: unknown): OkfKnowledgeEvidenceRef[] {
+  if (!Array.isArray(values)) throw new Error("evidenceRefs must be an array.");
+  return values.map((value, index) => {
+    const input = assertRecordValue(value, `evidenceRefs[${index}]`) as Record<string, unknown>;
+    return {
+      id: sanitizeOkfText(readRequiredString(input.id, `evidenceRefs[${index}].id`)),
+      kind: sanitizeOkfText(readRequiredString(input.kind, `evidenceRefs[${index}].kind`)),
+      source: sanitizeOkfText(readRequiredString(input.source, `evidenceRefs[${index}].source`)),
+      rawContentStored: readRequiredFalse(
+        input.rawContentStored,
+        `evidenceRefs[${index}].rawContentStored`,
+      ),
+      externalContentCopied: readRequiredFalse(
+        input.externalContentCopied,
+        `evidenceRefs[${index}].externalContentCopied`,
+      ),
+    };
+  });
+}
+
+function normalizeEvalSets(values: unknown): OkfKnowledgeEvalSet[] {
+  if (!Array.isArray(values)) throw new Error("evoEvalSets must be an array.");
+  return values.map((value, index) => {
+    const input = assertRecordValue(value, `evoEvalSets[${index}]`) as Record<string, unknown>;
+    const target = assertRecordValue(input.target, `evoEvalSets[${index}].target`) as Record<
+      string,
+      unknown
+    >;
+    const privacy = assertRecordValue(input.privacy, `evoEvalSets[${index}].privacy`) as Record<
+      string,
+      unknown
+    >;
+    const decision = normalizeEvalSetDecision(
+      readRequiredString(input.decision, `evoEvalSets[${index}].decision`),
+    );
+    return {
+      id: sanitizeOkfText(readRequiredString(input.id, `evoEvalSets[${index}].id`)),
+      target: {
+        kind: sanitizeOkfText(readRequiredString(target.kind, `evoEvalSets[${index}].target.kind`)),
+        id: sanitizeOkfText(readRequiredString(target.id, `evoEvalSets[${index}].target.id`)),
+      },
+      purpose: sanitizeOkfText(readRequiredString(input.purpose, `evoEvalSets[${index}].purpose`)),
+      roleTags: readStringArray(input.roleTags, `evoEvalSets[${index}].roleTags`).map(
+        sanitizeOkfText,
+      ),
+      cases: readEvalSetCases(input.cases, `evoEvalSets[${index}].cases`),
+      privacy: {
+        usesRawPrompt: readRequiredFalse(
+          privacy.usesRawPrompt,
+          `evoEvalSets[${index}].privacy.usesRawPrompt`,
+        ),
+        usesSourceDump: readRequiredFalse(
+          privacy.usesSourceDump,
+          `evoEvalSets[${index}].privacy.usesSourceDump`,
+        ),
+        usesRawCommandOutput: readRequiredFalse(
+          privacy.usesRawCommandOutput,
+          `evoEvalSets[${index}].privacy.usesRawCommandOutput`,
+        ),
+      },
+      decision,
+    };
+  });
+}
+
+function readEvalSetCases(value: unknown, path: string): OkfKnowledgeEvalSet["cases"] {
+  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
+  return value.map((item, index) => {
+    const input = assertRecordValue(item, `${path}[${index}]`) as Record<string, unknown>;
+    return {
+      id: sanitizeOkfText(readRequiredString(input.id, `${path}[${index}].id`)),
+      inputRefs: readStringArray(input.inputRefs, `${path}[${index}].inputRefs`).map(
+        sanitizeOkfText,
+      ),
+      assertions: readStringArray(input.assertions, `${path}[${index}].assertions`).map(
+        sanitizeOkfText,
+      ),
+      expectedReviewState: parseOkfReviewState(
+        readRequiredString(input.expectedReviewState, `${path}[${index}].expectedReviewState`),
+      ),
+    };
+  });
+}
+
+function normalizeDroppedSignals(values: unknown): Array<{ evidenceRef: string; reason: string }> {
+  if (!Array.isArray(values)) throw new Error("droppedSignals must be an array.");
+  return values.map((value, index) => {
+    const input = assertRecordValue(value, `droppedSignals[${index}]`) as Record<string, unknown>;
+    return {
+      evidenceRef: sanitizeOkfText(
+        readRequiredString(input.evidenceRef, `droppedSignals[${index}].evidenceRef`),
+      ),
+      reason: sanitizeOkfText(readRequiredString(input.reason, `droppedSignals[${index}].reason`)),
+    };
+  });
+}
+
+function normalizeConflicts(values: unknown): Array<{ candidateId: string; reason: string }> {
+  if (!Array.isArray(values)) throw new Error("conflicts must be an array.");
+  return values.map((value, index) => {
+    const input = assertRecordValue(value, `conflicts[${index}]`) as Record<string, unknown>;
+    return {
+      candidateId: sanitizeOkfText(
+        readRequiredString(input.candidateId, `conflicts[${index}].candidateId`),
+      ),
+      reason: sanitizeOkfText(readRequiredString(input.reason, `conflicts[${index}].reason`)),
+    };
+  });
+}
+
+function normalizeBodySections(
+  value: unknown,
+  path: string,
+): OkfKnowledgePlanCandidate["bodySections"] {
+  const input = assertRecordValue(value, path) as Record<string, unknown>;
+  return {
+    summary: sanitizeOkfText(readRequiredString(input.summary, `${path}.summary`)),
+    appliesWhen: readStringArray(input.appliesWhen, `${path}.appliesWhen`).map(sanitizeOkfText),
+    guidance: readStringArray(input.guidance, `${path}.guidance`).map(sanitizeOkfText),
+    antiCriteria: readStringArray(input.antiCriteria, `${path}.antiCriteria`).map(sanitizeOkfText),
+    verification: readStringArray(input.verification, `${path}.verification`).map(sanitizeOkfText),
+    citations: readStringArray(input.citations, `${path}.citations`).map(sanitizeOkfText),
+  };
+}
+
+function normalizePrivacyCheck(value: unknown, path: string): OkfKnowledgePrivacyCheck {
+  const input = assertRecordValue(value, path) as Record<string, unknown>;
+  return {
+    rawPromptsStored: readRequiredFalse(input.rawPromptsStored, `${path}.rawPromptsStored`),
+    rawLogsStored: readRequiredFalse(input.rawLogsStored, `${path}.rawLogsStored`),
+    sourceDumpsStored: readRequiredFalse(input.sourceDumpsStored, `${path}.sourceDumpsStored`),
+    rawCommandOutputStored: readRequiredFalse(
+      input.rawCommandOutputStored,
+      `${path}.rawCommandOutputStored`,
+    ),
+    secretsStored: readRequiredFalse(input.secretsStored, `${path}.secretsStored`),
+    internalLinksStored: readRequiredFalse(
+      input.internalLinksStored,
+      `${path}.internalLinksStored`,
+    ),
+  };
+}
+
+function normalizeScores(value: unknown, path: string): OkfKnowledgeCandidateScores {
+  const input = assertRecordValue(value, path) as Record<string, unknown>;
+  return {
+    evidenceStrength: readScore(input.evidenceStrength, `${path}.evidenceStrength`),
+    reuseValue: readScore(input.reuseValue, `${path}.reuseValue`),
+    actionability: readScore(input.actionability, `${path}.actionability`),
+    stability: readScore(input.stability, `${path}.stability`),
+    privacyRisk: readScore(input.privacyRisk, `${path}.privacyRisk`),
+    duplicationRisk: readScore(input.duplicationRisk, `${path}.duplicationRisk`),
+  };
+}
+
+function readOverlayUpdates(value: unknown, path: string): OkfKnowledgeOverlayUpdate[] {
+  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
+  return value.map((item, index) => {
+    const input = assertRecordValue(item, `${path}[${index}]`) as Record<string, unknown>;
+    return {
+      targetPath: sanitizeOkfText(
+        readRequiredString(input.targetPath, `${path}[${index}].targetPath`),
+      ),
+      operation: "append-link",
+      link: sanitizeOkfText(readRequiredString(input.link, `${path}[${index}].link`)),
+    };
+  });
+}
+
+function normalizeDecision(value: string): OkfKnowledgeDecision {
+  const normalized = value === "no-write" ? "no_write" : value;
+  if (!OKF_DECISIONS.includes(normalized as OkfKnowledgeDecision)) {
+    throw new Error("Candidate decision is invalid.");
+  }
+  return normalized as OkfKnowledgeDecision;
+}
+
+function normalizeTargetStore(value: string): OkfKnowledgeTargetStore {
+  if (!["okf", "repo-asset-proposal", "evo-eval-set", "none"].includes(value)) {
+    throw new Error("Candidate targetStore is invalid.");
+  }
+  return value as OkfKnowledgeTargetStore;
+}
+
+function normalizeConfidence(value: string): "low" | "medium" | "high" {
+  if (value !== "low" && value !== "medium" && value !== "high") {
+    throw new Error("Candidate confidence is invalid.");
+  }
+  return value;
+}
+
+function normalizeBasis(value: string): "direct" | "inferred" {
+  if (value !== "direct" && value !== "inferred") throw new Error("Candidate basis is invalid.");
+  return value;
+}
+
+function normalizeEvalSetDecision(value: string): OkfKnowledgeEvalSet["decision"] {
+  const normalized = value === "no-write" ? "no_write" : value;
+  if (
+    normalized !== "create" &&
+    normalized !== "needs-human" &&
+    normalized !== "no_write" &&
+    normalized !== "skip"
+  ) {
+    throw new Error("Eval set decision is invalid.");
+  }
+  return normalized as OkfKnowledgeEvalSet["decision"];
+}
+
+function assertRecordValue(value: unknown, path: string): Record<string, unknown> {
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  return value;
+}
+
+function readRequiredString(value: unknown, path: string): string {
+  if (!isNonEmptyString(value)) throw new Error(`${path} must be a non-empty string.`);
+  return value;
+}
+
+function readRequiredBoolean(value: unknown, path: string): boolean {
+  if (typeof value !== "boolean") throw new Error(`${path} must be boolean.`);
+  return value;
+}
+
+function readRequiredFalse(value: unknown, path: string): false {
+  if (value !== false) throw new Error(`${path} must be false.`);
+  return false;
+}
+
+function readStringArray(value: unknown, path: string): string[] {
+  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
+  return value.map((item, index) => readRequiredString(item, `${path}[${index}]`));
+}
+
+function readScore(value: unknown, path: string): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 5) {
+    throw new Error(`${path} must be an integer from 1 to 5.`);
+  }
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+function validateEvidenceRefValue(
+  evidenceRef: unknown,
+  path: string,
+  add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+): void {
+  if (!isRecord(evidenceRef)) {
+    add(path, "evidenceRef.object", "Evidence ref must be an object.");
+    return;
+  }
+  if (!isNonEmptyString(evidenceRef.id))
+    add(`${path}.id`, "evidenceRef.id", "Evidence ref id is required.");
+  if (!isNonEmptyString(evidenceRef.kind))
+    add(`${path}.kind`, "evidenceRef.kind", "Evidence ref kind is required.");
+  if (!isNonEmptyString(evidenceRef.source))
+    add(`${path}.source`, "evidenceRef.source", "Evidence ref source is required.");
+  if (evidenceRef.rawContentStored !== false)
+    add(
+      `${path}.rawContentStored`,
+      "evidenceRef.rawContentStored",
+      "Evidence ref rawContentStored must be false.",
+    );
+  if (evidenceRef.externalContentCopied !== false) {
+    add(
+      `${path}.externalContentCopied`,
+      "evidenceRef.externalContentCopied",
+      "Evidence ref externalContentCopied must be false.",
+    );
+  }
+}
+
+function validateEvalSetValue(
+  evalSet: unknown,
+  path: string,
+  add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+): void {
+  if (!isRecord(evalSet)) {
+    add(path, "evalSet.object", "Eval set must be an object.");
+    return;
+  }
+  if (!isNonEmptyString(evalSet.id)) add(`${path}.id`, "evalSet.id", "Eval set id is required.");
+  if (!isRecord(evalSet.target)) {
+    add(`${path}.target`, "evalSet.target", "Eval set target is required.");
+  } else {
+    if (!isNonEmptyString(evalSet.target.kind))
+      add(`${path}.target.kind`, "evalSet.target.kind", "Eval set target kind is required.");
+    if (!isNonEmptyString(evalSet.target.id))
+      add(`${path}.target.id`, "evalSet.target.id", "Eval set target id is required.");
+  }
+  if (!isNonEmptyString(evalSet.purpose))
+    add(`${path}.purpose`, "evalSet.purpose", "Eval set purpose is required.");
+  validateStringArrayValue(evalSet.roleTags, `${path}.roleTags`, add);
+  if (!Array.isArray(evalSet.cases)) {
+    add(`${path}.cases`, "evalSet.cases", "Eval set cases must be an array.");
+  } else {
+    evalSet.cases.forEach((item, index) => {
+      const casePath = `${path}.cases[${index}]`;
+      if (!isRecord(item)) {
+        add(casePath, "evalSet.case.object", "Eval set case must be an object.");
+        return;
+      }
+      if (!isNonEmptyString(item.id))
+        add(`${casePath}.id`, "evalSet.case.id", "Eval set case id is required.");
+      validateStringArrayValue(item.inputRefs, `${casePath}.inputRefs`, add);
+      validateStringArrayValue(item.assertions, `${casePath}.assertions`, add);
+      if (!OKF_REVIEW_STATES.includes(item.expectedReviewState as OkfKnowledgeReviewState)) {
+        add(
+          `${casePath}.expectedReviewState`,
+          "evalSet.case.expectedReviewState",
+          "Eval set case expectedReviewState is invalid.",
+        );
+      }
+    });
+  }
+  if (!isRecord(evalSet.privacy)) {
+    add(`${path}.privacy`, "evalSet.privacy", "Eval set privacy is required.");
+  } else {
+    if (evalSet.privacy.usesRawPrompt !== false)
+      add(
+        `${path}.privacy.usesRawPrompt`,
+        "evalSet.privacy.usesRawPrompt",
+        "Eval set usesRawPrompt must be false.",
+      );
+    if (evalSet.privacy.usesSourceDump !== false)
+      add(
+        `${path}.privacy.usesSourceDump`,
+        "evalSet.privacy.usesSourceDump",
+        "Eval set usesSourceDump must be false.",
+      );
+    if (evalSet.privacy.usesRawCommandOutput !== false) {
+      add(
+        `${path}.privacy.usesRawCommandOutput`,
+        "evalSet.privacy.usesRawCommandOutput",
+        "Eval set usesRawCommandOutput must be false.",
+      );
+    }
+  }
+  if (!["create", "needs-human", "no_write", "skip"].includes(String(evalSet.decision))) {
+    add(`${path}.decision`, "evalSet.decision", "Eval set decision is invalid.");
+  }
+}
+
+function validateStringArrayValue(
+  value: unknown,
+  path: string,
+  add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+): void {
+  if (!Array.isArray(value)) {
+    add(path, "array.required", "Field must be an array.");
+    return;
+  }
+  value.forEach((item, index) => {
+    if (!isNonEmptyString(item))
+      add(`${path}[${index}]`, "array.string", "Array items must be non-empty strings.");
+  });
+}
+
+function validateOverlayUpdatesValue(
+  value: unknown,
+  path: string,
+  add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+): void {
+  if (!Array.isArray(value)) {
+    add(path, "overlayUpdates.array", "Overlay updates must be an array.");
+    return;
+  }
+  value.forEach((item, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!isRecord(item)) {
+      add(itemPath, "overlayUpdate.object", "Overlay update must be an object.");
+      return;
+    }
+    if (item.operation !== "append-link")
+      add(`${itemPath}.operation`, "overlayUpdate.operation", "Overlay operation is invalid.");
+    validateTargetPathValue(item.targetPath, `${itemPath}.targetPath`, false, add);
+    if (!isNonEmptyString(item.link))
+      add(`${itemPath}.link`, "overlayUpdate.link", "Overlay link is required.");
+  });
+}
+
+function validateScoresValue(
+  value: unknown,
+  path: string,
+  add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+): void {
+  if (!isRecord(value)) {
+    add(path, "scores.object", "Scores must be an object.");
+    return;
+  }
+  for (const key of [
+    "evidenceStrength",
+    "reuseValue",
+    "actionability",
+    "stability",
+    "privacyRisk",
+    "duplicationRisk",
+  ]) {
+    const score = value[key];
+    if (typeof score !== "number" || !Number.isInteger(score) || score < 1 || score > 5) {
+      add(`${path}.${key}`, "scores.range", "Scores must be integers from 1 to 5.");
+    }
+  }
+}
+
+function validatePrivacyCheckValue(
+  value: unknown,
+  path: string,
+  add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+): void {
+  if (!isRecord(value)) {
+    add(path, "privacy.object", "Privacy check must be an object.");
+    return;
+  }
+  for (const key of OKF_PRIVACY_FLAG_KEYS) {
+    if (value[key] !== false)
+      add(`${path}.${key}`, "privacy.false", "Privacy fields must be false.");
+  }
+}
+
+function validateBodySectionsValue(
+  value: unknown,
+  path: string,
+  add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+): void {
+  if (!isRecord(value)) {
+    add(path, "bodySections.object", "Body sections must be an object.");
+    return;
+  }
+  if (!isNonEmptyString(value.summary))
+    add(`${path}.summary`, "bodySections.summary", "Body summary is required.");
+  validateStringArrayValue(value.appliesWhen, `${path}.appliesWhen`, add);
+  validateStringArrayValue(value.guidance, `${path}.guidance`, add);
+  validateStringArrayValue(value.antiCriteria, `${path}.antiCriteria`, add);
+  validateStringArrayValue(value.verification, `${path}.verification`, add);
+  validateStringArrayValue(value.citations, `${path}.citations`, add);
+}
+
+function validateTargetPathValue(
+  value: unknown,
+  path: string,
+  requireMarkdown: boolean,
+  add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+): void {
+  if (!isNonEmptyString(value)) {
+    add(path, "targetPath.required", "Target path is required.");
+    return;
+  }
+  const normalized = value.replace(/^\/+/u, "");
+  if (
+    normalized !== value ||
+    isAbsolute(value) ||
+    normalized.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  ) {
+    add(path, "targetPath.relative", "Target path must be a safe relative path.");
+  }
+  if (normalized.includes("index.md") || normalized.includes("log.md")) {
+    add(path, "targetPath.reserved", "Target path cannot use reserved filenames.");
+  }
+  if (requireMarkdown && !normalized.endsWith(".md")) {
+    add(path, "targetPath.markdown", "Active OKF concept target paths must end in .md.");
+  }
+}
+
+function isBehaviorChangeCandidate(candidate: unknown): boolean {
+  if (!isRecord(candidate)) return false;
+  const kind = typeof candidate.kind === "string" ? candidate.kind : "";
+  const haystack = [
+    kind,
+    candidate.targetStore,
+    candidate.targetPath,
+    candidate.stableKey,
+    candidate.title,
+    candidate.description,
+    candidate.claim,
+    candidate.howToApply,
+  ].join(" ");
+  return (
+    BEHAVIOR_CHANGE_KINDS.has(kind) ||
+    /role|team|workflow|routing|tool[-_\s]*use|subagent|task[-_\s]*split/i.test(haystack)
+  );
+}
+
+export function loadActiveOkfKnowledgeIndex(input: { homeDir: string }): OkfActiveKnowledgeIndex {
+  const okfDir = resolveOkfKnowledgePaths(input.homeDir).okfDir;
+  if (!existsSync(okfDir)) return { concepts: [] };
+  const concepts: OkfActiveKnowledgeIndex["concepts"] = [];
+  for (const file of listMarkdownFilesSync(okfDir)) {
+    if (RESERVED_OKF_FILENAMES.has(file.name)) continue;
+    const content = readFileSync(file.path, "utf8");
+    if (isUnsafeOkfQueryContent(content)) continue;
+    const parsed = parseOkfConceptFile(okfDir, file.path, content);
+    if (parsed === null || !isActiveOkfReviewState(parsed.reviewState)) continue;
+    concepts.push({
+      id: parsed.id,
+      sourceLink: parsed.sourceLink,
+      stableKey: parsed.stableKey,
+      reviewState: parsed.reviewState,
+      title: parsed.title,
+      description: parsed.description,
+      type: parsed.type,
+      repoTags: parsed.repoTags,
+      roleTags: parsed.roleTags,
+      workflowTags: parsed.workflowTags,
+      targetPath: parsed.sourceLink.replace(/^\//u, ""),
+    });
+  }
+  return {
+    concepts: concepts.sort((left, right) => left.id.localeCompare(right.id)),
+  };
+}
+
+export function findCandidateConflictOrDuplicate(
+  candidate: OkfKnowledgePlanCandidate,
+  index: OkfActiveKnowledgeIndex,
+): OkfCandidateConflictOrDuplicate | null {
+  const targetPath = candidate.targetPath.replace(/^\/+/u, "");
+  const duplicate = index.concepts.find(
+    (concept) =>
+      concept.stableKey === candidate.stableKey ||
+      concept.targetPath === targetPath ||
+      concept.sourceLink === `/${targetPath}`,
+  );
+  if (duplicate !== undefined) {
+    return {
+      kind: "duplicate",
+      conceptId: duplicate.id,
+      reason: `Duplicate active OKF concept ${duplicate.id} already covers stable key ${candidate.stableKey}.`,
+    };
+  }
+
+  const candidateTitle = normalizeComparableText(candidate.title);
+  const conflict = index.concepts.find((concept) => {
+    if (normalizeComparableText(concept.title) !== candidateTitle) return false;
+    if (concept.stableKey === candidate.stableKey) return false;
+    if (candidate.repoTags.length === 0 || concept.repoTags.length === 0) return true;
+    return candidate.repoTags.some((tag) => concept.repoTags.includes(tag));
+  });
+  if (conflict === undefined) return null;
+  return {
+    kind: "conflict",
+    conceptId: conflict.id,
+    reason: `Potential active OKF conflict with ${conflict.id}; title and repo scope overlap.`,
+  };
+}
+
+export function scoreOkfKnowledgeCandidate(
+  candidate: OkfKnowledgePlanCandidate,
+  context: OkfKnowledgePlanContext,
+): OkfKnowledgeCandidateScores {
+  const conflict = findCandidateConflictOrDuplicate(candidate, context.activeIndex);
+  const hasVerification =
+    candidate.bodySections.verification.length > 0 || candidate.verificationNotApplicableReason;
+  const metadataOnly =
+    candidate.metadataOnlyEvidence &&
+    context.batch.evidenceWindow.sourceRefs.every(
+      (sourceRef) =>
+        sourceRef.rawContentStored === false && sourceRef.externalContentCopied === false,
+    ) &&
+    context.batch.evidenceWindow.events.every((event) => event.rawContentStored === false);
+  const privacyRisk = hasUnsafeCandidateContent(candidate) ? 5 : metadataOnly ? 1 : 3;
+  const evidenceStrength =
+    candidate.basis === "direct" && candidate.confidence === "high" && metadataOnly
+      ? hasVerification
+        ? 5
+        : 4
+      : candidate.confidence === "medium"
+        ? 3
+        : 2;
+  const actionability =
+    candidate.howToApply.trim() !== "" &&
+    candidate.bodySections.guidance.some((item) => item.trim() !== "")
+      ? 4
+      : 2;
+  const reuseValue =
+    candidate.kind === "evos-case" || candidate.roleTags.length > 0 || candidate.repoTags.length > 0
+      ? 4
+      : 3;
+  const stability = /hard policy|hard rule|must always|never allow/i.test(
+    `${candidate.claim} ${candidate.howToApply}`,
+  )
+    ? 2
+    : 4;
+  const duplicationRisk = conflict === null ? 1 : conflict.kind === "duplicate" ? 5 : 4;
+  return {
+    evidenceStrength,
+    reuseValue,
+    actionability,
+    stability,
+    privacyRisk,
+    duplicationRisk,
+  };
+}
+
+export function decideOkfKnowledgeCandidate(
+  candidate: OkfKnowledgePlanCandidate,
+  context: OkfKnowledgePlanContext,
+): OkfKnowledgePlanCandidate {
+  const originalUnsafe = hasUnsafeCandidateContent(candidate);
+  const sanitized = sanitizeOkfPlanCandidate(candidate);
+  const conflict = findCandidateConflictOrDuplicate(sanitized, context.activeIndex);
+  const scored = scoreOkfKnowledgeCandidate(sanitized, context);
+  const scores = {
+    ...scored,
+    privacyRisk: originalUnsafe ? 5 : scored.privacyRisk,
+  };
+  const hasVerification =
+    sanitized.bodySections.verification.length > 0 ||
+    sanitized.verificationNotApplicableReason !== undefined;
+  const localActiveTarget = sanitized.targetStore === "okf" || sanitized.kind === "evos-case";
+  const hasScopeTags = sanitized.repoTags.length > 0 && sanitized.roleTags.length > 0;
+  const highRiskRequiresHuman =
+    hasHighRiskHumanReviewSignal(candidate) || hasHighRiskHumanReviewSignal(sanitized);
+  const autoAcceptEligible =
+    !highRiskRequiresHuman &&
+    conflict === null &&
+    localActiveTarget &&
+    sanitized.targetStore === "okf" &&
+    sanitized.basis === "direct" &&
+    sanitized.metadataOnlyEvidence &&
+    hasVerification &&
+    hasScopeTags &&
+    scores.evidenceStrength >= 4 &&
+    scores.reuseValue >= 3 &&
+    scores.actionability >= 3 &&
+    scores.stability >= 3 &&
+    scores.privacyRisk <= 2 &&
+    scores.duplicationRisk <= 2;
+
+  if (autoAcceptEligible) {
+    return {
+      ...sanitized,
+      decision: "auto-accept",
+      scores,
+      reviewState: "auto-accepted",
+      decisionReason:
+        "Auto-accepted: high-confidence metadata-only evidence passed verification, privacy, scope, and duplicate checks.",
+    };
+  }
+
+  if (highRiskRequiresHuman) {
+    return {
+      ...sanitized,
+      decision: "needs-human",
+      scores,
+      reviewState: "needs-human",
+      decisionReason: "Needs human review: high-risk domain requires review.",
+    };
+  }
+
+  if (conflict?.kind === "duplicate") {
+    return {
+      ...sanitized,
+      decision: "no_write",
+      scores,
+      reviewState: "auto-stored/unreviewed",
+      decisionReason: conflict.reason,
+    };
+  }
+
+  const reusable = scores.reuseValue >= 3 || scores.actionability >= 3;
+  if (reusable) {
+    return {
+      ...sanitized,
+      decision: "needs-human",
+      scores,
+      reviewState: "needs-human",
+      decisionReason:
+        conflict?.reason ??
+        explainNeedsHumanDecision(sanitized, scores, hasVerification, hasScopeTags),
+    };
+  }
+
+  return {
+    ...sanitized,
+    decision: "no_write",
+    scores,
+    reviewState: "auto-stored/unreviewed",
+    decisionReason: "No write: candidate did not meet reusable knowledge thresholds.",
+  };
+}
+
+export async function activateOkfKnowledgePlan(input: {
+  homeDir: string;
+  plan: OkfKnowledgePlan;
+  overwrite?: boolean;
+  evidenceWindowPath?: string | null;
+}): 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";
+  if (!validation.ok) {
+    await writeFailedOkfKnowledgePlanArtifact({
+      homeDir: input.homeDir,
+      projectKey,
+      runId,
+      rawPlan: input.plan,
+      findings: validation.findings,
+      error: "OKF knowledge plan contract validation failed.",
+      failureKind: "validation",
+    });
+    throw new Error("OKF knowledge plan contract validation failed.");
+  }
+  validateOkfKnowledgePlan(input.plan);
+  const paths = resolveOkfKnowledgePaths(input.homeDir);
+  const tmpRunDir = join(paths.tmpDir, `${input.plan.projectKey}-${input.plan.runId}`);
+  const planPath = join(tmpRunDir, "knowledge-plan.json");
+  const failedPlanPath = resolveFailedPlanPath(
+    input.homeDir,
+    input.plan.projectKey,
+    input.plan.runId,
+  );
+
+  await ensureOkfKnowledgeBase(input.homeDir);
+  await writeJson(planPath, input.plan, { overwrite: true });
+
+  const conceptPaths: string[] = [];
+  const overlayPaths: string[] = [];
+  const skippedCandidates: string[] = [];
+  const needsHumanCandidates: string[] = [];
+  const affectedDirectories = new Set<string>([paths.okfDir]);
+
+  try {
+    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") {
+        await writeNeedsHumanKnowledgeCandidate({
+          homeDir: input.homeDir,
+          plan: input.plan,
+          candidate,
+        });
+        needsHumanCandidates.push(candidate.id);
+        continue;
+      }
+      if (candidate.targetStore !== "okf") {
+        skippedCandidates.push(candidate.id);
+        continue;
+      }
+
+      const targetPath = resolveOkfTargetPath(paths.okfDir, candidate.targetPath);
+      const exists = await pathExists(targetPath);
+      if (
+        exists &&
+        input.overwrite !== true &&
+        (candidate.decision === "create" || candidate.decision === "auto-accept")
+      ) {
+        skippedCandidates.push(candidate.id);
+        await appendOkfLog(
+          paths.okfDir,
+          `**Skip**: Candidate \`${candidate.id}\` matched existing [${candidate.title}](${toOkfLink(paths.okfDir, targetPath)}).`,
+        );
+        continue;
+      }
+
+      await mkdir(dirname(targetPath), { recursive: true });
+      await writeFile(targetPath, renderOkfConcept(candidate, input.plan), "utf8");
+      conceptPaths.push(targetPath);
+      affectedDirectories.add(dirname(targetPath));
+
+      for (const update of candidate.overlayUpdates) {
+        const overlayPath = resolveOkfTargetPath(paths.okfDir, update.targetPath);
+        await ensureOverlayConcept({
+          okfDir: paths.okfDir,
+          overlayPath,
+          candidate,
+          projectKey: input.plan.projectKey,
+          runId: input.plan.runId,
+          link: update.link,
+        });
+        overlayPaths.push(overlayPath);
+        affectedDirectories.add(dirname(overlayPath));
+      }
+    }
+
+    const indexPaths = await regenerateOkfDirectoryIndexes(paths.okfDir);
+    const derivedIndexPaths = await rebuildOkfKnowledgeIndexes({ homeDir: input.homeDir });
+    const logPaths = await appendOrganizerLogs({
+      okfDir: paths.okfDir,
+      affectedDirectories: [...affectedDirectories],
+      plan: input.plan,
+      conceptPaths,
+      overlayPaths,
+      skippedCandidates,
+      needsHumanCandidates,
+    });
+    await rm(tmpRunDir, { recursive: true, force: true });
+    await rm(failedPlanPath, { force: true });
+
+    return {
+      planPath,
+      failedPlanPath,
+      evidenceWindowPath: input.evidenceWindowPath ?? null,
+      conceptPaths,
+      overlayPaths,
+      skippedCandidates,
+      needsHumanCandidates,
+      indexPaths,
+      derivedIndexPaths,
+      logPaths,
+    };
+  } catch (error) {
+    await writeFailedOkfKnowledgePlanArtifact({
+      homeDir: input.homeDir,
+      projectKey: input.plan.projectKey,
+      runId: input.plan.runId,
+      plan: input.plan,
+      findings: [],
+      error: error instanceof Error ? error.message : String(error),
+      failureKind: "organizer",
+    });
+    await rm(tmpRunDir, { recursive: true, force: true });
+    await writeJson(
+      join(dirname(failedPlanPath), "organizer-report.json"),
+      {
+        schemaVersion: 1,
+        kind: "okf-organizer-report",
+        projectKey: input.plan.projectKey,
+        runId: input.plan.runId,
+        status: "failed",
+        error: error instanceof Error ? error.message : String(error),
+      },
+      { overwrite: true },
+    );
+    throw error;
+  }
+}
+
+export async function readFailedOkfKnowledgePlan(input: {
+  homeDir: string;
+  projectKey: string;
+  runId: string;
+}): Promise<{ path: string; plan: OkfKnowledgePlan }> {
+  const artifact = await readFailedOkfKnowledgePlanArtifact(input);
+  if (artifact.artifact.plan === undefined) {
+    throw new Error("Failed OKF knowledge plan is not resumable.");
+  }
+  const plan = artifact.artifact.plan;
+  validateOkfKnowledgePlan(plan);
+  return { path: artifact.path, plan };
+}
+
+export async function writeFailedOkfKnowledgePlanArtifact(input: {
+  homeDir: string;
+  projectKey: string;
+  runId: string;
+  rawPlan?: unknown;
+  plan?: OkfKnowledgePlan;
+  findings: OkfKnowledgePlanValidationFinding[];
+  error: string;
+  failureKind: "validation" | "organizer";
+}): Promise<{ path: string; artifact: OkfKnowledgeFailedPlanArtifact }> {
+  const path = resolveFailedPlanPath(input.homeDir, input.projectKey, input.runId);
+  const artifact: OkfKnowledgeFailedPlanArtifact = {
+    schemaVersion: 1,
+    kind: "okf-knowledge-failed-plan",
+    failureKind: input.failureKind,
+    projectKey: sanitizePlanStorageId("projectKey", input.projectKey),
+    runId: sanitizePlanStorageId("runId", input.runId),
+    createdAt: new Date().toISOString(),
+    resumable: input.failureKind === "organizer" && input.plan !== undefined,
+    findings: input.findings.map((finding) => ({
+      path: sanitizeOkfText(finding.path),
+      code: sanitizeOkfText(finding.code),
+      severity: finding.severity,
+      message: sanitizeOkfText(finding.message),
+    })),
+    error: sanitizeOkfText(input.error),
+    ...(input.rawPlan === undefined
+      ? {}
+      : { redactedPlan: sanitizeReviewQueueValue(input.rawPlan) }),
+    ...(input.failureKind === "organizer" && input.plan !== undefined ? { plan: input.plan } : {}),
+  };
+  await writeJson(path, artifact, { overwrite: true });
+  return { path, artifact };
+}
+
+export async function readFailedOkfKnowledgePlanArtifact(input: {
+  homeDir: string;
+  projectKey: string;
+  runId: string;
+}): Promise<{ path: string; artifact: OkfKnowledgeFailedPlanArtifact }> {
+  const path = resolveFailedPlanPath(input.homeDir, input.projectKey, input.runId);
+  const value = JSON.parse(await readFile(path, "utf8")) as unknown;
+  if (isRecord(value) && value.kind === "okf-knowledge-failed-plan") {
+    const artifact = value as unknown as OkfKnowledgeFailedPlanArtifact;
+    validateFailedPlanArtifact(artifact);
+    return { path, artifact };
+  }
+  const legacyPlan = value as OkfKnowledgePlan;
+  validateOkfKnowledgePlan(legacyPlan);
+  return {
+    path,
+    artifact: {
+      schemaVersion: 1,
+      kind: "okf-knowledge-failed-plan",
+      failureKind: "organizer",
+      projectKey: legacyPlan.projectKey,
+      runId: legacyPlan.runId,
+      createdAt: new Date().toISOString(),
+      resumable: true,
+      plan: legacyPlan,
+      findings: [],
+      error: "Legacy failed OKF knowledge plan.",
+    },
+  };
+}
+
+export async function resumeFailedOkfKnowledgePlan(input: {
+  homeDir: string;
+  projectKey: string;
+  runId: string;
+  overwrite?: boolean;
+}): Promise<OkfKnowledgeActivationResult> {
+  const { plan } = await readFailedOkfKnowledgePlan(input);
+  return await activateOkfKnowledgePlan({
+    homeDir: input.homeDir,
+    plan,
+    overwrite: input.overwrite ?? true,
+    evidenceWindowPath: null,
+  });
+}
+
+export async function discardFailedOkfKnowledgePlan(input: {
+  homeDir: string;
+  projectKey: string;
+  runId: string;
+}): Promise<{ path: string }> {
+  const path = resolveFailedPlanPath(input.homeDir, input.projectKey, input.runId);
+  await rm(path, { force: true });
+  return { path };
+}
+
+export async function rebuildOkfKnowledgeIndexes(input: { homeDir: string }): Promise<string[]> {
+  const paths = resolveOkfKnowledgePaths(input.homeDir);
+  await mkdir(paths.indexesDir, { recursive: true });
+  const concepts = (await listOkfKnowledgeConcepts({ homeDir: input.homeDir })).filter(
+    isActiveOkfConcept,
+  );
+  const conceptSummaries = concepts.map((concept) => ({
+    id: concept.id,
+    type: concept.type,
+    title: concept.title,
+    description: concept.description,
+    sourceLink: concept.sourceLink,
+    stableKey: concept.stableKey,
+    reviewState: concept.reviewState,
+    tags: concept.tags,
+    repoTags: concept.repoTags,
+    roleTags: concept.roleTags,
+    workflowTags: concept.workflowTags,
+    pathScopes: concept.pathScopes,
+  }));
+  const pathsWritten = [
+    join(paths.indexesDir, "index.json"),
+    join(paths.indexesDir, "concepts.json"),
+    join(paths.indexesDir, "repos.json"),
+    join(paths.indexesDir, "roles.json"),
+    join(paths.indexesDir, "workflows.json"),
+  ];
+  await writeJson(
+    pathsWritten[0] as string,
+    {
+      schemaVersion: 1,
+      kind: "okf-knowledge-index",
+      conceptCount: concepts.length,
+      updatedAt: new Date().toISOString(),
+    },
+    { overwrite: true },
+  );
+  await writeJson(
+    pathsWritten[1] as string,
+    {
+      schemaVersion: 1,
+      kind: "okf-concepts-index",
+      concepts: conceptSummaries,
+    },
+    { overwrite: true },
+  );
+  await writeJson(
+    pathsWritten[2] as string,
+    {
+      schemaVersion: 1,
+      kind: "okf-repos-index",
+      repos: groupConceptsByTag(concepts, "repoTags"),
+    },
+    { overwrite: true },
+  );
+  await writeJson(
+    pathsWritten[3] as string,
+    {
+      schemaVersion: 1,
+      kind: "okf-roles-index",
+      roles: groupConceptsByTag(concepts, "roleTags"),
+    },
+    { overwrite: true },
+  );
+  await writeJson(
+    pathsWritten[4] as string,
+    {
+      schemaVersion: 1,
+      kind: "okf-workflows-index",
+      workflows: groupConceptsByTag(concepts, "workflowTags"),
+    },
+    { overwrite: true },
+  );
+  return pathsWritten;
+}
+
+export async function listOkfKnowledgeConcepts(input: {
+  homeDir: string;
+  projectKey?: string;
+  roleId?: string;
+  workflowId?: string;
+  paths?: string[];
+}): Promise<OkfKnowledgeConcept[]> {
+  const okfDir = resolveOkfKnowledgePaths(input.homeDir).okfDir;
+  if (!(await pathExists(okfDir))) return [];
+  const files = await listMarkdownFiles(okfDir);
+  const concepts: OkfKnowledgeConcept[] = [];
+  for (const file of files) {
+    if (RESERVED_OKF_FILENAMES.has(file.name)) continue;
+    const content = await readFile(file.path, "utf8");
+    const parsed = parseOkfConceptFile(okfDir, file.path, content);
+    if (parsed !== null) concepts.push(parsed);
+  }
+  return concepts
+    .filter((concept) => matchesConceptFilters(concept, input))
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export async function readOkfKnowledgeConcept(input: {
+  homeDir: string;
+  conceptId: string;
+}): Promise<OkfKnowledgeConcept> {
+  const id = normalizeConceptId(input.conceptId);
+  const concepts = await listOkfKnowledgeConcepts({ homeDir: input.homeDir });
+  const matches = concepts.filter(
+    (concept) => concept.id === id || concept.sourceLink === `/${id}.md`,
+  );
+  if (matches.length === 0) throw new Error(`OKF knowledge concept not found: ${input.conceptId}`);
+  if (matches.length > 1) throw new Error(`OKF knowledge concept is ambiguous: ${input.conceptId}`);
+  return matches[0] as OkfKnowledgeConcept;
+}
+
+export async function queryOkfKnowledge(input: {
+  homeDir: string;
+  projectKey?: string;
+  roleId?: string;
+  workflowId?: string;
+  queryText?: string;
+  paths?: string[];
+  limit?: number;
+  includeStale?: boolean;
+  now?: string | Date;
+}): Promise<OkfKnowledgeQueryResult> {
+  const okfDir = resolveOkfKnowledgePaths(input.homeDir).okfDir;
+  const scope = normalizeKnowledgeQueryScope(input);
+  const queryText = normalizeKnowledgeQueryText(input.queryText);
+  const now = normalizeQueryNow(input.now);
+  const warnings: string[] = [];
+  if (!(await pathExists(okfDir))) {
+    return {
+      projectKey: scope.projectKey,
+      roleId: scope.roleId,
+      workflowId: scope.workflowId,
+      ...(queryText === undefined ? {} : { queryText }),
+      paths: scope.paths,
+      items: [],
+      warnings,
+    };
+  }
+
+  const files = await listMarkdownFiles(okfDir);
+  const candidates: RankedOkfContextCandidate[] = [];
+  for (const file of files) {
+    if (RESERVED_OKF_FILENAMES.has(file.name)) continue;
+    const content = await readFile(file.path, "utf8");
+    const sourceLink = toOkfLink(okfDir, file.path);
+    if (isUnsafeOkfQueryContent(content)) {
+      warnings.push(`Omitted unsafe OKF knowledge item: ${sourceLink}. Run evodev knowledge lint.`);
+      continue;
+    }
+    const parsed = parseOkfConceptFile(okfDir, file.path, content);
+    if (parsed === null) continue;
+    const lifecycleEligibility = resolveOkfConceptQueryEligibility(parsed, {
+      includeStale: input.includeStale === true,
+      now,
+    });
+    if (lifecycleEligibility.include === false) continue;
+    const match = matchOkfConceptForContext(parsed, scope);
+    if (match === null) continue;
+    const section = resolveContextSection(parsed);
+    const structuredScore = calculateOkfContextScore(parsed, match);
+    const lexical =
+      queryText === undefined
+        ? { score: 0, reasons: [] }
+        : scoreLexicalKnowledgeDocument(createLexicalKnowledgeDocumentFromOkfConcept(parsed), {
+            queryText,
+          });
+    const structuredOverlayExempt =
+      queryText !== undefined &&
+      match.overlayMatch &&
+      (scope.projectKey !== undefined ||
+        scope.roleId !== undefined ||
+        scope.workflowId !== undefined);
+    if (queryText !== undefined && lexical.score <= 0 && !structuredOverlayExempt) continue;
+    if (lifecycleEligibility.stale) {
+      warnings.push(
+        `Included stale OKF knowledge item: ${parsed.sourceLink} (${lifecycleEligibility.reason}).`,
+      );
+    }
+    candidates.push({
+      concept: parsed,
+      section,
+      score: structuredScore + lexical.score + lifecycleEligibility.scoreAdjustment,
+      matchReasons: [
+        ...match.reasons,
+        ...(lifecycleEligibility.stale ? ["lifecycle:stale"] : []),
+        ...lexical.reasons,
+        ...(queryText !== undefined && lexical.score <= 0 && structuredOverlayExempt
+          ? ["q:scope-overlay"]
+          : []),
+      ],
+    });
+  }
+
+  const limit = input.limit ?? 12;
+  const items = candidates
+    .sort((left, right) => {
+      const score = right.score - left.score;
+      if (score !== 0) return score;
+      const section =
+        contextSectionSortWeight(left.section) - contextSectionSortWeight(right.section);
+      if (section !== 0) return section;
+      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,
+    }));
+
+  return {
+    projectKey: scope.projectKey,
+    roleId: scope.roleId,
+    workflowId: scope.workflowId,
+    ...(queryText === undefined ? {} : { queryText }),
+    paths: scope.paths,
+    items,
+    warnings,
+  };
+}
+
+export function createLexicalKnowledgeDocumentFromOkfConcept(
+  concept: OkfKnowledgeConcept,
+): LexicalKnowledgeDocument {
+  return createLexicalKnowledgeDocument({
+    id: concept.id,
+    sourceType: "okf",
+    sourceLink: concept.sourceLink,
+    section: resolveContextSection(concept),
+    title: concept.title,
+    description: concept.description,
+    tags: concept.tags,
+    repoTags: concept.repoTags,
+    roleTags: concept.roleTags,
+    workflowTags: concept.workflowTags,
+    pathScopes: concept.pathScopes,
+    stableKey: concept.stableKey,
+    headings: extractMarkdownHeadings(concept.body),
+    bodySummary: summarizeLexicalBody(concept.body),
+  });
+}
+
+export function createLexicalKnowledgeDocumentFromEvosCase(
+  evosCase: EvolutionEvosCase,
+): LexicalKnowledgeDocument {
+  return createLexicalKnowledgeDocument({
+    id: evosCase.id,
+    sourceType: "evos-case",
+    sourceLink: `cases/${evosCase.projectKey}/${evosCase.id}.json`,
+    section: "accepted-evos-cases",
+    title: evosCase.title,
+    description: evosCase.expectedFutureBehavior || evosCase.result.summary || evosCase.title,
+    tags: evosCase.tags,
+    repoTags: [evosCase.projectKey],
+    roleTags: evosCase.roleTags,
+    workflowTags: evosCase.tags
+      .filter((tag) => tag.startsWith("workflow-") || tag.startsWith("workflow:"))
+      .map((tag) => tag.replace(/^workflow[:-]/u, "")),
+    pathScopes: [],
+    stableKey: `evos:${evosCase.projectKey}:${evosCase.id}`,
+    headings: ["Trigger", "Intervention", "Result", "Expected Future Behavior"],
+    bodySummary: [
+      evosCase.trigger.summary,
+      evosCase.intervention.summary,
+      evosCase.result.summary,
+      evosCase.expectedFutureBehavior,
+      ...evosCase.result.verificationSignals,
+    ].join(" "),
+  });
+}
+
+export function scoreLexicalKnowledgeDocument(
+  document: LexicalKnowledgeDocument,
+  input: { queryText?: string },
+): LexicalKnowledgeScore {
+  const queryText = normalizeKnowledgeQueryText(input.queryText);
+  if (queryText === undefined) return { score: 0, reasons: [] };
+  const query = parseLexicalQuery(queryText);
+  if (
+    query.tokens.length === 0 &&
+    query.pathAnchors.length === 0 &&
+    query.exactAnchors.length === 0
+  ) {
+    return { score: 0, reasons: [] };
+  }
+
+  let score = 0;
+  const reasons: string[] = [];
+  const add = (value: number, reason: string) => {
+    const safeReason = sanitizeLexicalReason(reason);
+    if (safeReason === "" || reasons.includes(safeReason)) return;
+    score += value;
+    reasons.push(safeReason);
+  };
+
+  const titleTokens = new Set(tokenizeLexicalText(document.title));
+  const descriptionTokens = new Set(tokenizeLexicalText(document.description));
+  const headingTokens = new Set(document.headings.flatMap(tokenizeLexicalText));
+  const tagTokens = new Set(
+    [
+      ...document.tags,
+      ...document.repoTags,
+      ...document.roleTags,
+      ...document.workflowTags,
+    ].flatMap((tag) => [sanitizeSlug(tag), ...tokenizeLexicalText(tag)]),
+  );
+  const pathValues = [
+    document.id,
+    document.sourceLink,
+    document.stableKey,
+    ...document.pathScopes,
+    ...document.headings,
+  ];
+  const pathTokens = new Set(pathValues.flatMap(tokenizeLexicalText));
+  const bodyTokens = new Set(tokenizeLexicalText(document.bodySummary));
+  const safeTokens = new Set(document.safeTokens);
+  const allText = normalizeLexicalComparable(
+    [
+      document.id,
+      document.sourceLink,
+      document.stableKey,
+      document.title,
+      document.description,
+      ...document.tags,
+      ...document.repoTags,
+      ...document.roleTags,
+      ...document.workflowTags,
+      ...document.pathScopes,
+      ...document.headings,
+      document.bodySummary,
+    ].join(" "),
+  );
+
+  for (const anchor of query.pathAnchors) {
+    if (pathAnchorMatches(anchor, pathValues)) add(90, `q:path:${anchor}`);
+  }
+  for (const anchor of query.exactAnchors) {
+    if (allText.includes(normalizeLexicalComparable(anchor))) add(80, `q:exact:${anchor}`);
+  }
+  for (const anchor of query.scriptAnchors) {
+    const scriptName = anchor.replace(/^(?:bun|npm|pnpm|yarn)-run-/u, "");
+    if (
+      allText.includes(normalizeLexicalComparable(anchor)) ||
+      allText.includes(normalizeLexicalComparable(scriptName)) ||
+      safeTokens.has(scriptName)
+    ) {
+      add(75, `q:script:${anchor}`);
+    }
+  }
+
+  for (const token of query.tokens) {
+    if (token.length < 3) continue;
+    if (titleTokens.has(token)) {
+      add(34, `q:title:${token}`);
+      continue;
+    }
+    if (tagTokens.has(token)) {
+      add(32, `q:tag:${token}`);
+      continue;
+    }
+    if (pathTokens.has(token) || pathAnchorMatches(token, pathValues)) {
+      add(30, `q:path:${token}`);
+      continue;
+    }
+    if (headingTokens.has(token)) {
+      add(18, `q:heading:${token}`);
+      continue;
+    }
+    if (descriptionTokens.has(token)) {
+      add(12, `q:description:${token}`);
+      continue;
+    }
+    if (bodyTokens.has(token)) {
+      add(8, `q:body:${token}`);
+      continue;
+    }
+    if (safeTokens.has(token)) {
+      add(3, `q:token:${token}`);
+    }
+  }
+
+  return { score, reasons };
+}
+
+export function rankKnowledgeContextItems(
+  items: OkfKnowledgeContextItem[],
+  limit?: number,
+): OkfKnowledgeContextItem[] {
+  return [...items]
+    .sort((left, right) => {
+      const score = (right.score ?? 0) - (left.score ?? 0);
+      if (score !== 0) return score;
+      const section =
+        contextSectionSortWeight(left.section) - contextSectionSortWeight(right.section);
+      if (section !== 0) return section;
+      if (left.sourceType !== right.sourceType) return left.sourceType === "okf" ? -1 : 1;
+      const id = left.id.localeCompare(right.id);
+      if (id !== 0) return id;
+      return left.sourceLink.localeCompare(right.sourceLink);
+    })
+    .slice(0, limit ?? items.length)
+    .map((item, index) => ({ ...item, rank: index + 1 }));
+}
+
+export async function queryScopedOkfKnowledgeContext(input: {
+  homeDir: string;
+  projectKey?: string;
+  roleId?: string;
+  workflowId?: string;
+  queryText?: string;
+  paths?: string[];
+  limit?: number;
+  includeStale?: boolean;
+  now?: string | Date;
+}): Promise<OkfKnowledgeQueryResult> {
+  const result = await queryOkfKnowledge(input);
+  const evosCases = await listEvolutionEvosCases({
+    homeDir: input.homeDir,
+    projectKey: input.projectKey,
+    roleId: input.roleId,
+    reviewStates: ["accepted", "auto-accepted"],
+  });
+  return mergeAcceptedEvosCasesIntoKnowledgeQuery(
+    result,
+    evosCases.cases,
+    evosCases.warnings,
+    input.limit,
+  );
+}
+
+export function mergeAcceptedEvosCasesIntoKnowledgeQuery(
+  result: OkfKnowledgeQueryResult,
+  cases: EvolutionEvosCase[],
+  warnings: string[] = [],
+  limit?: number,
+): OkfKnowledgeQueryResult {
+  const startRank = result.items.length + 1;
+  const evosItems = cases.flatMap<OkfKnowledgeContextItem>((evosCase, index) => {
+    const document = createLexicalKnowledgeDocumentFromEvosCase(evosCase);
+    const lexical = scoreLexicalKnowledgeDocument(document, { queryText: result.queryText });
+    if (result.queryText !== undefined && lexical.score <= 0) return [];
+    const structuredReasons = [
+      "active-review-state",
+      `repo:${evosCase.projectKey}`,
+      ...(result.roleId !== undefined && evosCase.roleTags.includes(result.roleId)
+        ? [`role:${result.roleId}`]
+        : []),
+    ];
+    const structuredScore =
+      (result.projectKey !== undefined && evosCase.projectKey === result.projectKey ? 100 : 0) +
+      (result.roleId !== undefined && evosCase.roleTags.includes(result.roleId) ? 100 : 0);
+    return [
+      {
+        id: evosCase.id,
+        sourceType: "evos-case",
+        sourceLink: document.sourceLink,
+        section: "accepted-evos-cases",
+        rank: startRank + index,
+        score: structuredScore + lexical.score,
+        title: evosCase.title,
+        summary: evosCase.expectedFutureBehavior || evosCase.result.summary || evosCase.title,
+        matchReasons:
+          lexical.reasons.length === 0
+            ? structuredReasons
+            : [...structuredReasons, ...lexical.reasons],
+      },
+    ];
+  });
+  const items = rankKnowledgeContextItems(
+    [...result.items, ...evosItems],
+    limit ?? result.items.length + evosItems.length,
+  );
+  return {
+    ...result,
+    items,
+    warnings: [...result.warnings, ...warnings],
+  };
+}
+
+export async function createScopedKnowledgeContextPack(input: {
+  homeDir: string;
+  projectKey?: string;
+  roleId?: string;
+  workflowId?: string;
+  paths?: string[];
+  queryText?: string;
+  limit?: number;
+}): Promise<ScopedKnowledgeContextPack | null> {
+  const result = await queryScopedOkfKnowledgeContext(input);
+  if (result.items.length === 0) return null;
+  const scope: ScopedKnowledgeContextPackScope = {
+    ...(result.projectKey === undefined ? {} : { projectKey: result.projectKey }),
+    ...(result.roleId === undefined ? {} : { roleId: result.roleId }),
+    ...(result.workflowId === undefined ? {} : { workflowId: result.workflowId }),
+    paths: result.paths,
+  };
+  const items = result.items.map<ScopedKnowledgeContextPackItem>((item) => ({
+    id: item.id,
+    sourceType: item.sourceType,
+    sourceLink: item.sourceLink,
+    section: item.section,
+    rank: item.rank,
+    title: sanitizeOkfText(item.title),
+    matchReasons: uniqueStrings(item.matchReasons.map(sanitizeLexicalReason)),
+  }));
+  const okfIndexRevision = createKnowledgeContextRevision(items);
+  const queryText = normalizeKnowledgeQueryText(result.queryText);
+  const packSeed = stableJsonStringify({
+    okfIndexRevision,
+    scope,
+    queryText: queryText ?? null,
+    items: items.map((item) => ({
+      id: item.id,
+      sourceType: item.sourceType,
+      sourceLink: item.sourceLink,
+      section: item.section,
+      rank: item.rank,
+      matchReasons: item.matchReasons,
+    })),
+  });
+  return {
+    version: 1,
+    kind: "evodev-scoped-knowledge-context-pack",
+    id: `ctxpack-${sha256Short(packSeed)}`,
+    okfIndexRevision,
+    scope,
+    ...(queryText === undefined ? {} : { queryText }),
+    items,
+    warnings:
+      result.warnings.length === 0
+        ? []
+        : [
+            "Some scoped knowledge items were omitted because they failed safety validation; run evodev knowledge lint.",
+          ],
+    rawContentStored: false,
+  };
+}
+
+export function formatScopedKnowledgePromptBlock(pack: ScopedKnowledgeContextPack): string {
+  return [
+    "EvoDev Scoped Knowledge Context",
+    `Context pack: ${sanitizeOkfText(pack.id)}`,
+    `Project: ${pack.scope.projectKey ?? "all"}`,
+    `Role: ${pack.scope.roleId ?? "any"}`,
+    `Workflow: ${pack.scope.workflowId ?? "any"}`,
+    ...(pack.queryText === undefined ? [] : [`Query: ${sanitizeOkfText(pack.queryText)}`]),
+    `Paths: ${pack.scope.paths.length === 0 ? "all" : pack.scope.paths.join(", ")}`,
+    "Raw content stored: false",
+    "",
+    "Applicable items:",
+    ...pack.items.flatMap((item) => [
+      `- ${item.rank}. ${sanitizeOkfText(item.id)} (${item.section}; ${item.sourceType})`,
+      `  Source: ${sanitizeOkfText(item.sourceLink)}`,
+      `  Match: ${item.matchReasons.length === 0 ? "generic" : item.matchReasons.join(", ")}`,
+    ]),
+    ...(pack.warnings.length === 0
+      ? []
+      : [
+          "",
+          "Warnings:",
+          "- Some scoped knowledge items were omitted because they failed safety validation; run evodev knowledge lint.",
+        ]),
+  ].join("\n");
+}
+
+export function resolveContextInjectionReceiptPath(input: {
+  homeDir: string;
+  sessionKey: string;
+  contextPackId: string;
+}): string {
+  const stateDir = resolveEvoDevPaths(input.homeDir).stateDir;
+  return join(
+    stateDir,
+    "context-injections",
+    sanitizeReceiptPathSegment(input.sessionKey),
+    `${sanitizeReceiptPathSegment(input.contextPackId)}.json`,
+  );
+}
+
+export async function hasContextInjectionReceipt(input: {
+  homeDir: string;
+  sessionKey: string;
+  contextPackId: string;
+}): Promise<boolean> {
+  return pathExists(resolveContextInjectionReceiptPath(input));
+}
+
+export async function writeContextInjectionReceipt(input: {
+  homeDir: string;
+  sessionKey: string;
+  pack: ScopedKnowledgeContextPack;
+  trigger: ContextInjectionTrigger;
+  hookEventId?: string | null;
+  injectedAt?: string;
+}): Promise<{ path: string; receipt: ContextInjectionReceipt }> {
+  const receipt: ContextInjectionReceipt = {
+    version: 1,
+    contextPackId: input.pack.id,
+    okfIndexRevision: input.pack.okfIndexRevision,
+    scope: input.pack.scope,
+    itemIds: input.pack.items.map((item) => item.id),
+    injectedAt: input.injectedAt ?? new Date().toISOString(),
+    hookEventId: input.hookEventId ?? null,
+    trigger: input.trigger,
+    rawContentStored: false,
+  };
+  const path = resolveContextInjectionReceiptPath({
+    homeDir: input.homeDir,
+    sessionKey: input.sessionKey,
+    contextPackId: input.pack.id,
+  });
+  await writeJson(path, receipt, { overwrite: true });
+  return { path, receipt };
+}
+
+export async function markOkfKnowledgeConceptStale(input: {
+  homeDir: string;
+  conceptId: string;
+  now?: string | Date;
+}): Promise<OkfKnowledgeLifecycleMutationResult> {
+  const target = await readMutableOkfConcept(input.homeDir, input.conceptId);
+  const lifecycle: OkfKnowledgeLifecycle = {
+    ...target.concept.lifecycle,
+    status: "stale",
+    revokedAt: null,
+    revokedReason: null,
+  };
+  await writeConceptLifecycleFrontmatter({
+    path: target.concept.path,
+    content: target.content,
+    reviewState: "stale",
+    lifecycle,
+  });
+  const logPaths = await appendLifecycleLogs({
+    okfDir: target.paths.okfDir,
+    conceptPaths: [target.concept.path],
+    entry: `**Lifecycle**: Marked \`${target.concept.id}\` stale.`,
+  });
+  const indexPaths = await rebuildOkfKnowledgeIndexes({ homeDir: input.homeDir });
+  return { conceptPaths: [target.concept.path], logPaths, indexPaths };
+}
+
+export async function revokeOkfKnowledgeConcept(input: {
+  homeDir: string;
+  conceptId: string;
+  reason: string;
+  now?: string | Date;
+}): Promise<OkfKnowledgeLifecycleMutationResult> {
+  const reason = validateLifecycleReason(input.reason);
+  const target = await readMutableOkfConcept(input.homeDir, input.conceptId);
+  const timestamp = normalizeQueryNow(input.now).toISOString();
+  const lifecycle: OkfKnowledgeLifecycle = {
+    ...target.concept.lifecycle,
+    status: "revoked",
+    revokedAt: timestamp,
+    revokedReason: reason,
+  };
+  await writeConceptLifecycleFrontmatter({
+    path: target.concept.path,
+    content: target.content,
+    reviewState: "revoked",
+    lifecycle,
+  });
+  const logPaths = await appendLifecycleLogs({
+    okfDir: target.paths.okfDir,
+    conceptPaths: [target.concept.path],
+    entry: `**Lifecycle**: Revoked \`${target.concept.id}\`; reason=${reason}.`,
+  });
+  const indexPaths = await rebuildOkfKnowledgeIndexes({ homeDir: input.homeDir });
+  return { conceptPaths: [target.concept.path], logPaths, indexPaths };
+}
+
+export async function supersedeOkfKnowledgeConcept(input: {
+  homeDir: string;
+  oldConceptId: string;
+  newConceptId: string;
+  now?: string | Date;
+}): Promise<OkfKnowledgeLifecycleMutationResult> {
+  const oldId = normalizeConceptId(input.oldConceptId);
+  const newId = normalizeConceptId(input.newConceptId);
+  if (oldId === newId) throw new Error("Lifecycle supersede requires different concept ids.");
+  const oldTarget = await readMutableOkfConcept(input.homeDir, oldId);
+  const newTarget = await readMutableOkfConcept(input.homeDir, newId);
+  if (
+    newTarget.concept.lifecycle.status === "deprecated" ||
+    newTarget.concept.lifecycle.status === "revoked" ||
+    newTarget.concept.lifecycle.status === "superseded" ||
+    newTarget.concept.reviewState === "deprecated" ||
+    newTarget.concept.reviewState === "revoked" ||
+    newTarget.concept.reviewState === "superseded"
+  ) {
+    throw new Error(
+      "Lifecycle replacement concept must not be deprecated, revoked, or superseded.",
+    );
+  }
+  const oldLifecycle: OkfKnowledgeLifecycle = {
+    ...oldTarget.concept.lifecycle,
+    status: "superseded",
+    supersededBy: newTarget.concept.id,
+    revokedAt: null,
+    revokedReason: null,
+  };
+  const newLifecycle: OkfKnowledgeLifecycle = {
+    ...newTarget.concept.lifecycle,
+    supersedes: uniqueStrings([...newTarget.concept.lifecycle.supersedes, oldTarget.concept.id]),
+  };
+  await writeConceptLifecycleFrontmatter({
+    path: oldTarget.concept.path,
+    content: oldTarget.content,
+    reviewState: "superseded",
+    lifecycle: oldLifecycle,
+  });
+  await writeConceptLifecycleFrontmatter({
+    path: newTarget.concept.path,
+    content: newTarget.content,
+    reviewState: newTarget.concept.reviewState,
+    lifecycle: newLifecycle,
+  });
+  const conceptPaths = uniqueStrings([oldTarget.concept.path, newTarget.concept.path]);
+  const logPaths = await appendLifecycleLogs({
+    okfDir: oldTarget.paths.okfDir,
+    conceptPaths,
+    entry: `**Lifecycle**: Superseded \`${oldTarget.concept.id}\` with \`${newTarget.concept.id}\`.`,
+  });
+  const indexPaths = await rebuildOkfKnowledgeIndexes({ homeDir: input.homeDir });
+  return { conceptPaths, logPaths, indexPaths };
+}
+
+async function readMutableOkfConcept(
+  homeDir: string,
+  conceptId: string,
+): Promise<{
+  paths: OkfPaths;
+  concept: OkfKnowledgeConcept;
+  content: string;
+}> {
+  const paths = resolveOkfKnowledgePaths(homeDir);
+  const id = normalizeConceptId(conceptId);
+  const files = await listMarkdownFiles(paths.okfDir);
+  const matches: Array<{ concept: OkfKnowledgeConcept; content: string }> = [];
+  for (const file of files) {
+    if (RESERVED_OKF_FILENAMES.has(file.name)) continue;
+    const content = await readFile(file.path, "utf8");
+    const concept = parseOkfConceptFile(paths.okfDir, file.path, content);
+    if (concept === null) continue;
+    if (concept.id === id || concept.sourceLink === `/${id}.md`) {
+      matches.push({ concept, content });
+    }
+  }
+  if (matches.length === 0) throw new Error(`OKF knowledge concept not found: ${conceptId}`);
+  if (matches.length > 1) throw new Error(`OKF knowledge concept is ambiguous: ${conceptId}`);
+  const match = matches[0] as { concept: OkfKnowledgeConcept; content: string };
+  return { paths, concept: match.concept, content: match.content };
+}
+
+async function writeConceptLifecycleFrontmatter(input: {
+  path: string;
+  content: string;
+  reviewState: OkfKnowledgeReviewState;
+  lifecycle: OkfKnowledgeLifecycle;
+}): Promise<void> {
+  const parsed = extractFrontmatter(input.content);
+  if (parsed === null) throw new Error(`OKF concept missing frontmatter: ${input.path}`);
+  const frontmatter = upsertOkfLifecycleFrontmatter(
+    parsed.frontmatter,
+    input.reviewState,
+    input.lifecycle,
+  );
+  await writeFile(input.path, `---\n${frontmatter.trimEnd()}\n---\n${parsed.body}`, "utf8");
+}
+
+function upsertOkfLifecycleFrontmatter(
+  frontmatter: string,
+  reviewState: OkfKnowledgeReviewState,
+  lifecycle: OkfKnowledgeLifecycle,
+): string {
+  const lines = frontmatter.split("\n");
+  const evodevIndex = lines.findIndex((line) => line.trim() === "evodev:");
+  const replacement = [
+    `  reviewState: ${yamlString(reviewState)}`,
+    ...renderLifecycleYaml("  ", lifecycle).split("\n"),
+  ];
+  if (evodevIndex < 0) return [...lines, "evodev:", ...replacement].join("\n");
+  const evodevEnd = findYamlBlockEnd(lines, evodevIndex, 0);
+  const evodevBlock = lines.slice(evodevIndex + 1, evodevEnd);
+  const filtered: string[] = [];
+  for (let index = 0; index < evodevBlock.length; index += 1) {
+    const line = evodevBlock[index] ?? "";
+    if (/^ {2}reviewState:/u.test(line)) continue;
+    if (/^ {2}lifecycle:\s*$/u.test(line)) {
+      for (index += 1; index < evodevBlock.length; index += 1) {
+        const candidate = evodevBlock[index] ?? "";
+        if (candidate.trim() === "") continue;
+        const indent = candidate.length - candidate.trimStart().length;
+        if (indent <= 2) {
+          index -= 1;
+          break;
+        }
+      }
+      continue;
+    }
+    filtered.push(line);
+  }
+  const insertAfter = Math.max(
+    filtered.findIndex((line) => /^ {2}stableKey:/u.test(line)),
+    filtered.findIndex((line) => /^ {2}schema:/u.test(line)),
+  );
+  const nextBlock =
+    insertAfter < 0
+      ? [...replacement, ...filtered]
+      : [...filtered.slice(0, insertAfter + 1), ...replacement, ...filtered.slice(insertAfter + 1)];
+  return [...lines.slice(0, evodevIndex + 1), ...nextBlock, ...lines.slice(evodevEnd)].join("\n");
+}
+
+async function appendLifecycleLogs(input: {
+  okfDir: string;
+  conceptPaths: string[];
+  entry: string;
+}): Promise<string[]> {
+  const directories = [
+    ...new Set(
+      input.conceptPaths.flatMap((path) => ancestorDirectories(input.okfDir, dirname(path))),
+    ),
+  ];
+  const logPaths: string[] = [];
+  for (const directory of directories) {
+    const logPath = join(directory, "log.md");
+    await prependLogEntry(logPath, sanitizeOkfText(input.entry));
+    logPaths.push(logPath);
+  }
+  return logPaths;
+}
+
+function validateLifecycleReason(value: string): string {
+  const reason = value.trim();
+  if (reason === "") throw new Error("Lifecycle revoke requires a non-empty reason.");
+  if (FORBIDDEN_OKF_TEXT.test(reason) || PRIVATE_OR_INTERNAL_URL.test(reason)) {
+    throw new Error("Lifecycle revoke reason contains unsafe raw or sensitive text.");
+  }
+  return sanitizeOkfText(reason);
+}
+
+export async function lintOkfKnowledge(input: {
+  homeDir: string;
+  stale?: boolean;
+  now?: string | Date;
+}): Promise<OkfKnowledgeLintResult> {
+  const paths = resolveOkfKnowledgePaths(input.homeDir);
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const now = normalizeQueryNow(input.now);
+  if (!(await pathExists(paths.okfDir))) {
+    return {
+      ok: true,
+      errors,
+      warnings: ["OKF knowledge bundle does not exist."],
+      conceptCount: 0,
+    };
+  }
+  const directories = await listDirectories(paths.okfDir);
+  for (const directory of directories) {
+    const indexPath = join(directory, "index.md");
+    const logPath = join(directory, "log.md");
+    if (!(await pathExists(indexPath)))
+      errors.push(`Missing index.md: ${displayOkfPath(paths.okfDir, directory)}`);
+    if (!(await pathExists(logPath)))
+      errors.push(`Missing log.md: ${displayOkfPath(paths.okfDir, directory)}`);
+  }
+
+  let conceptCount = 0;
+  const files = await listMarkdownFiles(paths.okfDir);
+  const knownConceptIds = new Set(
+    files
+      .filter((file) => !RESERVED_OKF_FILENAMES.has(file.name))
+      .map((file) => toOkfRelativePath(paths.okfDir, file.path).replace(/\.md$/, "")),
+  );
+  for (const file of files) {
+    const rel = displayOkfPath(paths.okfDir, file.path);
+    const content = await readFile(file.path, "utf8");
+    if (file.name === "index.md") {
+      if (file.path !== join(paths.okfDir, "index.md") && hasFrontmatter(content)) {
+        errors.push(`Non-root index.md must not have frontmatter: ${rel}`);
+      }
+      continue;
+    }
+    if (file.name === "log.md") {
+      if (hasFrontmatter(content)) errors.push(`log.md must not have frontmatter: ${rel}`);
+      continue;
+    }
+    conceptCount += 1;
+    const parsed = extractFrontmatter(content);
+    if (parsed === null) {
+      errors.push(`Concept missing parseable YAML frontmatter: ${rel}`);
+      continue;
+    }
+    const type = readYamlScalar(parsed.frontmatter, "type");
+    if (type === null || type.trim() === "") errors.push(`Concept missing non-empty type: ${rel}`);
+    if (readYamlScalar(parsed.frontmatter, "title") === null)
+      warnings.push(`Concept missing title: ${rel}`);
+    if (readYamlScalar(parsed.frontmatter, "description") === null)
+      warnings.push(`Concept missing description: ${rel}`);
+    if (!parsed.frontmatter.includes("evodev:"))
+      warnings.push(`Concept missing evodev extension: ${rel}`);
+    const reviewState = parseOkfReviewState(
+      readIndentedYamlScalar(parsed.frontmatter, "reviewState") ?? "auto-stored/unreviewed",
+    );
+    if (reviewState === "auto-stored/unreviewed") {
+      warnings.push(`Concept missing active lifecycle reviewState: ${rel}`);
+    }
+    if (FORBIDDEN_OKF_TEXT.test(content))
+      errors.push(`Concept contains forbidden sensitive text: ${rel}`);
+    if (input.stale === true) {
+      const concept = parseOkfConceptFile(paths.okfDir, file.path, content);
+      if (concept !== null) {
+        lintOkfLifecycle({
+          concept,
+          frontmatter: parsed.frontmatter,
+          knownConceptIds,
+          now,
+          errors,
+          warnings,
+        });
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings, conceptCount };
+}
+
+export function formatOkfKnowledgeList(concepts: OkfKnowledgeConcept[]): string {
+  if (concepts.length === 0) return "EvoDev OKF knowledge concepts: none";
+  return [
+    "EvoDev OKF knowledge concepts",
+    "",
+    ...concepts.map(
+      (concept) => `  - ${concept.id} (${concept.type}): ${concept.title} [${concept.sourceLink}]`,
+    ),
+  ].join("\n");
+}
+
+export function formatOkfKnowledgeQuery(result: OkfKnowledgeQueryResult): string {
+  const sectionLabels: Array<[OkfKnowledgeContextSection, string]> = [
+    ["applicable-knowledge", "Applicable Knowledge"],
+    ["role-attention", "Role Attention"],
+    ["repo-attention", "Repo Attention"],
+    ["workflow-attention", "Workflow Attention"],
+    ["verification", "Verification"],
+    ["accepted-evos-cases", "Accepted Evos Cases"],
+  ];
+  return [
+    "# EvoDev Knowledge Context",
+    "",
+    `Project: ${result.projectKey ?? "all"}`,
+    `Role: ${result.roleId ?? "any"}`,
+    `Workflow: ${result.workflowId ?? "any"}`,
+    ...(result.queryText === undefined ? [] : [`Query: ${sanitizeOkfText(result.queryText)}`]),
+    `Scope: ${result.paths.length === 0 ? "all" : result.paths.join(", ")}`,
+    "",
+    ...sectionLabels.flatMap(([section, label]) => {
+      const items = result.items.filter((item) => item.section === section);
+      return [
+        `## ${label}`,
+        "",
+        ...(items.length === 0
+          ? ["- none"]
+          : items.map(
+              (item) =>
+                `- ${item.summary}\n  Source: ${item.sourceLink}\n  Match: ${item.matchReasons.join(", ")}\n  Rank: ${item.rank}`,
+            )),
+        "",
+      ];
+    }),
+    ...(result.warnings.length === 0
+      ? ["Warnings: none"]
+      : ["Warnings:", ...result.warnings.map((warning) => `  - ${warning}`)]),
+  ].join("\n");
+}
+
+export function formatOkfKnowledgePlan(plan: OkfKnowledgePlan): string {
+  return [
+    "EvoDev OKF knowledge plan",
+    "",
+    `Project: ${plan.projectKey}`,
+    `Run: ${plan.runId}`,
+    `Candidates: ${plan.candidates.length}`,
+    ...(plan.candidates.length === 0
+      ? ["  - none"]
+      : plan.candidates.map((candidate) => {
+          const scores = resolveCandidateScoresForWrite(candidate);
+          return `  - ${sanitizeOkfText(candidate.id)} (${sanitizeOkfText(candidate.kind)}, ${candidate.decision}, ${resolveCandidateReviewStateForWrite(candidate)}): ${sanitizeOkfText(candidate.title)}; scores evidence=${scores.evidenceStrength} reuse=${scores.reuseValue} action=${scores.actionability} stability=${scores.stability} privacy=${scores.privacyRisk} duplicate=${scores.duplicationRisk}; reason=${sanitizeOkfText(candidate.decisionReason ?? "legacy plan")}`;
+        })),
+    `Conflicts: ${plan.conflicts.length}`,
+    ...plan.conflicts.map(
+      (conflict) =>
+        `  - ${sanitizeOkfText(conflict.candidateId)}: ${sanitizeOkfText(conflict.reason)}`,
+    ),
+  ].join("\n");
+}
+
+export function formatOkfKnowledgeLint(result: OkfKnowledgeLintResult): string {
+  return [
+    "EvoDev OKF knowledge lint",
+    "",
+    `Status: ${result.ok ? "PASS" : "FAIL"}`,
+    `Concepts: ${result.conceptCount}`,
+    ...(result.errors.length === 0
+      ? ["Errors: none"]
+      : ["Errors:", ...result.errors.map((item) => `  - ${item}`)]),
+    ...(result.warnings.length === 0
+      ? ["Warnings: none"]
+      : ["Warnings:", ...result.warnings.map((item) => `  - ${item}`)]),
+  ].join("\n");
+}
+
+function createCandidateFromKnowledgeRecord(
+  record: EvolutionKnowledgeRecord,
+  batch: EvolutionDistillationBatch,
+): OkfKnowledgePlanCandidate {
+  const type = knowledgeKindToOkfType(record.kind);
+  const category = knowledgeKindToDirectory(record.kind);
+  const targetPath = `concepts/${category}/${record.id}.md`;
+  const sourceLink = `/${targetPath}`;
+  const hasVerificationEvidence = batch.evidenceWindow.events.some(
+    (event) => event.kind === "verification" || /test|lint|typecheck|build/i.test(event.summary),
+  );
+  return {
+    id: record.id,
+    decision: "create",
+    kind: record.kind,
+    okfType: type,
+    targetStore: "okf",
+    targetPath,
+    stableKey: `${record.kind}:${record.projectKey}:${record.id}`,
+    confidence: record.confidence,
+    title: record.title,
+    description: record.summary,
+    claim: record.summary,
+    basis: "direct",
+    metadataOnlyEvidence: true,
+    howToApply: record.body,
+    antiCriteria: ["Do not treat this knowledge as a hard policy."],
+    roleTags: record.roleTags,
+    repoTags: [record.projectKey],
+    workflowTags: record.tags.filter((tag) => tag.startsWith("workflow-")),
+    pathScopes: [],
+    relatedConceptLinks: [],
+    overlayUpdates: createOverlayUpdates(record.projectKey, record.roleTags, [], sourceLink),
+    scores: DEFAULT_OKF_CANDIDATE_SCORES,
+    decisionReason: "Pending M3 decision scoring.",
+    evidenceRefs: record.provenance.sourceRefs,
+    reviewState: record.reviewState,
+    bodySections: {
+      summary: record.summary,
+      appliesWhen: [`Working in repo scope \`${record.projectKey}\`.`],
+      guidance: [record.body],
+      antiCriteria: ["Do not store raw trace payloads in active knowledge."],
+      verification: hasVerificationEvidence ? ["Use verified local outcomes as evidence."] : [],
+      citations: [],
+    },
+    privacyCheck: createOkfPrivacyCheck(),
+  };
+}
+
+function resolveFailedPlanPath(homeDir: string, projectKey: string, runId: string): string {
+  const root = join(resolveEvoDevPaths(homeDir).stateDir, "evolution");
+  const path = join(
+    root,
+    sanitizePlanStorageId("projectKey", projectKey),
+    sanitizePlanStorageId("runId", runId),
+    "knowledge-plan.failed.json",
+  );
+  assertPathDescendant(root, path, "failedPlanPath");
+  return path;
+}
+
+async function ensureLocalKnowledgeGitRepository(knowledgeDir: string): Promise<void> {
+  await mkdir(knowledgeDir, { recursive: true });
+  const gitDir = join(knowledgeDir, ".git");
+  if (await pathExists(gitDir)) return;
+
+  await mkdir(join(gitDir, "objects", "info"), { recursive: true });
+  await mkdir(join(gitDir, "objects", "pack"), { recursive: true });
+  await mkdir(join(gitDir, "refs", "heads"), { recursive: true });
+  await mkdir(join(gitDir, "refs", "tags"), { recursive: true });
+  await mkdir(join(gitDir, "info"), { recursive: true });
+  await writeTextIfMissing(join(gitDir, "HEAD"), "ref: refs/heads/main\n");
+  await writeTextIfMissing(
+    join(gitDir, "config"),
+    [
+      "[core]",
+      "\trepositoryformatversion = 0",
+      "\tfilemode = true",
+      "\tbare = false",
+      "\tlogallrefupdates = true",
+      "",
+    ].join("\n"),
+  );
+  await writeTextIfMissing(
+    join(gitDir, "info", "exclude"),
+    [
+      "# EvoDev user-local knowledge git repository.",
+      "# No remote is configured by default.",
+      "",
+    ].join("\n"),
+  );
+}
+
+function sanitizePlanStorageId(field: string, value: string): string {
+  const trimmed = value.trim();
+  if (trimmed === "") throw new Error(`Invalid OKF knowledge plan ${field}: ${value}`);
+  if (trimmed.split(/[\\/]+/u).some((segment) => segment === "." || segment === "..")) {
+    throw new Error(`Invalid OKF knowledge plan ${field}: ${value}`);
+  }
+  const sanitized =
+    trimmed
+      .toLowerCase()
+      .replace(/[^a-z0-9._/-]+/gu, "-")
+      .replace(/[\\/]+/gu, "-")
+      .replace(/^-+|-+$/gu, "")
+      .slice(0, 160) || "unknown";
+  if (sanitized === "." || sanitized === "..") {
+    throw new Error(`Invalid OKF knowledge plan ${field}: ${value}`);
+  }
+  return sanitized;
+}
+
+function assertPathDescendant(root: string, candidate: string, field: string): void {
+  const normalizedRoot = resolve(root);
+  const normalizedCandidate = resolve(candidate);
+  const relativePath = relative(normalizedRoot, normalizedCandidate);
+  if (relativePath === "" || relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error(`OKF knowledge path ${field} escaped expected root.`);
+  }
+}
+
+async function writeTextIfMissing(path: string, value: string): Promise<void> {
+  if (await pathExists(path)) return;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, value, { encoding: "utf8", flag: "wx" });
+}
+
+function createCandidateFromEvosCase(evosCase: EvolutionEvosCase): OkfKnowledgePlanCandidate {
+  const targetPath = `concepts/evos/${evosCase.id}.md`;
+  const sourceLink = `/${targetPath}`;
+  return {
+    id: evosCase.id,
+    decision: "create",
+    kind: "evos-case",
+    okfType: "EvoDev Evolution Case",
+    targetStore: "okf",
+    targetPath,
+    stableKey: `evos:${evosCase.projectKey}:${evosCase.id}`,
+    confidence: evosCase.confidence,
+    title: evosCase.title,
+    description: evosCase.trigger.summary,
+    claim: evosCase.expectedFutureBehavior,
+    basis: "direct",
+    metadataOnlyEvidence: true,
+    howToApply: evosCase.expectedFutureBehavior,
+    antiCriteria: ["Do not directly change runtime behavior from an evos case."],
+    roleTags: evosCase.roleTags,
+    repoTags: [evosCase.projectKey],
+    workflowTags: [],
+    pathScopes: [],
+    relatedConceptLinks: [],
+    overlayUpdates: createOverlayUpdates(evosCase.projectKey, evosCase.roleTags, [], sourceLink),
+    scores: DEFAULT_OKF_CANDIDATE_SCORES,
+    decisionReason: "Pending M3 decision scoring.",
+    evidenceRefs: evosCase.provenance.sourceRefs,
+    reviewState: evosCase.reviewState,
+    bodySections: {
+      summary: evosCase.result.summary,
+      appliesWhen: [evosCase.trigger.summary],
+      guidance: [evosCase.expectedFutureBehavior],
+      antiCriteria: ["Use as contextual evidence, not as a hard rule."],
+      verification: evosCase.result.verificationSignals,
+      citations: [],
+    },
+    privacyCheck: createOkfPrivacyCheck(),
+  };
+}
+
+function createOverlayUpdates(
+  projectKey: string,
+  roleTags: string[],
+  workflowTags: string[],
+  sourceLink: string,
+): OkfKnowledgeOverlayUpdate[] {
+  return [
+    {
+      targetPath: `repos/${sanitizeSlug(projectKey)}/overview.md`,
+      operation: "append-link",
+      link: sourceLink,
+    },
+    ...roleTags.map((role) => ({
+      targetPath: `roles/${sanitizeSlug(role)}/attention.md`,
+      operation: "append-link" as const,
+      link: sourceLink,
+    })),
+    ...workflowTags.map((workflow) => ({
+      targetPath: `workflows/${sanitizeSlug(workflow)}/attention.md`,
+      operation: "append-link" as const,
+      link: sourceLink,
+    })),
+  ];
+}
+
+async function writeNeedsHumanKnowledgeCandidate(input: {
+  homeDir: string;
+  plan: OkfKnowledgePlan;
+  candidate: OkfKnowledgePlanCandidate;
+}): Promise<string> {
+  const root = join(resolveEvoDevPaths(input.homeDir).stateDir, "evolution");
+  const targetDir = join(
+    root,
+    sanitizePlanStorageId("projectKey", input.plan.projectKey),
+    sanitizePlanStorageId("runId", input.plan.runId),
+    "review-candidates",
+  );
+  const targetPath = join(
+    targetDir,
+    `${sanitizePlanStorageId("candidateId", input.candidate.id)}.json`,
+  );
+  assertPathDescendant(root, targetPath, "reviewCandidatePath");
+  const candidateSnapshot = sanitizeReviewQueueValue(input.candidate);
+  await writeJson(
+    targetPath,
+    {
+      schemaVersion: 1,
+      kind: "evolution-review-candidate",
+      id: input.candidate.id,
+      projectKey: input.plan.projectKey,
+      runId: input.plan.runId,
+      createdAt: input.plan.createdAt,
+      candidateKind: input.candidate.kind,
+      title: sanitizeOkfText(input.candidate.title),
+      targetStore: input.candidate.targetStore,
+      targetPath: sanitizeOkfText(input.candidate.targetPath),
+      stableKey: sanitizeOkfText(input.candidate.stableKey),
+      reviewState: "needs-human",
+      reasons: [sanitizeOkfText(input.candidate.decisionReason)],
+      candidate: candidateSnapshot,
+      provenance: {
+        runId: input.plan.runId,
+        evidenceWindowId: input.plan.evidenceWindowId,
+        evidenceRefs: input.candidate.evidenceRefs.map(sanitizeOkfText),
+        createdBy: "evodev",
+        rawLogsStored: false,
+        rawPromptsStored: false,
+        sourceDumpsStored: false,
+        rawCommandOutputStored: false,
+      },
+      privacy: {
+        classification: "local-private",
+        rawPromptsStored: false,
+        rawLogsStored: false,
+        sourceDumpsStored: false,
+        rawCommandOutputStored: false,
+        secretsStored: false,
+        internalLinksStored: false,
+      },
+    },
+    { overwrite: true },
+  );
+  return targetPath;
+}
+
+function sanitizeOkfPlanCandidate(candidate: OkfKnowledgePlanCandidate): OkfKnowledgePlanCandidate {
+  return sanitizeReviewQueueValue(candidate) as OkfKnowledgePlanCandidate;
+}
+
+function sanitizeReviewQueueValue(value: unknown): unknown {
+  if (typeof value === "string") return sanitizeOkfText(value);
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) return value.map(sanitizeReviewQueueValue);
+  if (typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [key, sanitizeReviewQueueValue(child)]),
+  );
+}
+
+function sanitizeOkfText(value: string): string {
+  return value
+    .replace(new RegExp(PRIVATE_OR_INTERNAL_URL.source, "gi"), "[redacted]")
+    .replace(new RegExp(FORBIDDEN_OKF_TEXT.source, "gi"), "[redacted]")
+    .replace(/\s+/gu, " ")
+    .trim()
+    .slice(0, 800);
+}
+
+function hasUnsafeCandidateContent(candidate: OkfKnowledgePlanCandidate): boolean {
+  const content = JSON.stringify(candidate);
+  return (
+    FORBIDDEN_OKF_TEXT.test(content) ||
+    FORBIDDEN_OKF_FIELD.test(content) ||
+    PRIVATE_OR_INTERNAL_URL.test(content) ||
+    (candidate.privacyCheck !== undefined &&
+      Object.values(candidate.privacyCheck).some((value) => value !== false))
+  );
+}
+
+function hasHighRiskHumanReviewSignal(candidate: unknown): boolean {
+  if (!isRecord(candidate)) return false;
+  const body = isRecord(candidate.bodySections) ? candidate.bodySections : {};
+  const stringArray = (value: unknown): string[] =>
+    Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+  const stringValue = (value: unknown): string => (typeof value === "string" ? value : "");
+  const values = [
+    stringValue(candidate.id),
+    stringValue(candidate.kind),
+    stringValue(candidate.okfType),
+    stringValue(candidate.targetStore),
+    stringValue(candidate.targetPath),
+    stringValue(candidate.stableKey),
+    stringValue(candidate.title),
+    stringValue(candidate.description),
+    stringValue(candidate.claim),
+    stringValue(candidate.howToApply),
+    ...stringArray(candidate.antiCriteria),
+    ...stringArray(candidate.roleTags),
+    ...stringArray(candidate.repoTags),
+    ...stringArray(candidate.workflowTags),
+    ...stringArray(candidate.pathScopes),
+    ...stringArray(candidate.relatedConceptLinks),
+    stringValue(body.summary),
+    ...stringArray(body.appliesWhen),
+    ...stringArray(body.guidance),
+    ...stringArray(body.antiCriteria),
+    ...stringArray(body.verification),
+    ...stringArray(body.citations),
+  ];
+  return HUMAN_REVIEW_DOMAIN_PATTERN.test(values.join(" "));
+}
+
+function explainNeedsHumanDecision(
+  candidate: OkfKnowledgePlanCandidate,
+  scores: OkfKnowledgeCandidateScores,
+  hasVerification: boolean,
+  hasScopeTags: boolean,
+): string {
+  const reasons: string[] = [];
+  if (candidate.targetStore !== "okf") reasons.push("target is not user-local OKF");
+  if (candidate.basis !== "direct") reasons.push("basis is inferred");
+  if (!candidate.metadataOnlyEvidence) reasons.push("evidence is not metadata-only");
+  if (!hasVerification) reasons.push("verification evidence is missing");
+  if (!hasScopeTags) reasons.push("repo or role tags are missing");
+  if (scores.evidenceStrength < 4) reasons.push("evidence strength is below auto-accept");
+  if (scores.privacyRisk > 2) reasons.push("privacy risk is above auto-accept");
+  if (scores.stability < 3) reasons.push("stability is below auto-accept");
+  if (scores.duplicationRisk > 2) reasons.push("duplication risk is above auto-accept");
+  return `Needs human review: ${reasons.join("; ") || "auto-accept gates were not all satisfied"}.`;
+}
+
+function resolveCandidateReviewStateForWrite(
+  candidate: OkfKnowledgePlanCandidate,
+): OkfKnowledgeReviewState {
+  if (candidate.reviewState === "auto-accepted" || candidate.decision === "auto-accept") {
+    return "auto-accepted";
+  }
+  if (candidate.reviewState === "accepted" || candidate.decision === "create") return "accepted";
+  if (candidate.decision === "update") return "accepted";
+  return candidate.reviewState ?? "auto-stored/unreviewed";
+}
+
+function resolveCandidateScoresForWrite(
+  candidate: OkfKnowledgePlanCandidate,
+): OkfKnowledgeCandidateScores {
+  return candidate.scores ?? DEFAULT_OKF_CANDIDATE_SCORES;
+}
+
+function normalizeComparableText(value: string): string {
+  return sanitizeSlug(value).replace(/[._/-]+/gu, "-");
+}
+
+function listMarkdownFilesSync(root: string): Array<{ path: string; name: string }> {
+  if (!existsSync(root)) return [];
+  const entries = readdirSync(root, { withFileTypes: true });
+  const files: Array<{ path: string; name: string }> = [];
+  for (const entry of entries) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listMarkdownFilesSync(path));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push({ path, name: entry.name });
+    }
+  }
+  return files;
+}
+
+function knowledgeKindToOkfType(kind: string): string {
+  if (kind === "rule") return "EvoDev Rule";
+  if (kind === "workflow-hint") return "EvoDev Pattern";
+  if (kind === "role-note") return "EvoDev Role Attention";
+  if (kind === "verification-pattern") return "EvoDev Verification Pattern";
+  if (kind === "skill-gap") return "EvoDev Warning";
+  return "EvoDev Evolution Case";
+}
+
+function knowledgeKindToDirectory(kind: string): string {
+  if (kind === "rule") return "rules";
+  if (kind === "workflow-hint") return "patterns";
+  if (kind === "role-note") return "glossary";
+  if (kind === "verification-pattern") return "verification";
+  if (kind === "skill-gap") return "warnings";
+  return "evos";
+}
+
+async function ensureOverlayConcept(input: {
+  okfDir: string;
+  overlayPath: string;
+  candidate: OkfKnowledgePlanCandidate;
+  projectKey: string;
+  runId: string;
+  link: string;
+}): Promise<void> {
+  const relativePath = toOkfRelativePath(input.okfDir, input.overlayPath);
+  const segments = relativePath.split("/");
+  const root = segments[0] ?? "repos";
+  const scopeId = segments[1] ?? input.projectKey;
+  const type =
+    root === "roles"
+      ? "EvoDev Role Attention"
+      : root === "workflows"
+        ? "EvoDev Workflow Attention"
+        : "EvoDev Repo Attention";
+  await ensureOkfDirectory(
+    input.okfDir,
+    dirname(relativePath),
+    scopeId,
+    `Attention overlay for ${scopeId}.`,
+  );
+  const exists = await pathExists(input.overlayPath);
+  const linkLine = `- [${input.candidate.title}](${input.link}) - ${input.candidate.description}`;
+  if (exists) {
+    const current = await readFile(input.overlayPath, "utf8");
+    if (current.includes(input.link)) return;
+    await writeFile(input.overlayPath, `${current.trimEnd()}\n${linkLine}\n`, "utf8");
+    return;
+  }
+  await writeFile(
+    input.overlayPath,
+    [
+      "---",
+      `type: ${yamlString(type)}`,
+      `title: ${yamlString(`${scopeId} attention`)}`,
+      `description: ${yamlString(`Attention overlay for ${scopeId}.`)}`,
+      `resource: ${yamlString(`evodev://${relativePath.replace(/\.md$/, "")}`)}`,
+      "tags:",
+      `  - ${yamlString("evodev")}`,
+      `  - ${yamlString(`${root.slice(0, -1)}:${scopeId}`)}`,
+      `timestamp: ${yamlString(new Date().toISOString())}`,
+      "evodev:",
+      `  schema: ${yamlString("knowledge/v1")}`,
+      `  stableKey: ${yamlString(`overlay:${relativePath.replace(/\.md$/, "")}`)}`,
+      `  reviewState: ${yamlString(resolveCandidateReviewStateForWrite(input.candidate))}`,
+      renderLifecycleYaml(
+        "  ",
+        createDefaultOkfLifecycle({
+          type,
+          path: relativePath,
+          tags: ["evodev", `${root.slice(0, -1)}:${scopeId}`],
+          title: `${scopeId} attention`,
+          reviewState: resolveCandidateReviewStateForWrite(input.candidate),
+          createdAt: new Date().toISOString(),
+        }),
+      ),
+      "  source:",
+      `    kind: ${yamlString("okf-organizer")}`,
+      `    projectKey: ${yamlString(input.projectKey)}`,
+      "    rawContentStored: false",
+      "  scope:",
+      "    repoTags:",
+      `      - ${yamlString(input.projectKey)}`,
+      "    roleTags: []",
+      "    workflowTags: []",
+      "    pathScopes: []",
+      renderPrivacyYaml("  "),
+      "  organizer:",
+      `    lastAction: ${yamlString(input.candidate.decision)}`,
+      `    lastRunId: ${yamlString(input.runId)}`,
+      "    duplicateOf: null",
+      "    supersedes: []",
+      "---",
+      "",
+      "# Attention",
+      "",
+      "This overlay links scope-specific attention to canonical EvoDev knowledge.",
+      "",
+      "# Linked Core Knowledge",
+      "",
+      linkLine,
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+}
+
+function renderOkfConcept(candidate: OkfKnowledgePlanCandidate, plan: OkfKnowledgePlan): string {
+  const scores = resolveCandidateScoresForWrite(candidate);
+  return [
+    "---",
+    `type: ${yamlString(candidate.okfType)}`,
+    `title: ${yamlString(candidate.title)}`,
+    `description: ${yamlString(candidate.description)}`,
+    `resource: ${yamlString(`evodev://${candidate.targetPath.replace(/\.md$/, "")}`)}`,
+    "tags:",
+    ...[
+      "evodev",
+      candidate.kind,
+      ...candidate.roleTags.map((tag) => `role:${tag}`),
+      ...candidate.repoTags.map((tag) => `repo:${tag}`),
+      ...candidate.workflowTags.map((tag) => `workflow:${tag}`),
+    ].map((tag) => `  - ${yamlString(tag)}`),
+    `timestamp: ${yamlString(plan.createdAt)}`,
+    "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,
+      }),
+    ),
+    "  source:",
+    `    kind: ${yamlString("trace-distillation")}`,
+    `    projectKey: ${yamlString(plan.projectKey)}`,
+    `    runId: ${yamlString(plan.runId)}`,
+    `    evidenceWindowId: ${yamlString(plan.evidenceWindowId)}`,
+    "    rawContentStored: false",
+    "  scope:",
+    renderYamlList("    repoTags", candidate.repoTags),
+    renderYamlList("    roleTags", candidate.roleTags),
+    renderYamlList("    workflowTags", candidate.workflowTags),
+    renderYamlList("    pathScopes", candidate.pathScopes),
+    renderPrivacyYaml("  "),
+    "  organizer:",
+    `    lastAction: ${yamlString(candidate.decision)}`,
+    `    lastRunId: ${yamlString(plan.runId)}`,
+    "    duplicateOf: null",
+    "    supersedes: []",
+    "  scores:",
+    `    evidenceStrength: ${scores.evidenceStrength}`,
+    `    reuseValue: ${scores.reuseValue}`,
+    `    actionability: ${scores.actionability}`,
+    `    stability: ${scores.stability}`,
+    `    privacyRisk: ${scores.privacyRisk}`,
+    `    duplicationRisk: ${scores.duplicationRisk}`,
+    "---",
+    "",
+    "# Summary",
+    "",
+    candidate.bodySections.summary,
+    "",
+    "# Applies When",
+    "",
+    renderMarkdownList(candidate.bodySections.appliesWhen),
+    "",
+    "# Guidance",
+    "",
+    renderMarkdownList(candidate.bodySections.guidance),
+    "",
+    "# Anti-Criteria",
+    "",
+    renderMarkdownList(candidate.bodySections.antiCriteria),
+    "",
+    "# Verification",
+    "",
+    renderMarkdownList(
+      candidate.bodySections.verification.length === 0
+        ? ["No verification command is stored in this concept."]
+        : candidate.bodySections.verification,
+    ),
+    "",
+    "# Related Concepts",
+    "",
+    renderMarkdownList(
+      candidate.relatedConceptLinks.length === 0
+        ? ["No related concepts yet."]
+        : candidate.relatedConceptLinks,
+    ),
+    "",
+    "# Citations",
+    "",
+    renderMarkdownList(
+      candidate.bodySections.citations.length === 0
+        ? ["No external citations stored."]
+        : candidate.bodySections.citations,
+    ),
+    "",
+  ].join("\n");
+}
+
+async function ensureOkfDirectory(
+  okfDir: string,
+  relativeDir: string,
+  title: string,
+  description: string,
+): Promise<void> {
+  const dir =
+    relativeDir === "" || relativeDir === "." ? okfDir : resolveOkfTargetPath(okfDir, relativeDir);
+  await mkdir(dir, { recursive: true });
+  const isRoot = dir === okfDir;
+  const indexPath = join(dir, "index.md");
+  if (!(await pathExists(indexPath))) {
+    await writeFile(
+      indexPath,
+      isRoot
+        ? [
+            "---",
+            `okf_version: ${yamlString("0.1")}`,
+            `title: ${yamlString(title)}`,
+            `description: ${yamlString(description)}`,
+            "---",
+            "",
+            `# ${title}`,
+            "",
+            description,
+            "",
+          ].join("\n")
+        : [`# ${title}`, "", description, ""].join("\n"),
+      "utf8",
+    );
+  }
+  const logPath = join(dir, "log.md");
+  if (!(await pathExists(logPath))) {
+    await writeFile(
+      logPath,
+      [
+        "# Directory Update Log",
+        "",
+        `## ${todayIsoDate()}`,
+        "* **Initialization**: Created OKF directory.",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+  }
+}
+
+async function regenerateOkfDirectoryIndexes(okfDir: string): Promise<string[]> {
+  const directories = await listDirectories(okfDir);
+  const paths: string[] = [];
+  for (const directory of directories) {
+    const rel = toOkfRelativePath(okfDir, directory);
+    const isRoot = directory === okfDir;
+    const entries = await readdir(directory, { withFileTypes: true });
+    const conceptLines: string[] = [];
+    const directoryLines: string[] = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      if (entry.isDirectory()) {
+        directoryLines.push(`* [${entry.name}](./${entry.name}/) - ${titleFromSlug(entry.name)}.`);
+        continue;
+      }
+      if (
+        !entry.isFile() ||
+        !entry.name.endsWith(".md") ||
+        RESERVED_OKF_FILENAMES.has(entry.name)
+      ) {
+        continue;
+      }
+      const filePath = join(directory, entry.name);
+      const concept = parseOkfConceptFile(okfDir, filePath, await readFile(filePath, "utf8"));
+      if (concept !== null && !isActiveOkfConcept(concept)) continue;
+      const title = concept?.title ?? titleFromSlug(entry.name.replace(/\.md$/, ""));
+      const description = concept?.description ?? "";
+      conceptLines.push(`* [${title}](./${entry.name}) - ${description}`);
+    }
+    const content = [
+      ...(isRoot
+        ? [
+            "---",
+            `okf_version: ${yamlString("0.1")}`,
+            `title: ${yamlString("EvoDev User Knowledge")}`,
+            `description: ${yamlString("User-local active engineering knowledge for EvoDev.")}`,
+            "---",
+            "",
+          ]
+        : []),
+      `# ${isRoot ? "EvoDev Knowledge" : titleFromSlug(rel.split("/").at(-1) ?? "Index")}`,
+      "",
+      ...(directoryLines.length === 0 ? [] : ["# Subdirectories", "", ...directoryLines, ""]),
+      ...(conceptLines.length === 0 ? [] : ["# Concepts", "", ...conceptLines, ""]),
+    ].join("\n");
+    const indexPath = join(directory, "index.md");
+    await writeFile(indexPath, content, "utf8");
+    paths.push(indexPath);
+  }
+  return paths;
+}
+
+async function appendOrganizerLogs(input: {
+  okfDir: string;
+  affectedDirectories: string[];
+  plan: OkfKnowledgePlan;
+  conceptPaths: string[];
+  overlayPaths: string[];
+  skippedCandidates: string[];
+  needsHumanCandidates: string[];
+}): Promise<string[]> {
+  const summary = `**Update**: Distilled run \`${input.plan.runId}\` for repo \`${input.plan.projectKey}\`; created/updated ${input.conceptPaths.length} concept(s), updated ${input.overlayPaths.length} overlay(s), skipped ${input.skippedCandidates.length}, needs-human ${input.needsHumanCandidates.length}.`;
+  const paths: string[] = [];
+  const uniqueDirectories = [
+    ...new Set(
+      input.affectedDirectories.flatMap((directory) =>
+        ancestorDirectories(input.okfDir, directory),
+      ),
+    ),
+  ];
+  for (const directory of uniqueDirectories) {
+    const logPath = join(directory, "log.md");
+    await prependLogEntry(logPath, summary);
+    paths.push(logPath);
+  }
+  return paths;
+}
+
+function ancestorDirectories(root: string, directory: string): string[] {
+  const directories = [directory];
+  let current = directory;
+  while (current !== root && current.startsWith(root)) {
+    current = dirname(current);
+    directories.push(current);
+  }
+  return directories;
+}
+
+async function appendOkfLog(okfDir: string, entry: string): Promise<void> {
+  await prependLogEntry(join(okfDir, "log.md"), entry);
+}
+
+async function prependLogEntry(logPath: string, entry: string): Promise<void> {
+  await mkdir(dirname(logPath), { recursive: true });
+  const date = todayIsoDate();
+  const existing = (await pathExists(logPath))
+    ? await readFile(logPath, "utf8")
+    : "# Directory Update Log\n";
+  const line = `* ${entry}`;
+  if (existing.includes(`## ${date}`)) {
+    await writeFile(logPath, existing.replace(`## ${date}\n`, `## ${date}\n${line}\n`), "utf8");
+    return;
+  }
+  const withoutTitle = existing.replace(/^# Directory Update Log\s*/u, "").trimStart();
+  await writeFile(
+    logPath,
+    `${["# Directory Update Log", "", `## ${date}`, line, "", withoutTitle].join("\n").trimEnd()}\n`,
+    "utf8",
+  );
+}
+
+function parseOkfConceptFile(
+  okfDir: string,
+  filePath: string,
+  content: string,
+): OkfKnowledgeConcept | null {
+  const parsed = extractFrontmatter(content);
+  if (parsed === null) return null;
+  const rel = toOkfRelativePath(okfDir, filePath);
+  const id = rel.replace(/\.md$/, "");
+  const frontmatter = parsed.frontmatter;
+  const stableKey =
+    readIndentedYamlScalar(frontmatter, "stableKey") ?? `legacy:${rel.replace(/\.md$/, "")}`;
+  const reviewState = parseOkfReviewState(
+    readIndentedYamlScalar(frontmatter, "reviewState") ?? "auto-stored/unreviewed",
+  );
+  const type = readYamlScalar(frontmatter, "type") ?? "Unknown";
+  const title = readYamlScalar(frontmatter, "title") ?? titleFromSlug(id.split("/").at(-1) ?? id);
+  const description = readYamlScalar(frontmatter, "description") ?? "";
+  const tags = readYamlList(frontmatter, "tags");
+  const repoTags = readYamlList(frontmatter, "repoTags");
+  const roleTags = readYamlList(frontmatter, "roleTags");
+  const workflowTags = readYamlList(frontmatter, "workflowTags");
+  const pathScopes = readYamlList(frontmatter, "pathScopes");
+  const lifecycleParsed = parseOkfLifecycle(frontmatter, {
+    type,
+    path: rel,
+    tags,
+    title,
+    reviewState,
+    createdAt: readYamlScalar(frontmatter, "timestamp") ?? undefined,
+  });
+  return {
+    id,
+    path: filePath,
+    sourceLink: `/${rel}`,
+    type,
+    stableKey,
+    reviewState,
+    lifecycle: lifecycleParsed.lifecycle,
+    lifecyclePersisted: lifecycleParsed.persisted,
+    title,
+    description,
+    tags,
+    repoTags,
+    roleTags,
+    workflowTags,
+    pathScopes,
+    body: parsed.body,
+  };
+}
+
+function matchesConceptFilters(
+  concept: OkfKnowledgeConcept,
+  input: { projectKey?: string; roleId?: string; workflowId?: string; paths?: string[] },
+): boolean {
+  if (
+    input.projectKey !== undefined &&
+    concept.repoTags.length > 0 &&
+    !concept.repoTags.includes(sanitizeSlug(input.projectKey)) &&
+    !concept.tags.includes(`repo:${sanitizeSlug(input.projectKey)}`)
+  ) {
+    return false;
+  }
+  if (
+    input.roleId !== undefined &&
+    concept.roleTags.length > 0 &&
+    !concept.roleTags.includes(sanitizeSlug(input.roleId)) &&
+    !concept.tags.includes(`role:${sanitizeSlug(input.roleId)}`)
+  ) {
+    return false;
+  }
+  if (
+    input.workflowId !== undefined &&
+    concept.workflowTags.length > 0 &&
+    !concept.workflowTags.includes(sanitizeSlug(input.workflowId)) &&
+    !concept.tags.includes(`workflow:${sanitizeSlug(input.workflowId)}`)
+  ) {
+    return false;
+  }
+  if (input.paths !== undefined && input.paths.length > 0 && concept.pathScopes.length > 0) {
+    return input.paths.some((path) =>
+      concept.pathScopes.some((scope) => path.startsWith(scope) || scope.startsWith(path)),
+    );
+  }
+  return true;
+}
+
+function normalizeKnowledgeQueryScope(input: {
+  projectKey?: string;
+  roleId?: string;
+  workflowId?: string;
+  paths?: string[];
+}): KnowledgeQueryScope {
+  return {
+    projectKey: input.projectKey === undefined ? undefined : sanitizeSlug(input.projectKey),
+    roleId: input.roleId === undefined ? undefined : sanitizeSlug(input.roleId),
+    workflowId: input.workflowId === undefined ? undefined : sanitizeSlug(input.workflowId),
+    paths: (input.paths ?? []).flatMap((path) => {
+      const normalized = normalizeRepoRelativeScopePath(path);
+      return normalized === null ? [] : [normalized];
+    }),
+    hasPathFilter: (input.paths ?? []).length > 0,
+  };
+}
+
+function normalizeKnowledgeQueryText(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const normalized = sanitizeOkfText(value);
+  return normalized === "" ? undefined : normalized;
+}
+
+function createKnowledgeContextRevision(items: ScopedKnowledgeContextPackItem[]): string {
+  return `okf-rev-${sha256Short(
+    stableJsonStringify(
+      items.map((item) => ({
+        id: item.id,
+        sourceType: item.sourceType,
+        sourceLink: item.sourceLink,
+        section: item.section,
+        title: item.title,
+        matchReasons: item.matchReasons,
+      })),
+    ),
+  )}`;
+}
+
+function sha256Short(value: string): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+function stableJsonStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableJsonStringify).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, child]) => child !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right));
+  return `{${entries
+    .map(([key, child]) => `${JSON.stringify(key)}:${stableJsonStringify(child)}`)
+    .join(",")}}`;
+}
+
+function sanitizeReceiptPathSegment(value: string): string {
+  const segment = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/gu, "-")
+    .replace(/-+/gu, "-")
+    .replace(/^-+|-+$/gu, "")
+    .slice(0, 160);
+  return segment === "" ? "unknown" : segment;
+}
+
+function createLexicalKnowledgeDocument(
+  input: Omit<LexicalKnowledgeDocument, "safeTokens">,
+): LexicalKnowledgeDocument {
+  const safeInput = {
+    ...input,
+    title: sanitizeOkfText(input.title),
+    description: sanitizeOkfText(input.description),
+    tags: input.tags.map(sanitizeOkfText),
+    repoTags: input.repoTags.map(sanitizeOkfText),
+    roleTags: input.roleTags.map(sanitizeOkfText),
+    workflowTags: input.workflowTags.map(sanitizeOkfText),
+    pathScopes: input.pathScopes.map(sanitizeOkfText),
+    stableKey: sanitizeOkfText(input.stableKey),
+    headings: input.headings.map(sanitizeOkfText),
+    bodySummary: sanitizeOkfText(input.bodySummary),
+  };
+  return {
+    ...safeInput,
+    safeTokens: uniqueStrings(
+      [
+        safeInput.id,
+        safeInput.sourceLink,
+        safeInput.stableKey,
+        safeInput.title,
+        safeInput.description,
+        ...safeInput.tags,
+        ...safeInput.repoTags,
+        ...safeInput.roleTags,
+        ...safeInput.workflowTags,
+        ...safeInput.pathScopes,
+        ...safeInput.headings,
+        safeInput.bodySummary,
+      ].flatMap(tokenizeLexicalText),
+    ),
+  };
+}
+
+function parseLexicalQuery(queryText: string): {
+  tokens: string[];
+  exactAnchors: string[];
+  pathAnchors: string[];
+  scriptAnchors: string[];
+} {
+  return {
+    tokens: uniqueStrings(tokenizeLexicalText(queryText)),
+    exactAnchors: uniqueStrings(extractExactAnchors(queryText)),
+    pathAnchors: uniqueStrings(extractPathAnchors(queryText)),
+    scriptAnchors: uniqueStrings(extractScriptAnchors(queryText)),
+  };
+}
+
+function tokenizeLexicalText(value: string): string[] {
+  const normalized = normalizeLexicalComparable(value)
+    .replace(/([a-z]+)(\d{3,6})/gu, "$1$2 $1 $2")
+    .replace(/(\d)([a-z])/gu, "$1 $2");
+  return uniqueStrings([
+    ...normalized.split(/[^a-z0-9]+/u).filter((token) => token !== ""),
+    ...extractExactAnchors(value),
+    ...extractScriptAnchors(value),
+    ...extractPathAnchors(value).flatMap((path) => [
+      path,
+      ...path.split(/[/.]+/u).filter((token) => token !== ""),
+    ]),
+  ]);
+}
+
+function normalizeLexicalComparable(value: string): string {
+  return sanitizeOkfText(value).toLowerCase().replace(/\\/gu, "/");
+}
+
+function extractExactAnchors(value: string): string[] {
+  return uniqueStrings(
+    [...value.matchAll(/\b[a-z]{1,8}\d{3,6}\b/giu)].map((match) => match[0].toLowerCase()),
+  );
+}
+
+function extractScriptAnchors(value: string): string[] {
+  return uniqueStrings(
+    [...value.matchAll(/\b(bun|npm|pnpm|yarn)\s+run\s+([a-z0-9:_./-]+)/giu)].map(
+      (match) => `${match[1]?.toLowerCase()}-run-${sanitizeSlug(match[2] ?? "")}`,
+    ),
+  );
+}
+
+function extractPathAnchors(value: string): string[] {
+  const anchors = [
+    ...value.matchAll(
+      /(?:\.{0,2}\/)?[a-z0-9_.-]+(?:\/[a-z0-9_.-]+)+(?:\.[a-z0-9]+)?|[a-z0-9_.-]+\.(?:ts|tsx|js|jsx|json|md|yml|yaml|toml|rs|py|go|java|kt|swift|css|scss|html)/giu,
+    ),
+  ].map((match) => normalizeQueryPathAnchor(match[0]));
+  return uniqueStrings(anchors.filter((anchor) => anchor !== ""));
+}
+
+function normalizeQueryPathAnchor(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/\\/gu, "/")
+    .replace(/^\.?\//u, "")
+    .replace(/\/+/gu, "/")
+    .replace(/\/$/u, "");
+}
+
+function pathAnchorMatches(anchor: string, values: string[]): boolean {
+  const normalizedAnchor = normalizeQueryPathAnchor(anchor);
+  if (normalizedAnchor === "") return false;
+  const anchorBase = normalizedAnchor.split("/").at(-1) ?? normalizedAnchor;
+  return values.some((value) => {
+    const normalizedValue = normalizeQueryPathAnchor(value.replace(/^evodev:\/\//u, ""));
+    if (normalizedValue === "") return false;
+    const valueBase = normalizedValue.split("/").at(-1) ?? normalizedValue;
+    return (
+      normalizedValue === normalizedAnchor ||
+      normalizedValue.includes(normalizedAnchor) ||
+      normalizedAnchor.includes(normalizedValue) ||
+      segmentAwarePathOverlap(normalizedAnchor, normalizedValue) ||
+      (anchorBase.includes(".") && anchorBase === valueBase)
+    );
+  });
+}
+
+function extractMarkdownHeadings(body: string): string[] {
+  return body
+    .split("\n")
+    .flatMap((line) => {
+      const match = line.match(/^#{1,6}\s+(.+?)\s*$/u);
+      return match?.[1] === undefined ? [] : [match[1]];
+    })
+    .slice(0, 20);
+}
+
+function summarizeLexicalBody(body: string): string {
+  return body
+    .replace(/^#{1,6}\s+/gmu, "")
+    .replace(/\s+/gu, " ")
+    .trim()
+    .slice(0, 1200);
+}
+
+function sanitizeLexicalReason(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(new RegExp(PRIVATE_OR_INTERNAL_URL.source, "gi"), "redacted")
+    .replace(new RegExp(FORBIDDEN_OKF_TEXT.source, "gi"), "redacted")
+    .replace(/[^a-z0-9:._/-]+/gu, "-")
+    .replace(/-+/gu, "-")
+    .replace(/^-+|-+$/gu, "")
+    .slice(0, 120);
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.filter((value) => value !== ""))];
+}
+
+function matchOkfConceptForContext(
+  concept: OkfKnowledgeConcept,
+  scope: KnowledgeQueryScope,
+): OkfContextMatch | null {
+  const reasons: string[] = [];
+  let exactMatches = 0;
+  let overlayMatch = false;
+  let pathMatch = false;
+
+  const repoTags = collectScopedTags(concept, "repo");
+  if (scope.projectKey !== undefined) {
+    if (repoTags.length > 0 && !repoTags.includes(scope.projectKey)) return null;
+    if (repoTags.includes(scope.projectKey)) {
+      reasons.push(`repo:${scope.projectKey}`);
+      exactMatches += 1;
+    }
+  }
+
+  const roleTags = collectScopedTags(concept, "role");
+  if (scope.roleId !== undefined) {
+    if (roleTags.length > 0 && !roleTags.includes(scope.roleId)) return null;
+    if (roleTags.includes(scope.roleId)) {
+      reasons.push(`role:${scope.roleId}`);
+      exactMatches += 1;
+    }
+  }
+
+  const workflowTags = collectScopedTags(concept, "workflow");
+  if (scope.workflowId !== undefined) {
+    if (workflowTags.length > 0 && !workflowTags.includes(scope.workflowId)) return null;
+    if (workflowTags.includes(scope.workflowId)) {
+      reasons.push(`workflow:${scope.workflowId}`);
+      exactMatches += 1;
+    }
+  }
+
+  const overlay = matchOverlayScope(concept.id, scope);
+  if (overlay === null) return null;
+  if (overlay !== "none") {
+    overlayMatch = true;
+    reasons.push(`overlay:${overlay}`);
+    exactMatches += 1;
+  }
+
+  const pathScopes = concept.pathScopes.flatMap((path) => {
+    const normalized = normalizeRepoRelativeScopePath(path);
+    return normalized === null ? [] : [normalized];
+  });
+  if (scope.hasPathFilter && pathScopes.length > 0) {
+    if (scope.paths.length === 0) return null;
+    pathMatch = scope.paths.some((path) =>
+      pathScopes.some((pathScope) => segmentAwarePathOverlap(path, pathScope)),
+    );
+    if (!pathMatch) return null;
+    reasons.push("path-scope");
+    exactMatches += 1;
+  }
+
+  return { reasons, exactMatches, overlayMatch, pathMatch };
+}
+
+function collectScopedTags(
+  concept: OkfKnowledgeConcept,
+  kind: "repo" | "role" | "workflow",
+): string[] {
+  const direct =
+    kind === "repo" ? concept.repoTags : kind === "role" ? concept.roleTags : concept.workflowTags;
+  const prefix = `${kind}:`;
+  return [
+    ...new Set([
+      ...direct.map(sanitizeSlug),
+      ...concept.tags
+        .filter((tag) => tag.startsWith(prefix))
+        .map((tag) => sanitizeSlug(tag.slice(prefix.length))),
+    ]),
+  ].filter((tag) => tag !== "unknown");
+}
+
+function matchOverlayScope(
+  conceptId: string,
+  scope: KnowledgeQueryScope,
+): "repo" | "role" | "workflow" | "none" | null {
+  const [root, id] = conceptId.split("/");
+  if (root === "repos") {
+    if (scope.projectKey !== undefined && id !== scope.projectKey) return null;
+    return scope.projectKey === undefined ? "none" : "repo";
+  }
+  if (root === "roles") {
+    if (scope.roleId !== undefined && id !== scope.roleId) return null;
+    return scope.roleId === undefined ? "none" : "role";
+  }
+  if (root === "workflows") {
+    if (scope.workflowId !== undefined && id !== scope.workflowId) return null;
+    return scope.workflowId === undefined ? "none" : "workflow";
+  }
+  return "none";
+}
+
+function calculateOkfContextScore(concept: OkfKnowledgeConcept, match: OkfContextMatch): number {
+  let score = 0;
+  score += match.exactMatches * 100;
+  if (match.overlayMatch) score += 80;
+  if (match.pathMatch) score += 40;
+  if (concept.id.startsWith("concepts/")) score += 1;
+  return score;
+}
+
+function resolveContextSection(concept: OkfKnowledgeConcept): OkfKnowledgeContextSection {
+  if (concept.id.startsWith("roles/")) return "role-attention";
+  if (concept.id.startsWith("repos/")) return "repo-attention";
+  if (concept.id.startsWith("workflows/")) return "workflow-attention";
+  if (concept.id.startsWith("concepts/evos/")) return "accepted-evos-cases";
+  if (concept.id.startsWith("concepts/verification/")) return "verification";
+  if (/verification/i.test(concept.type)) return "verification";
+  return "applicable-knowledge";
+}
+
+function contextSectionSortWeight(section: OkfKnowledgeContextSection): number {
+  if (section === "role-attention") return 0;
+  if (section === "repo-attention") return 1;
+  if (section === "workflow-attention") return 2;
+  if (section === "verification") return 3;
+  if (section === "applicable-knowledge") return 4;
+  return 5;
+}
+
+function normalizeRepoRelativeScopePath(value: string): string | null {
+  const trimmed = value.trim().replace(/\\/gu, "/");
+  if (trimmed === "" || trimmed.startsWith("/") || /^[A-Za-z]:\//u.test(trimmed)) return null;
+  const normalized = trimmed.replace(/\/+/gu, "/").replace(/^\.\//u, "").replace(/\/$/u, "");
+  const segments = normalized.split("/");
+  if (
+    segments.length === 0 ||
+    segments.some((segment) => segment === "" || segment === "." || segment === "..")
+  ) {
+    return null;
+  }
+  return segments.join("/");
+}
+
+function segmentAwarePathOverlap(left: string, right: string): boolean {
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+function isUnsafeOkfQueryContent(content: string): boolean {
+  const parsed = extractFrontmatter(content);
+  const frontmatter = parsed?.frontmatter ?? "";
+  if (OKF_QUERY_PRIVACY_FLAG_KEYS.some((key) => readOkfPrivacyBoolean(frontmatter, key) === true)) {
+    return true;
+  }
+  if (FORBIDDEN_OKF_FIELD.test(content)) return true;
+  if (FORBIDDEN_OKF_TEXT.test(content)) return true;
+  if (PRIVATE_OR_INTERNAL_URL.test(content)) return true;
+  return false;
+}
+
+function isActiveOkfConcept(concept: OkfKnowledgeConcept): boolean {
+  return resolveOkfConceptQueryEligibility(concept, {
+    includeStale: false,
+    now: new Date(),
+  }).include;
+}
+
+function isActiveOkfReviewState(reviewState: OkfKnowledgeReviewState): boolean {
+  return ACTIVE_OKF_REVIEW_STATES.includes(reviewState);
+}
+
+function resolveOkfConceptQueryEligibility(
+  concept: OkfKnowledgeConcept,
+  input: { includeStale: boolean; now: Date },
+): { include: boolean; stale: boolean; scoreAdjustment: number; reason: string } {
+  if (
+    concept.lifecycle.status === "deprecated" ||
+    concept.lifecycle.status === "revoked" ||
+    concept.lifecycle.status === "superseded" ||
+    concept.reviewState === "deprecated" ||
+    concept.reviewState === "revoked" ||
+    concept.reviewState === "superseded"
+  ) {
+    return { include: false, stale: false, scoreAdjustment: 0, reason: "inactive" };
+  }
+  const staleByStatus = concept.lifecycle.status === "stale" || concept.reviewState === "stale";
+  const staleByDate = isLifecycleDateDue(concept.lifecycle.staleAfter, input.now);
+  const stale = staleByStatus || staleByDate;
+  if (stale) {
+    return {
+      include: input.includeStale,
+      stale: input.includeStale,
+      scoreAdjustment: input.includeStale ? -250 : 0,
+      reason: staleByStatus ? "status=stale" : `staleAfter=${concept.lifecycle.staleAfter}`,
+    };
+  }
+  return {
+    include: isActiveOkfReviewState(concept.reviewState) && concept.lifecycle.status === "active",
+    stale: false,
+    scoreAdjustment: 0,
+    reason: "active",
+  };
+}
+
+function normalizeQueryNow(value: string | Date | undefined): Date {
+  if (value instanceof Date && Number.isFinite(value.getTime())) return value;
+  if (typeof value === "string") {
+    const normalized = normalizeIsoDateString(value);
+    if (normalized !== null) return new Date(normalized);
+  }
+  return new Date();
+}
+
+function isLifecycleDateDue(value: string, now: Date): boolean {
+  const normalized = normalizeIsoDateString(value);
+  return normalized !== null && Date.parse(normalized) <= now.getTime();
+}
+
+function readYamlBoolean(frontmatter: string, key: string): boolean | null {
+  const scalar = readYamlScalar(frontmatter, key);
+  if (scalar === null) return null;
+  if (scalar === "true") return true;
+  if (scalar === "false") return false;
+  return null;
+}
+
+function readOkfPrivacyBoolean(frontmatter: string, key: string): boolean | null {
+  const root = readYamlBoolean(frontmatter, key);
+  const privacyBlock = extractNestedYamlBlock(frontmatter, "evodev", "privacy");
+  const nested = privacyBlock === null ? null : readIndentedYamlBoolean(privacyBlock, key);
+  if (root === true || nested === true) return true;
+  if (root === false || nested === false) return false;
+  return null;
+}
+
+function readIndentedYamlBoolean(frontmatter: string, key: string): boolean | null {
+  const scalar = readIndentedYamlScalar(frontmatter, key);
+  if (scalar === null) return null;
+  if (scalar === "true") return true;
+  if (scalar === "false") return false;
+  return null;
+}
+
+function validateOkfKnowledgePlan(plan: OkfKnowledgePlan): void {
+  assertOkfKnowledgePlanContract(plan);
+}
+
+function validateFailedPlanArtifact(artifact: OkfKnowledgeFailedPlanArtifact): void {
+  if (!isRecord(artifact)) throw new Error("Failed plan artifact must be an object.");
+  if (artifact.schemaVersion !== 1)
+    throw new Error("Failed plan artifact schemaVersion must be 1.");
+  if (artifact.kind !== "okf-knowledge-failed-plan")
+    throw new Error("Failed plan artifact kind is invalid.");
+  if (artifact.failureKind !== "validation" && artifact.failureKind !== "organizer") {
+    throw new Error("Failed plan artifact failureKind is invalid.");
+  }
+  if (!isNonEmptyString(artifact.projectKey))
+    throw new Error("Failed plan artifact projectKey is required.");
+  if (!isNonEmptyString(artifact.runId)) throw new Error("Failed plan artifact runId is required.");
+  if (!isNonEmptyString(artifact.createdAt))
+    throw new Error("Failed plan artifact createdAt is required.");
+  if (typeof artifact.resumable !== "boolean")
+    throw new Error("Failed plan artifact resumable must be boolean.");
+  if (!Array.isArray(artifact.findings))
+    throw new Error("Failed plan artifact findings must be an array.");
+  for (const finding of artifact.findings) {
+    if (!isRecord(finding)) throw new Error("Failed plan finding must be an object.");
+    if (
+      !isNonEmptyString(finding.path) ||
+      !isNonEmptyString(finding.code) ||
+      !isNonEmptyString(finding.message)
+    ) {
+      throw new Error("Failed plan finding fields are required.");
+    }
+    if (finding.severity !== "error" && finding.severity !== "warning") {
+      throw new Error("Failed plan finding severity is invalid.");
+    }
+  }
+  if (!isNonEmptyString(artifact.error)) throw new Error("Failed plan artifact error is required.");
+  if (artifact.plan !== undefined) validateOkfKnowledgePlan(artifact.plan);
+}
+
+function assertCandidateScores(scores: OkfKnowledgeCandidateScores): void {
+  for (const [key, value] of Object.entries(scores)) {
+    if (!Number.isInteger(value) || value < 1 || value > 5) {
+      throw new Error(`OKF candidate score ${key} must be an integer from 1 to 5.`);
+    }
+  }
+}
+
+function assertOkfCandidateNoUnsafeContent(candidate: OkfKnowledgePlanCandidate): void {
+  if (hasUnsafeCandidateContent(candidate)) {
+    throw new Error("OKF candidate contains unsafe raw or sensitive content.");
+  }
+}
+
+function assertOkfPrivacy(privacy: OkfKnowledgePrivacyCheck): void {
+  if (
+    privacy.rawPromptsStored !== false ||
+    privacy.rawLogsStored !== false ||
+    privacy.sourceDumpsStored !== false ||
+    privacy.rawCommandOutputStored !== false ||
+    privacy.secretsStored !== false ||
+    privacy.internalLinksStored !== false
+  ) {
+    throw new Error("OKF knowledge privacy fields must all be false.");
+  }
+}
+
+function createOkfPrivacyCheck(): OkfKnowledgePrivacyCheck {
+  return {
+    rawPromptsStored: false,
+    rawLogsStored: false,
+    sourceDumpsStored: false,
+    rawCommandOutputStored: false,
+    secretsStored: false,
+    internalLinksStored: false,
+  };
+}
+
+function createDefaultOkfLifecycle(input: {
+  type: string;
+  path: string;
+  tags: string[];
+  title: string;
+  reviewState: OkfKnowledgeReviewState;
+  createdAt?: string;
+}): OkfKnowledgeLifecycle {
+  const createdAt = normalizeIsoDateString(input.createdAt) ?? "1970-01-01T00:00:00.000Z";
+  const policy = resolveOkfLifecyclePolicy(input);
+  return {
+    status: lifecycleStatusFromReviewState(input.reviewState),
+    createdAt,
+    lastVerifiedAt: createdAt,
+    reviewAfter: addDaysIso(createdAt, policy.reviewAfterDays),
+    staleAfter: addDaysIso(createdAt, policy.staleAfterDays),
+    supersedes: [],
+    supersededBy: null,
+    revokedAt: null,
+    revokedReason: null,
+  };
+}
+
+function parseOkfLifecycle(
+  frontmatter: string,
+  input: {
+    type: string;
+    path: string;
+    tags: string[];
+    title: string;
+    reviewState: OkfKnowledgeReviewState;
+    createdAt?: string;
+  },
+): { lifecycle: OkfKnowledgeLifecycle; persisted: boolean } {
+  const defaults = createDefaultOkfLifecycle(input);
+  const block = extractNestedYamlBlock(frontmatter, "evodev", "lifecycle");
+  if (block === null) return { lifecycle: defaults, persisted: false };
+  const status = readIndentedYamlScalar(block, "status");
+  const createdAt = readIndentedYamlScalar(block, "createdAt");
+  const lastVerifiedAt = readIndentedYamlScalar(block, "lastVerifiedAt");
+  const reviewAfter = readIndentedYamlScalar(block, "reviewAfter");
+  const staleAfter = readIndentedYamlScalar(block, "staleAfter");
+  const revokedAt = readIndentedYamlScalar(block, "revokedAt");
+  return {
+    persisted: true,
+    lifecycle: {
+      status: isOkfLifecycleStatus(status) ? status : defaults.status,
+      createdAt: normalizeIsoDateString(createdAt) ?? defaults.createdAt,
+      lastVerifiedAt: normalizeIsoDateString(lastVerifiedAt) ?? defaults.lastVerifiedAt,
+      reviewAfter: normalizeIsoDateString(reviewAfter) ?? defaults.reviewAfter,
+      staleAfter: normalizeIsoDateString(staleAfter) ?? defaults.staleAfter,
+      supersedes: readYamlList(block, "supersedes"),
+      supersededBy: readNullableLifecycleString(readIndentedYamlScalar(block, "supersededBy")),
+      revokedAt:
+        readNullableLifecycleString(revokedAt) === null ? null : normalizeIsoDateString(revokedAt),
+      revokedReason: readNullableLifecycleString(readIndentedYamlScalar(block, "revokedReason")),
+    },
+  };
+}
+
+function lintOkfLifecycle(input: {
+  concept: OkfKnowledgeConcept;
+  frontmatter: string;
+  knownConceptIds: Set<string>;
+  now: Date;
+  errors: string[];
+  warnings: string[];
+}): void {
+  const source = input.concept.sourceLink;
+  const block = extractNestedYamlBlock(input.frontmatter, "evodev", "lifecycle");
+  if (!input.concept.lifecyclePersisted || block === null) {
+    input.warnings.push(`Lifecycle missing: ${source}`);
+  } else {
+    const status = readIndentedYamlScalar(block, "status");
+    if (!isOkfLifecycleStatus(status)) {
+      input.errors.push(
+        `Lifecycle invalid status: ${source} status=${sanitizeOkfText(status ?? "missing")}`,
+      );
+    }
+    for (const field of ["createdAt", "lastVerifiedAt", "reviewAfter", "staleAfter"] as const) {
+      const value = readIndentedYamlScalar(block, field);
+      if (value === null) {
+        input.warnings.push(`Lifecycle missing date: ${source} ${field}`);
+      } else if (normalizeIsoDateString(value) === null) {
+        input.errors.push(`Lifecycle invalid date: ${source} ${field}`);
+      }
+    }
+  }
+
+  if (isLifecycleDateDue(input.concept.lifecycle.reviewAfter, input.now)) {
+    input.warnings.push(
+      `Lifecycle review due: ${source} reviewAfter=${input.concept.lifecycle.reviewAfter}`,
+    );
+  }
+  if (isLifecycleDateDue(input.concept.lifecycle.staleAfter, input.now)) {
+    input.warnings.push(
+      `Lifecycle stale due: ${source} staleAfter=${input.concept.lifecycle.staleAfter}`,
+    );
+  }
+  if (input.concept.lifecycle.status === "stale" || input.concept.reviewState === "stale") {
+    input.warnings.push(`Lifecycle stale status: ${source}`);
+  }
+  if (input.concept.lifecycle.status === "revoked" || input.concept.reviewState === "revoked") {
+    if (input.concept.lifecycle.revokedAt === null) {
+      input.warnings.push(`Lifecycle revoked missing revokedAt: ${source}`);
+    }
+    if (input.concept.lifecycle.revokedReason === null) {
+      input.warnings.push(`Lifecycle revoked missing revokedReason: ${source}`);
+    }
+  }
+  if (
+    input.concept.lifecycle.status === "superseded" ||
+    input.concept.reviewState === "superseded"
+  ) {
+    const replacement = input.concept.lifecycle.supersededBy;
+    if (replacement === null) {
+      input.warnings.push(`Lifecycle superseded missing supersededBy: ${source}`);
+    } else if (!input.knownConceptIds.has(normalizeConceptId(replacement))) {
+      input.warnings.push(
+        `Lifecycle superseded replacement missing: ${source} supersededBy=${sanitizeOkfText(replacement)}`,
+      );
+    }
+  }
+}
+
+function renderLifecycleYaml(indent: string, lifecycle: OkfKnowledgeLifecycle): string {
+  return [
+    `${indent}lifecycle:`,
+    `${indent}  status: ${yamlString(lifecycle.status)}`,
+    `${indent}  createdAt: ${yamlString(lifecycle.createdAt)}`,
+    `${indent}  lastVerifiedAt: ${yamlString(lifecycle.lastVerifiedAt)}`,
+    `${indent}  reviewAfter: ${yamlString(lifecycle.reviewAfter)}`,
+    `${indent}  staleAfter: ${yamlString(lifecycle.staleAfter)}`,
+    renderYamlList(`${indent}  supersedes`, lifecycle.supersedes),
+    `${indent}  supersededBy: ${yamlNullableString(lifecycle.supersededBy)}`,
+    `${indent}  revokedAt: ${yamlNullableString(lifecycle.revokedAt)}`,
+    `${indent}  revokedReason: ${yamlNullableString(lifecycle.revokedReason)}`,
+  ].join("\n");
+}
+
+function lifecycleStatusFromReviewState(
+  reviewState: OkfKnowledgeReviewState,
+): OkfKnowledgeLifecycleStatus {
+  if (reviewState === "stale") return "stale";
+  if (reviewState === "deprecated") return "deprecated";
+  if (reviewState === "revoked") return "revoked";
+  if (reviewState === "superseded") return "superseded";
+  return "active";
+}
+
+function resolveOkfLifecyclePolicy(input: {
+  type: string;
+  path: string;
+  tags: string[];
+  title: string;
+}): { reviewAfterDays: number; staleAfterDays: number } {
+  const comparable =
+    `${input.type} ${input.path} ${input.tags.join(" ")} ${input.title}`.toLowerCase();
+  if (/\bverification\b/u.test(comparable)) return { reviewAfterDays: 120, staleAfterDays: 240 };
+  if (/\bworkflow\b/u.test(comparable)) return { reviewAfterDays: 60, staleAfterDays: 120 };
+  return { reviewAfterDays: 90, staleAfterDays: 180 };
+}
+
+function isOkfLifecycleStatus(value: string | null): value is OkfKnowledgeLifecycleStatus {
+  return OKF_LIFECYCLE_STATUSES.includes(value as OkfKnowledgeLifecycleStatus);
+}
+
+function normalizeIsoDateString(value: string | null | undefined): string | null {
+  if (value === undefined || value === null || value === "" || value === "null") return null;
+  const time = Date.parse(value);
+  if (!Number.isFinite(time)) return null;
+  return new Date(time).toISOString();
+}
+
+function addDaysIso(value: string, days: number): string {
+  const date = new Date(value);
+  date.setUTCDate(date.getUTCDate() + days);
+  return date.toISOString();
+}
+
+function readNullableLifecycleString(value: string | null): string | null {
+  if (value === null) return null;
+  const normalized = sanitizeOkfText(value);
+  return normalized === "" || normalized === "null" ? null : normalized;
+}
+
+function yamlNullableString(value: string | null): string {
+  return value === null ? "null" : yamlString(value);
+}
+
+function renderPrivacyYaml(indent: string): string {
+  return [
+    `${indent}privacy:`,
+    `${indent}  classification: ${yamlString("local-private")}`,
+    `${indent}  rawPromptsStored: false`,
+    `${indent}  rawLogsStored: false`,
+    `${indent}  sourceDumpsStored: false`,
+    `${indent}  rawCommandOutputStored: false`,
+    `${indent}  secretsStored: false`,
+    `${indent}  internalLinksStored: false`,
+  ].join("\n");
+}
+
+function renderYamlList(key: string, values: string[]): string {
+  if (values.length === 0) return `${key}: []`;
+  return [`${key}:`, ...values.map((value) => `      - ${yamlString(value)}`)].join("\n");
+}
+
+function renderMarkdownList(values: string[]): string {
+  return values.map((value) => `- ${value}`).join("\n");
+}
+
+function yamlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+function extractFrontmatter(content: string): { frontmatter: string; body: string } | null {
+  if (!content.startsWith("---\n")) return null;
+  const end = content.indexOf("\n---", 4);
+  if (end < 0) return null;
+  const frontmatter = content.slice(4, end).trim();
+  const body = content.slice(end + 4).replace(/^\n/u, "");
+  return { frontmatter, body };
+}
+
+function hasFrontmatter(content: string): boolean {
+  return extractFrontmatter(content) !== null;
+}
+
+function extractNestedYamlBlock(
+  frontmatter: string,
+  rootKey: string,
+  childKey: string,
+): string | null {
+  const lines = frontmatter.split("\n");
+  const rootIndex = lines.findIndex((line) => line.trim() === `${rootKey}:`);
+  if (rootIndex < 0) return null;
+  const rootEnd = findYamlBlockEnd(lines, rootIndex, 0);
+  const childIndex = lines.findIndex(
+    (line, index) =>
+      index > rootIndex &&
+      index < rootEnd &&
+      line.startsWith("  ") &&
+      line.trim() === `${childKey}:`,
+  );
+  if (childIndex < 0) return null;
+  const childEnd = findYamlBlockEnd(lines, childIndex, 2);
+  return lines.slice(childIndex + 1, childEnd).join("\n");
+}
+
+function findYamlBlockEnd(lines: string[], startIndex: number, parentIndent: number): number {
+  for (let index = startIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    if (line.trim() === "") continue;
+    const indent = line.length - line.trimStart().length;
+    if (indent <= parentIndent) return index;
+  }
+  return lines.length;
+}
+
+function readYamlScalar(frontmatter: string, key: string): string | null {
+  const match = frontmatter.match(new RegExp(`^${escapeRegExp(key)}:\\s*(.+?)\\s*$`, "m"));
+  if (match?.[1] === undefined) return null;
+  return parseYamlValue(match[1]);
+}
+
+function readIndentedYamlScalar(frontmatter: string, key: string): string | null {
+  const match = frontmatter.match(new RegExp(`^\\s*${escapeRegExp(key)}:\\s*(.+?)\\s*$`, "m"));
+  if (match?.[1] === undefined) return null;
+  return parseYamlValue(match[1]);
+}
+
+function parseOkfReviewState(value: string): OkfKnowledgeReviewState {
+  return OKF_REVIEW_STATES.includes(value as OkfKnowledgeReviewState)
+    ? (value as OkfKnowledgeReviewState)
+    : "auto-stored/unreviewed";
+}
+
+function readYamlList(frontmatter: string, key: string): string[] {
+  const inline = frontmatter.match(
+    new RegExp(`^\\s*${escapeRegExp(key)}:\\s*\\[(.*?)\\]\\s*$`, "m"),
+  );
+  if (inline?.[1] !== undefined) {
+    return inline[1]
+      .split(",")
+      .map((item) => parseYamlValue(item.trim()))
+      .filter((item) => item !== "");
+  }
+  const lines = frontmatter.split("\n");
+  const values: string[] = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    if (!line.trim().startsWith(`${key}:`)) continue;
+    for (let next = index + 1; next < lines.length; next += 1) {
+      const candidate = lines[next] ?? "";
+      if (!/^\s+-\s+/u.test(candidate)) break;
+      values.push(parseYamlValue(candidate.replace(/^\s+-\s+/u, "")));
+    }
+  }
+  return [...new Set(values.filter((value) => value !== ""))];
+}
+
+function parseYamlValue(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    try {
+      return JSON.parse(trimmed) as string;
+    } catch {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed.replace(/^['"]|['"]$/gu, "");
+}
+
+async function listMarkdownFiles(root: string): Promise<Array<{ path: string; name: string }>> {
+  if (!(await pathExists(root))) return [];
+  const entries = await readdir(root, { withFileTypes: true });
+  const files: Array<{ path: string; name: string }> = [];
+  for (const entry of entries) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listMarkdownFiles(path)));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push({ path, name: entry.name });
+    }
+  }
+  return files;
+}
+
+async function listDirectories(root: string): Promise<string[]> {
+  if (!(await pathExists(root))) return [];
+  const entries = await readdir(root, { withFileTypes: true });
+  const directories = [root];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    directories.push(...(await listDirectories(join(root, entry.name))));
+  }
+  return directories;
+}
+
+function groupConceptsByTag(
+  concepts: OkfKnowledgeConcept[],
+  field: "repoTags" | "roleTags" | "workflowTags",
+): Array<{ id: string; concepts: Array<{ id: string; title: string; sourceLink: string }> }> {
+  const groups = new Map<string, Array<{ id: string; title: string; sourceLink: string }>>();
+  for (const concept of concepts) {
+    for (const id of concept[field]) {
+      groups.set(id, [
+        ...(groups.get(id) ?? []),
+        { id: concept.id, title: concept.title, sourceLink: concept.sourceLink },
+      ]);
+    }
+  }
+  return [...groups.entries()].map(([id, groupedConcepts]) => ({ id, concepts: groupedConcepts }));
+}
+
+function resolveOkfTargetPath(okfDir: string, targetPath: string): string {
+  const clean = targetPath.replace(/^\/+/u, "");
+  if (clean.split("/").some((segment) => segment === ".." || segment === "." || segment === "")) {
+    throw new Error(`Unsafe OKF target path: ${targetPath}`);
+  }
+  const resolved = join(okfDir, clean);
+  const rel = relative(okfDir, resolved);
+  if (rel.startsWith("..") || rel === "") throw new Error(`Unsafe OKF target path: ${targetPath}`);
+  return resolved;
+}
+
+function normalizeConceptId(value: string): string {
+  return value.replace(/^\/+/u, "").replace(/\.md$/u, "");
+}
+
+function toOkfRelativePath(okfDir: string, path: string): string {
+  return relative(okfDir, path).replace(/\\/gu, "/");
+}
+
+function toOkfLink(okfDir: string, path: string): string {
+  return `/${toOkfRelativePath(okfDir, path)}`;
+}
+
+function displayOkfPath(okfDir: string, path: string): string {
+  const rel = toOkfRelativePath(okfDir, path);
+  return rel === "" ? "/" : rel;
+}
+
+function sanitizeSlug(value: string): string {
+  const slug = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._/-]+/gu, "-")
+    .replace(/\/+/gu, "/")
+    .replace(/^-+|-+$/gu, "");
+  return slug === "" ? "unknown" : slug;
+}
+
+function titleFromSlug(value: string): string {
+  return value
+    .replace(/\.md$/u, "")
+    .split(/[/-]/u)
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function todayIsoDate(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+async function writeJson(
+  path: string,
+  value: unknown,
+  options: { overwrite?: boolean } = {},
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const flag = options.overwrite === true ? "w" : "wx";
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag });
+}
+
+async function renameOrCopy(source: string, target: string): Promise<void> {
+  await mkdir(dirname(target), { recursive: true });
+  try {
+    await rename(source, target);
+  } catch {
+    if (await pathExists(source)) {
+      await writeFile(target, await readFile(source, "utf8"), "utf8");
+    }
+  }
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+    throw error;
+  }
+}