@evo-dev/core 0.0.1-alpha.4 → 0.0.1-alpha.5

package/src/evolution/knowledge/index.ts

@@ -1656,10 +1656,10 @@ export function decideOkfKnowledgeCandidate(
   if (highRiskRequiresHuman) {
     return {
       ...sanitized,
-      decision: "needs-human",
+      decision: "no_write",
       scores,
-      reviewState: "needs-human",
-      decisionReason: "Needs human review: high-risk domain requires review.",
+      reviewState: "auto-stored/unreviewed",
+      decisionReason: "No write: high-risk knowledge is not eligible for automatic activation.",
     };
   }
 
@@ -1677,12 +1677,12 @@ export function decideOkfKnowledgeCandidate(
   if (reusable) {
     return {
       ...sanitized,
-      decision: "needs-human",
+      decision: "no_write",
       scores,
-      reviewState: "needs-human",
+      reviewState: "auto-stored/unreviewed",
       decisionReason:
         conflict?.reason ??
-        explainNeedsHumanDecision(sanitized, scores, hasVerification, hasScopeTags),
+        explainAutomaticNoWriteDecision(sanitized, scores, hasVerification, hasScopeTags),
     };
   }
 
@@ -1746,12 +1746,7 @@ export async function activateOkfKnowledgePlan(input: {
         continue;
       }
       if (candidate.decision === "needs-human") {
-        await writeNeedsHumanKnowledgeCandidate({
-          homeDir: input.homeDir,
-          plan: input.plan,
-          candidate,
-        });
-        needsHumanCandidates.push(candidate.id);
+        skippedCandidates.push(candidate.id);
         continue;
       }
       if (candidate.targetStore !== "okf") {
@@ -3165,66 +3160,6 @@ function createOverlayUpdates(
   ];
 }
 
-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;
 }
@@ -3292,7 +3227,7 @@ function hasHighRiskHumanReviewSignal(candidate: unknown): boolean {
   return HUMAN_REVIEW_DOMAIN_PATTERN.test(values.join(" "));
 }
 
-function explainNeedsHumanDecision(
+function explainAutomaticNoWriteDecision(
   candidate: OkfKnowledgePlanCandidate,
   scores: OkfKnowledgeCandidateScores,
   hasVerification: boolean,
@@ -3308,7 +3243,7 @@ function explainNeedsHumanDecision(
   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"}.`;
+  return `No write: ${reasons.join("; ") || "auto-accept gates were not all satisfied"}.`;
 }
 
 function resolveCandidateReviewStateForWrite(

package/src/evolution/paths.ts

@@ -12,12 +12,14 @@ export function resolveEvolutionPaths(input: {
   const projectKey = sanitizeStorageId("projectKey", input.projectKey);
   const runId = sanitizeStorageId("runId", input.runId);
   const evolutionStateDir = join(paths.stateDir, "evolution");
+  const projectStateDir = join(evolutionStateDir, projectKey);
   const runStateDir = join(evolutionStateDir, projectKey, runId);
   const repoProposalsDir = join(runStateDir, "proposals");
   const reviewCandidatesDir = join(runStateDir, "review-candidates");
   const knowledgeProjectDir = join(paths.knowledgeDir, projectKey);
   const evosCasesProjectDir = join(paths.evosCasesDir, projectKey);
   assertPathDescendant(evolutionStateDir, runStateDir, "runStateDir");
+  assertPathDescendant(evolutionStateDir, projectStateDir, "projectStateDir");
   assertPathDescendant(evolutionStateDir, reviewCandidatesDir, "reviewCandidatesDir");
   assertPathDescendant(paths.knowledgeDir, knowledgeProjectDir, "knowledgeProjectDir");
   assertPathDescendant(paths.evosCasesDir, evosCasesProjectDir, "evosCasesProjectDir");
@@ -35,6 +37,7 @@ export function resolveEvolutionPaths(input: {
     knowledgeProjectDir,
     knowledgeRecordsDir: join(knowledgeProjectDir, "records"),
     knowledgeIndexPath: join(knowledgeProjectDir, "index.json"),
+    knowledgeReviewHistoryPath: join(projectStateDir, "knowledge-review-history.jsonl"),
     evosCasesProjectDir,
     evosIndexPath: paths.evosIndexPath,
   };

package/src/evolution/processor/distillation.ts

@@ -26,8 +26,8 @@ import {
   collectRoleIds,
   createEvolutionEvosCase,
   createEvolutionKnowledgeRecord,
-  createEvolutionRepoProposal,
   createPrivacyFields,
+  hasConcreteRepoProposalChanges,
   listDirectoryNames,
   parseEvosCase,
   parseKnowledgeRecord,
@@ -36,6 +36,7 @@ import {
   validateEvolutionDistillationBatch,
   validateEvolutionEvidenceWindow,
   validateEvolutionEvosCase,
+  validateEvolutionRepoProposal,
 } from "../shared.ts";
 import { chooseEvosTriggerKind, createTriggerSummary } from "../triggers/classification.ts";
 
@@ -97,10 +98,7 @@ export function createEvolutionDistillationBatch(input: {
           relations: {
             relatedKnowledgeIds: [],
             evosCaseIds: [createStableId("evo", [input.evidenceWindow.id, "case"])],
-            proposalIds:
-              failedSignals.length === 0
-                ? []
-                : [createStableId("proposal", [input.evidenceWindow.id, "engineering-practice"])],
+            proposalIds: [],
             supersedes: [],
           },
           privacy: createPrivacyFields(),
@@ -146,34 +144,9 @@ export function createEvolutionDistillationBatch(input: {
           }),
         ];
 
-  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(),
-          }),
-        ];
+  // Failure metadata is evidence, not a repository change proposal. A proposal is only valid
+  // after another stage supplies concrete target files and proposed changes.
+  const repoProposals: EvolutionRepoProposal[] = [];
 
   const batch: EvolutionDistillationBatch = {
     schemaVersion: 1,
@@ -302,6 +275,42 @@ export async function writeEvolutionDistillationBatch(input: {
   };
 }
 
+export async function writeEvolutionRepoProposal(input: {
+  homeDir: string;
+  proposal: EvolutionRepoProposal;
+}): Promise<{ proposalPath: string; indexPath: string }> {
+  validateEvolutionRepoProposal(input.proposal);
+  if (!hasConcreteRepoProposalChanges(input.proposal)) {
+    throw new Error("Repo proposal must include a target repository and concrete file changes.");
+  }
+  const paths = resolveEvolutionPaths({
+    homeDir: input.homeDir,
+    projectKey: input.proposal.projectKey,
+    runId: input.proposal.provenance.runId,
+  });
+  const proposalPath = join(paths.repoProposalsDir, `${input.proposal.id}.json`);
+  await writeJson(proposalPath, input.proposal, { overwrite: false });
+
+  const allRunProposals = await readJsonFiles(paths.repoProposalsDir, parseRepoProposal);
+  await writeJson(
+    paths.repoProposalsIndexPath,
+    {
+      schemaVersion: 1,
+      projectKey: input.proposal.projectKey,
+      runId: input.proposal.provenance.runId,
+      updatedAt: input.proposal.provenance.createdAt,
+      proposals: allRunProposals.map((proposal) => ({
+        id: proposal.id,
+        kind: proposal.kind,
+        title: proposal.title,
+        reviewState: proposal.reviewState,
+      })),
+    },
+    { overwrite: true },
+  );
+  return { proposalPath, indexPath: paths.repoProposalsIndexPath };
+}
+
 export async function activateEvolutionDistillationBatch(input: {
   homeDir: string;
   batch: EvolutionDistillationBatch;

package/src/evolution/processor/process.ts

@@ -1,22 +1,14 @@
 import { mkdir, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { resolveEvoDevPaths } from "../../config/paths.ts";
-import {
-  createStableId,
-  isFileExistsError,
-  normalizeTimestamp,
-  writeJsonFile as writeJson,
-} from "../../utils/index.ts";
+import { createStableId, isFileExistsError, normalizeTimestamp } from "../../utils/index.ts";
 import { analyzeEvolutionRun } from "../evidence/analysis.ts";
-import { resolveEvolutionPaths } from "../paths.ts";
 import type {
   EvolutionProcessInput,
   EvolutionProcessResult,
-  EvolutionReviewCandidate,
   EvolutionTriggerStatus,
-  SegmentEvolutionTriggerRecord,
 } from "../schema.ts";
-import { createPrivacyFields, sanitizeText, validateEvolutionReviewCandidate } from "../shared.ts";
+import { sanitizeText } from "../shared.ts";
 import {
   groupTriggersByRun,
   listEvolutionTriggers,
@@ -103,16 +95,11 @@ export async function processEvolutionTriggers(
         attempts: (current) => current.attempts + 1,
       });
       try {
-        await writeSegmentReviewCandidate({
-          homeDir: input.homeDir,
-          trigger,
-          now,
-        });
         result.consumed += 1;
         await updateSegmentTriggers(input.homeDir, [trigger], {
           status: "consumed",
           updatedAt: now,
-          processedBatchId: createStableId("segment-review", [trigger.id]),
+          processedBatchId: createStableId("segment-evidence", [trigger.id]),
           lastError: null,
         });
       } catch (error) {
@@ -246,61 +233,3 @@ async function acquireEvolutionProcessLock(
 async function releaseEvolutionProcessLock(lock: { path: string }): Promise<void> {
   await rm(lock.path, { force: true });
 }
-
-async function writeSegmentReviewCandidate(input: {
-  homeDir: string;
-  trigger: SegmentEvolutionTriggerRecord;
-  now: string;
-}): Promise<EvolutionReviewCandidate> {
-  const runId = input.trigger.runId ?? `session-${input.trigger.sessionKey}`;
-  const paths = resolveEvolutionPaths({
-    homeDir: input.homeDir,
-    projectKey: input.trigger.projectKey,
-    runId,
-  });
-  const candidate: EvolutionReviewCandidate = {
-    schemaVersion: 1,
-    kind: "evolution-review-candidate",
-    id: createStableId("review", [input.trigger.id]),
-    projectKey: input.trigger.projectKey,
-    runId: paths.runId,
-    createdAt: input.now,
-    candidateKind: "session-memory-segment",
-    title: sanitizeText(`Review session segment ${input.trigger.reason}`),
-    targetStore: "session-memory-segments",
-    targetPath: input.trigger.segmentPath,
-    stableKey: createStableId("segment-candidate", [
-      input.trigger.projectKey,
-      input.trigger.sessionKey,
-      input.trigger.segmentId,
-    ]),
-    reviewState: "needs-human",
-    reasons: [input.trigger.reason, input.trigger.strength],
-    candidate: {
-      segmentId: input.trigger.segmentId,
-      sessionKey: input.trigger.sessionKey,
-      roleId: input.trigger.roleId,
-      summary: input.trigger.summary,
-      reviewAction:
-        "Open the referenced local session segment for raw evidence before approving memory or OKF changes.",
-      directOkfWrite: false,
-      localOnly: true,
-    },
-    provenance: {
-      runId: paths.runId,
-      evidenceWindowId: input.trigger.segmentId,
-      evidenceRefs: [input.trigger.id, input.trigger.segmentId],
-      createdBy: "evodev",
-      rawLogsStored: false,
-      rawPromptsStored: false,
-      sourceDumpsStored: false,
-      rawCommandOutputStored: false,
-    },
-    privacy: createPrivacyFields(),
-  };
-  validateEvolutionReviewCandidate(candidate);
-  await writeJson(join(paths.reviewCandidatesDir, `${candidate.id}.json`), candidate, {
-    overwrite: true,
-  });
-  return candidate;
-}

package/src/evolution/schema.ts

@@ -278,6 +278,19 @@ export interface EvolutionKnowledgeRecord {
   };
 }
 
+export interface EvolutionKnowledgeReviewHistoryRecord {
+  version: 1;
+  kind: "evolution-knowledge-review-state-changed";
+  knowledgeId: string;
+  projectKey: string;
+  roleTags: string[];
+  artifactCreatedAt: string;
+  previousReviewState: EvolutionReviewState;
+  nextReviewState: EvolutionReviewState;
+  changedAt: string;
+  metadataOnly: true;
+}
+
 export interface EvolutionEvosCase {
   schemaVersion: 1;
   id: string;
@@ -327,13 +340,20 @@ export interface EvolutionRepoProposal {
   roleTags: string[];
   tags: string[];
   reviewState: "pending" | "accepted" | "rejected" | "deferred" | "applied";
+  reviewStateChangedAt?: string;
   confidence: EvolutionConfidence;
   targetRepoPath: string | null;
   plannedFiles: Array<{
     relativePath: string;
     action: "create" | "update";
     reason: string;
+    proposedChange?: string;
   }>;
+  lastDecision?: {
+    state: "accepted" | "rejected" | "deferred";
+    reason: string | null;
+    decidedAt: string;
+  };
   apply: {
     autoApply: false;
     requiresExplicitCommand: true;
@@ -366,7 +386,8 @@ export interface EvolutionReviewCandidate {
   targetStore: string;
   targetPath: string;
   stableKey: string;
-  reviewState: "needs-human";
+  reviewState: "needs-human" | "accepted" | "rejected" | "deferred";
+  reviewStateChangedAt?: string;
   reasons: string[];
   candidate: unknown;
   provenance: {
@@ -455,6 +476,7 @@ export interface EvolutionResolvedPaths {
   knowledgeProjectDir: string;
   knowledgeRecordsDir: string;
   knowledgeIndexPath: string;
+  knowledgeReviewHistoryPath: string;
   evosCasesProjectDir: string;
   evosIndexPath: string;
 }

package/src/evolution/shared.ts

@@ -27,6 +27,7 @@ import type {
 
 export const MAX_EVIDENCE_EVENTS = 200;
 export const MAX_TEXT_LENGTH = 600;
+export const MAX_PROPOSED_CHANGE_LENGTH = 16 * 1024;
 export const PROCESS_LOCK_STALE_MS = 5 * 60 * 1000;
 export const REVIEW_STATES: readonly EvolutionReviewState[] = [
   "auto-accepted",
@@ -330,6 +331,9 @@ export function createEvolutionRepoProposal(
       relativePath: sanitizeRelativePath(file.relativePath),
       action: file.action,
       reason: sanitizeText(file.reason),
+      ...(file.proposedChange === undefined
+        ? {}
+        : { proposedChange: sanitizeProposedChange(file.proposedChange) }),
     })),
   };
   validateEvolutionRepoProposal(proposal);
@@ -357,6 +361,33 @@ export function validateEvolutionRepoProposal(proposal: EvolutionRepoProposal):
     "deferred",
     "applied",
   ]);
+  if (
+    proposal.reviewStateChangedAt !== undefined &&
+    Number.isNaN(new Date(proposal.reviewStateChangedAt).getTime())
+  ) {
+    throw new Error("Repo proposal reviewStateChangedAt must be a valid timestamp.");
+  }
+  for (const file of proposal.plannedFiles) {
+    if (file.proposedChange !== undefined && file.proposedChange.trim() === "") {
+      throw new Error("Repo proposal proposedChange must not be empty.");
+    }
+  }
+  if (proposal.lastDecision !== undefined) {
+    assertEnum("lastDecision.state", proposal.lastDecision.state, [
+      "accepted",
+      "rejected",
+      "deferred",
+    ]);
+    if (
+      proposal.lastDecision.reason !== null &&
+      (proposal.lastDecision.reason.trim() === "" || proposal.lastDecision.reason.length > 500)
+    ) {
+      throw new Error("Repo proposal decision reason must be 1-500 characters.");
+    }
+    if (Number.isNaN(new Date(proposal.lastDecision.decidedAt).getTime())) {
+      throw new Error("Repo proposal decision timestamp must be valid.");
+    }
+  }
   if (proposal.apply.autoApply !== false || proposal.apply.requiresExplicitCommand !== true) {
     throw new Error("Repo proposal must require explicit apply.");
   }
@@ -365,6 +396,17 @@ export function validateEvolutionRepoProposal(proposal: EvolutionRepoProposal):
   assertNoForbiddenRawFields(proposal);
 }
 
+export function hasConcreteRepoProposalChanges(proposal: EvolutionRepoProposal): boolean {
+  return (
+    proposal.targetRepoPath !== null &&
+    proposal.targetRepoPath.trim() !== "" &&
+    proposal.plannedFiles.length > 0 &&
+    proposal.plannedFiles.every(
+      (file) => file.proposedChange !== undefined && file.proposedChange.trim() !== "",
+    )
+  );
+}
+
 export function validateEvolutionReviewCandidate(candidate: EvolutionReviewCandidate): void {
   if (!isRecord(candidate)) throw new Error("Review candidate must be an object.");
   if (candidate.schemaVersion !== 1) {
@@ -382,8 +424,17 @@ export function validateEvolutionReviewCandidate(candidate: EvolutionReviewCandi
   assertString("reviewCandidate.targetStore", candidate.targetStore);
   assertString("reviewCandidate.targetPath", candidate.targetPath);
   assertString("reviewCandidate.stableKey", candidate.stableKey);
-  if (candidate.reviewState !== "needs-human") {
-    throw new Error("Review candidate reviewState must be needs-human.");
+  assertEnum("reviewCandidate.reviewState", candidate.reviewState, [
+    "needs-human",
+    "accepted",
+    "rejected",
+    "deferred",
+  ]);
+  if (
+    candidate.reviewStateChangedAt !== undefined &&
+    Number.isNaN(new Date(candidate.reviewStateChangedAt).getTime())
+  ) {
+    throw new Error("Review candidate reviewStateChangedAt must be a valid timestamp.");
   }
   if (!Array.isArray(candidate.reasons))
     throw new Error("Review candidate reasons must be an array.");
@@ -616,6 +667,15 @@ export function sanitizeText(value: string): string {
     .slice(0, MAX_TEXT_LENGTH);
 }
 
+export function sanitizeProposedChange(value: string): string {
+  return value
+    .replace(SENSITIVE_TEXT_REPLACE_PATTERN, "[redacted]")
+    .replaceAll("\r\n", "\n")
+    .replaceAll("\r", "\n")
+    .trim()
+    .slice(0, MAX_PROPOSED_CHANGE_LENGTH);
+}
+
 export function sanitizeId(value: string): string {
   return (
     value