@interleavelove/keating 0.1.0

package/dist/src/core/evolution.js

@@ -0,0 +1,224 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { Prng } from "./random.js";
+import { clamp } from "./util.js";
+import { DEFAULT_POLICY, clampPolicy } from "./policy.js";
+import { benchmarkToMarkdown, runBenchmarkSuite } from "./benchmark.js";
+function diffPolicy(before, after) {
+    const keys = [
+        "analogyDensity",
+        "socraticRatio",
+        "formalism",
+        "retrievalPractice",
+        "exerciseCount",
+        "diagramBias",
+        "reflectionBias",
+        "interdisciplinaryBias",
+        "challengeRate"
+    ];
+    return keys
+        .map((field) => {
+        const previous = before[field];
+        const next = after[field];
+        const delta = typeof previous === "number" && typeof next === "number" ? next - previous : 0;
+        return { field, before: previous, after: next, delta };
+    })
+        .filter((entry) => entry.delta !== 0);
+}
+function mutateScalar(prng, value, amplitude = 0.18) {
+    return clamp(value + (prng.next() * 2 - 1) * amplitude);
+}
+function mutatePolicy(parent, prng, iteration) {
+    const mutated = clampPolicy({
+        ...parent,
+        name: `keating-candidate-${iteration}`,
+        analogyDensity: mutateScalar(prng, parent.analogyDensity),
+        socraticRatio: mutateScalar(prng, parent.socraticRatio),
+        formalism: mutateScalar(prng, parent.formalism),
+        retrievalPractice: mutateScalar(prng, parent.retrievalPractice),
+        exerciseCount: parent.exerciseCount + prng.int(-1, 1),
+        diagramBias: mutateScalar(prng, parent.diagramBias),
+        reflectionBias: mutateScalar(prng, parent.reflectionBias),
+        interdisciplinaryBias: mutateScalar(prng, parent.interdisciplinaryBias),
+        challengeRate: mutateScalar(prng, parent.challengeRate)
+    });
+    return mutated;
+}
+function policyVector(policy) {
+    return [
+        policy.analogyDensity,
+        policy.socraticRatio,
+        policy.formalism,
+        policy.retrievalPractice,
+        policy.exerciseCount / 5,
+        policy.diagramBias,
+        policy.reflectionBias,
+        policy.interdisciplinaryBias,
+        policy.challengeRate
+    ];
+}
+function euclideanDistance(a, b) {
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        sum += (a[i] - b[i]) ** 2;
+    }
+    return Math.sqrt(sum / a.length);
+}
+export function noveltyScore(existingPolicies, candidate) {
+    if (existingPolicies.length === 0)
+        return 1;
+    const candidateVec = policyVector(candidate);
+    let minDist = Infinity;
+    for (const existing of existingPolicies) {
+        const dist = euclideanDistance(candidateVec, policyVector(existing));
+        minDist = Math.min(minDist, dist);
+    }
+    return minDist;
+}
+async function loadArchive(filePath) {
+    try {
+        const content = await readFile(filePath, "utf8");
+        return JSON.parse(content);
+    }
+    catch {
+        return {
+            currentPolicy: DEFAULT_POLICY,
+            bestScore: 0,
+            candidates: []
+        };
+    }
+}
+async function saveArchive(filePath, archive) {
+    await writeFile(filePath, `${JSON.stringify(archive, null, 2)}\n`, "utf8");
+}
+export async function evolvePolicy(archivePath, basePolicy, focusTopic, iterations = 24, seed = 20260401) {
+    const archive = await loadArchive(archivePath);
+    const baseline = runBenchmarkSuite(basePolicy, focusTopic, seed);
+    let best = baseline;
+    const acceptedCandidates = [];
+    const exploredCandidates = [];
+    const prng = new Prng(seed + 17);
+    const seen = [...archive.candidates.map((entry) => entry.policy), basePolicy];
+    for (let iteration = 1; iteration <= iterations; iteration += 1) {
+        const candidatePolicy = mutatePolicy(best.policy, prng, iteration);
+        const novelty = noveltyScore(seen, candidatePolicy);
+        const candidateBenchmark = runBenchmarkSuite(candidatePolicy, focusTopic, seed + iteration * 11);
+        const parameterDelta = diffPolicy(best.policy, candidatePolicy);
+        const candidate = {
+            policy: candidatePolicy,
+            benchmark: candidateBenchmark,
+            parentName: best.policy.name,
+            iteration,
+            novelty,
+            accepted: false,
+            parameterDelta,
+            decision: {
+                improves: false,
+                safe: false,
+                novelEnough: false,
+                scoreDelta: 0,
+                weakestTopicDelta: 0,
+                reasons: []
+            }
+        };
+        const bestWeakest = Math.min(...best.topicBenchmarks.map((entry) => entry.meanScore));
+        const candidateWeakest = Math.min(...candidateBenchmark.topicBenchmarks.map((entry) => entry.meanScore));
+        const improves = candidateBenchmark.overallScore > best.overallScore;
+        const safe = candidateWeakest >= bestWeakest - 1.5;
+        const novelEnough = novelty >= 0.05;
+        candidate.decision.improves = improves;
+        candidate.decision.safe = safe;
+        candidate.decision.novelEnough = novelEnough;
+        candidate.decision.scoreDelta = candidateBenchmark.overallScore - best.overallScore;
+        candidate.decision.weakestTopicDelta = candidateWeakest - bestWeakest;
+        if (improves) {
+            candidate.decision.reasons.push(`overall score improved by ${candidate.decision.scoreDelta.toFixed(2)}`);
+        }
+        else {
+            candidate.decision.reasons.push(`overall score regressed by ${Math.abs(candidate.decision.scoreDelta).toFixed(2)}`);
+        }
+        if (safe) {
+            candidate.decision.reasons.push(`weakest-topic score stayed within tolerance (${candidate.decision.weakestTopicDelta.toFixed(2)})`);
+        }
+        else {
+            candidate.decision.reasons.push(`weakest-topic score fell too far (${candidate.decision.weakestTopicDelta.toFixed(2)})`);
+        }
+        if (novelEnough) {
+            candidate.decision.reasons.push(`novelty ${novelty.toFixed(3)} cleared the 0.05 threshold`);
+        }
+        else {
+            candidate.decision.reasons.push(`novelty ${novelty.toFixed(3)} was too close to archived policies`);
+        }
+        if (improves && safe && novelEnough) {
+            candidate.accepted = true;
+            best = candidateBenchmark;
+            acceptedCandidates.push(candidate);
+        }
+        exploredCandidates.push(candidate);
+        seen.push(candidate.policy);
+    }
+    const nextArchive = {
+        currentPolicy: best.policy,
+        bestScore: best.overallScore,
+        candidates: [
+            ...archive.candidates,
+            ...exploredCandidates.map((entry) => ({
+                policy: entry.policy,
+                score: entry.benchmark.overallScore,
+                novelty: entry.novelty,
+                accepted: entry.accepted,
+                iteration: entry.iteration
+            }))
+        ]
+    };
+    await saveArchive(archivePath, nextArchive);
+    return {
+        baseline,
+        best,
+        acceptedCandidates,
+        exploredCandidates,
+        archive: nextArchive
+    };
+}
+export function evolutionToMarkdown(run) {
+    const lines = [
+        `# Evolution Report: ${run.best.policy.name}`,
+        "",
+        `- Baseline score: ${run.baseline.overallScore.toFixed(2)}`,
+        `- Best score: ${run.best.overallScore.toFixed(2)}`,
+        `- Accepted candidates: ${run.acceptedCandidates.length}`,
+        `- Explored candidates: ${run.exploredCandidates.length}`,
+        ""
+    ];
+    lines.push("## Accepted Candidates");
+    lines.push("");
+    if (run.acceptedCandidates.length === 0) {
+        lines.push("- No candidate cleared both the novelty and safety gates in this run.");
+    }
+    else {
+        for (const candidate of run.acceptedCandidates) {
+            lines.push(`- Iteration ${candidate.iteration}: ${candidate.policy.name} scored ${candidate.benchmark.overallScore.toFixed(2)} with novelty ${candidate.novelty.toFixed(3)}.`);
+        }
+    }
+    lines.push("");
+    lines.push("## Decision Ledger");
+    lines.push("");
+    for (const candidate of run.exploredCandidates) {
+        lines.push(`- Iteration ${candidate.iteration} ${candidate.policy.name}: ${candidate.accepted ? "accepted" : "rejected"}`);
+        lines.push(`  - score delta: ${candidate.decision.scoreDelta.toFixed(2)}`);
+        lines.push(`  - weakest-topic delta: ${candidate.decision.weakestTopicDelta.toFixed(2)}`);
+        lines.push(`  - novelty: ${candidate.novelty.toFixed(3)}`);
+        lines.push(`  - gates: improves=${candidate.decision.improves}, safe=${candidate.decision.safe}, novelEnough=${candidate.decision.novelEnough}`);
+        lines.push(`  - reasons: ${candidate.decision.reasons.join("; ")}`);
+        if (candidate.parameterDelta.length > 0) {
+            lines.push(`  - parameter delta: ${candidate.parameterDelta
+                .map((entry) => `${entry.field}:${entry.delta >= 0 ? "+" : ""}${entry.delta.toFixed(2)}`)
+                .join(", ")}`);
+        }
+    }
+    lines.push("");
+    lines.push("## Best Benchmark Snapshot");
+    lines.push("");
+    lines.push(benchmarkToMarkdown(run.best).trim());
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}

package/dist/src/core/learner-state.js

@@ -0,0 +1,88 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { clamp } from "./util.js";
+const DEFAULT_LEARNER_STATE = {
+    coveredTopics: [],
+    identifiedMisconceptions: [],
+    feedback: [],
+    profile: {
+        id: "default",
+        priorKnowledge: 0.5,
+        abstractionComfort: 0.5,
+        analogyNeed: 0.5,
+        dialoguePreference: 0.5,
+        diagramAffinity: 0.5,
+        persistence: 0.5,
+        transferDesire: 0.5,
+        anxiety: 0.3
+    }
+};
+export async function loadLearnerState(filePath) {
+    // Read JSON from filePath. If file doesn't exist or is invalid, return default with id "learner-1"
+    try {
+        const raw = await readFile(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { id: "learner-1", ...DEFAULT_LEARNER_STATE };
+    }
+}
+export async function saveLearnerState(filePath, state) {
+    await writeFile(filePath, JSON.stringify(state, null, 2), "utf8");
+}
+export function recordTopicCoverage(state, topic, masteryEstimate) {
+    const existing = state.coveredTopics.find(t => t.slug === topic.slug);
+    if (existing) {
+        existing.lastSeen = new Date().toISOString();
+        existing.masteryEstimate = clamp(masteryEstimate);
+        existing.sessionCount += 1;
+    }
+    else {
+        state.coveredTopics.push({
+            slug: topic.slug,
+            domain: topic.domain,
+            lastSeen: new Date().toISOString(),
+            masteryEstimate: clamp(masteryEstimate),
+            sessionCount: 1
+        });
+    }
+    return state;
+}
+export function recordMisconception(state, topic, misconception) {
+    const existing = state.identifiedMisconceptions.find(m => m.topic === topic && m.misconception === misconception);
+    if (!existing) {
+        state.identifiedMisconceptions.push({ topic, misconception, addressed: false });
+    }
+    return state;
+}
+export function recordFeedback(state, topic, signal) {
+    state.feedback.push({
+        topic,
+        timestamp: new Date().toISOString(),
+        signal
+    });
+    return state;
+}
+export function buildProfileFromFeedback(state) {
+    const profile = { ...state.profile };
+    if (state.feedback.length === 0)
+        return profile;
+    const total = state.feedback.length;
+    const confusedCount = state.feedback.filter(f => f.signal === "confused").length;
+    const positiveCount = state.feedback.filter(f => f.signal === "thumbs-up").length;
+    const negativeCount = state.feedback.filter(f => f.signal === "thumbs-down").length;
+    const confusionRate = confusedCount / total;
+    const satisfactionRate = positiveCount / total;
+    // High confusion suggests lower abstraction comfort and higher anxiety
+    profile.abstractionComfort = clamp(profile.abstractionComfort - confusionRate * 0.2);
+    profile.anxiety = clamp(profile.anxiety + confusionRate * 0.15);
+    // High satisfaction suggests the current teaching style works
+    profile.persistence = clamp(profile.persistence + satisfactionRate * 0.1);
+    // High negative feedback suggests teaching style mismatch
+    profile.dialoguePreference = clamp(profile.dialoguePreference + (negativeCount / total) * 0.1);
+    // Update prior knowledge from covered topics
+    if (state.coveredTopics.length > 0) {
+        const avgMastery = state.coveredTopics.reduce((sum, t) => sum + t.masteryEstimate, 0) / state.coveredTopics.length;
+        profile.priorKnowledge = clamp(avgMastery);
+    }
+    return profile;
+}

package/dist/src/core/lesson-plan.js

@@ -0,0 +1,155 @@
+import { resolveTopic } from "./topics.js";
+function prerequisiteBullets(topic) {
+    return topic.prerequisites.map((item) => `Recall ${item} and connect it to ${topic.title}.`);
+}
+function misconceptionBullets(topic) {
+    return topic.misconceptions.map((item) => `Address misconception: ${item}`);
+}
+function practiceBullets(topic, exerciseCount) {
+    const bullets = [...topic.exercises];
+    while (bullets.length < exerciseCount) {
+        bullets.push(`Invent a new example that makes ${topic.title} easier to explain.`);
+    }
+    return bullets.slice(0, exerciseCount).map((item) => `Practice: ${item}`);
+}
+export function buildLessonPlan(topicName, policy) {
+    const topic = resolveTopic(topicName);
+    const phases = [
+        {
+            id: "orient",
+            title: "Orientation",
+            purpose: "Assess prerequisites and frame the core question.",
+            bullets: [
+                `State the big question: ${topic.summary}`,
+                ...prerequisiteBullets(topic)
+            ]
+        },
+        {
+            id: "intuition",
+            title: "Intuition",
+            purpose: "Teach the concept concretely before pushing notation or abstract framing.",
+            bullets: topic.intuition.map((item) => `Intuition: ${item}`)
+        },
+        {
+            id: "formal-core",
+            title: "Formal Core",
+            purpose: "Escalate into rigorous structure once intuition has traction.",
+            bullets: topic.formalCore.map((item) => `Formal: ${item}`)
+        },
+        {
+            id: "misconceptions",
+            title: "Misconception Repair",
+            purpose: "Anticipate predictable mistakes before they calcify.",
+            bullets: misconceptionBullets(topic)
+        },
+        {
+            id: "examples",
+            title: "Worked Examples",
+            purpose: "Move between examples so the learner sees the invariant structure.",
+            bullets: topic.examples.map((item) => `Example: ${item}`)
+        },
+        {
+            id: "practice",
+            title: "Guided Practice",
+            purpose: "Force retrieval and re-expression, not passive agreement.",
+            bullets: practiceBullets(topic, policy.exerciseCount)
+        },
+        {
+            id: "transfer",
+            title: "Transfer and Reflection",
+            purpose: "Bridge the concept across domains and make the learner summarize what changed.",
+            bullets: [
+                ...topic.reflections.map((item) => `Reflect: ${item}`),
+                `Bridge ${topic.title} into: ${topic.interdisciplinaryHooks.join(", ")}.`
+            ]
+        }
+    ];
+    if (policy.diagramBias >= 0.55) {
+        phases.splice(4, 0, {
+            id: "diagram",
+            title: "Diagram",
+            purpose: "Compress the concept into a visual structure before free recall.",
+            bullets: [
+                `Map the concept using nodes: ${topic.diagramNodes.join(" -> ")}.`,
+                `Ask the learner to narrate the diagram without reading from it.`
+            ]
+        });
+    }
+    if (policy.socraticRatio >= 0.6) {
+        phases[0].bullets.unshift(`Open with a diagnostic question instead of a lecture on ${topic.title}.`);
+        phases[5].bullets.unshift(`Pause after each practice step and ask the learner to predict the next move.`);
+    }
+    // Domain-specific phase customizations
+    if (topic.domain === "code") {
+        const exIdx = phases.findIndex((p) => p.id === "examples");
+        if (exIdx !== -1) {
+            phases.splice(exIdx + 1, 0, {
+                id: "live-code",
+                title: "Live Code",
+                purpose: "Write and trace runnable code so the learner sees the concept execute.",
+                bullets: [
+                    `Write a minimal runnable example demonstrating ${topic.title}.`,
+                    `Step through execution line by line, narrating state changes.`,
+                    `Ask the learner to predict output before running.`
+                ]
+            });
+        }
+    }
+    if (topic.domain === "law") {
+        const examples = phases.find((p) => p.id === "examples");
+        if (examples) {
+            examples.bullets.push(`Cite at least one leading case or statute relevant to ${topic.title}.`, `Distinguish the ratio decidendi from obiter dicta.`);
+        }
+    }
+    if (topic.domain === "medicine") {
+        const formalCore = phases.find((p) => p.id === "formal-core");
+        if (formalCore) {
+            formalCore.bullets.push(`Reference the level of evidence (RCT, meta-analysis, observational) for key claims about ${topic.title}.`, `Distinguish mechanism-based reasoning from evidence-based conclusions.`);
+        }
+    }
+    if (topic.domain === "history") {
+        const examples = phases.find((p) => p.id === "examples");
+        if (examples) {
+            examples.bullets.push(`Place ${topic.title} on a timeline with at least two contextual events.`, `Distinguish primary sources from secondary interpretation.`);
+        }
+    }
+    if (topic.domain === "psychology") {
+        const misconceptions = phases.find((p) => p.id === "misconceptions");
+        if (misconceptions) {
+            misconceptions.bullets.push(`Flag the replication status of key studies related to ${topic.title}.`, `Distinguish folk-psychology usage from empirical findings.`);
+        }
+    }
+    if (topic.domain === "politics") {
+        const transfer = phases.find((p) => p.id === "transfer");
+        if (transfer) {
+            transfer.bullets.push(`Present at least two competing analytical frameworks for ${topic.title}.`, `Distinguish normative claims from descriptive ones.`);
+        }
+    }
+    if (topic.domain === "arts") {
+        const examples = phases.find((p) => p.id === "examples");
+        if (examples) {
+            examples.bullets.push(`Ground analysis in at least one specific work that exemplifies ${topic.title}.`, `Connect formal technique to expressive effect.`);
+        }
+    }
+    return { topic, policy, phases };
+}
+export function lessonPlanToMarkdown(plan) {
+    const lines = [
+        `# Lesson Plan: ${plan.topic.title}`,
+        "",
+        `- Domain: ${plan.topic.domain}`,
+        `- Policy: ${plan.policy.name}`,
+        `- Summary: ${plan.topic.summary}`,
+        ""
+    ];
+    for (const phase of plan.phases) {
+        lines.push(`## ${phase.title}`);
+        lines.push(phase.purpose);
+        lines.push("");
+        for (const bullet of phase.bullets) {
+            lines.push(`- ${bullet}`);
+        }
+        lines.push("");
+    }
+    return `${lines.join("\n").trim()}\n`;
+}

package/dist/src/core/map.js

@@ -0,0 +1,89 @@
+import { spawnSync } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { buildLessonPlan } from "./lesson-plan.js";
+import { mapsDir } from "./paths.js";
+import { slugify } from "./util.js";
+function mermaidLabel(text) {
+    return text.replaceAll('"', "'").replaceAll("\n", " ");
+}
+export function lessonPlanToMermaid(topicName, policy) {
+    const plan = buildLessonPlan(topicName, policy);
+    const topicId = slugify(plan.topic.title);
+    const lines = [
+        "graph TD",
+        "  classDef phase fill:#12263f,stroke:#8db5ff,color:#f8f5ec,stroke-width:1px;",
+        "  classDef concept fill:#173122,stroke:#8fd7b6,color:#f8f5ec,stroke-width:1px;",
+        "  classDef friction fill:#3a2317,stroke:#ff9b6b,color:#f8f5ec,stroke-width:1px;",
+        "  classDef transfer fill:#2f2140,stroke:#d3a6ff,color:#f8f5ec,stroke-width:1px;",
+        `  learner(("Learner state"))`,
+        `  thesis["${mermaidLabel(plan.topic.title)}: ${mermaidLabel(plan.topic.summary)}"]`
+    ];
+    lines.push('  subgraph pedagogy["Teaching Loop"]');
+    for (const phase of plan.phases) {
+        lines.push(`    ${phase.id}["${mermaidLabel(phase.title)}"]`);
+    }
+    for (let index = 0; index < plan.phases.length - 1; index += 1) {
+        lines.push(`    ${plan.phases[index].id} --> ${plan.phases[index + 1].id}`);
+    }
+    lines.push("  end");
+    lines.push('  subgraph meaning["Meaning Map"]');
+    lines.push(`    ${topicId}_core["${mermaidLabel(plan.topic.title)}"]`);
+    for (const [index, node] of plan.topic.diagramNodes.entries()) {
+        lines.push(`    ${topicId}_concept_${index}["${mermaidLabel(node)}"]`);
+        lines.push(`    ${topicId}_core --> ${topicId}_concept_${index}`);
+    }
+    for (const [index, prerequisite] of plan.topic.prerequisites.slice(0, 3).entries()) {
+        lines.push(`    ${topicId}_prereq_${index}["Prereq: ${mermaidLabel(prerequisite)}"]`);
+        lines.push(`    ${topicId}_prereq_${index} --> ${topicId}_core`);
+    }
+    lines.push("  end");
+    lines.push('  subgraph friction["Misconceptions And Practice"]');
+    for (const [index, misconception] of plan.topic.misconceptions.slice(0, 2).entries()) {
+        lines.push(`    ${topicId}_mis_${index}["${mermaidLabel(misconception)}"]`);
+        lines.push(`    ${topicId}_core --> ${topicId}_mis_${index}`);
+    }
+    for (const [index, exercise] of plan.topic.exercises.slice(0, 2).entries()) {
+        lines.push(`    ${topicId}_exercise_${index}["Practice: ${mermaidLabel(exercise)}"]`);
+        lines.push(`    ${topicId}_mis_${Math.min(index, Math.max(plan.topic.misconceptions.length - 1, 0))} --> ${topicId}_exercise_${index}`);
+    }
+    lines.push("  end");
+    lines.push('  subgraph transfer["Transfer Hooks"]');
+    for (const [index, hook] of plan.topic.interdisciplinaryHooks.entries()) {
+        lines.push(`    ${topicId}_hook_${index}["${mermaidLabel(hook)}"]`);
+        lines.push(`    ${topicId}_core --> ${topicId}_hook_${index}`);
+    }
+    lines.push("  end");
+    lines.push("  learner --> orient");
+    lines.push("  thesis --> orient");
+    lines.push(`  ${plan.phases.at(-1).id} --> ${topicId}_hook_0`);
+    lines.push(`  ${plan.phases.find((phase) => phase.id === "diagram")?.id ?? "examples"} --> ${topicId}_core`);
+    lines.push(`  class ${plan.phases.map((phase) => phase.id).join(",")} phase;`);
+    lines.push(`  class ${topicId}_core,${plan.topic.diagramNodes.map((_, index) => `${topicId}_concept_${index}`).join(",")},${plan.topic.prerequisites.slice(0, 3).map((_, index) => `${topicId}_prereq_${index}`).join(",")} concept;`);
+    const frictionNodes = [
+        ...plan.topic.misconceptions.slice(0, 2).map((_, index) => `${topicId}_mis_${index}`),
+        ...plan.topic.exercises.slice(0, 2).map((_, index) => `${topicId}_exercise_${index}`)
+    ];
+    if (frictionNodes.length > 0) {
+        lines.push(`  class ${frictionNodes.join(",")} friction;`);
+    }
+    const transferNodes = plan.topic.interdisciplinaryHooks.map((_, index) => `${topicId}_hook_${index}`);
+    if (transferNodes.length > 0) {
+        lines.push(`  class ${transferNodes.join(",")} transfer;`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function writeLessonMap(cwd, topicName, policy) {
+    const slug = slugify(topicName);
+    const mmdPath = join(mapsDir(cwd), `${slug}.mmd`);
+    const svgPath = join(mapsDir(cwd), `${slug}.svg`);
+    await writeFile(mmdPath, lessonPlanToMermaid(topicName, policy), "utf8");
+    const render = spawnSync("oxdraw", ["--input", mmdPath, "--output", svgPath], {
+        cwd,
+        encoding: "utf8"
+    });
+    if (render.status === 0) {
+        return { mmdPath, svgPath };
+    }
+    return { mmdPath, svgPath: null };
+}

package/dist/src/core/paths.js

@@ -0,0 +1,69 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+export function keatingRoot(cwd) {
+    return join(cwd, ".keating");
+}
+export function stateDir(cwd) {
+    return join(keatingRoot(cwd), "state");
+}
+export function outputsDir(cwd) {
+    return join(keatingRoot(cwd), "outputs");
+}
+export function plansDir(cwd) {
+    return join(outputsDir(cwd), "plans");
+}
+export function mapsDir(cwd) {
+    return join(outputsDir(cwd), "maps");
+}
+export function animationsDir(cwd) {
+    return join(outputsDir(cwd), "animations");
+}
+export function benchmarksDir(cwd) {
+    return join(outputsDir(cwd), "benchmarks");
+}
+export function evolutionDir(cwd) {
+    return join(outputsDir(cwd), "evolution");
+}
+export function promptEvolutionDir(cwd) {
+    return join(outputsDir(cwd), "prompt-evolution");
+}
+export function tracesDir(cwd) {
+    return join(outputsDir(cwd), "traces");
+}
+export function sessionsDir(cwd) {
+    return join(keatingRoot(cwd), "sessions");
+}
+export function currentPolicyPath(cwd) {
+    return join(stateDir(cwd), "current-policy.json");
+}
+export function policyArchivePath(cwd) {
+    return join(stateDir(cwd), "policy-archive.json");
+}
+export function promptEvolutionArchivePath(cwd) {
+    return join(stateDir(cwd), "prompt-evolution-archive.json");
+}
+export function learnerStatePath(cwd) {
+    return join(stateDir(cwd), "learner.json");
+}
+export function verificationsDir(cwd) {
+    return join(outputsDir(cwd), "verifications");
+}
+export function verificationCachePath(cwd) {
+    return join(stateDir(cwd), "verification-cache.json");
+}
+export async function ensureKeatingDirs(cwd) {
+    await Promise.all([
+        mkdir(stateDir(cwd), { recursive: true }),
+        mkdir(join(stateDir(cwd), "snapshots"), { recursive: true }),
+        mkdir(plansDir(cwd), { recursive: true }),
+        mkdir(mapsDir(cwd), { recursive: true }),
+        mkdir(animationsDir(cwd), { recursive: true }),
+        mkdir(benchmarksDir(cwd), { recursive: true }),
+        mkdir(evolutionDir(cwd), { recursive: true }),
+        mkdir(promptEvolutionDir(cwd), { recursive: true }),
+        mkdir(tracesDir(cwd), { recursive: true }),
+        mkdir(verificationsDir(cwd), { recursive: true }),
+        mkdir(join(outputsDir(cwd), "improvements"), { recursive: true }),
+        mkdir(sessionsDir(cwd), { recursive: true })
+    ]);
+}

package/dist/src/core/pi-agent.js

@@ -0,0 +1,58 @@
+import { spawnSync } from "node:child_process";
+import { loadKeatingConfig, mergePiDefaults } from "./config.js";
+/**
+ * Programmatic interface to the Pi agent via CLI.
+ * This ensures we use the same provider, model, and thinking settings as the user's Pi install.
+ */
+export async function piComplete(cwd, prompt, options = {}) {
+    const config = await loadKeatingConfig(cwd);
+    const args = ["-p", "--no-session", "--no-tools", "--no-extensions", "--no-skills"];
+    if (options.systemPrompt) {
+        args.push("--system-prompt", options.systemPrompt);
+    }
+    if (options.json) {
+        args.push("--mode", "json");
+    }
+    if (options.thinking) {
+        args.push("--thinking", options.thinking);
+    }
+    const finalArgs = mergePiDefaults(config, [...args, prompt]);
+    const result = spawnSync("pi", finalArgs, {
+        cwd,
+        encoding: "utf8",
+        env: {
+            ...process.env,
+            PI_SKIP_VERSION_CHECK: "1"
+        }
+    });
+    if (result.status !== 0) {
+        throw new Error(`Pi completion failed (exit ${result.status}): ${result.stderr || result.stdout}`);
+    }
+    return result.stdout.trim();
+}
+/**
+ * Specialized helper for JSON completions.
+ */
+export async function piCompleteJson(cwd, prompt, options = {}) {
+    const response = await piComplete(cwd, prompt, { ...options, json: true });
+    try {
+        // Some models output reasoning BEFORE the JSON block.
+        // We try to find all JSON-like blocks and pick the one that parses successfully,
+        // prioritizing the last one.
+        const matches = response.match(/\{[\s\S]*?\}/g);
+        if (!matches)
+            return JSON.parse(response);
+        for (let i = matches.length - 1; i >= 0; i--) {
+            try {
+                return JSON.parse(matches[i]);
+            }
+            catch {
+                continue;
+            }
+        }
+        throw new Error("No valid JSON block found in response.");
+    }
+    catch (error) {
+        throw new Error(`Failed to parse Pi JSON response: ${response}\nError: ${error}`);
+    }
+}