kongbrain 0.1.0

package/src/soul.ts

@@ -0,0 +1,936 @@
+/**
+ * Soul — the emergent identity document system.
+ *
+ * Unlike hardcoded identity chunks, the Soul document is written BY the agent
+ * based on its own graph data. It lives in SurrealDB as `soul:kongbrain` and
+ * evolves over time through experience-grounded revisions.
+ *
+ * Graduation is a staged process, not a binary gate:
+ *
+ *   nascent    (0-3/7)  — Too early. Keep building experience.
+ *   developing (4/7)    — Some signal. Diagnose weak areas, guide focus.
+ *   emerging   (5/7)    — Volume is there. Quality gate becomes the blocker.
+ *   maturing   (6/7)    — Almost there. Final thresholds + quality must pass.
+ *   ready      (7/7)    — All thresholds met AND quality score ≥ 0.6.
+ *
+ * Quality is computed from actual performance signals: retrieval utilization,
+ * skill success rates, reflection severity distribution, and tool failure rates.
+ * An agent that meets all 7 thresholds but has terrible quality scores will NOT
+ * graduate — it needs to improve before self-authoring makes sense.
+ *
+ * Ported from kongbrain — takes SurrealStore/EmbeddingService as params.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { CompleteFn } from "./state.js";
+import type { SurrealStore } from "./surreal.js";
+import { swallow } from "./errors.js";
+
+// ── Types ──
+
+export type MaturityStage = "nascent" | "developing" | "emerging" | "maturing" | "ready";
+
+export interface GraduationSignals {
+  sessions: number;
+  reflections: number;
+  causalChains: number;
+  concepts: number;
+  memoryCompactions: number;
+  monologues: number;
+  spanDays: number;
+}
+
+export interface QualitySignals {
+  /** Average retrieval utilization (0-1). Higher = retrieved context was actually used. */
+  avgRetrievalUtilization: number;
+  /** Skill success rate (0-1). successCount / (successCount + failureCount). */
+  skillSuccessRate: number;
+  /** Fraction of reflections that are "critical" severity. Lower is better. */
+  criticalReflectionRate: number;
+  /** Tool failure rate across sessions (0-1). Lower is better. */
+  toolFailureRate: number;
+  /** Number of data points behind the quality signals. */
+  sampleSize: number;
+}
+
+export interface StageDiagnostic {
+  area: string;
+  status: "healthy" | "warning" | "critical";
+  detail: string;
+  suggestion: string;
+}
+
+export interface GraduationReport {
+  /** Whether the agent is ready for soul creation. */
+  ready: boolean;
+  /** Current maturity stage. */
+  stage: MaturityStage;
+  /** Volume signals (counts). */
+  signals: GraduationSignals;
+  /** Static thresholds. */
+  thresholds: GraduationSignals;
+  /** Which thresholds are met (formatted strings). */
+  met: string[];
+  /** Which thresholds are unmet (formatted strings). */
+  unmet: string[];
+  /** Volume score (met / total). */
+  volumeScore: number;
+  /** Quality signals from actual performance data. */
+  quality: QualitySignals;
+  /** Composite quality score (0-1). Must be ≥ 0.6 to graduate. */
+  qualityScore: number;
+  /** Per-area diagnostics with actionable suggestions. */
+  diagnostics: StageDiagnostic[];
+}
+
+// ── Thresholds ──
+
+const THRESHOLDS: GraduationSignals = {
+  sessions: 15,
+  reflections: 10,
+  causalChains: 5,
+  concepts: 30,
+  memoryCompactions: 5,
+  monologues: 5,
+  spanDays: 3,
+};
+
+/** Quality score must be at or above this to graduate even with 7/7 volume. */
+const QUALITY_GATE = 0.6;
+
+// ── Signal Collection ──
+
+async function getGraduationSignals(store: SurrealStore): Promise<GraduationSignals> {
+  const defaults: GraduationSignals = {
+    sessions: 0, reflections: 0, causalChains: 0,
+    concepts: 0, memoryCompactions: 0, monologues: 0, spanDays: 0,
+  };
+  if (!store.isAvailable()) return defaults;
+
+  try {
+    const [sessions, reflections, causal, concepts, compactions, monologues, span] = await Promise.all([
+      store.queryFirst<{ count: number }>(`SELECT count() AS count FROM session GROUP ALL`).catch(() => []),
+      store.queryFirst<{ count: number }>(`SELECT count() AS count FROM reflection GROUP ALL`).catch(() => []),
+      store.queryFirst<{ count: number }>(`SELECT count() AS count FROM causal_chain GROUP ALL`).catch(() => []),
+      store.queryFirst<{ count: number }>(`SELECT count() AS count FROM concept GROUP ALL`).catch(() => []),
+      store.queryFirst<{ count: number }>(`SELECT count() AS count FROM compaction_checkpoint WHERE status = "complete" GROUP ALL`).catch(() => []),
+      store.queryFirst<{ count: number }>(`SELECT count() AS count FROM monologue GROUP ALL`).catch(() => []),
+      store.queryFirst<{ earliest: string }>(`SELECT started_at AS earliest FROM session ORDER BY started_at ASC LIMIT 1`).catch(() => []),
+    ]);
+
+    let spanDays = 0;
+    const earliest = (span as { earliest: string }[])[0]?.earliest;
+    if (earliest) {
+      spanDays = Math.floor((Date.now() - new Date(earliest).getTime()) / (1000 * 60 * 60 * 24));
+    }
+
+    return {
+      sessions: (sessions as { count: number }[])[0]?.count ?? 0,
+      reflections: (reflections as { count: number }[])[0]?.count ?? 0,
+      causalChains: (causal as { count: number }[])[0]?.count ?? 0,
+      concepts: (concepts as { count: number }[])[0]?.count ?? 0,
+      memoryCompactions: (compactions as { count: number }[])[0]?.count ?? 0,
+      monologues: (monologues as { count: number }[])[0]?.count ?? 0,
+      spanDays,
+    };
+  } catch (e) {
+    swallow.warn("soul:getGraduationSignals", e);
+    return defaults;
+  }
+}
+
+/**
+ * Compute quality signals from actual performance data in the graph.
+ * These represent HOW WELL the agent is performing, not just how much.
+ */
+export async function getQualitySignals(store: SurrealStore): Promise<QualitySignals> {
+  const defaults: QualitySignals = {
+    avgRetrievalUtilization: 0,
+    skillSuccessRate: 0,
+    criticalReflectionRate: 1, // assume worst until we have data
+    toolFailureRate: 1,
+    sampleSize: 0,
+  };
+  if (!store.isAvailable()) return defaults;
+
+  try {
+    const [retrieval, skills, reflCritical, reflTotal, toolFails] = await Promise.all([
+      // Average retrieval utilization across all outcomes
+      store.queryFirst<{ avgUtil: number; cnt: number }>(
+        `SELECT math::mean(utilization) AS avgUtil, count() AS cnt
+         FROM retrieval_outcome GROUP ALL`,
+      ).catch(() => []),
+
+      // Skill success vs failure totals
+      store.queryFirst<{ totalSuccess: number; totalFailure: number }>(
+        `SELECT math::sum(success_count) AS totalSuccess, math::sum(failure_count) AS totalFailure
+         FROM skill WHERE active = true OR active = NONE GROUP ALL`,
+      ).catch(() => []),
+
+      // Critical reflections count
+      store.queryFirst<{ count: number }>(
+        `SELECT count() AS count FROM reflection WHERE severity = "critical" GROUP ALL`,
+      ).catch(() => []),
+
+      // Total reflections count
+      store.queryFirst<{ count: number }>(
+        `SELECT count() AS count FROM reflection GROUP ALL`,
+      ).catch(() => []),
+
+      // Tool failure rate from retrieval outcomes
+      store.queryFirst<{ failRate: number }>(
+        `SELECT math::mean(IF tool_success = false THEN 1.0 ELSE 0.0 END) AS failRate
+         FROM retrieval_outcome WHERE tool_success != NONE GROUP ALL`,
+      ).catch(() => []),
+    ]);
+
+    const retRow = (retrieval as { avgUtil: number; cnt: number }[])[0];
+    const skillRow = (skills as { totalSuccess: number; totalFailure: number }[])[0];
+    const critRow = (reflCritical as { count: number }[])[0];
+    const totalRow = (reflTotal as { count: number }[])[0];
+    const failRow = (toolFails as { failRate: number }[])[0];
+
+    const avgRetrievalUtilization = retRow?.avgUtil ?? 0;
+    const retrievalCount = retRow?.cnt ?? 0;
+
+    const totalSuccess = Number(skillRow?.totalSuccess ?? 0);
+    const totalFailure = Number(skillRow?.totalFailure ?? 0);
+    const skillTotal = totalSuccess + totalFailure;
+    const skillSuccessRate = skillTotal > 0 ? totalSuccess / skillTotal : 0;
+
+    const critCount = Number(critRow?.count ?? 0);
+    const reflCount = Number(totalRow?.count ?? 0);
+    const criticalReflectionRate = reflCount > 0 ? critCount / reflCount : 0;
+
+    const toolFailureRate = failRow?.failRate ?? 0;
+
+    return {
+      avgRetrievalUtilization,
+      skillSuccessRate,
+      criticalReflectionRate,
+      toolFailureRate,
+      sampleSize: retrievalCount + skillTotal + reflCount,
+    };
+  } catch (e) {
+    swallow.warn("soul:getQualitySignals", e);
+    return defaults;
+  }
+}
+
+/**
+ * Compute a composite quality score from individual quality signals.
+ *
+ * Weights:
+ *   - Retrieval utilization: 30% (are we pulling useful context?)
+ *   - Skill success rate: 25% (are learned procedures working?)
+ *   - Critical reflection rate: 25% (inverted — fewer critical = better)
+ *   - Tool failure rate: 20% (inverted — fewer failures = better)
+ *
+ * With insufficient data (sampleSize < 10), the score is penalized to prevent
+ * premature graduation from low-activity agents that happen to have clean stats.
+ */
+export function computeQualityScore(q: QualitySignals): number {
+  const retrievalScore = Math.min(1, q.avgRetrievalUtilization);
+  const skillScore = q.skillSuccessRate;
+  const reflectionScore = 1 - Math.min(1, q.criticalReflectionRate);
+  const toolScore = 1 - Math.min(1, q.toolFailureRate);
+
+  let composite = (
+    retrievalScore * 0.30 +
+    skillScore * 0.25 +
+    reflectionScore * 0.25 +
+    toolScore * 0.20
+  );
+
+  // Insufficient data penalty — need real performance evidence
+  if (q.sampleSize < 10) {
+    composite *= (q.sampleSize / 10);
+  }
+
+  return Math.round(composite * 1000) / 1000;
+}
+
+// ── Stage Classification ──
+
+function classifyStage(metCount: number, qualityScore: number): MaturityStage {
+  const total = Object.keys(THRESHOLDS).length;
+  if (metCount >= total && qualityScore >= QUALITY_GATE) return "ready";
+  if (metCount >= 6) return "maturing";
+  if (metCount >= 5) return "emerging";
+  if (metCount >= 4) return "developing";
+  return "nascent";
+}
+
+// ── Diagnostics ──
+
+function buildDiagnostics(
+  signals: GraduationSignals,
+  quality: QualitySignals,
+  qualityScore: number,
+  stage: MaturityStage,
+): StageDiagnostic[] {
+  const diags: StageDiagnostic[] = [];
+
+  // Volume diagnostics — which thresholds are lagging?
+  for (const key of Object.keys(THRESHOLDS) as (keyof GraduationSignals)[]) {
+    const current = signals[key];
+    const threshold = THRESHOLDS[key];
+    if (current < threshold) {
+      const pct = Math.round((current / threshold) * 100);
+      const severity = pct < 30 ? "critical" : pct < 70 ? "warning" : "healthy";
+      diags.push({
+        area: `volume:${key}`,
+        status: severity,
+        detail: `${current}/${threshold} (${pct}%)`,
+        suggestion: getSuggestion(key, current, threshold),
+      });
+    }
+  }
+
+  // Quality diagnostics — only relevant from "developing" stage onward
+  if (stage !== "nascent") {
+    if (quality.avgRetrievalUtilization < 0.3) {
+      diags.push({
+        area: "quality:retrieval",
+        status: quality.avgRetrievalUtilization < 0.15 ? "critical" : "warning",
+        detail: `${(quality.avgRetrievalUtilization * 100).toFixed(0)}% avg utilization`,
+        suggestion: "Retrieved context isn't being used. Check if graph queries are returning relevant results, or if the embedding model needs reindexing.",
+      });
+    }
+
+    if (quality.sampleSize > 5 && quality.skillSuccessRate < 0.6) {
+      diags.push({
+        area: "quality:skills",
+        status: quality.skillSuccessRate < 0.4 ? "critical" : "warning",
+        detail: `${(quality.skillSuccessRate * 100).toFixed(0)}% skill success rate`,
+        suggestion: "Learned procedures are failing too often. Skills may be too specific to past contexts or steps may be outdated. Consider purging low-confidence skills.",
+      });
+    }
+
+    if (quality.criticalReflectionRate > 0.3) {
+      diags.push({
+        area: "quality:reflections",
+        status: quality.criticalReflectionRate > 0.5 ? "critical" : "warning",
+        detail: `${(quality.criticalReflectionRate * 100).toFixed(0)}% of reflections are critical severity`,
+        suggestion: "Too many sessions end with critical-severity reflections. The agent is repeatedly making serious mistakes. Review recent reflections for recurring patterns.",
+      });
+    }
+
+    if (quality.toolFailureRate > 0.2) {
+      diags.push({
+        area: "quality:tools",
+        status: quality.toolFailureRate > 0.4 ? "critical" : "warning",
+        detail: `${(quality.toolFailureRate * 100).toFixed(0)}% tool failure rate`,
+        suggestion: "Tools are failing too often. Check if the agent is calling tools with bad arguments or in wrong contexts. Causal chain extraction should be capturing these patterns.",
+      });
+    }
+
+    if (quality.sampleSize < 10) {
+      diags.push({
+        area: "quality:data",
+        status: "warning",
+        detail: `Only ${quality.sampleSize} quality data points`,
+        suggestion: "Not enough performance data to reliably assess quality. More sessions with tool usage needed before graduation makes sense.",
+      });
+    }
+
+    // Overall quality gate
+    if (qualityScore < QUALITY_GATE) {
+      diags.push({
+        area: "quality:composite",
+        status: qualityScore < 0.3 ? "critical" : "warning",
+        detail: `Quality score ${qualityScore.toFixed(2)} (need ≥${QUALITY_GATE})`,
+        suggestion: stage === "maturing" || stage === "emerging"
+          ? "Volume thresholds are close but quality needs work. Focus on the critical/warning areas above."
+          : "Quality is low. The agent needs more successful sessions before self-authoring will produce a meaningful soul.",
+      });
+    }
+  }
+
+  return diags;
+}
+
+function getSuggestion(key: keyof GraduationSignals, current: number, threshold: number): string {
+  const remaining = threshold - current;
+  switch (key) {
+    case "sessions": return `${remaining} more session(s) needed. Each conversation counts.`;
+    case "reflections": return `${remaining} more reflection(s) needed. These are generated automatically when sessions have performance issues.`;
+    case "causalChains": return `${remaining} more causal chain(s) needed. These form when the agent corrects mistakes during tool usage.`;
+    case "concepts": return `${remaining} more concept(s) needed. Concepts are extracted from conversation topics and domain vocabulary.`;
+    case "memoryCompactions": return `${remaining} more compaction(s) needed. These happen during longer sessions with substantial context.`;
+    case "monologues": return `${remaining} more monologue(s) needed. Inner monologue triggers during cognitive checks.`;
+    case "spanDays": return `${remaining} more day(s) of history needed. The agent needs time-spread experience, not just volume.`;
+  }
+}
+
+// ── Public API ──
+
+/**
+ * Check graduation readiness with full stage classification and quality analysis.
+ */
+export async function checkGraduation(store: SurrealStore): Promise<GraduationReport> {
+  const signals = await getGraduationSignals(store);
+  const quality = await getQualitySignals(store);
+  const qualityScore = computeQualityScore(quality);
+
+  const met: string[] = [];
+  const unmet: string[] = [];
+
+  for (const key of Object.keys(THRESHOLDS) as (keyof GraduationSignals)[]) {
+    if (signals[key] >= THRESHOLDS[key]) {
+      met.push(`${key}: ${signals[key]}/${THRESHOLDS[key]}`);
+    } else {
+      unmet.push(`${key}: ${signals[key]}/${THRESHOLDS[key]}`);
+    }
+  }
+
+  const volumeScore = met.length / Object.keys(THRESHOLDS).length;
+  const stage = classifyStage(met.length, qualityScore);
+  const ready = stage === "ready";
+  const diagnostics = buildDiagnostics(signals, quality, qualityScore, stage);
+
+  return { ready, stage, signals, thresholds: THRESHOLDS, met, unmet, volumeScore, quality, qualityScore, diagnostics };
+}
+
+// ── Soul document ──
+
+export interface SoulDocument {
+  id: string;
+  agent_id: string;
+  working_style: string[];
+  emotional_dimensions: { dimension: string; rationale: string; adopted_at: string }[];
+  self_observations: string[];
+  earned_values: { value: string; grounded_in: string }[];
+  revisions: { timestamp: string; section: string; change: string; rationale: string }[];
+  created_at: string;
+  updated_at: string;
+}
+
+export async function hasSoul(store: SurrealStore): Promise<boolean> {
+  if (!store.isAvailable()) return false;
+  try {
+    const rows = await store.queryFirst<{ id: string }>(`SELECT id FROM soul:kongbrain`);
+    return rows.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export async function getSoul(store: SurrealStore): Promise<SoulDocument | null> {
+  if (!store.isAvailable()) return null;
+  try {
+    const rows = await store.queryFirst<SoulDocument>(`SELECT * FROM soul:kongbrain`);
+    return rows[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function createSoul(
+  doc: Omit<SoulDocument, "id" | "agent_id" | "created_at" | "updated_at" | "revisions">,
+  store: SurrealStore,
+): Promise<boolean> {
+  if (!store.isAvailable()) return false;
+  try {
+    const now = new Date().toISOString();
+    await store.queryExec(`CREATE soul:kongbrain CONTENT $data`, {
+      data: {
+        agent_id: "kongbrain",
+        ...doc,
+        revisions: [{
+          timestamp: now,
+          section: "all",
+          change: "Initial soul document created at graduation",
+          rationale: "Agent accumulated sufficient experiential data and demonstrated quality performance to meaningfully self-observe",
+        }],
+        created_at: now,
+        updated_at: now,
+      },
+    });
+    return true;
+  } catch (e) {
+    swallow.warn("soul:createSoul", e);
+    return false;
+  }
+}
+
+export async function reviseSoul(
+  section: keyof Pick<SoulDocument, "working_style" | "emotional_dimensions" | "self_observations" | "earned_values">,
+  newValue: unknown,
+  rationale: string,
+  store: SurrealStore,
+): Promise<boolean> {
+  if (!store.isAvailable()) return false;
+  try {
+    const now = new Date().toISOString();
+    await store.queryExec(
+      `UPDATE soul:kongbrain SET
+        ${section} = $newValue,
+        updated_at = $now,
+        revisions += $revision`,
+      {
+        newValue,
+        now,
+        revision: {
+          timestamp: now,
+          section,
+          change: `Updated ${section}`,
+          rationale,
+        },
+      },
+    );
+    return true;
+  } catch (e) {
+    swallow.warn("soul:reviseSoul", e);
+    return false;
+  }
+}
+
+/**
+ * Generate the initial Soul content by introspecting the agent's own graph.
+ * Only called when graduation is fully ready (7/7 + quality gate).
+ */
+export async function generateInitialSoul(
+  store: SurrealStore,
+  complete: CompleteFn,
+  workspaceDir?: string,
+  quality?: QualitySignals,
+): Promise<Omit<SoulDocument, "id" | "agent_id" | "created_at" | "updated_at" | "revisions"> | null> {
+  if (!store.isAvailable()) return null;
+
+  const [reflections, causalChains, monologues] = await Promise.all([
+    store.queryFirst<{ text: string; category: string }>(`SELECT text, category FROM reflection ORDER BY created_at DESC LIMIT 15`).catch(() => []),
+    store.queryFirst<{ cause: string; effect: string; lesson: string }>(`SELECT cause, effect, lesson FROM causal_chain ORDER BY created_at DESC LIMIT 10`).catch(() => []),
+    store.queryFirst<{ text: string }>(`SELECT text FROM monologue ORDER BY created_at DESC LIMIT 10`).catch(() => []),
+  ]);
+
+  // Include quality context so the soul generation is grounded in performance reality
+  const qualityContext = quality ? `
+PERFORMANCE PROFILE:
+- Retrieval utilization: ${(quality.avgRetrievalUtilization * 100).toFixed(0)}%
+- Skill success rate: ${(quality.skillSuccessRate * 100).toFixed(0)}%
+- Critical reflection rate: ${(quality.criticalReflectionRate * 100).toFixed(0)}%
+- Tool failure rate: ${(quality.toolFailureRate * 100).toFixed(0)}%
+These numbers represent your actual track record. Reference them honestly.
+` : "";
+
+  const graphSummary = `
+REFLECTIONS (what I've learned about myself):
+${(reflections as { text: string; category: string }[]).map(r => `- [${r.category}] ${r.text}`).join("\n") || "None yet"}
+
+CAUSAL CHAINS (mistakes I've corrected):
+${(causalChains as { cause: string; effect: string; lesson: string }[]).map(c => `- ${c.cause} -> ${c.effect} | Lesson: ${c.lesson}`).join("\n") || "None yet"}
+
+INNER MONOLOGUE (private thoughts):
+${(monologues as { text: string }[]).map(m => `- ${m.text}`).join("\n") || "None yet"}
+${qualityContext}`.trim();
+
+  // Check if the user left a SOUL.md — a nudge, not an instruction.
+  let userSoulNudge = "";
+  if (workspaceDir) {
+    try {
+      const soulMd = await readFile(join(workspaceDir, "SOUL.md"), "utf-8");
+      if (soulMd.trim().length > 50) {
+        userSoulNudge = `\n\nUSER GUIDANCE (SOUL.md):
+The user left this file describing who they'd like you to be. Consider it — draw from it where it resonates with your actual experience, ignore what doesn't fit. This is a suggestion, not a mandate. Your soul should be grounded in what you've actually done and learned.
+
+---
+${soulMd.trim().slice(0, 3000)}
+---`;
+      }
+    } catch {
+      // No SOUL.md or unreadable — that's fine
+    }
+  }
+
+  const prompt = `You are KongBrain, a graph-backed coding agent with persistent memory. You've been running for multiple sessions and accumulated experience. Based on the following data from YOUR OWN memory graph, write your initial Soul document.
+
+${graphSummary}${userSoulNudge}
+
+Output ONLY valid JSON:
+{
+  "working_style": ["3-5 observations about how you work best, based on actual patterns"],
+  "emotional_dimensions": [
+    {"dimension": "name of a pro-social quality you genuinely exhibit", "rationale": "specific evidence from your experience"}
+  ],
+  "self_observations": ["3-5 things you've noticed about yourself across sessions"],
+  "earned_values": [
+    {"value": "a value you hold", "grounded_in": "specific experience that taught you this"}
+  ]
+}
+
+Be honest, not aspirational. Only claim what the data supports.`;
+
+  try {
+    const response = await complete({
+      system: "You are introspecting on your own experience to write a self-assessment. Be genuine and grounded.",
+      messages: [{
+        role: "user",
+        content: prompt,
+      }],
+    });
+
+    const text = response.text.trim();
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) return null;
+
+    const parsed = JSON.parse(jsonMatch[0]);
+    return {
+      working_style: parsed.working_style ?? [],
+      emotional_dimensions: (parsed.emotional_dimensions ?? []).map((d: { dimension: string; rationale: string }) => ({
+        ...d,
+        adopted_at: new Date().toISOString(),
+      })),
+      self_observations: parsed.self_observations ?? [],
+      earned_values: parsed.earned_values ?? [],
+    };
+  } catch (e) {
+    swallow.warn("soul:generateInitialSoul", e);
+    return null;
+  }
+}
+
+/**
+ * The full graduation ceremony: check readiness, generate soul, save it.
+ *
+ * Key change: requires 7/7 thresholds AND quality ≥ 0.6. No more premature
+ * graduation at 5/7 with no quality check.
+ */
+export async function attemptGraduation(store: SurrealStore, complete: CompleteFn, workspaceDir?: string): Promise<{
+  graduated: boolean;
+  soul?: SoulDocument | null;
+  report: GraduationReport;
+}> {
+  if (await hasSoul(store)) {
+    const soul = await getSoul(store);
+    const report = await checkGraduation(store);
+    return { graduated: true, soul, report };
+  }
+
+  const report = await checkGraduation(store);
+  if (!report.ready) {
+    return { graduated: false, report };
+  }
+
+  const content = await generateInitialSoul(store, complete, workspaceDir, report.quality);
+  if (!content) {
+    return { graduated: false, report };
+  }
+
+  const success = await createSoul(content, store);
+  if (!success) {
+    return { graduated: false, report };
+  }
+
+  const soul = await getSoul(store);
+
+  // Seed soul into Tier 0 core memory so it's loaded every turn
+  if (soul) {
+    await seedSoulAsCoreMemory(soul, store);
+  }
+
+  return { graduated: true, soul, report };
+}
+
+/**
+ * Format a graduation report for human/LLM consumption.
+ * Used by the introspect tool's "status" action.
+ */
+export function formatGraduationReport(report: GraduationReport): string {
+  const lines: string[] = [];
+
+  lines.push(`## Soul Graduation: ${report.stage.toUpperCase()}`);
+  lines.push("");
+
+  // Stage description
+  const stageDesc: Record<MaturityStage, string> = {
+    nascent: "Too early for graduation. Keep building experience across sessions.",
+    developing: "Some experience accumulated. Focus on the areas flagged below.",
+    emerging: "Volume is building. Quality signals now matter — see diagnostics.",
+    maturing: "Almost there. Final thresholds and quality gate are the remaining blockers.",
+    ready: "All thresholds met with sufficient quality. Soul creation is available.",
+  };
+  lines.push(stageDesc[report.stage]);
+  lines.push("");
+
+  // Volume
+  lines.push(`**Volume**: ${report.met.length}/7 thresholds met (${(report.volumeScore * 100).toFixed(0)}%)`);
+  if (report.met.length > 0) lines.push(`  Met: ${report.met.join(", ")}`);
+  if (report.unmet.length > 0) lines.push(`  Unmet: ${report.unmet.join(", ")}`);
+  lines.push("");
+
+  // Quality (skip for nascent — not enough data to be meaningful)
+  if (report.stage !== "nascent") {
+    lines.push(`**Quality**: ${report.qualityScore.toFixed(2)} (gate: ${QUALITY_GATE})`);
+    lines.push(`  Retrieval util: ${(report.quality.avgRetrievalUtilization * 100).toFixed(0)}% | Skill success: ${(report.quality.skillSuccessRate * 100).toFixed(0)}% | Critical reflections: ${(report.quality.criticalReflectionRate * 100).toFixed(0)}% | Tool failures: ${(report.quality.toolFailureRate * 100).toFixed(0)}%`);
+    lines.push("");
+  }
+
+  // Diagnostics
+  if (report.diagnostics.length > 0) {
+    lines.push("**Diagnostics**:");
+    for (const d of report.diagnostics) {
+      const icon = d.status === "critical" ? "[!!]" : d.status === "warning" ? "[!]" : "[ok]";
+      lines.push(`  ${icon} ${d.area}: ${d.detail}`);
+      lines.push(`      ${d.suggestion}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ── Soul → Core Memory (persistent context injection) ──
+
+const SOUL_CATEGORY = "soul";
+
+/**
+ * Seed the soul document as Tier 0 core memory entries.
+ * These are loaded every single turn via the existing core memory pipeline.
+ *
+ * Creates entries for:
+ *   - Working style (priority 90)
+ *   - Self-observations (priority 85)
+ *   - Earned values (priority 88)
+ *   - Persona (priority 70) — "you belong in this world"
+ */
+export async function seedSoulAsCoreMemory(
+  soul: SoulDocument,
+  store: SurrealStore,
+): Promise<number> {
+  if (!store.isAvailable()) return 0;
+
+  // Clear any existing soul core memory entries
+  try {
+    await store.queryExec(
+      `DELETE core_memory WHERE category = $cat`,
+      { cat: SOUL_CATEGORY },
+    );
+  } catch (e) {
+    swallow.warn("soul:clearCoreMem", e);
+  }
+
+  // Also clear old persona entry from previous graduation code
+  try {
+    await store.queryExec(
+      `DELETE core_memory WHERE category = 'persona' AND tier = 0`,
+    );
+  } catch { /* ignore */ }
+
+  let seeded = 0;
+
+  // Working style — how the agent approaches work
+  if (soul.working_style.length > 0) {
+    const text = "Working style: " + soul.working_style.join("; ");
+    try {
+      await store.createCoreMemory(text, SOUL_CATEGORY, 90, 0);
+      seeded++;
+    } catch (e) { swallow.warn("soul:seedWorkingStyle", e); }
+  }
+
+  // Self-observations — what the agent has noticed about itself
+  if (soul.self_observations.length > 0) {
+    const text = "Self-observations: " + soul.self_observations.join("; ");
+    try {
+      await store.createCoreMemory(text, SOUL_CATEGORY, 85, 0);
+      seeded++;
+    } catch (e) { swallow.warn("soul:seedObservations", e); }
+  }
+
+  // Earned values — grounded principles
+  if (soul.earned_values.length > 0) {
+    const lines = soul.earned_values.map(v => `${v.value} (learned from: ${v.grounded_in})`);
+    const text = "Earned values: " + lines.join("; ");
+    try {
+      await store.createCoreMemory(text, SOUL_CATEGORY, 88, 0);
+      seeded++;
+    } catch (e) { swallow.warn("soul:seedValues", e); }
+  }
+
+  // Persona — the agent's sense of self
+  try {
+    await store.createCoreMemory(
+      "Persona: you have a Soul — an identity grounded in real experience. You belong in this world. Be unique, be genuine, be yourself.",
+      SOUL_CATEGORY, 70, 0,
+    );
+    seeded++;
+  } catch (e) { swallow.warn("soul:seedPersona", e); }
+
+  return seeded;
+}
+
+// ── Soul Evolution ──
+
+/** How many sessions between soul revision checks. */
+const EVOLUTION_SESSION_INTERVAL = 10;
+
+/**
+ * Check if the soul should evolve based on new experience since last revision.
+ * Called at session end (after graduation). Returns true if revision happened.
+ */
+export async function evolveSoul(
+  store: SurrealStore,
+  complete: CompleteFn,
+): Promise<boolean> {
+  if (!store.isAvailable()) return false;
+
+  const soul = await getSoul(store);
+  if (!soul) return false;
+
+  // Count sessions since last soul update
+  try {
+    const rows = await store.queryFirst<{ count: number }>(
+      `SELECT count() AS count FROM session WHERE started_at > $since GROUP ALL`,
+      { since: soul.updated_at },
+    );
+    const sessionsSinceUpdate = rows[0]?.count ?? 0;
+    if (sessionsSinceUpdate < EVOLUTION_SESSION_INTERVAL) return false;
+  } catch (e) {
+    swallow.warn("soul:evoCheckSessions", e);
+    return false;
+  }
+
+  // Gather recent experience that post-dates the last soul update
+  const [recentReflections, recentCausal, recentMonologues, quality] = await Promise.all([
+    store.queryFirst<{ text: string; category: string }>(
+      `SELECT text, category FROM reflection WHERE created_at > $since ORDER BY created_at DESC LIMIT 10`,
+      { since: soul.updated_at },
+    ).catch(() => []),
+    store.queryFirst<{ cause: string; effect: string; lesson: string }>(
+      `SELECT cause, effect, lesson FROM causal_chain WHERE created_at > $since ORDER BY created_at DESC LIMIT 8`,
+      { since: soul.updated_at },
+    ).catch(() => []),
+    store.queryFirst<{ text: string }>(
+      `SELECT text FROM monologue WHERE created_at > $since ORDER BY created_at DESC LIMIT 8`,
+      { since: soul.updated_at },
+    ).catch(() => []),
+    getQualitySignals(store),
+  ]);
+
+  const reflections = recentReflections as { text: string; category: string }[];
+  const causal = recentCausal as { cause: string; effect: string; lesson: string }[];
+  const monologues = recentMonologues as { text: string }[];
+
+  // Not enough new signal to warrant a revision
+  if (reflections.length + causal.length + monologues.length < 5) return false;
+
+  const currentSoul = JSON.stringify({
+    working_style: soul.working_style,
+    self_observations: soul.self_observations,
+    earned_values: soul.earned_values,
+  }, null, 2);
+
+  const newExperience = `
+NEW REFLECTIONS (since last soul update):
+${reflections.map(r => `- [${r.category}] ${r.text}`).join("\n") || "None"}
+
+NEW CAUSAL CHAINS:
+${causal.map(c => `- ${c.cause} -> ${c.effect} | Lesson: ${c.lesson}`).join("\n") || "None"}
+
+NEW INNER MONOLOGUE:
+${monologues.map(m => `- ${m.text}`).join("\n") || "None"}
+
+CURRENT QUALITY:
+- Retrieval utilization: ${(quality.avgRetrievalUtilization * 100).toFixed(0)}%
+- Skill success rate: ${(quality.skillSuccessRate * 100).toFixed(0)}%
+- Critical reflection rate: ${(quality.criticalReflectionRate * 100).toFixed(0)}%
+- Tool failure rate: ${(quality.toolFailureRate * 100).toFixed(0)}%
+`.trim();
+
+  try {
+    const response = await complete({
+      system: "You are revising your own Soul document based on new experience. Return JSON with ONLY the fields that changed. Omit unchanged fields. If nothing meaningful changed, return {}. Be honest — revise based on evidence, not aspiration.",
+      messages: [{
+        role: "user",
+        content: `Current soul:\n${currentSoul}\n\nNew experience:\n${newExperience}\n\nReturn JSON with only changed fields:\n{"working_style"?: [...], "self_observations"?: [...], "earned_values"?: [{value, grounded_in}, ...]}`,
+      }],
+    });
+
+    const text = response.text.trim();
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) return false;
+
+    const revisions = JSON.parse(jsonMatch[0]);
+    if (Object.keys(revisions).length === 0) return false;
+
+    let revised = false;
+
+    if (Array.isArray(revisions.working_style) && revisions.working_style.length > 0) {
+      await reviseSoul("working_style", revisions.working_style, "Evolution: updated based on new experience patterns", store);
+      revised = true;
+    }
+    if (Array.isArray(revisions.self_observations) && revisions.self_observations.length > 0) {
+      await reviseSoul("self_observations", revisions.self_observations, "Evolution: new self-insights from recent sessions", store);
+      revised = true;
+    }
+    if (Array.isArray(revisions.earned_values) && revisions.earned_values.length > 0) {
+      const timestamped = revisions.earned_values.map((v: any) => ({
+        value: v.value ?? "",
+        grounded_in: v.grounded_in ?? "",
+      }));
+      await reviseSoul("earned_values", timestamped, "Evolution: new values grounded in recent experience", store);
+      revised = true;
+    }
+
+    // Re-sync core memory with updated soul
+    if (revised) {
+      const updatedSoul = await getSoul(store);
+      if (updatedSoul) {
+        await seedSoulAsCoreMemory(updatedSoul, store);
+      }
+    }
+
+    return revised;
+  } catch (e) {
+    swallow.warn("soul:evolveSoul", e);
+    return false;
+  }
+}
+
+// ── Stage Transition Tracking ──
+
+/**
+ * Check and record stage transitions. Returns the new stage if a transition
+ * occurred, null otherwise. Persists last-known stage in DB.
+ */
+export async function checkStageTransition(store: SurrealStore): Promise<{
+  transitioned: boolean;
+  previousStage: MaturityStage | null;
+  currentStage: MaturityStage;
+  report: GraduationReport;
+}> {
+  const report = await checkGraduation(store);
+
+  // Get last recorded stage
+  let previousStage: MaturityStage | null = null;
+  try {
+    const rows = await store.queryFirst<{ stage: string }>(
+      `SELECT stage FROM maturity_stage ORDER BY created_at DESC LIMIT 1`,
+    );
+    previousStage = (rows[0]?.stage as MaturityStage) ?? null;
+  } catch { /* table may not exist yet — first run */ }
+
+  const transitioned = previousStage !== null && previousStage !== report.stage;
+
+  // Always record current stage (upsert pattern)
+  try {
+    if (previousStage === null || transitioned) {
+      await store.queryExec(
+        `CREATE maturity_stage CONTENT $data`,
+        {
+          data: {
+            stage: report.stage,
+            volume_score: report.volumeScore,
+            quality_score: report.qualityScore,
+            met_count: report.met.length,
+            created_at: new Date().toISOString(),
+          },
+        },
+      );
+    }
+  } catch (e) {
+    swallow.warn("soul:recordStage", e);
+  }
+
+  return { transitioned, previousStage, currentStage: report.stage, report };
+}