keating 0.3.6

package/dist/src/core/projects.js

@@ -0,0 +1,281 @@
+/**
+ * Projects & Assignments Engine — long-horizon learning with milestones.
+ *
+ * Learners get multi-stage projects that span days or weeks, with:
+ * - Milestones (verified checkpoints)
+ * - Deliverables (artifacts to produce)
+ * - Rubrics (grading criteria)
+ * - Progress tracking
+ */
+import { resolveTopic } from "./topics.js";
+// ─── Project Generation ───────────────────────────────────────────────────
+export function generateProject(topicName) {
+    const topic = resolveTopic(topicName);
+    const id = `proj-${topic.slug}-${Date.now().toString(36)}`;
+    const milestones = [
+        {
+            id: `${id}-m1`,
+            title: "Research & Foundation",
+            description: `Investigate the core definitions, history, and key figures behind ${topic.title}.`,
+            deliverables: [
+                {
+                    id: `${id}-d1`,
+                    title: "Concept Map",
+                    description: `Create a concept map showing ${topic.title}, its prerequisites, and key relationships.`,
+                    format: "diagram",
+                    rubric: [
+                        "Includes core concept node",
+                        "Links to at least 3 prerequisites",
+                        "Shows relationship arrows with labels",
+                        "Identifies at least 1 common misconception"
+                    ]
+                },
+                {
+                    id: `${id}-d2`,
+                    title: "Annotated Summary",
+                    description: `Write a 200-word summary of ${topic.title} annotated with your own questions and connections.`,
+                    format: "essay",
+                    minWords: 200,
+                    rubric: [
+                        "Accurately captures core definition",
+                        "Includes at least 2 personal questions",
+                        "Connects to prior knowledge",
+                        "Identifies what is still unclear"
+                    ]
+                }
+            ],
+            estimatedHours: 2,
+            prerequisites: topic.prerequisites,
+            status: "not_started"
+        },
+        {
+            id: `${id}-m2`,
+            title: "Deep Dive",
+            description: `Work through examples and exercises demonstrating ${topic.title} in practice.`,
+            deliverables: [
+                {
+                    id: `${id}-d3`,
+                    title: "Worked Examples",
+                    description: `Solve ${topic.examples.length} worked examples, showing all reasoning.`,
+                    format: "implementation",
+                    rubric: [
+                        "All steps shown with justification",
+                        "At least one alternative approach explored",
+                        "Common mistakes identified and avoided",
+                        "Final answer verifiable"
+                    ]
+                },
+                {
+                    id: `${id}-d4`,
+                    title: "Practice Problems",
+                    description: `Create 3 original practice problems on ${topic.title} with solutions.`,
+                    format: "implementation",
+                    rubric: [
+                        "Problems cover different difficulty levels",
+                        "Solutions are correct and complete",
+                        "At least one problem targets a known misconception",
+                        "Clear marking scheme provided"
+                    ]
+                }
+            ],
+            estimatedHours: 4,
+            prerequisites: [],
+            status: "not_started"
+        },
+        {
+            id: `${id}-m3`,
+            title: "Transfer & Synthesis",
+            description: `Apply ${topic.title} to a new domain or build a creative extension.`,
+            deliverables: [
+                {
+                    id: `${id}-d5`,
+                    title: "Transfer Report",
+                    description: `Choose a domain from ${topic.interdisciplinaryHooks.join(", ")} and build an explicit bridge.`,
+                    format: "analysis",
+                    minWords: 300,
+                    rubric: [
+                        "Chooses a specific external domain",
+                        "Identifies structural similarities",
+                        "Acknowledges where the analogy breaks",
+                        "Proposes a novel insight or question"
+                    ]
+                }
+            ],
+            estimatedHours: 3,
+            prerequisites: [],
+            status: "not_started"
+        },
+        {
+            id: `${id}-m4`,
+            title: "Teach-Back",
+            description: `Teach ${topic.title} to another learner. Teaching is the ultimate test of understanding.`,
+            deliverables: [
+                {
+                    id: `${id}-d6`,
+                    title: "Teaching Artifact",
+                    description: `Create a teaching artifact: slides, blog post, video script, or interactive demo.`,
+                    format: "presentation",
+                    rubric: [
+                        "Intuition comes before formalism",
+                        "At least 2 examples (one simple, one complex)",
+                        "Common misconception addressed explicitly",
+                        "Includes a reflection question for the student"
+                    ]
+                }
+            ],
+            estimatedHours: 4,
+            prerequisites: [],
+            status: "not_started"
+        }
+    ];
+    return {
+        id,
+        title: `${topic.title} Mastery Project`,
+        topic: topic.title,
+        slug: topic.slug,
+        description: `A comprehensive project to master ${topic.title} through research, practice, transfer, and teaching.`,
+        learningObjectives: [
+            `Define ${topic.title} precisely`,
+            `Apply ${topic.title} to solve unfamiliar problems`,
+            `Transfer ${topic.title} to at least one new domain`,
+            `Teach ${topic.title} to someone with no prior exposure`
+        ],
+        milestones,
+        totalEstimatedHours: milestones.reduce((s, m) => s + m.estimatedHours, 0),
+        generatedAt: new Date().toISOString()
+    };
+}
+// ─── Assignment Generation ────────────────────────────────────────────────
+export function generateAssignment(topicName) {
+    const topic = resolveTopic(topicName);
+    const id = `asgn-${topic.slug}-${Date.now().toString(36)}`;
+    return {
+        id,
+        slug: topic.slug,
+        title: `${topic.title} Challenge`,
+        topic: topic.title,
+        instructions: `Complete all deliverables below. Focus on understanding, not speed. If you are stuck for more than 20 minutes, ask for help rather than guessing.`,
+        deliverables: [
+            {
+                id: `${id}-d1`,
+                title: "Core Analysis",
+                description: `Analyze ${topic.title} using formal definitions. Show your reasoning chain.`,
+                format: "essay",
+                minWords: 250,
+                rubric: [
+                    "Uses correct formal definitions",
+                    "Logic is sequential and verifiable",
+                    "Assumptions are stated explicitly",
+                    "Conclusion is supported by evidence"
+                ]
+            },
+            {
+                id: `${id}-d2`,
+                title: "Creative Extension",
+                description: `Propose a question, extension, or application of ${topic.title} that is NOT covered in standard textbooks.`,
+                format: "analysis",
+                rubric: [
+                    "Question is genuinely novel",
+                    "Builds on core concepts",
+                    "Is answerable with reasonable effort",
+                    "Author demonstrates awareness of what they do not yet know"
+                ]
+            }
+        ],
+        dueInDays: 7,
+        rubric: [
+            "All deliverables present and complete",
+            "Demonstrates original thinking, not paraphrasing",
+            "Acknowledges uncertainty where appropriate",
+            "Written in learner's own voice"
+        ],
+        generatedAt: new Date().toISOString()
+    };
+}
+// ─── Markdown output ──────────────────────────────────────────────────────
+export function projectToMarkdown(project) {
+    const lines = [
+        `# Project: ${project.title}`,
+        "",
+        project.description,
+        "",
+        `**Estimated time:** ${project.totalEstimatedHours} hours`,
+        `**ID:** ${project.id}`,
+        "",
+        "## Learning Objectives",
+        "",
+        ...project.learningObjectives.map(o => `- ${o}`),
+        ""
+    ];
+    for (const m of project.milestones) {
+        lines.push(`---`);
+        lines.push(`# Milestone: ${m.title}`);
+        lines.push(m.description);
+        lines.push(`**Status:** ${m.status} | **Estimated:** ${m.estimatedHours}h`);
+        if (m.prerequisites.length > 0) {
+            lines.push(`**Prerequisites:** ${m.prerequisites.join(", ")}`);
+        }
+        lines.push("");
+        for (const d of m.deliverables) {
+            lines.push(`### ${d.title}`);
+            lines.push(d.description);
+            if (d.minWords)
+                lines.push(`*Minimum length:* ${d.minWords} words`);
+            lines.push("**Rubric:**");
+            for (const r of d.rubric)
+                lines.push(`- [ ] ${r}`);
+            lines.push("");
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+export function assignmentToMarkdown(assignment) {
+    const lines = [
+        `# Assignment: ${assignment.title}`,
+        "",
+        assignment.instructions,
+        `**Due in:** ${assignment.dueInDays} days`,
+        "",
+        "## Deliverables",
+        ""
+    ];
+    for (const d of assignment.deliverables) {
+        lines.push(`### ${d.title}`);
+        lines.push(d.description);
+        if (d.minWords)
+            lines.push(`*Minimum:* ${d.minWords} words`);
+        lines.push("**Rubric:**");
+        for (const r of d.rubric)
+            lines.push(`- [ ] ${r}`);
+        lines.push("");
+    }
+    lines.push("## Overall Rubric");
+    for (const r of assignment.rubric)
+        lines.push(`- [ ] ${r}`);
+    lines.push("");
+    return lines.join("\n") + "\n";
+}
+export function computeProjectProgress(project) {
+    const totalMilestones = project.milestones.length;
+    const completedMilestones = project.milestones.filter(m => m.status === "reviewed").length;
+    const totalDeliverables = project.milestones.reduce((s, m) => s + m.deliverables.length, 0);
+    const completedDeliverables = project.milestones
+        .filter(m => m.status === "reviewed")
+        .reduce((s, m) => s + m.deliverables.length, 0);
+    const hours = project.milestones.reduce((s, m) => s + (m.status !== "not_started" ? m.estimatedHours : 0), 0);
+    let overall = "not_started";
+    if (completedMilestones === totalMilestones)
+        overall = "completed";
+    else if (completedMilestones > 0 || project.milestones.some(m => m.status === "in_progress"))
+        overall = "in_progress";
+    return {
+        projectId: project.id,
+        milestonesCompleted: completedMilestones,
+        milestonesTotal: totalMilestones,
+        deliverablesCompleted: completedDeliverables,
+        deliverablesTotal: totalDeliverables,
+        hoursLogged: hours,
+        overallStatus: overall,
+        lastActivityAt: new Date().toISOString()
+    };
+}

package/dist/src/core/prompt-evolution.js

@@ -0,0 +1,344 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadEnv } from "./env.js";
+import { promptEvolutionArchivePath, promptEvolutionDir } from "./paths.js";
+import { piComplete, piCompleteJson } from "./pi-agent.js";
+loadEnv();
+const KEATING_QUOTE = "Boys, you must strive to find your own voice. Because the longer you wait to begin, the less likely you are to find it at all.";
+let piAvailabilityCache = null;
+function promptNameFromPath(promptPath) {
+    const fileName = promptPath.split(/[\\/]/).pop() ?? promptPath;
+    return fileName.replace(/\.md$/, "");
+}
+function parsePromptBody(raw) {
+    if (!raw.startsWith("---"))
+        return raw.trim();
+    const parts = raw.split("\n---\n");
+    if (parts.length < 2)
+        return raw.trim();
+    return parts.slice(1).join("\n---\n").trim();
+}
+function parseFrontMatter(raw) {
+    if (!raw.startsWith("---"))
+        return "";
+    const parts = raw.split("\n---\n");
+    if (parts.length < 2)
+        return "";
+    return `${parts[0]}\n---`.trim();
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function keywordScore(body, keywords, base, bonus) {
+    const hits = keywords.filter((keyword) => body.includes(keyword)).length;
+    return clamp01(base + hits * bonus);
+}
+function heuristicPromptEvaluation(promptPath, prompt) {
+    const body = parsePromptBody(prompt).toLowerCase();
+    const objectives = {
+        voice_divergence: keywordScore(body, ["own words", "own language", "personal context", "say it again"], 0.35, 0.18),
+        diagnosis: keywordScore(body, ["diagnostic", "prerequisite", "misconception", "assumption check"], 0.4, 0.16),
+        verification: keywordScore(body, ["verify", "verification", "source", "unverified", "check claim"], 0.2, 0.18),
+        retrieval: keywordScore(body, ["retrieval", "reconstruct", "without looking", "recall", "practice"], 0.35, 0.18),
+        transfer: keywordScore(body, ["transfer", "bridge", "other domain", "practical consequence", "new setting"], 0.3, 0.18),
+        structure: keywordScore(body, ["diagnose", "intuition", "formal", "misconception", "example", "retrieval", "reflection"], 0.45, 0.09)
+    };
+    const feedback = [];
+    if (objectives.voice_divergence < 0.7)
+        feedback.push("Add an explicit requirement that the learner restate the idea in their own words.");
+    if (objectives.diagnosis < 0.7)
+        feedback.push("Strengthen diagnosis of prerequisite gaps and misconceptions before teaching.");
+    if (objectives.verification < 0.7)
+        feedback.push("Include a step that distinguishes verified claims from claims that still need checking.");
+    if (objectives.retrieval < 0.7)
+        feedback.push("Add a retrieval checkpoint that requires reconstruction rather than agreement.");
+    if (objectives.transfer < 0.7)
+        feedback.push("Bridge the concept into a different domain or practical context before ending.");
+    if (objectives.structure < 0.7)
+        feedback.push("Make the lesson loop explicit so the workflow is easy to follow and evaluate.");
+    const score = objectives.voice_divergence * 14 +
+        objectives.diagnosis * 20 +
+        objectives.verification * 18 +
+        objectives.retrieval * 18 +
+        objectives.transfer * 16 +
+        objectives.structure * 14;
+    return {
+        promptPath,
+        promptName: promptNameFromPath(promptPath),
+        score,
+        objectives,
+        feedback
+    };
+}
+function heuristicCandidatePrompt(basePrompt) {
+    const frontMatter = parseFrontMatter(basePrompt);
+    const body = parsePromptBody(basePrompt).trimEnd();
+    const additions = [
+        '4a. If the learner echoes your phrasing, stop and ask them to explain the idea again in their own words.',
+        '4b. Separate missing prerequisite, misconception, and partial intuition before choosing the next teaching move.',
+        '5a. Add one short retrieval checkpoint that the learner must answer without relying on your wording.',
+        '6a. Bridge the idea into a new domain, personal example, or practical consequence before ending.',
+        '6b. Mark any factual claim that still needs verification instead of presenting it as settled.'
+    ].filter((line) => !body.includes(line));
+    const evolvedBody = additions.length === 0 ? `${body}\n7a. Keep the learner cognitively active at every step.` : `${body}\n${additions.join("\n")}`;
+    return frontMatter ? `${frontMatter}\n${evolvedBody}\n` : `${evolvedBody}\n`;
+}
+export async function evaluatePromptContent(cwd, promptPath, prompt) {
+    const body = parsePromptBody(prompt);
+    const evalPrompt = `Evaluate the following teaching prompt template based on Keating's hyperteacher philosophy.
+Keating philosophy:
+- AI must not be a surrogate for thought.
+- Measuring success by the learner's independent articulation (finding their "voice").
+- Rejecting "surface agreement" (rote echoes or simple "yes/no" answers).
+- The "diagnose -> intuition -> formal core -> misconception repair -> example -> retrieval -> reflection" loop.
+
+Evaluate these objectives on a scale of 0 to 1 (floating point):
+1. voice_divergence: How well does the prompt force the learner to use their own language? Penalize prompts that allow the learner to echo the AI's explanation.
+2. diagnosis: Checking prerequisites and misconceptions before teaching.
+3. verification: Refusing to teach unverified claims as settled truth.
+4. retrieval: Using reconstruction and practice instead of passive agreement.
+5. transfer: Bridging the concept to other domains or practical consequences.
+6. structure: Having an explicit, logical teaching workflow.
+
+Provide the evaluation in JSON format:
+{
+  "objectives": {
+    "voice_divergence": number,
+    "diagnosis": number,
+    "verification": number,
+    "retrieval": number,
+    "transfer": number,
+    "structure": number
+  },
+  "feedback": string[]
+}
+
+Prompt Content:
+"""
+${body}
+"""
+`;
+    if (piAvailabilityCache === false) {
+        return heuristicPromptEvaluation(promptPath, prompt);
+    }
+    let data;
+    try {
+        data = await piCompleteJson(cwd, evalPrompt, { thinking: "low" });
+        piAvailabilityCache = true;
+    }
+    catch {
+        piAvailabilityCache = false;
+        const heuristic = heuristicPromptEvaluation(promptPath, prompt);
+        return heuristic;
+    }
+    // Guard against missing objectives in response
+    if (!data?.objectives) {
+        return heuristicPromptEvaluation(promptPath, prompt);
+    }
+    const objectives = data.objectives;
+    const score = objectives.voice_divergence * 14 +
+        objectives.diagnosis * 20 +
+        objectives.verification * 18 +
+        objectives.retrieval * 18 +
+        objectives.transfer * 16 +
+        objectives.structure * 14;
+    return {
+        promptPath,
+        promptName: promptNameFromPath(promptPath),
+        score,
+        objectives,
+        feedback: data.feedback
+    };
+}
+async function generateCandidatePrompt(cwd, basePrompt, evaluation, iteration) {
+    const frontMatter = parseFrontMatter(basePrompt);
+    const body = parsePromptBody(basePrompt);
+    const generationPrompt = `You are Keating's prompt-learning agent. Your goal is to evolve a teaching prompt template so that it prevents "surface agreement" and forces the learner to find their own voice.
+
+Original Prompt:
+"""
+${body}
+"""
+
+Feedback:
+${evaluation.feedback.map(f => `- ${f}`).join("\n")}
+
+Mandate:
+1. PUSH FOR DIVERGENCE: Add instructions that force the learner to re-explain the concept using their own analogies or personal context.
+2. REJECT ECHOES: Instruct the teacher to identify if the learner is just repeating words from the previous explanation and, if so, ask them to "say it again, but as if you're explaining it to someone else entirely."
+3. ADDRESS FEEDBACK: Address the specific gaps in diagnosis, verification, and structure.
+
+Evolved Prompt Body (no code blocks, no frontmatter):`;
+    if (piAvailabilityCache === false) {
+        return heuristicCandidatePrompt(basePrompt);
+    }
+    let evolvedBody;
+    try {
+        evolvedBody = await piComplete(cwd, generationPrompt, { thinking: "medium" });
+        piAvailabilityCache = true;
+    }
+    catch {
+        piAvailabilityCache = false;
+        return heuristicCandidatePrompt(basePrompt);
+    }
+    return frontMatter ? `${frontMatter}\n${evolvedBody}\n` : `${evolvedBody}\n`;
+}
+function objectiveVector(candidate) {
+    const { objectives } = candidate.evaluation;
+    return [
+        objectives.voice_divergence,
+        objectives.diagnosis,
+        objectives.verification,
+        objectives.retrieval,
+        objectives.transfer,
+        objectives.structure
+    ];
+}
+function pairwisePreference(left, right) {
+    const leftVector = objectiveVector(left);
+    const rightVector = objectiveVector(right);
+    let wins = 0;
+    let losses = 0;
+    for (let index = 0; index < leftVector.length; index += 1) {
+        if (leftVector[index] > rightVector[index])
+            wins += 1;
+        if (leftVector[index] < rightVector[index])
+            losses += 1;
+    }
+    const aggregateDelta = left.evaluation.score - right.evaluation.score;
+    return wins - losses + aggregateDelta / 25;
+}
+export function prosperStyleWinner(candidates) {
+    let best = candidates[0];
+    let bestScore = -Infinity;
+    for (const candidate of candidates) {
+        const score = candidates.reduce((sum, opponent) => {
+            if (candidate === opponent)
+                return sum;
+            return sum + pairwisePreference(candidate, opponent);
+        }, 0);
+        candidate.preferenceScore = score;
+        if (score > bestScore) {
+            best = candidate;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+async function loadArchive(archivePath) {
+    try {
+        const raw = await readFile(archivePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { winners: [] };
+    }
+}
+async function saveArchive(archivePath, archive) {
+    await writeFile(archivePath, `${JSON.stringify(archive, null, 2)}\n`, "utf8");
+}
+export async function evolvePrompt(cwd, promptName = "learn", iterations = 4, evaluator = evaluatePromptContent, generator = generateCandidatePrompt) {
+    const promptPath = join(cwd, "pi", "prompts", `${promptName}.md`);
+    const prompt = await readFile(promptPath, "utf8");
+    const baseline = await evaluator(cwd, promptPath, prompt);
+    const candidates = [];
+    for (let iteration = 1; iteration <= iterations; iteration += 1) {
+        const candidatePrompt = await generator(cwd, prompt, baseline, iteration);
+        const evaluation = await evaluator(cwd, promptPath, candidatePrompt);
+        candidates.push({
+            iteration,
+            label: `${promptName}-candidate-${iteration}`,
+            prompt: candidatePrompt,
+            evaluation,
+            parentLabel: promptName,
+            accepted: false,
+            preferenceScore: 0
+        });
+    }
+    const best = prosperStyleWinner(candidates);
+    for (const candidate of candidates) {
+        candidate.accepted = candidate.label === best.label && candidate.evaluation.score >= baseline.score;
+    }
+    const archivePath = promptEvolutionArchivePath(cwd);
+    const archive = await loadArchive(archivePath);
+    archive.winners.push({
+        promptName,
+        label: best.label,
+        score: best.evaluation.score,
+        objectives: best.evaluation.objectives,
+        updatedAt: new Date().toISOString()
+    });
+    await saveArchive(archivePath, archive);
+    return {
+        promptPath,
+        promptName,
+        baseline,
+        best,
+        exploredCandidates: candidates,
+        acceptedCandidates: candidates.filter((candidate) => candidate.accepted)
+    };
+}
+export async function writePromptEvolutionArtifacts(cwd, promptName = "learn") {
+    const run = await evolvePrompt(cwd, promptName);
+    const reportPath = join(promptEvolutionDir(cwd), `${promptName}.md`);
+    const evolvedPromptPath = join(promptEvolutionDir(cwd), `${promptName}.evolved.md`);
+    await writeFile(reportPath, promptEvolutionToMarkdown(run), "utf8");
+    await writeFile(evolvedPromptPath, run.best.prompt, "utf8");
+    return {
+        reportPath,
+        evolvedPromptPath,
+        bestScore: run.best.evaluation.score,
+        promptPath: run.promptPath
+    };
+}
+export function promptEvolutionToMarkdown(run) {
+    const objectiveList = (objectives) => [
+        `voice_divergence=${objectives.voice_divergence.toFixed(2)}`,
+        `diagnosis=${objectives.diagnosis.toFixed(2)}`,
+        `verification=${objectives.verification.toFixed(2)}`,
+        `retrieval=${objectives.retrieval.toFixed(2)}`,
+        `transfer=${objectives.transfer.toFixed(2)}`,
+        `structure=${objectives.structure.toFixed(2)}`
+    ];
+    const lines = [
+        `# Prompt Evolution Report: ${run.promptName}`,
+        "",
+        `- Source prompt: ${run.promptPath}`,
+        `- Baseline score: ${run.baseline.score.toFixed(2)}`,
+        `- Best candidate: ${run.best.label}`,
+        `- Best candidate score: ${run.best.evaluation.score.toFixed(2)}`,
+        `- PROSPER-style preference score: ${run.best.preferenceScore.toFixed(2)}`,
+        "",
+        "## Baseline Feedback",
+        ""
+    ];
+    if (run.baseline.feedback.length === 0) {
+        lines.push("- No major prompt-learning gaps detected.");
+    }
+    else {
+        for (const item of run.baseline.feedback) {
+            lines.push(`- ${item}`);
+        }
+    }
+    lines.push("");
+    lines.push("## Candidate Comparison");
+    lines.push("");
+    for (const candidate of run.exploredCandidates) {
+        lines.push(`### ${candidate.label}`);
+        lines.push(`- score: ${candidate.evaluation.score.toFixed(2)}`);
+        lines.push(`- preference: ${candidate.preferenceScore.toFixed(2)}`);
+        lines.push(`- accepted: ${candidate.accepted ? "yes" : "no"}`);
+        lines.push(`- objectives: ${objectiveList(candidate.evaluation.objectives).join(", ")}`);
+        lines.push("");
+    }
+    lines.push("## Recommended Prompt");
+    lines.push("```md");
+    lines.push(run.best.prompt.trimEnd());
+    lines.push("```");
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+import { learnPrompt } from "./ax-prompt-learner.js";
+export async function evolveWithACE(cwd, promptName = "learn", options) {
+    return learnPrompt(cwd, promptName, options);
+}