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

package/src/evolution/index.ts

@@ -1,2356 +1,16 @@
-import { createHash } from "node:crypto";
-import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { resolveEvoDevPaths } from "../config/paths.ts";
-import { resolveProjectLogKey } from "../runtime-logs/index.ts";
-
-export type EvolutionEvidenceSourceKind =
-  | "team-agent-trace"
-  | "session-trace"
-  | "task-contract"
-  | "verification"
-  | "review-summary"
-  | "user-feedback";
-
-export type EvolutionEvidenceEventKind =
-  | "trace"
-  | "tool-call"
-  | "skill-call"
-  | "subagent"
-  | "verification"
-  | "review"
-  | "user-feedback"
-  | "error"
-  | "run-state";
-
-export type EvolutionNormalizedEventType =
-  | "SessionStart"
-  | "UserPromptSubmit"
-  | "UserPromptExpansion"
-  | "PreToolUse"
-  | "PermissionRequest"
-  | "PostToolUse"
-  | "PostToolUseFailure"
-  | "PostToolBatch"
-  | "PermissionDenied"
-  | "SubagentStart"
-  | "Stop"
-  | "StopFailure"
-  | "TeammateIdle"
-  | "SubagentStop"
-  | "TaskCreated"
-  | "TaskCompleted"
-  | "PreCompact"
-  | "PostCompact"
-  | "SessionEnd"
-  | "ConfigChange"
-  | "CwdChanged"
-  | "FileChanged"
-  | "WorktreeCreate"
-  | "WorktreeRemove"
-  | "unknown";
-
-export type EvolutionTriggerStrength = "none" | "conditional" | "strong";
-export type EvolutionTriggerReason =
-  | "none"
-  | "turn-completed"
-  | "task-completed"
-  | "session-ended"
-  | "role-completed"
-  | "stop-failure"
-  | "tool-failure"
-  | "permission-denied"
-  | "explicit-command"
-  | "failure-signal";
-
-export type EvolutionEpisodeKind = "session" | "turn" | "task" | "role";
-export type EvolutionEpisodeStatus = "open" | "closed" | "failed";
-export type EvolutionTriggerStatus = "pending" | "processing" | "consumed" | "failed" | "skipped";
-
-export type EvolutionKnowledgeKind =
-  | "run-summary"
-  | "lesson"
-  | "rule"
-  | "workflow-hint"
-  | "skill-gap"
-  | "role-note"
-  | "verification-pattern";
-
-export type EvolutionReviewState =
-  | "auto-stored/unreviewed"
-  | "accepted"
-  | "rejected"
-  | "deferred"
-  | "deprecated"
-  | "superseded"
-  | "revoked";
-
-export type EvolutionAuthority = "contextual" | "reviewed";
-export type EvolutionConfidence = "low" | "medium" | "high";
-
-export type EvolutionProposalKind =
-  | "skill"
-  | "rule"
-  | "role-agent"
-  | "team"
-  | "ci"
-  | "test"
-  | "docs"
-  | "engineering-practice";
-
-export interface EvolutionPrivacyFields {
-  classification: "local-private";
-  rawPromptsStored: false;
-  rawLogsStored: false;
-  sourceDumpsStored: false;
-  rawCommandOutputStored: false;
-  secretsStored: false;
-  internalLinksStored: false;
-}
-
-export interface EvolutionEvidenceWindow {
-  schemaVersion: 1;
-  id: string;
-  kind: "evidence-window";
-  projectKey: string;
-  runId: string;
-  taskId: string | null;
-  createdAt: string;
-  sourceRefs: EvolutionEvidenceSourceRef[];
-  events: EvolutionEvidenceEvent[];
-  episodes: EvolutionEpisode[];
-  triggerPolicy: EvolutionTriggerPolicy;
-  privacy: EvolutionPrivacyFields;
-}
-
-export interface EvolutionEvidenceSourceRef {
-  id: string;
-  kind: EvolutionEvidenceSourceKind;
-  path: string;
-  roleId: string | null;
-  rawContentStored: false;
-}
-
-export interface EvolutionEvidenceEvent {
-  id: string;
-  kind: EvolutionEvidenceEventKind;
-  eventType: EvolutionNormalizedEventType;
-  hookEventId: string | null;
-  occurredAt: string | null;
-  summary: string;
-  roleId: string | null;
-  taskId: string | null;
-  evidenceRef: string;
-  episodeIds: string[];
-  triggerStrength: EvolutionTriggerStrength;
-  triggerReason: EvolutionTriggerReason;
-  rawContentStored: false;
-}
-
-export interface EvolutionEpisode {
-  id: string;
-  kind: EvolutionEpisodeKind;
-  status: EvolutionEpisodeStatus;
-  roleId: string | null;
-  taskId: string | null;
-  startedAt: string | null;
-  endedAt: string | null;
-  eventIds: string[];
-  triggerStrength: EvolutionTriggerStrength;
-  triggerReason: EvolutionTriggerReason;
-  summary: string;
-  rawContentStored: false;
-}
-
-export interface EvolutionTriggerPolicy {
-  strongest: EvolutionTriggerStrength;
-  reasons: EvolutionTriggerReason[];
-  distillRecommended: boolean;
-  evidenceSignals: {
-    failures: number;
-    verifications: number;
-    roleLifecycle: number;
-    skillCalls: number;
-  };
-}
-
-export interface EvolutionTriggerRecord {
-  schemaVersion: 1;
-  id: string;
-  kind: "evolution-trigger";
-  projectKey: string;
-  runId: string;
-  roleId: string | null;
-  taskId: string | null;
-  eventType: EvolutionNormalizedEventType;
-  eventId: string | null;
-  evidenceRef: string | null;
-  summary: string;
-  triggerStrength: EvolutionTriggerStrength;
-  triggerReason: EvolutionTriggerReason;
-  status: EvolutionTriggerStatus;
-  attempts: number;
-  createdAt: string;
-  updatedAt: string;
-  processedBatchId: string | null;
-  lastError: string | null;
-  rawContentStored: false;
-  privacy: EvolutionPrivacyFields;
-}
-
-export interface EvolutionTriggerDecision {
-  eventType: EvolutionNormalizedEventType;
-  strength: EvolutionTriggerStrength;
-  reason: EvolutionTriggerReason;
-  shouldQueue: boolean;
-  summary: string;
-}
-
-export interface EvolutionKnowledgeRecord {
-  schemaVersion: 1;
-  id: string;
-  kind: EvolutionKnowledgeKind;
-  title: string;
-  projectKey: string;
-  summary: string;
-  body: string;
-  roleTags: string[];
-  tags: string[];
-  reviewState: EvolutionReviewState;
-  authority: EvolutionAuthority;
-  confidence: EvolutionConfidence;
-  provenance: {
-    runId: string;
-    taskId: string | null;
-    evidenceWindowId: string;
-    sourceRefs: string[];
-    createdAt: string;
-    createdBy: "evodev";
-    rawLogsStored: false;
-    rawPromptsStored: false;
-    sourceDumpsStored: false;
-    rawCommandOutputStored: false;
-  };
-  relations: {
-    relatedKnowledgeIds: string[];
-    evosCaseIds: string[];
-    proposalIds: string[];
-    supersedes: string[];
-  };
-  privacy: EvolutionPrivacyFields;
-  runtime: {
-    canLoad: boolean;
-    hardBlocking: false;
-  };
-}
-
-export interface EvolutionEvosCase {
-  schemaVersion: 1;
-  id: string;
-  kind: "evos-case";
-  projectKey: string;
-  title: string;
-  roleTags: string[];
-  tags: string[];
-  reviewState: EvolutionReviewState;
-  confidence: EvolutionConfidence;
-  trigger: {
-    kind: "task-completion" | "plan-task-completion" | "session-completion" | "manual";
-    summary: string;
-  };
-  intervention: {
-    summary: string;
-    roleIds: string[];
-  };
-  result: {
-    summary: string;
-    verificationSignals: string[];
-  };
-  expectedFutureBehavior: string;
-  provenance: {
-    runId: string;
-    taskId: string | null;
-    evidenceWindowId: string;
-    sourceRefs: string[];
-    createdAt: string;
-    createdBy: "evodev";
-    rawLogsStored: false;
-    rawPromptsStored: false;
-    sourceDumpsStored: false;
-    rawCommandOutputStored: false;
-  };
-  privacy: EvolutionPrivacyFields;
-}
-
-export interface EvolutionRepoProposal {
-  schemaVersion: 1;
-  id: string;
-  kind: EvolutionProposalKind;
-  projectKey: string;
-  title: string;
-  summary: string;
-  rationale: string;
-  roleTags: string[];
-  tags: string[];
-  reviewState: "pending" | "accepted" | "rejected" | "deferred" | "applied";
-  confidence: EvolutionConfidence;
-  targetRepoPath: string | null;
-  plannedFiles: Array<{
-    relativePath: string;
-    action: "create" | "update";
-    reason: string;
-  }>;
-  apply: {
-    autoApply: false;
-    requiresExplicitCommand: true;
-    rollbackPlan: string;
-  };
-  provenance: {
-    runId: string;
-    taskId: string | null;
-    evidenceWindowId: string;
-    sourceRefs: string[];
-    createdAt: string;
-    createdBy: "evodev";
-    rawLogsStored: false;
-    rawPromptsStored: false;
-    sourceDumpsStored: false;
-    rawCommandOutputStored: false;
-  };
-  privacy: EvolutionPrivacyFields;
-}
-
-export interface EvolutionDistillationBatch {
-  schemaVersion: 1;
-  id: string;
-  projectKey: string;
-  runId: string;
-  createdAt: string;
-  evidenceWindow: EvolutionEvidenceWindow;
-  knowledgeRecords: EvolutionKnowledgeRecord[];
-  evosCases: EvolutionEvosCase[];
-  repoProposals: EvolutionRepoProposal[];
-  warnings: string[];
-}
-
-export interface EvolutionAnalyzeInput {
-  homeDir: string;
-  runId: string;
-  projectKey?: string;
-  projectDir?: string;
-  now?: string | Date;
-}
-
-export interface EvolutionAnalyzeResult {
-  evidenceWindow: EvolutionEvidenceWindow;
-  warnings: string[];
-}
-
-export interface EvolutionWriteResult {
-  evidenceWindowPath: string;
-  batchPath: string;
-  knowledgePaths: string[];
-  evosCasePaths: string[];
-  repoProposalPaths: string[];
-  knowledgeIndexPath: string;
-  evosIndexPath: string;
-}
-
-export interface EvolutionReviewSnapshot {
-  projectKey: string | null;
-  knowledgeRecords: EvolutionKnowledgeRecord[];
-  evosCases: EvolutionEvosCase[];
-  repoProposals: EvolutionRepoProposal[];
-  triggers: EvolutionTriggerRecord[];
-}
-
-export interface EvolutionResolvedPaths {
-  projectKey: string;
-  runId: string;
-  evolutionStateDir: string;
-  runStateDir: string;
-  evidenceWindowPath: string;
-  batchPath: string;
-  triggersDir: string;
-  repoProposalsDir: string;
-  repoProposalsIndexPath: string;
-  knowledgeProjectDir: string;
-  knowledgeRecordsDir: string;
-  knowledgeIndexPath: string;
-  evosCasesProjectDir: string;
-  evosIndexPath: string;
-}
-
-export interface EvolutionTriggerInput {
-  homeDir: string;
-  projectKey: string;
-  runId: string;
-  roleId?: string | null;
-  taskId?: string | null;
-  eventType: string;
-  eventId?: string | null;
-  evidenceRef?: string | null;
-  summary?: string | null;
-  now?: string | Date;
-}
-
-export interface EvolutionTriggerListInput {
-  homeDir: string;
-  projectKey?: string;
-  runId?: string;
-  status?: EvolutionTriggerStatus;
-}
-
-export interface EvolutionProcessInput {
-  homeDir: string;
-  projectKey?: string;
-  runId?: string;
-  limit?: number;
-  now?: string | Date;
-  dryRun?: boolean;
-}
-
-export interface EvolutionProcessResult {
-  processed: number;
-  consumed: number;
-  skipped: number;
-  failed: number;
-  pending: number;
-  triggerIds: string[];
-  batchIds: string[];
-  warnings: string[];
-  dryRun: boolean;
-}
-
-const MAX_EVIDENCE_EVENTS = 200;
-const MAX_TEXT_LENGTH = 600;
-const PROCESS_LOCK_STALE_MS = 5 * 60 * 1000;
-const REVIEW_STATES: readonly EvolutionReviewState[] = [
-  "auto-stored/unreviewed",
-  "accepted",
-  "rejected",
-  "deferred",
-  "deprecated",
-  "superseded",
-  "revoked",
-];
-const KNOWLEDGE_KINDS: readonly EvolutionKnowledgeKind[] = [
-  "run-summary",
-  "lesson",
-  "rule",
-  "workflow-hint",
-  "skill-gap",
-  "role-note",
-  "verification-pattern",
-];
-const PROPOSAL_KINDS: readonly EvolutionProposalKind[] = [
-  "skill",
-  "rule",
-  "role-agent",
-  "team",
-  "ci",
-  "test",
-  "docs",
-  "engineering-practice",
-];
-const EVENT_KINDS: readonly EvolutionEvidenceEventKind[] = [
-  "trace",
-  "tool-call",
-  "skill-call",
-  "subagent",
-  "verification",
-  "review",
-  "user-feedback",
-  "error",
-  "run-state",
-];
-const NORMALIZED_EVENT_TYPES: readonly EvolutionNormalizedEventType[] = [
-  "SessionStart",
-  "UserPromptSubmit",
-  "UserPromptExpansion",
-  "PreToolUse",
-  "PermissionRequest",
-  "PostToolUse",
-  "PostToolUseFailure",
-  "PostToolBatch",
-  "PermissionDenied",
-  "SubagentStart",
-  "Stop",
-  "StopFailure",
-  "TeammateIdle",
-  "SubagentStop",
-  "TaskCreated",
-  "TaskCompleted",
-  "PreCompact",
-  "PostCompact",
-  "SessionEnd",
-  "ConfigChange",
-  "CwdChanged",
-  "FileChanged",
-  "WorktreeCreate",
-  "WorktreeRemove",
-  "unknown",
-];
-const TRIGGER_STRENGTHS: readonly EvolutionTriggerStrength[] = ["none", "conditional", "strong"];
-const TRIGGER_REASONS: readonly EvolutionTriggerReason[] = [
-  "none",
-  "turn-completed",
-  "task-completed",
-  "session-ended",
-  "role-completed",
-  "stop-failure",
-  "tool-failure",
-  "permission-denied",
-  "explicit-command",
-  "failure-signal",
-];
-const EPISODE_KINDS: readonly EvolutionEpisodeKind[] = ["session", "turn", "task", "role"];
-const EPISODE_STATUSES: readonly EvolutionEpisodeStatus[] = ["open", "closed", "failed"];
-const TRIGGER_STATUSES: readonly EvolutionTriggerStatus[] = [
-  "pending",
-  "processing",
-  "consumed",
-  "failed",
-  "skipped",
-];
-const FORBIDDEN_RAW_KEYS = new Set([
-  "commandhistory",
-  "commandoutput",
-  "credential",
-  "credentials",
-  "env",
-  "fullsource",
-  "memorybody",
-  "password",
-  "privatekey",
-  "prompt",
-  "promptbody",
-  "prompttext",
-  "rawcommand",
-  "rawcommandoutput",
-  "rawlog",
-  "rawlogs",
-  "rawoutput",
-  "rawpayload",
-  "rawprompt",
-  "secret",
-  "secretvalue",
-  "source",
-  "sourcebody",
-  "sourcecode",
-  "sourcecontent",
-  "sourcetext",
-  "stderr",
-  "stdout",
-  "token",
-  "transcript",
-  "transcriptbody",
-  "transcripttext",
-]);
-const SENSITIVE_TEXT_PATTERN =
-  /https?:\/\/\S+|\b(secret|token|password|passwd|api[_-]?key|apikey|credential|credentials|raw log|raw logs|raw output|raw source|raw prompt|shell history|command history)\b/i;
-const SENSITIVE_TEXT_REPLACE_PATTERN =
-  /https?:\/\/\S+|\b(secret|token|password|passwd|api[_-]?key|apikey|credential|credentials|raw log|raw logs|raw output|raw source|raw prompt|shell history|command history)\b/gi;
-
-export async function analyzeEvolutionRun(
-  input: EvolutionAnalyzeInput,
-): Promise<EvolutionAnalyzeResult> {
-  const projectKey = resolveEvolutionProjectKey(input);
-  const runId = sanitizeId(input.runId);
-  const paths = resolveEvolutionPaths({ homeDir: input.homeDir, projectKey, runId });
-  const warnings: string[] = [];
-  const sourceRefs: EvolutionEvidenceSourceRef[] = [];
-  const events: EvolutionEvidenceEvent[] = [];
-  const projectRunAgentsDir = join(
-    resolveEvoDevPaths(input.homeDir).logsDir,
-    projectKey,
-    runId,
-    "agents",
-  );
-
-  if (!(await pathExists(projectRunAgentsDir))) {
-    warnings.push(
-      `No agent trace directory found: ${displayPath(input.homeDir, projectRunAgentsDir)}`,
-    );
-  } else {
-    const roleDirs = await readdir(projectRunAgentsDir, { withFileTypes: true });
-    for (const roleDir of roleDirs.filter((entry) => entry.isDirectory())) {
-      const roleId = sanitizeId(roleDir.name);
-      const tracePath = join(projectRunAgentsDir, roleDir.name, "trace.log");
-      if (!(await pathExists(tracePath))) continue;
-
-      const sourceRef: EvolutionEvidenceSourceRef = {
-        id: `source-${sourceRefs.length + 1}`,
-        kind: "team-agent-trace",
-        path: displayPath(input.homeDir, tracePath),
-        roleId,
-        rawContentStored: false,
-      };
-      sourceRefs.push(sourceRef);
-      const parsed = await readTraceEvidenceEvents({
-        path: tracePath,
-        roleId,
-        sourceRefId: sourceRef.id,
-        existingCount: events.length,
-      });
-      events.push(...parsed.events);
-      warnings.push(...parsed.warnings);
-    }
-  }
-
-  if (events.length > MAX_EVIDENCE_EVENTS) {
-    warnings.push(
-      `Evidence events truncated from ${events.length} to ${MAX_EVIDENCE_EVENTS} metadata events.`,
-    );
-  }
-  const limitedEvents = events.slice(0, MAX_EVIDENCE_EVENTS);
-  const episodeAnalysis = buildEvolutionEpisodeAnalysis(limitedEvents);
-
-  const evidenceWindow: EvolutionEvidenceWindow = {
-    schemaVersion: 1,
-    id: createStableId("evidence", [projectKey, runId]),
-    kind: "evidence-window",
-    projectKey,
-    runId,
-    taskId: null,
-    createdAt: normalizeTimestamp(input.now),
-    sourceRefs,
-    events: episodeAnalysis.events,
-    episodes: episodeAnalysis.episodes,
-    triggerPolicy: episodeAnalysis.triggerPolicy,
-    privacy: createPrivacyFields(),
-  };
-  validateEvolutionEvidenceWindow(evidenceWindow);
-
-  return {
-    evidenceWindow,
-    warnings,
-  };
-}
-
-export function createEvolutionDistillationBatch(input: {
-  evidenceWindow: EvolutionEvidenceWindow;
-  now?: string | Date;
-  warnings?: string[];
-}): EvolutionDistillationBatch {
-  validateEvolutionEvidenceWindow(input.evidenceWindow);
-  const createdAt = normalizeTimestamp(input.now);
-  const roleIds = collectRoleIds(input.evidenceWindow);
-  const sourceRefs = input.evidenceWindow.sourceRefs.map((sourceRef) => sourceRef.id);
-  const failedSignals = input.evidenceWindow.events.filter(
-    (event) =>
-      event.kind === "error" ||
-      event.triggerReason === "stop-failure" ||
-      event.triggerReason === "tool-failure" ||
-      event.triggerReason === "permission-denied" ||
-      /fail|failed|failure|error|issue/i.test(event.summary),
-  );
-  const verificationSignals = input.evidenceWindow.events
-    .filter(
-      (event) => event.kind === "verification" || /test|lint|typecheck|build/i.test(event.summary),
-    )
-    .slice(0, 8)
-    .map((event) => event.summary);
-  const autoKnowledgeEligible =
-    input.evidenceWindow.events.length > 0 &&
-    failedSignals.length === 0 &&
-    verificationSignals.length > 0 &&
-    input.evidenceWindow.triggerPolicy.distillRecommended &&
-    input.evidenceWindow.triggerPolicy.evidenceSignals.failures === 0;
-  const confidence: EvolutionConfidence = autoKnowledgeEligible
-    ? "high"
-    : failedSignals.length === 0
-      ? "medium"
-      : "low";
-
-  const knowledgeRecords = !autoKnowledgeEligible
-    ? []
-    : [
-        createEvolutionKnowledgeRecord({
-          id: createStableId("k", [input.evidenceWindow.id, "run-summary"]),
-          kind: "run-summary",
-          title: `Project run ${input.evidenceWindow.runId} evidence summary`,
-          projectKey: input.evidenceWindow.projectKey,
-          summary: createRunSummary(input.evidenceWindow, roleIds, failedSignals.length),
-          body: [
-            `Run ${input.evidenceWindow.runId} produced ${input.evidenceWindow.events.length} redacted metadata evidence event(s).`,
-            `Observed role(s): ${roleIds.length === 0 ? "none" : roleIds.join(", ")}.`,
-            "This record is auto-stored and unreviewed; role agents may use it only as contextual evidence.",
-          ].join("\n"),
-          roleTags: roleIds,
-          tags: ["project-run", "auto-stored", "unreviewed"],
-          reviewState: "auto-stored/unreviewed",
-          authority: "contextual",
-          confidence,
-          provenance: createProvenance(input.evidenceWindow, createdAt, sourceRefs),
-          relations: {
-            relatedKnowledgeIds: [],
-            evosCaseIds: [createStableId("evo", [input.evidenceWindow.id, "case"])],
-            proposalIds:
-              failedSignals.length === 0
-                ? []
-                : [createStableId("proposal", [input.evidenceWindow.id, "engineering-practice"])],
-            supersedes: [],
-          },
-          privacy: createPrivacyFields(),
-          runtime: { canLoad: true, hardBlocking: false },
-        }),
-      ];
-
-  const evosCases =
-    input.evidenceWindow.events.length === 0
-      ? []
-      : [
-          createEvolutionEvosCase({
-            id: createStableId("evo", [input.evidenceWindow.id, "case"]),
-            projectKey: input.evidenceWindow.projectKey,
-            title: `Run ${input.evidenceWindow.runId} evolution case`,
-            roleTags: roleIds,
-            tags: [
-              "project-run",
-              "evidence-window",
-              `trigger-${input.evidenceWindow.triggerPolicy.strongest}`,
-            ],
-            reviewState: "auto-stored/unreviewed",
-            confidence,
-            trigger: {
-              kind: chooseEvosTriggerKind(input.evidenceWindow),
-              summary: createTriggerSummary(input.evidenceWindow),
-            },
-            intervention: {
-              summary: `Collected ${input.evidenceWindow.events.length} redacted event(s) and ${input.evidenceWindow.episodes.length} episode(s) from role trace logs.`,
-              roleIds,
-            },
-            result: {
-              summary:
-                failedSignals.length === 0
-                  ? "No failure signal was detected in the redacted evidence summaries."
-                  : `${failedSignals.length} potential failure or issue signal(s) were detected.`,
-              verificationSignals,
-            },
-            expectedFutureBehavior:
-              "Future role agents should inspect accepted knowledge first and treat unreviewed cases as contextual evidence only.",
-            provenance: createProvenance(input.evidenceWindow, createdAt, sourceRefs),
-            privacy: createPrivacyFields(),
-          }),
-        ];
-
-  const repoProposals =
-    failedSignals.length === 0
-      ? []
-      : [
-          createEvolutionRepoProposal({
-            id: createStableId("proposal", [input.evidenceWindow.id, "engineering-practice"]),
-            kind: "engineering-practice",
-            projectKey: input.evidenceWindow.projectKey,
-            title: `Review repeated failure signals for ${input.evidenceWindow.runId}`,
-            summary:
-              "Failure or issue signals appeared in redacted run evidence; review whether repository rules, tests, skills, or role agents need improvement.",
-            rationale:
-              "EvoDev stores this as a proposal only. It must not modify the user repository until an explicit apply command is implemented and invoked.",
-            roleTags: roleIds,
-            tags: ["proposal", "failure-signal"],
-            reviewState: "pending",
-            confidence: "low",
-            targetRepoPath: null,
-            plannedFiles: [],
-            apply: {
-              autoApply: false,
-              requiresExplicitCommand: true,
-              rollbackPlan: "No repository files are changed by this proposal.",
-            },
-            provenance: createProvenance(input.evidenceWindow, createdAt, sourceRefs),
-            privacy: createPrivacyFields(),
-          }),
-        ];
-
-  const batch: EvolutionDistillationBatch = {
-    schemaVersion: 1,
-    id: createStableId("batch", [input.evidenceWindow.id, createdAt]),
-    projectKey: input.evidenceWindow.projectKey,
-    runId: input.evidenceWindow.runId,
-    createdAt,
-    evidenceWindow: input.evidenceWindow,
-    knowledgeRecords,
-    evosCases,
-    repoProposals,
-    warnings: (input.warnings ?? []).map(sanitizeText),
-  };
-  validateEvolutionDistillationBatch(batch);
-  return batch;
-}
-
-export async function writeEvolutionDistillationBatch(input: {
-  homeDir: string;
-  batch: EvolutionDistillationBatch;
-  overwrite?: boolean;
-}): Promise<EvolutionWriteResult> {
-  validateEvolutionDistillationBatch(input.batch);
-  const paths = resolveEvolutionPaths({
-    homeDir: input.homeDir,
-    projectKey: input.batch.projectKey,
-    runId: input.batch.runId,
-  });
-  const overwrite = input.overwrite === true;
-  await writeJson(paths.evidenceWindowPath, input.batch.evidenceWindow, { overwrite });
-  await writeJson(paths.batchPath, input.batch, { overwrite });
-
-  const knowledgePaths: string[] = [];
-  for (const record of input.batch.knowledgeRecords) {
-    const path = join(paths.knowledgeRecordsDir, `${record.id}.json`);
-    await writeJson(path, record, { overwrite });
-    knowledgePaths.push(path);
-  }
-
-  const evosCasePaths: string[] = [];
-  for (const evosCase of input.batch.evosCases) {
-    const path = join(paths.evosCasesProjectDir, `${evosCase.id}.json`);
-    await writeJson(path, evosCase, { overwrite });
-    evosCasePaths.push(path);
-  }
-
-  const repoProposalPaths: string[] = [];
-  for (const proposal of input.batch.repoProposals) {
-    const path = join(paths.repoProposalsDir, `${proposal.id}.json`);
-    await writeJson(path, proposal, { overwrite });
-    repoProposalPaths.push(path);
-  }
-
-  const allProjectKnowledgeRecords = await readJsonFiles(
-    paths.knowledgeRecordsDir,
-    parseKnowledgeRecord,
-  );
-  await writeJson(
-    paths.knowledgeIndexPath,
-    {
-      schemaVersion: 1,
-      projectKey: input.batch.projectKey,
-      updatedAt: input.batch.createdAt,
-      records: allProjectKnowledgeRecords.map((record) => ({
-        id: record.id,
-        kind: record.kind,
-        title: record.title,
-        reviewState: record.reviewState,
-        roleTags: record.roleTags,
-      })),
-    },
-    { overwrite: true },
-  );
-
-  const evosCasesRootDir = resolveEvoDevPaths(input.homeDir).evosCasesDir;
-  const evosProjectKeys = await listDirectoryNames(evosCasesRootDir);
-  const evosProjects = await Promise.all(
-    evosProjectKeys.map(async (projectKey) => {
-      const cases = await readJsonFiles(join(evosCasesRootDir, projectKey), parseEvosCase);
-      return {
-        projectKey,
-        cases: cases.map((evosCase) => ({
-          id: evosCase.id,
-          title: evosCase.title,
-          reviewState: evosCase.reviewState,
-        })),
-      };
-    }),
-  );
-  await writeJson(
-    paths.evosIndexPath,
-    {
-      schemaVersion: 1,
-      updatedAt: input.batch.createdAt,
-      projects: evosProjects,
-    },
-    { overwrite: true },
-  );
-
-  const allRunProposals = await readJsonFiles(paths.repoProposalsDir, parseRepoProposal);
-  await writeJson(
-    paths.repoProposalsIndexPath,
-    {
-      schemaVersion: 1,
-      projectKey: input.batch.projectKey,
-      runId: input.batch.runId,
-      updatedAt: input.batch.createdAt,
-      proposals: allRunProposals.map((proposal) => ({
-        id: proposal.id,
-        kind: proposal.kind,
-        title: proposal.title,
-        reviewState: proposal.reviewState,
-      })),
-    },
-    { overwrite: true },
-  );
-
-  return {
-    evidenceWindowPath: paths.evidenceWindowPath,
-    batchPath: paths.batchPath,
-    knowledgePaths,
-    evosCasePaths,
-    repoProposalPaths,
-    knowledgeIndexPath: paths.knowledgeIndexPath,
-    evosIndexPath: paths.evosIndexPath,
-  };
-}
-
-export async function readEvolutionReviewSnapshot(input: {
-  homeDir: string;
-  projectKey?: string;
-}): Promise<EvolutionReviewSnapshot> {
-  const paths = resolveEvoDevPaths(input.homeDir);
-  const projectKeys =
-    input.projectKey === undefined
-      ? await listDirectoryNames(paths.knowledgeDir)
-      : [sanitizeStorageId("projectKey", input.projectKey)];
-  const knowledgeRecords: EvolutionKnowledgeRecord[] = [];
-  const evosCases: EvolutionEvosCase[] = [];
-  const repoProposals: EvolutionRepoProposal[] = [];
-  const triggers: EvolutionTriggerRecord[] = [];
-
-  for (const projectKey of projectKeys) {
-    const resolved = resolveEvolutionPaths({
-      homeDir: input.homeDir,
-      projectKey,
-      runId: "review",
-    });
-    knowledgeRecords.push(
-      ...(await readJsonFiles(resolved.knowledgeRecordsDir, parseKnowledgeRecord)),
-    );
-    evosCases.push(...(await readJsonFiles(resolved.evosCasesProjectDir, parseEvosCase)));
-  }
-
-  const evolutionStateDir = join(paths.stateDir, "evolution");
-  const stateProjectKeys =
-    input.projectKey === undefined
-      ? await listDirectoryNames(evolutionStateDir)
-      : [sanitizeStorageId("projectKey", input.projectKey)];
-  for (const projectKey of stateProjectKeys) {
-    const projectStateDir = join(evolutionStateDir, projectKey);
-    const runIds = await listDirectoryNames(projectStateDir);
-    for (const runId of runIds) {
-      const proposalsDir = join(projectStateDir, runId, "proposals");
-      repoProposals.push(...(await readJsonFiles(proposalsDir, parseRepoProposal)));
-      triggers.push(
-        ...(await readJsonFiles(join(projectStateDir, runId, "triggers"), parseTrigger)),
-      );
-    }
-  }
-
-  return {
-    projectKey:
-      input.projectKey === undefined ? null : sanitizeStorageId("projectKey", input.projectKey),
-    knowledgeRecords,
-    evosCases,
-    repoProposals,
-    triggers,
-  };
-}
-
-export async function listEvolutionKnowledgeRecords(input: {
-  homeDir: string;
-  projectKey?: string;
-}): Promise<EvolutionKnowledgeRecord[]> {
-  return (
-    await readEvolutionReviewSnapshot({
-      homeDir: input.homeDir,
-      projectKey: input.projectKey,
-    })
-  ).knowledgeRecords.sort((left, right) => left.id.localeCompare(right.id));
-}
-
-export async function readEvolutionKnowledgeRecordById(input: {
-  homeDir: string;
-  knowledgeId: string;
-  projectKey?: string;
-}): Promise<EvolutionKnowledgeRecord> {
-  const matches = (await listEvolutionKnowledgeRecords(input)).filter(
-    (record) => record.id === input.knowledgeId,
-  );
-  if (matches.length === 0) throw new Error(`Knowledge record not found: ${input.knowledgeId}`);
-  if (matches.length > 1) {
-    throw new Error(`Knowledge record id is ambiguous across projects: ${input.knowledgeId}`);
-  }
-  return matches[0] as EvolutionKnowledgeRecord;
-}
-
-export async function updateEvolutionKnowledgeReviewState(input: {
-  homeDir: string;
-  knowledgeId: string;
-  projectKey?: string;
-  reviewState: "accepted" | "rejected" | "deferred";
-}): Promise<{ path: string; record: EvolutionKnowledgeRecord }> {
-  const record = await readEvolutionKnowledgeRecordById(input);
-  const next: EvolutionKnowledgeRecord = {
-    ...record,
-    reviewState: input.reviewState,
-    authority: input.reviewState === "accepted" ? "reviewed" : "contextual",
-    runtime: {
-      ...record.runtime,
-      canLoad: input.reviewState === "accepted",
-      hardBlocking: false,
-    },
-  };
-  validateEvolutionKnowledgeRecord(next);
-  const paths = resolveEvolutionPaths({
-    homeDir: input.homeDir,
-    projectKey: next.projectKey,
-    runId: "review",
-  });
-  const path = join(paths.knowledgeRecordsDir, `${next.id}.json`);
-  await writeJson(path, next, { overwrite: true });
-  const allProjectKnowledgeRecords = await readJsonFiles(
-    paths.knowledgeRecordsDir,
-    parseKnowledgeRecord,
-  );
-  await writeJson(
-    paths.knowledgeIndexPath,
-    {
-      version: 1,
-      kind: "evolution-knowledge-index",
-      projectKey: next.projectKey,
-      updatedAt: new Date().toISOString(),
-      records: allProjectKnowledgeRecords.map((item) => ({
-        id: item.id,
-        kind: item.kind,
-        title: item.title,
-        roleTags: item.roleTags,
-        tags: item.tags,
-        reviewState: item.reviewState,
-        authority: item.authority,
-        confidence: item.confidence,
-        runtime: item.runtime,
-      })),
-    },
-    { overwrite: true },
-  );
-  return { path, record: next };
-}
-
-export function formatEvolutionAnalyzeResult(result: EvolutionAnalyzeResult): string {
-  const roles = collectRoleIds(result.evidenceWindow);
-  return [
-    "EvoDev evolution analyze",
-    "",
-    `Project: ${result.evidenceWindow.projectKey}`,
-    `Run: ${result.evidenceWindow.runId}`,
-    `Evidence window: ${result.evidenceWindow.id}`,
-    `Sources: ${result.evidenceWindow.sourceRefs.length}`,
-    `Events: ${result.evidenceWindow.events.length}`,
-    `Episodes: ${result.evidenceWindow.episodes.length}`,
-    `Trigger: ${result.evidenceWindow.triggerPolicy.strongest} (${result.evidenceWindow.triggerPolicy.reasons.join(", ") || "none"}); distillRecommended=${result.evidenceWindow.triggerPolicy.distillRecommended}`,
-    `Roles: ${roles.length === 0 ? "none" : roles.join(", ")}`,
-    "Privacy: metadata-only; rawLogs=false; rawPrompts=false; sourceDumps=false; rawCommandOutput=false",
-    ...(result.warnings.length === 0
-      ? ["Warnings: none"]
-      : ["Warnings:", ...result.warnings.map((warning) => `  - ${warning}`)]),
-  ].join("\n");
-}
-
-export function formatEvolutionDistillationBatch(batch: EvolutionDistillationBatch): string {
-  return [
-    "EvoDev evolution distillation",
-    "",
-    `Batch: ${batch.id}`,
-    `Project: ${batch.projectKey}`,
-    `Run: ${batch.runId}`,
-    `Evidence events: ${batch.evidenceWindow.events.length}`,
-    `Episodes: ${batch.evidenceWindow.episodes.length}`,
-    `Trigger: ${batch.evidenceWindow.triggerPolicy.strongest}; distillRecommended=${batch.evidenceWindow.triggerPolicy.distillRecommended}`,
-    `Knowledge records: ${batch.knowledgeRecords.length}`,
-    `Evos cases: ${batch.evosCases.length}`,
-    `Repo proposals: ${batch.repoProposals.length}`,
-    "Default review state: auto-stored/unreviewed for knowledge and evos cases.",
-    "Runtime authority: contextual only; hardBlocking=false.",
-    ...(batch.knowledgeRecords.length === 0
-      ? ["Knowledge: none"]
-      : [
-          "Knowledge:",
-          ...batch.knowledgeRecords.map(
-            (record) =>
-              `  - ${record.id} (${record.kind}, ${record.reviewState}, ${record.confidence}): ${record.title}`,
-          ),
-        ]),
-    ...(batch.evosCases.length === 0
-      ? ["Evos cases: none"]
-      : [
-          "Evos cases:",
-          ...batch.evosCases.map(
-            (evosCase) =>
-              `  - ${evosCase.id} (${evosCase.reviewState}, ${evosCase.confidence}): ${evosCase.title}`,
-          ),
-        ]),
-    ...(batch.repoProposals.length === 0
-      ? ["Repo proposals: none"]
-      : [
-          "Repo proposals:",
-          ...batch.repoProposals.map(
-            (proposal) =>
-              `  - ${proposal.id} (${proposal.kind}, ${proposal.reviewState}, ${proposal.confidence}): ${proposal.title}`,
-          ),
-        ]),
-    ...(batch.warnings.length === 0
-      ? []
-      : ["Warnings:", ...batch.warnings.map((warning) => `  - ${warning}`)]),
-  ].join("\n");
-}
-
-export function formatEvolutionWriteResult(result: EvolutionWriteResult): string {
-  return [
-    "EvoDev evolution write",
-    "",
-    `Evidence window: ${result.evidenceWindowPath}`,
-    `Distillation batch: ${result.batchPath}`,
-    `Knowledge records: ${result.knowledgePaths.length}`,
-    ...result.knowledgePaths.map((path) => `  - ${path}`),
-    `Evos cases: ${result.evosCasePaths.length}`,
-    ...result.evosCasePaths.map((path) => `  - ${path}`),
-    `Repo proposals: ${result.repoProposalPaths.length}`,
-    ...result.repoProposalPaths.map((path) => `  - ${path}`),
-    `Knowledge index: ${result.knowledgeIndexPath}`,
-    `Evos index: ${result.evosIndexPath}`,
-  ].join("\n");
-}
-
-export function formatEvolutionProcessResult(result: EvolutionProcessResult): string {
-  return [
-    "EvoDev evolution process",
-    "",
-    `Mode: ${result.dryRun ? "dry-run" : "write"}`,
-    `Processed triggers: ${result.processed}`,
-    `Consumed: ${result.consumed}`,
-    `Skipped: ${result.skipped}`,
-    `Failed: ${result.failed}`,
-    `Still pending: ${result.pending}`,
-    `Batches: ${result.batchIds.length}`,
-    ...result.batchIds.map((batchId) => `  - ${batchId}`),
-    ...(result.warnings.length === 0
-      ? ["Warnings: none"]
-      : ["Warnings:", ...result.warnings.map((warning) => `  - ${warning}`)]),
-  ].join("\n");
-}
-
-export function formatEvolutionReviewSnapshot(snapshot: EvolutionReviewSnapshot): string {
-  return [
-    "EvoDev evolution review snapshot",
-    "",
-    `Project: ${snapshot.projectKey ?? "all"}`,
-    `Knowledge records: ${snapshot.knowledgeRecords.length}`,
-    ...snapshot.knowledgeRecords.map(
-      (record) =>
-        `  - ${record.id} (${record.projectKey}, ${record.kind}, ${record.reviewState}, ${record.confidence}): ${record.title}`,
-    ),
-    `Evos cases: ${snapshot.evosCases.length}`,
-    ...snapshot.evosCases.map(
-      (evosCase) =>
-        `  - ${evosCase.id} (${evosCase.projectKey}, ${evosCase.reviewState}, ${evosCase.confidence}): ${evosCase.title}`,
-    ),
-    `Repo proposals: ${snapshot.repoProposals.length}`,
-    ...snapshot.repoProposals.map(
-      (proposal) =>
-        `  - ${proposal.id} (${proposal.projectKey}, ${proposal.kind}, ${proposal.reviewState}, ${proposal.confidence}): ${proposal.title}`,
-    ),
-    `Triggers: ${snapshot.triggers.length}`,
-    ...snapshot.triggers.map(
-      (trigger) =>
-        `  - ${trigger.id} (${trigger.projectKey}, ${trigger.runId}, ${trigger.eventType}, ${trigger.status}, ${trigger.triggerStrength}): ${trigger.summary}`,
-    ),
-  ].join("\n");
-}
-
-export function resolveEvolutionPaths(input: {
-  homeDir: string;
-  projectKey: string;
-  runId: string;
-}): EvolutionResolvedPaths {
-  const paths = resolveEvoDevPaths(input.homeDir);
-  const projectKey = sanitizeStorageId("projectKey", input.projectKey);
-  const runId = sanitizeStorageId("runId", input.runId);
-  const evolutionStateDir = join(paths.stateDir, "evolution");
-  const runStateDir = join(evolutionStateDir, projectKey, runId);
-  const repoProposalsDir = join(runStateDir, "proposals");
-  const knowledgeProjectDir = join(paths.knowledgeDir, projectKey);
-  const evosCasesProjectDir = join(paths.evosCasesDir, projectKey);
-  assertPathDescendant(evolutionStateDir, runStateDir, "runStateDir");
-  assertPathDescendant(paths.knowledgeDir, knowledgeProjectDir, "knowledgeProjectDir");
-  assertPathDescendant(paths.evosCasesDir, evosCasesProjectDir, "evosCasesProjectDir");
-  return {
-    projectKey,
-    runId,
-    evolutionStateDir,
-    runStateDir,
-    evidenceWindowPath: join(runStateDir, "evidence-window.json"),
-    batchPath: join(runStateDir, "distillation-batch.json"),
-    triggersDir: join(runStateDir, "triggers"),
-    repoProposalsDir,
-    repoProposalsIndexPath: join(runStateDir, "proposals.index.json"),
-    knowledgeProjectDir,
-    knowledgeRecordsDir: join(knowledgeProjectDir, "records"),
-    knowledgeIndexPath: join(knowledgeProjectDir, "index.json"),
-    evosCasesProjectDir,
-    evosIndexPath: paths.evosIndexPath,
-  };
-}
-
-export function validateEvolutionEvidenceWindow(window: EvolutionEvidenceWindow): void {
-  if (!isRecord(window)) throw new Error("Evidence window must be an object.");
-  if (window.schemaVersion !== 1) throw new Error("Evidence window schemaVersion must be 1.");
-  if (window.kind !== "evidence-window") throw new Error("Evidence window kind is invalid.");
-  assertString("projectKey", window.projectKey);
-  assertString("runId", window.runId);
-  assertString("id", window.id);
-  assertString("createdAt", window.createdAt);
-  assertPrivacy(window.privacy);
-  if (!Array.isArray(window.sourceRefs)) throw new Error("sourceRefs must be an array.");
-  for (const sourceRef of window.sourceRefs) {
-    assertString("sourceRefs.id", sourceRef.id);
-    assertString("sourceRefs.path", sourceRef.path);
-    if (sourceRef.rawContentStored !== false)
-      throw new Error("sourceRefs.rawContentStored must be false.");
-  }
-  if (!Array.isArray(window.events)) throw new Error("events must be an array.");
-  for (const event of window.events) {
-    assertString("events.id", event.id);
-    assertEnum("events.kind", event.kind, EVENT_KINDS);
-    assertEnum("events.eventType", event.eventType, NORMALIZED_EVENT_TYPES);
-    assertEnum("events.triggerStrength", event.triggerStrength, TRIGGER_STRENGTHS);
-    assertEnum("events.triggerReason", event.triggerReason, TRIGGER_REASONS);
-    assertString("events.summary", event.summary);
-    assertString("events.evidenceRef", event.evidenceRef);
-    if (!Array.isArray(event.episodeIds)) throw new Error("events.episodeIds must be an array.");
-    for (const episodeId of event.episodeIds) assertString("events.episodeIds", episodeId);
-    if (event.rawContentStored !== false) throw new Error("events.rawContentStored must be false.");
-  }
-  if (!Array.isArray(window.episodes)) throw new Error("episodes must be an array.");
-  for (const episode of window.episodes) {
-    assertString("episodes.id", episode.id);
-    assertEnum("episodes.kind", episode.kind, EPISODE_KINDS);
-    assertEnum("episodes.status", episode.status, EPISODE_STATUSES);
-    assertEnum("episodes.triggerStrength", episode.triggerStrength, TRIGGER_STRENGTHS);
-    assertEnum("episodes.triggerReason", episode.triggerReason, TRIGGER_REASONS);
-    assertString("episodes.summary", episode.summary);
-    if (!Array.isArray(episode.eventIds)) throw new Error("episodes.eventIds must be an array.");
-    for (const eventId of episode.eventIds) assertString("episodes.eventIds", eventId);
-    if (episode.rawContentStored !== false)
-      throw new Error("episodes.rawContentStored must be false.");
-  }
-  assertEnum("triggerPolicy.strongest", window.triggerPolicy.strongest, TRIGGER_STRENGTHS);
-  if (!Array.isArray(window.triggerPolicy.reasons))
-    throw new Error("triggerPolicy.reasons must be an array.");
-  for (const reason of window.triggerPolicy.reasons) {
-    assertEnum("triggerPolicy.reasons", reason, TRIGGER_REASONS);
-  }
-  assertNoForbiddenRawFields(window);
-}
-
-export function validateEvolutionKnowledgeRecord(record: EvolutionKnowledgeRecord): void {
-  if (!isRecord(record)) throw new Error("Knowledge record must be an object.");
-  if (record.schemaVersion !== 1) throw new Error("Knowledge record schemaVersion must be 1.");
-  assertEnum("kind", record.kind, KNOWLEDGE_KINDS);
-  assertEnum("reviewState", record.reviewState, REVIEW_STATES);
-  assertEnum("authority", record.authority, ["contextual", "reviewed"]);
-  if (record.reviewState === "auto-stored/unreviewed" && record.authority !== "contextual") {
-    throw new Error("Unreviewed knowledge must remain contextual.");
-  }
-  if (record.runtime.hardBlocking !== false) {
-    throw new Error("Knowledge runtime.hardBlocking must be false.");
-  }
-  assertPrivacy(record.privacy);
-  assertProvenance(record.provenance);
-  assertNoForbiddenRawFields(record);
-}
-
-export function validateEvolutionDistillationBatch(batch: EvolutionDistillationBatch): void {
-  if (!isRecord(batch)) throw new Error("Distillation batch must be an object.");
-  if (batch.schemaVersion !== 1) throw new Error("Distillation batch schemaVersion must be 1.");
-  validateEvolutionEvidenceWindow(batch.evidenceWindow);
-  for (const record of batch.knowledgeRecords) validateEvolutionKnowledgeRecord(record);
-  for (const evosCase of batch.evosCases) validateEvolutionEvosCase(evosCase);
-  for (const proposal of batch.repoProposals) validateEvolutionRepoProposal(proposal);
-  assertNoForbiddenRawFields(batch);
-}
-
-export function resolveEvolutionTriggerDecision(input: {
-  eventType: string;
-  summary?: string | null;
-}): EvolutionTriggerDecision {
-  const eventType = normalizeEvolutionEventType(input.eventType);
-  const trigger = decideEvolutionTrigger({
-    eventType,
-    summary: input.summary ?? "",
-    kind: "trace",
-  });
-  return {
-    eventType,
-    strength: trigger.strength,
-    reason: trigger.reason,
-    shouldQueue: trigger.strength !== "none",
-    summary: createTriggerDecisionSummary(eventType, trigger.strength, trigger.reason),
-  };
-}
-
-export async function enqueueEvolutionTrigger(
-  input: EvolutionTriggerInput,
-): Promise<EvolutionTriggerRecord | null> {
-  const decision = resolveEvolutionTriggerDecision({
-    eventType: input.eventType,
-    summary: input.summary,
-  });
-  if (!decision.shouldQueue) return null;
-
-  const now = normalizeTimestamp(input.now);
-  const projectKey = sanitizeId(input.projectKey);
-  const runId = sanitizeId(input.runId);
-  const id = createStableId("trigger", [
-    projectKey,
-    runId,
-    input.roleId ?? "",
-    input.eventId ?? "",
-    decision.eventType,
-    now,
-  ]);
-  const trigger: EvolutionTriggerRecord = {
-    schemaVersion: 1,
-    id,
-    kind: "evolution-trigger",
-    projectKey,
-    runId,
-    roleId: input.roleId === undefined || input.roleId === null ? null : sanitizeId(input.roleId),
-    taskId: input.taskId === undefined || input.taskId === null ? null : sanitizeId(input.taskId),
-    eventType: decision.eventType,
-    eventId:
-      input.eventId === undefined || input.eventId === null ? null : sanitizeId(input.eventId),
-    evidenceRef:
-      input.evidenceRef === undefined || input.evidenceRef === null
-        ? null
-        : sanitizeText(input.evidenceRef),
-    summary: sanitizeText(input.summary ?? decision.summary),
-    triggerStrength: decision.strength,
-    triggerReason: decision.reason,
-    status: "pending",
-    attempts: 0,
-    createdAt: now,
-    updatedAt: now,
-    processedBatchId: null,
-    lastError: null,
-    rawContentStored: false,
-    privacy: createPrivacyFields(),
-  };
-  validateEvolutionTriggerRecord(trigger);
-  const paths = resolveEvolutionPaths({ homeDir: input.homeDir, projectKey, runId });
-  await writeJson(join(paths.triggersDir, `${trigger.id}.json`), trigger, { overwrite: false });
-  return trigger;
-}
-
-export async function listEvolutionTriggers(
-  input: EvolutionTriggerListInput,
-): Promise<EvolutionTriggerRecord[]> {
-  const paths = resolveEvoDevPaths(input.homeDir);
-  const evolutionStateDir = join(paths.stateDir, "evolution");
-  const projectKeys =
-    input.projectKey === undefined
-      ? await listDirectoryNames(evolutionStateDir)
-      : [sanitizeStorageId("projectKey", input.projectKey)];
-  const triggers: EvolutionTriggerRecord[] = [];
-  for (const projectKey of projectKeys) {
-    const projectStateDir = join(evolutionStateDir, projectKey);
-    const runIds =
-      input.runId === undefined
-        ? await listDirectoryNames(projectStateDir)
-        : [sanitizeStorageId("runId", input.runId)];
-    for (const runId of runIds) {
-      const runTriggers = await readJsonFiles(
-        join(projectStateDir, runId, "triggers"),
-        parseTrigger,
-      );
-      triggers.push(
-        ...runTriggers.filter(
-          (trigger) => input.status === undefined || trigger.status === input.status,
-        ),
-      );
-    }
-  }
-  return triggers.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
-}
-
-export async function processEvolutionTriggers(
-  input: EvolutionProcessInput,
-): Promise<EvolutionProcessResult> {
-  const now = normalizeTimestamp(input.now);
-  const limit = input.limit ?? 20;
-  const dryRun = input.dryRun === true;
-  const warnings: string[] = [];
-  const lock = dryRun ? null : await acquireEvolutionProcessLock(input.homeDir, now);
-  if (!dryRun && lock === null) {
-    warnings.push("Evolution trigger processor is already running; this pass was skipped.");
-    return {
-      processed: 0,
-      consumed: 0,
-      skipped: 0,
-      failed: 0,
-      pending: 0,
-      triggerIds: [],
-      batchIds: [],
-      warnings,
-      dryRun,
-    };
-  }
-
-  try {
-    const pending = (
-      await listEvolutionTriggers({
-        homeDir: input.homeDir,
-        projectKey: input.projectKey,
-        runId: input.runId,
-        status: "pending",
-      })
-    ).slice(0, limit);
-    const grouped = groupTriggersByRun(pending);
-    const result: EvolutionProcessResult = {
-      processed: 0,
-      consumed: 0,
-      skipped: 0,
-      failed: 0,
-      pending: 0,
-      triggerIds: pending.map((trigger) => trigger.id),
-      batchIds: [],
-      warnings,
-      dryRun,
-    };
-
-    for (const triggers of grouped) {
-      result.processed += triggers.length;
-      if (dryRun) {
-        result.pending += triggers.length;
-        continue;
-      }
-      await updateTriggers(input.homeDir, triggers, {
-        status: "processing",
-        updatedAt: now,
-        attempts: (trigger) => trigger.attempts + 1,
-      });
-
-      try {
-        const first = triggers[0];
-        if (first === undefined) continue;
-        const analysis = await analyzeEvolutionRun({
-          homeDir: input.homeDir,
-          projectKey: first.projectKey,
-          runId: first.runId,
-          now,
-        });
-        warnings.push(...analysis.warnings);
-        const missingTrace = triggers.some(
-          (trigger) =>
-            trigger.eventId !== null &&
-            !analysis.evidenceWindow.events.some((event) => event.hookEventId === trigger.eventId),
-        );
-        if (missingTrace) {
-          result.pending += triggers.length;
-          await updateTriggers(input.homeDir, triggers, {
-            status: "pending",
-            updatedAt: now,
-            lastError: "waiting-for-trace",
-          });
-          continue;
-        }
-        if (!analysis.evidenceWindow.triggerPolicy.distillRecommended) {
-          result.skipped += triggers.length;
-          await updateTriggers(input.homeDir, triggers, {
-            status: "skipped",
-            updatedAt: now,
-            lastError: "no-distillation-signal",
-          });
-          continue;
-        }
-
-        const batch = createEvolutionDistillationBatch({
-          evidenceWindow: analysis.evidenceWindow,
-          warnings: analysis.warnings,
-          now,
-        });
-        await writeEvolutionDistillationBatch({
-          homeDir: input.homeDir,
-          batch,
-          overwrite: true,
-        });
-        result.consumed += triggers.length;
-        result.batchIds.push(batch.id);
-        await updateTriggers(input.homeDir, triggers, {
-          status: "consumed",
-          updatedAt: now,
-          processedBatchId: batch.id,
-          lastError: null,
-        });
-      } catch (error) {
-        result.failed += triggers.length;
-        const message = sanitizeText(error instanceof Error ? error.message : String(error));
-        warnings.push(message);
-        await updateTriggers(input.homeDir, triggers, {
-          status: "failed",
-          updatedAt: now,
-          lastError: message,
-        });
-      }
-    }
-
-    return result;
-  } finally {
-    if (lock !== null) await releaseEvolutionProcessLock(lock);
-  }
-}
-
-function createEvolutionKnowledgeRecord(
-  input: Omit<EvolutionKnowledgeRecord, "schemaVersion">,
-): EvolutionKnowledgeRecord {
-  const record: EvolutionKnowledgeRecord = {
-    ...input,
-    schemaVersion: 1,
-    id: sanitizeId(input.id),
-    title: sanitizeText(input.title),
-    projectKey: sanitizeId(input.projectKey),
-    summary: sanitizeText(input.summary),
-    body: sanitizeText(input.body),
-    roleTags: uniqueSanitizedIds(input.roleTags),
-    tags: uniqueSanitizedIds(input.tags),
-  };
-  validateEvolutionKnowledgeRecord(record);
-  return record;
-}
-
-function createEvolutionEvosCase(
-  input: Omit<EvolutionEvosCase, "schemaVersion" | "kind">,
-): EvolutionEvosCase {
-  const evosCase: EvolutionEvosCase = {
-    ...input,
-    schemaVersion: 1,
-    kind: "evos-case",
-    id: sanitizeId(input.id),
-    projectKey: sanitizeId(input.projectKey),
-    title: sanitizeText(input.title),
-    roleTags: uniqueSanitizedIds(input.roleTags),
-    tags: uniqueSanitizedIds(input.tags),
-    trigger: {
-      kind: input.trigger.kind,
-      summary: sanitizeText(input.trigger.summary),
-    },
-    intervention: {
-      summary: sanitizeText(input.intervention.summary),
-      roleIds: uniqueSanitizedIds(input.intervention.roleIds),
-    },
-    result: {
-      summary: sanitizeText(input.result.summary),
-      verificationSignals: input.result.verificationSignals.map(sanitizeText),
-    },
-    expectedFutureBehavior: sanitizeText(input.expectedFutureBehavior),
-  };
-  validateEvolutionEvosCase(evosCase);
-  return evosCase;
-}
-
-function createEvolutionRepoProposal(
-  input: Omit<EvolutionRepoProposal, "schemaVersion">,
-): EvolutionRepoProposal {
-  const proposal: EvolutionRepoProposal = {
-    ...input,
-    schemaVersion: 1,
-    id: sanitizeId(input.id),
-    projectKey: sanitizeId(input.projectKey),
-    title: sanitizeText(input.title),
-    summary: sanitizeText(input.summary),
-    rationale: sanitizeText(input.rationale),
-    roleTags: uniqueSanitizedIds(input.roleTags),
-    tags: uniqueSanitizedIds(input.tags),
-    plannedFiles: input.plannedFiles.map((file) => ({
-      relativePath: sanitizeRelativePath(file.relativePath),
-      action: file.action,
-      reason: sanitizeText(file.reason),
-    })),
-  };
-  validateEvolutionRepoProposal(proposal);
-  return proposal;
-}
-
-function validateEvolutionEvosCase(evosCase: EvolutionEvosCase): void {
-  if (!isRecord(evosCase)) throw new Error("Evos case must be an object.");
-  if (evosCase.schemaVersion !== 1) throw new Error("Evos case schemaVersion must be 1.");
-  if (evosCase.kind !== "evos-case") throw new Error("Evos case kind is invalid.");
-  assertEnum("reviewState", evosCase.reviewState, REVIEW_STATES);
-  assertPrivacy(evosCase.privacy);
-  assertProvenance(evosCase.provenance);
-  assertNoForbiddenRawFields(evosCase);
-}
-
-function validateEvolutionRepoProposal(proposal: EvolutionRepoProposal): void {
-  if (!isRecord(proposal)) throw new Error("Repo proposal must be an object.");
-  if (proposal.schemaVersion !== 1) throw new Error("Repo proposal schemaVersion must be 1.");
-  assertEnum("kind", proposal.kind, PROPOSAL_KINDS);
-  assertEnum("reviewState", proposal.reviewState, [
-    "pending",
-    "accepted",
-    "rejected",
-    "deferred",
-    "applied",
-  ]);
-  if (proposal.apply.autoApply !== false || proposal.apply.requiresExplicitCommand !== true) {
-    throw new Error("Repo proposal must require explicit apply.");
-  }
-  assertPrivacy(proposal.privacy);
-  assertProvenance(proposal.provenance);
-  assertNoForbiddenRawFields(proposal);
-}
-
-function validateEvolutionTriggerRecord(trigger: EvolutionTriggerRecord): void {
-  if (!isRecord(trigger)) throw new Error("Evolution trigger must be an object.");
-  if (trigger.schemaVersion !== 1) throw new Error("Evolution trigger schemaVersion must be 1.");
-  if (trigger.kind !== "evolution-trigger") throw new Error("Evolution trigger kind is invalid.");
-  assertString("trigger.id", trigger.id);
-  assertString("trigger.projectKey", trigger.projectKey);
-  assertString("trigger.runId", trigger.runId);
-  assertEnum("trigger.eventType", trigger.eventType, NORMALIZED_EVENT_TYPES);
-  assertEnum("trigger.triggerStrength", trigger.triggerStrength, TRIGGER_STRENGTHS);
-  assertEnum("trigger.triggerReason", trigger.triggerReason, TRIGGER_REASONS);
-  assertEnum("trigger.status", trigger.status, TRIGGER_STATUSES);
-  assertString("trigger.summary", trigger.summary);
-  assertString("trigger.createdAt", trigger.createdAt);
-  assertString("trigger.updatedAt", trigger.updatedAt);
-  if (typeof trigger.attempts !== "number" || trigger.attempts < 0) {
-    throw new Error("trigger.attempts must be a non-negative number.");
-  }
-  if (trigger.rawContentStored !== false)
-    throw new Error("trigger.rawContentStored must be false.");
-  assertPrivacy(trigger.privacy);
-  assertNoForbiddenRawFields(trigger);
-}
-
-async function readTraceEvidenceEvents(input: {
-  path: string;
-  roleId: string;
-  sourceRefId: string;
-  existingCount: number;
-}): Promise<{ events: EvolutionEvidenceEvent[]; warnings: string[] }> {
-  const raw = await readFile(input.path, "utf8");
-  const lines = raw.split("\n");
-  const events: EvolutionEvidenceEvent[] = [];
-  const warnings: string[] = [];
-
-  for (let index = 0; index < lines.length; index += 1) {
-    const line = lines[index]?.trim();
-    if (line === undefined || line === "") continue;
-
-    try {
-      const value = JSON.parse(line) as unknown;
-      if (!isRecord(value)) continue;
-      const event = createEvidenceEventFromTrace({
-        trace: value,
-        roleId: input.roleId,
-        sourceRefId: input.sourceRefId,
-        lineNumber: index + 1,
-        sequence: input.existingCount + events.length + 1,
-      });
-      if (event !== null) events.push(event);
-    } catch {
-      warnings.push(`Skipped malformed trace JSON at ${basename(input.path)}:${index + 1}.`);
-    }
-  }
-
-  return { events, warnings };
-}
-
-function createEvidenceEventFromTrace(input: {
-  trace: Record<string, unknown>;
-  roleId: string;
-  sourceRefId: string;
-  lineNumber: number;
-  sequence: number;
-}): EvolutionEvidenceEvent | null {
-  const phase = optionalString(input.trace.phase);
-  const target = optionalString(input.trace.target);
-  const traceEvent = isRecord(input.trace.event) ? input.trace.event : null;
-  const result = isRecord(input.trace.result) ? input.trace.result : null;
-  const error = optionalString(input.trace.error);
-  const eventSummary = traceEvent === null ? null : optionalString(traceEvent.summary);
-  const eventType = traceEvent === null ? null : optionalString(traceEvent.type);
-  const eventId = traceEvent === null ? null : optionalString(traceEvent.eventId);
-  const resultSummary = result === null ? null : optionalString(result.summary);
-  const summarySource =
-    error ?? resultSummary ?? eventSummary ?? [target, phase].filter(Boolean).join(" ");
-  if (summarySource.trim() === "") return null;
-  const normalizedType = normalizeEvolutionEventType(eventType);
-  const trigger = decideEvolutionTrigger({
-    eventType: normalizedType,
-    summary: summarySource,
-    kind: classifyEvidenceEvent({
-      error,
-      summary: summarySource,
-      target,
-      eventType,
-      phase,
-    }),
-  });
-
-  return {
-    id: `event-${String(input.sequence).padStart(4, "0")}`,
-    kind: classifyEvidenceEvent({
-      error,
-      summary: summarySource,
-      target,
-      eventType,
-      phase,
-    }),
-    eventType: normalizedType,
-    hookEventId: eventId === null ? null : sanitizeId(eventId),
-    occurredAt: optionalString(input.trace.timestamp),
-    summary: sanitizeText(summarySource),
-    roleId: sanitizeId(input.roleId),
-    taskId: extractTraceTaskId(input.trace),
-    evidenceRef: `${input.sourceRefId}#L${input.lineNumber}`,
-    episodeIds: [],
-    triggerStrength: trigger.strength,
-    triggerReason: trigger.reason,
-    rawContentStored: false,
-  };
-}
-
-function classifyEvidenceEvent(input: {
-  error: string | null;
-  summary: string;
-  target: string | null;
-  eventType: string | null;
-  phase: string | null;
-}): EvolutionEvidenceEventKind {
-  const haystack = [input.summary, input.target, input.eventType, input.phase]
-    .filter(Boolean)
-    .join(" ");
-  const normalizedType = normalizeEvolutionEventType(input.eventType);
-  if (
-    normalizedType === "StopFailure" ||
-    normalizedType === "PostToolUseFailure" ||
-    normalizedType === "PermissionDenied"
-  ) {
-    return "error";
-  }
-  if (
-    normalizedType === "PreToolUse" ||
-    normalizedType === "PostToolUse" ||
-    normalizedType === "PermissionRequest" ||
-    normalizedType === "PostToolBatch"
-  ) {
-    return "tool-call";
-  }
-  if (normalizedType === "SubagentStart" || normalizedType === "SubagentStop") return "subagent";
-  if (
-    normalizedType === "SessionStart" ||
-    normalizedType === "SessionEnd" ||
-    normalizedType === "UserPromptSubmit" ||
-    normalizedType === "Stop" ||
-    normalizedType === "TaskCreated" ||
-    normalizedType === "TaskCompleted"
-  ) {
-    return "run-state";
-  }
-  if (input.error !== null || /error|failed|failure|issue/i.test(haystack)) return "error";
-  if (/skill/i.test(haystack)) return "skill-call";
-  if (/subagent|agent|team|role/i.test(haystack)) return "subagent";
-  if (/tool/i.test(haystack)) return "tool-call";
-  if (/verify|verification|test|lint|typecheck|build/i.test(haystack)) return "verification";
-  if (/review/i.test(haystack)) return "review";
-  if (/completed|started|stopped|running/i.test(haystack)) return "run-state";
-  return "trace";
-}
-
-function buildEvolutionEpisodeAnalysis(events: EvolutionEvidenceEvent[]): {
-  events: EvolutionEvidenceEvent[];
-  episodes: EvolutionEpisode[];
-  triggerPolicy: EvolutionTriggerPolicy;
-} {
-  const episodeLinks = new Map<string, string[]>();
-  const episodes: EvolutionEpisode[] = [];
-  const addEpisode = (input: Omit<EvolutionEpisode, "rawContentStored">) => {
-    if (input.eventIds.length === 0) return;
-    const episode: EvolutionEpisode = { ...input, rawContentStored: false };
-    episodes.push(episode);
-    for (const eventId of episode.eventIds) {
-      episodeLinks.set(eventId, [...(episodeLinks.get(eventId) ?? []), episode.id]);
-    }
-  };
-
-  if (events.length > 0) {
-    const strongest = strongestTrigger(events);
-    addEpisode({
-      id: "episode-session-0001",
-      kind: "session",
-      status: events.some((event) => event.eventType === "StopFailure") ? "failed" : "closed",
-      roleId: null,
-      taskId: null,
-      startedAt: events[0]?.occurredAt ?? null,
-      endedAt: events.at(-1)?.occurredAt ?? null,
-      eventIds: events.map((event) => event.id),
-      triggerStrength: strongest.strength,
-      triggerReason: strongest.reason,
-      summary: `Session episode with ${events.length} metadata event(s).`,
-    });
-  }
-
-  let turnEvents: EvolutionEvidenceEvent[] = [];
-  let turnIndex = 1;
-  const closeTurn = (status: EvolutionEpisodeStatus) => {
-    if (turnEvents.length === 0) return;
-    const strongest = strongestTrigger(turnEvents);
-    addEpisode({
-      id: `episode-turn-${String(turnIndex).padStart(4, "0")}`,
-      kind: "turn",
-      status,
-      roleId: firstRoleId(turnEvents),
-      taskId: firstTaskId(turnEvents),
-      startedAt: turnEvents[0]?.occurredAt ?? null,
-      endedAt: turnEvents.at(-1)?.occurredAt ?? null,
-      eventIds: turnEvents.map((event) => event.id),
-      triggerStrength: strongest.strength,
-      triggerReason: strongest.reason,
-      summary: `Turn episode closed with ${turnEvents.length} metadata event(s).`,
-    });
-    turnEvents = [];
-    turnIndex += 1;
-  };
-  for (const event of events) {
-    if (event.eventType === "UserPromptSubmit") {
-      closeTurn("open");
-      turnEvents = [event];
-      continue;
-    }
-    if (turnEvents.length > 0) turnEvents.push(event);
-    if (event.eventType === "Stop" || event.eventType === "StopFailure") {
-      closeTurn(event.eventType === "StopFailure" ? "failed" : "closed");
-    }
-  }
-  closeTurn("open");
-
-  const taskIds = uniqueSanitizedIds(
-    events.flatMap((event) => (event.taskId === null ? [] : [event.taskId])),
-  );
-  taskIds.forEach((taskId, index) => {
-    const taskEvents = events.filter((event) => event.taskId === taskId);
-    const strongest = strongestTrigger(taskEvents);
-    addEpisode({
-      id: `episode-task-${String(index + 1).padStart(4, "0")}`,
-      kind: "task",
-      status: taskEvents.some((event) => event.eventType === "StopFailure") ? "failed" : "closed",
-      roleId: firstRoleId(taskEvents),
-      taskId,
-      startedAt: taskEvents[0]?.occurredAt ?? null,
-      endedAt: taskEvents.at(-1)?.occurredAt ?? null,
-      eventIds: taskEvents.map((event) => event.id),
-      triggerStrength: strongest.strength,
-      triggerReason: strongest.reason,
-      summary: `Task episode ${taskId} contains ${taskEvents.length} metadata event(s).`,
-    });
-  });
-
-  const roleIds = uniqueSanitizedIds(
-    events.flatMap((event) => (event.roleId === null ? [] : [event.roleId])),
-  );
-  roleIds.forEach((roleId, index) => {
-    const roleEvents = events.filter((event) => event.roleId === roleId);
-    const strongest = strongestTrigger(roleEvents);
-    addEpisode({
-      id: `episode-role-${String(index + 1).padStart(4, "0")}`,
-      kind: "role",
-      status: roleEvents.some((event) => event.eventType === "StopFailure") ? "failed" : "closed",
-      roleId,
-      taskId: firstTaskId(roleEvents),
-      startedAt: roleEvents[0]?.occurredAt ?? null,
-      endedAt: roleEvents.at(-1)?.occurredAt ?? null,
-      eventIds: roleEvents.map((event) => event.id),
-      triggerStrength: strongest.strength,
-      triggerReason: strongest.reason,
-      summary: `Role episode ${roleId} contains ${roleEvents.length} metadata event(s).`,
-    });
-  });
-
-  return {
-    events: events.map((event) => ({ ...event, episodeIds: episodeLinks.get(event.id) ?? [] })),
-    episodes,
-    triggerPolicy: createTriggerPolicy(events),
-  };
-}
-
-function normalizeEvolutionEventType(
-  value: string | null | undefined,
-): EvolutionNormalizedEventType {
-  if (value === "AgentStop") return "SubagentStop";
-  if (typeof value === "string" && (NORMALIZED_EVENT_TYPES as readonly string[]).includes(value)) {
-    return value as EvolutionNormalizedEventType;
-  }
-  return "unknown";
-}
-
-function decideEvolutionTrigger(input: {
-  eventType: EvolutionNormalizedEventType;
-  summary: string;
-  kind: EvolutionEvidenceEventKind;
-}): { strength: EvolutionTriggerStrength; reason: EvolutionTriggerReason } {
-  if (input.eventType === "TaskCompleted") return { strength: "strong", reason: "task-completed" };
-  if (input.eventType === "StopFailure") return { strength: "strong", reason: "stop-failure" };
-  if (input.eventType === "PostToolUseFailure")
-    return { strength: "strong", reason: "tool-failure" };
-  if (input.eventType === "PermissionDenied")
-    return { strength: "strong", reason: "permission-denied" };
-  if (input.eventType === "Stop") return { strength: "conditional", reason: "turn-completed" };
-  if (input.eventType === "SessionEnd") return { strength: "conditional", reason: "session-ended" };
-  if (input.eventType === "SubagentStop")
-    return { strength: "conditional", reason: "role-completed" };
-  if (input.kind === "error" || /fail|failed|failure|error|issue/i.test(input.summary)) {
-    return { strength: "strong", reason: "failure-signal" };
-  }
-  return { strength: "none", reason: "none" };
-}
-
-function createTriggerPolicy(events: EvolutionEvidenceEvent[]): EvolutionTriggerPolicy {
-  const failures = events.filter((event) => event.kind === "error").length;
-  const verifications = events.filter((event) => event.kind === "verification").length;
-  const roleLifecycle = events.filter((event) => event.kind === "subagent").length;
-  const skillCalls = events.filter((event) => event.kind === "skill-call").length;
-  const strongest = strongestTrigger(events);
-  const reasons = uniqueTriggerReasons(
-    events.flatMap((event) => (event.triggerReason === "none" ? [] : [event.triggerReason])),
-  );
-  const hasSignal = failures > 0 || verifications > 0 || roleLifecycle > 0 || skillCalls > 0;
-  return {
-    strongest: strongest.strength,
-    reasons,
-    distillRecommended:
-      strongest.strength === "strong" || (strongest.strength === "conditional" && hasSignal),
-    evidenceSignals: { failures, verifications, roleLifecycle, skillCalls },
-  };
-}
-
-function strongestTrigger(events: EvolutionEvidenceEvent[]): {
-  strength: EvolutionTriggerStrength;
-  reason: EvolutionTriggerReason;
-} {
-  const strong = events.find((event) => event.triggerStrength === "strong");
-  if (strong !== undefined) return { strength: "strong", reason: strong.triggerReason };
-  const conditional = events.find((event) => event.triggerStrength === "conditional");
-  if (conditional !== undefined) {
-    return { strength: "conditional", reason: conditional.triggerReason };
-  }
-  return { strength: "none", reason: "none" };
-}
-
-function uniqueTriggerReasons(values: EvolutionTriggerReason[]): EvolutionTriggerReason[] {
-  return [...new Set(values)].filter((reason) => reason !== "none");
-}
-
-function chooseEvosTriggerKind(
-  evidenceWindow: EvolutionEvidenceWindow,
-): EvolutionEvosCase["trigger"]["kind"] {
-  if (evidenceWindow.triggerPolicy.reasons.includes("task-completed")) return "task-completion";
-  if (evidenceWindow.triggerPolicy.reasons.includes("turn-completed")) return "session-completion";
-  if (evidenceWindow.triggerPolicy.reasons.includes("session-ended")) return "session-completion";
-  return "manual";
-}
-
-function createTriggerSummary(evidenceWindow: EvolutionEvidenceWindow): string {
-  const reasons = evidenceWindow.triggerPolicy.reasons.join(", ") || "manual";
-  return sanitizeText(
-    `Evolution distillation used ${evidenceWindow.triggerPolicy.strongest} trigger evidence: ${reasons}.`,
-  );
-}
-
-function createTriggerDecisionSummary(
-  eventType: EvolutionNormalizedEventType,
-  strength: EvolutionTriggerStrength,
-  reason: EvolutionTriggerReason,
-): string {
-  return `Hook event ${eventType} classified as ${strength} evolution trigger (${reason}).`;
-}
-
-function firstRoleId(events: EvolutionEvidenceEvent[]): string | null {
-  return events.find((event) => event.roleId !== null)?.roleId ?? null;
-}
-
-function firstTaskId(events: EvolutionEvidenceEvent[]): string | null {
-  return events.find((event) => event.taskId !== null)?.taskId ?? null;
-}
-
-function extractTraceTaskId(trace: Record<string, unknown>): string | null {
-  const event = isRecord(trace.event) ? trace.event : {};
-  const metadata = isRecord(event.metadata) ? event.metadata : {};
-  const input = isRecord(trace.input) ? trace.input : {};
-  const payload = isRecord(input.payload) ? input.payload : {};
-  return sanitizeOptionalId(
-    metadata.taskId ??
-      metadata.task_id ??
-      payload.taskId ??
-      payload.task_id ??
-      payload.taskID ??
-      null,
-  );
-}
-
-function createRunSummary(
-  evidenceWindow: EvolutionEvidenceWindow,
-  roleIds: string[],
-  failedSignalCount: number,
-): string {
-  const failureClause =
-    failedSignalCount === 0
-      ? "No failure signal was detected in metadata summaries."
-      : `${failedSignalCount} potential failure or issue signal(s) were detected.`;
-  return sanitizeText(
-    `Run ${evidenceWindow.runId} produced ${evidenceWindow.events.length} redacted event(s) across ${roleIds.length} role(s). ${failureClause}`,
-  );
-}
-
-function createProvenance(
-  evidenceWindow: EvolutionEvidenceWindow,
-  createdAt: string,
-  sourceRefs: string[],
-): EvolutionKnowledgeRecord["provenance"] {
-  return {
-    runId: evidenceWindow.runId,
-    taskId: evidenceWindow.taskId,
-    evidenceWindowId: evidenceWindow.id,
-    sourceRefs,
-    createdAt,
-    createdBy: "evodev",
-    rawLogsStored: false,
-    rawPromptsStored: false,
-    sourceDumpsStored: false,
-    rawCommandOutputStored: false,
-  };
-}
-
-function parseKnowledgeRecord(value: unknown): EvolutionKnowledgeRecord {
-  validateEvolutionKnowledgeRecord(value as EvolutionKnowledgeRecord);
-  return value as EvolutionKnowledgeRecord;
-}
-
-function parseEvosCase(value: unknown): EvolutionEvosCase {
-  validateEvolutionEvosCase(value as EvolutionEvosCase);
-  return value as EvolutionEvosCase;
-}
-
-function parseRepoProposal(value: unknown): EvolutionRepoProposal {
-  validateEvolutionRepoProposal(value as EvolutionRepoProposal);
-  return value as EvolutionRepoProposal;
-}
-
-function parseTrigger(value: unknown): EvolutionTriggerRecord {
-  validateEvolutionTriggerRecord(value as EvolutionTriggerRecord);
-  return value as EvolutionTriggerRecord;
-}
-
-async function readJsonFiles<T>(dir: string, parse: (value: unknown) => T): Promise<T[]> {
-  if (!(await pathExists(dir))) return [];
-  const entries = await readdir(dir, { withFileTypes: true });
-  const values: T[] = [];
-  for (const entry of entries) {
-    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
-    values.push(parse(JSON.parse(await readFile(join(dir, entry.name), "utf8")) as unknown));
-  }
-  return values;
-}
-
-function groupTriggersByRun(triggers: EvolutionTriggerRecord[]): EvolutionTriggerRecord[][] {
-  const groups = new Map<string, EvolutionTriggerRecord[]>();
-  for (const trigger of triggers) {
-    const key = `${trigger.projectKey}\0${trigger.runId}`;
-    groups.set(key, [...(groups.get(key) ?? []), trigger]);
-  }
-  return [...groups.values()];
-}
-
-async function acquireEvolutionProcessLock(
-  homeDir: string,
-  now: string,
-): Promise<{ path: string } | null> {
-  const paths = resolveEvoDevPaths(homeDir);
-  const lockPath = join(paths.stateDir, "evolution", ".process.lock");
-  await mkdir(dirname(lockPath), { recursive: true });
-  try {
-    await writeFile(
-      lockPath,
-      `${JSON.stringify(
-        {
-          schemaVersion: 1,
-          kind: "evolution-process-lock",
-          createdAt: now,
-          pid: process.pid,
-        },
-        null,
-        2,
-      )}\n`,
-      { encoding: "utf8", flag: "wx" },
-    );
-    return { path: lockPath };
-  } catch (error) {
-    if (!isFileExistsError(error)) throw error;
-    const current = await stat(lockPath).catch(() => null);
-    if (current !== null && Date.now() - current.mtimeMs > PROCESS_LOCK_STALE_MS) {
-      await rm(lockPath, { force: true });
-      return acquireEvolutionProcessLock(homeDir, now);
-    }
-    return null;
-  }
-}
-
-async function releaseEvolutionProcessLock(lock: { path: string }): Promise<void> {
-  await rm(lock.path, { force: true });
-}
-
-async function updateTriggers(
-  homeDir: string,
-  triggers: EvolutionTriggerRecord[],
-  patch: {
-    status: EvolutionTriggerStatus;
-    updatedAt: string;
-    attempts?: ((trigger: EvolutionTriggerRecord) => number) | number;
-    processedBatchId?: string | null;
-    lastError?: string | null;
-  },
-): Promise<void> {
-  for (const trigger of triggers) {
-    const next: EvolutionTriggerRecord = {
-      ...trigger,
-      status: patch.status,
-      updatedAt: patch.updatedAt,
-      attempts:
-        typeof patch.attempts === "function"
-          ? patch.attempts(trigger)
-          : (patch.attempts ?? trigger.attempts),
-      processedBatchId:
-        patch.processedBatchId === undefined ? trigger.processedBatchId : patch.processedBatchId,
-      lastError: patch.lastError === undefined ? trigger.lastError : patch.lastError,
-    };
-    validateEvolutionTriggerRecord(next);
-    const paths = resolveEvolutionPaths({
-      homeDir,
-      projectKey: next.projectKey,
-      runId: next.runId,
-    });
-    await writeJson(join(paths.triggersDir, `${next.id}.json`), next, { overwrite: true });
-  }
-}
-
-function isFileExistsError(error: unknown): boolean {
-  return (
-    error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "EEXIST"
-  );
-}
-
-async function listDirectoryNames(dir: string): Promise<string[]> {
-  if (!(await pathExists(dir))) return [];
-  const entries = await readdir(dir, { withFileTypes: true });
-  return entries
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => entry.name)
-    .sort();
-}
-
-async function writeJson(
-  path: string,
-  value: unknown,
-  options: { overwrite: boolean },
-): Promise<void> {
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, {
-    encoding: "utf8",
-    flag: options.overwrite ? "w" : "wx",
-  });
-}
-
-function resolveEvolutionProjectKey(input: EvolutionAnalyzeInput): string {
-  if (input.projectKey !== undefined) return sanitizeId(input.projectKey);
-  if (input.projectDir !== undefined) return resolveProjectLogKey(input.homeDir, input.projectDir);
-  throw new Error("Missing project scope: pass --project <projectKey> or --project-dir <path>.");
-}
-
-function collectRoleIds(evidenceWindow: EvolutionEvidenceWindow): string[] {
-  return uniqueSanitizedIds([
-    ...evidenceWindow.sourceRefs.flatMap((sourceRef) =>
-      sourceRef.roleId === null ? [] : [sourceRef.roleId],
-    ),
-    ...evidenceWindow.events.flatMap((event) => (event.roleId === null ? [] : [event.roleId])),
-  ]);
-}
-
-function createStableId(prefix: string, parts: string[]): string {
-  const hash = createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, 16);
-  return `${prefix}-${hash}`;
-}
-
-function createPrivacyFields(): EvolutionPrivacyFields {
-  return {
-    classification: "local-private",
-    rawPromptsStored: false,
-    rawLogsStored: false,
-    sourceDumpsStored: false,
-    rawCommandOutputStored: false,
-    secretsStored: false,
-    internalLinksStored: false,
-  };
-}
-
-function assertPrivacy(privacy: EvolutionPrivacyFields): void {
-  if (!isRecord(privacy)) throw new Error("privacy must be an object.");
-  if (privacy.classification !== "local-private") {
-    throw new Error("privacy.classification must be local-private.");
-  }
-  if (
-    privacy.rawPromptsStored !== false ||
-    privacy.rawLogsStored !== false ||
-    privacy.sourceDumpsStored !== false ||
-    privacy.rawCommandOutputStored !== false ||
-    privacy.secretsStored !== false ||
-    privacy.internalLinksStored !== false
-  ) {
-    throw new Error("Evolution privacy fields must remain metadata-only and raw-content-free.");
-  }
-}
-
-function assertProvenance(provenance: EvolutionKnowledgeRecord["provenance"]): void {
-  if (!isRecord(provenance)) throw new Error("provenance must be an object.");
-  assertString("provenance.runId", provenance.runId);
-  assertString("provenance.evidenceWindowId", provenance.evidenceWindowId);
-  assertString("provenance.createdAt", provenance.createdAt);
-  if (provenance.createdBy !== "evodev") throw new Error("provenance.createdBy must be evodev.");
-  if (
-    provenance.rawLogsStored !== false ||
-    provenance.rawPromptsStored !== false ||
-    provenance.sourceDumpsStored !== false ||
-    provenance.rawCommandOutputStored !== false
-  ) {
-    throw new Error(
-      "Evolution provenance cannot store raw logs, prompts, source, or command output.",
-    );
-  }
-}
-
-function assertEnum<T extends string>(
-  field: string,
-  value: unknown,
-  allowed: readonly T[],
-): asserts value is T {
-  if (typeof value !== "string" || !allowed.includes(value as T)) {
-    throw new Error(`${field} must be one of: ${allowed.join(", ")}`);
-  }
-}
-
-function assertString(field: string, value: unknown): asserts value is string {
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(`${field} must be a non-empty string.`);
-  }
-}
-
-function assertNoForbiddenRawFields(value: unknown, path = ""): void {
-  if (value === null || value === undefined) return;
-  if (typeof value === "string") {
-    if (SENSITIVE_TEXT_PATTERN.test(value)) {
-      throw new Error(`Evolution record contains sensitive content at ${path || "value"}.`);
-    }
-    return;
-  }
-  if (typeof value !== "object") return;
-  if (Array.isArray(value)) {
-    value.forEach((item, index) => assertNoForbiddenRawFields(item, `${path}[${index}]`));
-    return;
-  }
-  for (const [key, child] of Object.entries(value)) {
-    const normalizedKey = key.toLowerCase().replace(/[^a-z0-9]/g, "");
-    if (FORBIDDEN_RAW_KEYS.has(normalizedKey)) {
-      throw new Error(
-        `Evolution record contains forbidden raw field: ${path ? `${path}.` : ""}${key}`,
-      );
-    }
-    assertNoForbiddenRawFields(child, path ? `${path}.${key}` : key);
-  }
-}
-
-function sanitizeText(value: string): string {
-  return value
-    .replace(SENSITIVE_TEXT_REPLACE_PATTERN, "[redacted]")
-    .replace(/\s+/g, " ")
-    .trim()
-    .slice(0, MAX_TEXT_LENGTH);
-}
-
-function sanitizeId(value: string): string {
-  return (
-    value
-      .replace(/[^a-zA-Z0-9._/-]/g, "-")
-      .replace(/[\\/]+/g, "-")
-      .slice(0, 160) || "local"
-  );
-}
-
-function sanitizeStorageId(field: string, value: string): string {
-  const sanitized = sanitizeId(value);
-  if (sanitized === "." || sanitized === "..") {
-    throw new Error(`Invalid evolution ${field}: ${value}`);
-  }
-  if (sanitized.includes("/") || sanitized.includes("\\")) {
-    throw new Error(`Invalid evolution ${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(`Evolution path ${field} escaped expected root.`);
-  }
-}
-
-function sanitizeOptionalId(value: unknown): string | null {
-  if (typeof value !== "string" || value.trim() === "") return null;
-  return sanitizeId(value);
-}
-
-function uniqueSanitizedIds(values: string[]): string[] {
-  return [...new Set(values.map(sanitizeId).filter((value) => value !== ""))];
-}
-
-function sanitizeRelativePath(value: string): string {
-  const sanitized = value.replace(/\\/g, "/").replace(/^\/+/, "");
-  if (sanitized === "" || sanitized.startsWith("../") || sanitized.includes("/../")) {
-    throw new Error(`Invalid relative path in repo proposal: ${value}`);
-  }
-  return sanitized;
-}
-
-function normalizeTimestamp(value?: string | Date): string {
-  if (value instanceof Date) return value.toISOString();
-  if (typeof value === "string" && value.trim() !== "") return new Date(value).toISOString();
-  return new Date().toISOString();
-}
-
-function displayPath(homeDir: string, path: string): string {
-  const relativePath = relative(homeDir, path);
-  if (relativePath !== "" && !relativePath.startsWith("..")) return `~/${relativePath}`;
-  return path;
-}
-
-async function pathExists(path: string): Promise<boolean> {
-  try {
-    await stat(path);
-    return true;
-  } catch (error) {
-    if (
-      error instanceof Error &&
-      "code" in error &&
-      (error as NodeJS.ErrnoException).code === "ENOENT"
-    ) {
-      return false;
-    }
-    throw error;
-  }
-}
-
-function optionalString(value: unknown): string | null {
-  return typeof value === "string" && value.trim() !== "" ? value : null;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+export * from "./schema.ts";
+export * from "./paths.ts";
+export * from "./evidence/analysis.ts";
+export * from "./processor/index.ts";
+export * from "./candidates/index.ts";
+export * from "./triggers/index.ts";
+export * from "./formatters.ts";
+export {
+  createEvolutionRepoProposal,
+  hasConcreteRepoProposalChanges,
+  sanitizeProposedChange,
+  validateEvolutionDistillationBatch,
+  validateEvolutionEvidenceWindow,
+  validateEvolutionKnowledgeRecord,
+  validateEvolutionRepoProposal,
+} from "./shared.ts";