feat(history): record evidence-backed terminal outcomes

Author: root

universal-refiner/src/core/blackboard.ts

@@ -36,7 +36,10 @@ export class AgenticBlackboard {
   private static listeners: Array<() => void> = [];
 
   private static getGlobalDir(): string {
-    return process.env.PROMPT_REFINER_GLOBAL_DIR || path.join(os.homedir(), ".refiner");
+    return process.env.PROMPT_REFINER_GLOBAL_DIR
+      || (process.env.PROMPT_REFINER_PROJECT_DIR
+        ? path.join(process.env.PROMPT_REFINER_PROJECT_DIR, ".global-refiner")
+        : path.join(os.homedir(), ".refiner"));
   }
 
   private static getGlobalLogPath(): string {
@@ -60,7 +63,10 @@ export class AgenticBlackboard {
   }
 
   private static getStoragePath(rootPath: string): string {
-    const projectRoot = this.findProjectRoot(rootPath);
+    const effectiveRoot = rootPath === "."
+      ? process.env.PROMPT_REFINER_PROJECT_DIR || rootPath
+      : rootPath;
+    const projectRoot = this.findProjectRoot(effectiveRoot);
     return path.join(projectRoot, this.DOT_REFINER, this.STORAGE_NAME);
   }
 

universal-refiner/src/core/ports.ts

@@ -0,0 +1,11 @@
+const DEFAULT_DASHBOARD_PORT = 3000;
+
+export function resolveDashboardPort(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env.PROMPT_REFINER_DASHBOARD_PORT || env.PORT;
+  if (!raw) return DEFAULT_DASHBOARD_PORT;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535) {
+    throw new Error(`Invalid dashboard port: ${raw}`);
+  }
+  return parsed;
+}

universal-refiner/src/history/event-store.ts

@@ -181,6 +181,52 @@ export class EventStore {
     );
   }
 
+  recordTerminalOutcome(outcome: {
+    goal_id: string;
+    repo_id?: string;
+    status: "completed" | "failed" | "cancelled" | "blocked" | "budget_exhausted";
+    evidence: string[];
+    summary: string;
+    candidate?: {
+      id: string;
+      lesson_type: string;
+      title: string;
+      summary: string;
+      confidence: string;
+    };
+  }): boolean {
+    if (!outcome.goal_id.trim() || !outcome.summary.trim() || outcome.evidence.length === 0) {
+      throw new Error("Terminal outcomes require goal id, summary, and evidence.");
+    }
+    const now = new Date().toISOString();
+    const transaction = this.db.transaction(() => {
+      const inserted = this.db.prepare(`
+        INSERT OR IGNORE INTO terminal_outcomes (goal_id, repo_id, status, evidence_json, summary, created_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(outcome.goal_id, outcome.repo_id || null, outcome.status, JSON.stringify(outcome.evidence), outcome.summary, now);
+      if (inserted.changes === 0) return false;
+      if (outcome.candidate) {
+        this.recordLesson({
+          id: outcome.candidate.id,
+          repo_id: outcome.repo_id,
+          lesson_type: outcome.candidate.lesson_type,
+          title: outcome.candidate.title,
+          summary: outcome.candidate.summary,
+          evidence_json: JSON.stringify(outcome.evidence),
+          confidence: outcome.candidate.confidence,
+          source: "terminal_outcome",
+          approved: 0,
+        });
+      }
+      return true;
+    });
+    return transaction();
+  }
+
+  getTerminalOutcome(goalId: string): any | undefined {
+    return this.db.prepare(`SELECT * FROM terminal_outcomes WHERE goal_id = ?`).get(goalId);
+  }
+
   linkCommitToExecution(executionId: string, commitId: string) {
     const stmt = this.db.prepare(`
       INSERT OR IGNORE INTO execution_commits (execution_id, commit_id)

universal-refiner/src/history/schema.ts

@@ -56,6 +56,15 @@ CREATE TABLE IF NOT EXISTS executions (
   artifacts_json TEXT NOT NULL DEFAULT '{}'
 );
 
+CREATE TABLE IF NOT EXISTS terminal_outcomes (
+  goal_id TEXT PRIMARY KEY,
+  repo_id TEXT,
+  status TEXT NOT NULL,
+  evidence_json TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
 CREATE TABLE IF NOT EXISTS tests (
   id TEXT PRIMARY KEY,
   execution_id TEXT NOT NULL,

universal-refiner/tests/history.test.ts

@@ -120,6 +120,33 @@ describe("EventStore", () => {
     expect(store.getRecentLessons("repo").map(lesson => lesson.id)).toEqual(["approved"]);
   });
 
+  it("records one terminal outcome and gates its lesson candidate on approval", () => {
+    const store = EventStore.getInstance();
+    const outcome = {
+      goal_id: "goal-1",
+      repo_id: "repo",
+      status: "completed" as const,
+      evidence: ["cas://evidence/verification/1"],
+      summary: "All mandatory checks passed.",
+      candidate: {
+        id: "lesson-goal-1",
+        lesson_type: "quality",
+        title: "Candidate lesson",
+        summary: "Preserve deterministic verification.",
+        confidence: "high",
+      },
+    };
+
+    expect(store.recordTerminalOutcome(outcome)).toBe(true);
+    expect(store.recordTerminalOutcome(outcome)).toBe(false);
+    expect(store.getTerminalOutcome("goal-1").status).toBe("completed");
+    expect(store.getLearningCandidates("repo").lessons.map(lesson => lesson.id)).toEqual(["lesson-goal-1"]);
+    expect(store.getRecentLessons("repo")).toEqual([]);
+
+    expect(store.reviewLesson("repo", "lesson-goal-1", true)).toBe(true);
+    expect(store.getRecentLessons("repo").map(lesson => lesson.id)).toContain("lesson-goal-1");
+  });
+
   it("should persist learning candidate approval and rejection", () => {
     const store = EventStore.getInstance();
     store.recordLesson({

universal-refiner/tests/setup.ts

@@ -0,0 +1,10 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+const isolationRoot = fs.mkdtempSync(path.join(os.tmpdir(), "prompt-refiner-tests-"));
+const projectRoot = path.join(isolationRoot, "project");
+
+fs.mkdirSync(path.join(projectRoot, ".refiner"), { recursive: true });
+process.env.PROMPT_REFINER_PROJECT_DIR = projectRoot;
+process.env.PROMPT_REFINER_GLOBAL_DIR = path.join(isolationRoot, "global");

universal-refiner/vitest.config.ts

@@ -2,6 +2,8 @@ import { defineConfig } from "vitest/config";
 
 export default defineConfig({
   test: {
+    exclude: ["node_modules/**", "dist/**", "tests/e2e/**"],
+    setupFiles: ["./tests/setup.ts"],
     coverage: {
       provider: "v8",
       include: ["hooks/lib/**/*.ts", "src/**/*.ts"],