@koan-labs/koan 0.2.0

package/dist/core/schemas.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+export const StrictnessSchema = z.enum(["advisory", "strict"]);
+export const LanguageSchema = z.enum(["ko", "en", "mixed"]);
+export const DevelopmentUnderstandingSchema = z.enum([
+    "non_technical",
+    "beginner",
+    "intermediate",
+    "expert"
+]);
+export const ExplanationStyleSchema = z.enum([
+    "short",
+    "example_first",
+    "step_by_step",
+    "technical_ok"
+]);
+export const OutputUseSchema = z.enum([
+    "self_implementation",
+    "agent_execution",
+    "team_sharing",
+    "learning"
+]);
+export const LearningModeSchema = z.enum(["approval_required", "auto_with_review"]);
+export const UserProfileSchema = z.object({
+    developmentUnderstanding: DevelopmentUnderstandingSchema,
+    explanationStyle: ExplanationStyleSchema,
+    language: LanguageSchema,
+    outputUse: OutputUseSchema,
+    domainBackground: z.string(),
+    learningMode: LearningModeSchema
+});
+export const DEFAULT_CONVERGENCE_THRESHOLD = 0.7;
+export const ProjectSettingsSchema = z
+    .object({ convergenceThreshold: z.number().min(0).max(1) })
+    .default({ convergenceThreshold: DEFAULT_CONVERGENCE_THRESHOLD });
+export const ProjectConfigSchema = z.object({
+    version: z.literal(1),
+    koanVersion: z.string(),
+    projectRoot: z.string(),
+    strictness: StrictnessSchema,
+    experimentalHandoff: z.boolean(),
+    documents: z.object({
+        readme: z.string(),
+        goal: z.string(),
+        status: z.string(),
+        plan: z.string()
+    }),
+    settings: ProjectSettingsSchema
+});
+export const AmbiguityAxisSchema = z.enum([
+    "purpose",
+    "target_users",
+    "current_goal",
+    "scope",
+    "non_goals",
+    "constraints",
+    "success_criteria",
+    "philosophical_intent",
+    "implementation_plan",
+    "qa_criteria",
+    "handoff_readiness"
+]);
+export const AxisScoreSchema = z.object({
+    axis: AmbiguityAxisSchema,
+    clarity: z.number().min(0).max(1),
+    evidence: z.array(z.string()),
+    updatedAt: z.string()
+});
+export const AmbiguityLedgerSchema = z.object({
+    version: z.literal(1),
+    goalId: z.string(),
+    axes: z.array(AxisScoreSchema)
+});
+export const AnswerRecordSchema = z.object({
+    questionId: z.string(),
+    axis: AmbiguityAxisSchema,
+    question: z.string(),
+    answer: z.string(),
+    recordedAt: z.string()
+});
+export const SessionStateSchema = z.object({
+    version: z.literal(1),
+    sessionId: z.string(),
+    activeGoalId: z.string().nullable(),
+    phase: z.enum(["setup", "questioning", "crystallizing", "ready", "archived"]),
+    lastQuestionId: z.string().nullable(),
+    answers: z.array(AnswerRecordSchema).default([]),
+    updatedAt: z.string()
+});
+export const WritePlanOperationSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("write"), path: z.string(), content: z.string() }),
+    z.object({
+        type: z.literal("append"),
+        path: z.string(),
+        content: z.string(),
+        headerIfMissing: z.string().optional()
+    }),
+    z.object({
+        type: z.literal("managed-region"),
+        path: z.string(),
+        name: z.string(),
+        content: z.string()
+    })
+]);
+export const WritePlanSchema = z.object({
+    description: z.string(),
+    operations: z.array(WritePlanOperationSchema)
+});
+export const CommandLogEntrySchema = z.object({
+    at: z.string(),
+    command: z.string(),
+    summary: z.string()
+});
+export const CommandLogSchema = z.object({
+    version: z.literal(1),
+    entries: z.array(CommandLogEntrySchema)
+});
+export const UserProfileRefSchema = z.object({
+    version: z.literal(1),
+    profilePath: z.string(),
+    overrides: UserProfileSchema.partial()
+});
+export const QuestionContextSchema = z.object({
+    sessionId: z.string(),
+    axis: AmbiguityAxisSchema,
+    questionId: z.string(),
+    askedAt: z.string()
+});
+export const McpCacheSchema = z.object({
+    version: z.literal(1),
+    lastQuestion: QuestionContextSchema.nullable(),
+    rawIntent: z.string().nullable().default(null)
+});

package/dist/core/scoring.d.ts

@@ -0,0 +1,9 @@
+import { type AmbiguityAxis, type AmbiguityLedger } from "./schemas.js";
+export declare const ANSWERED_CLARITY = 0.8;
+export declare const AXIS_PRIORITY: readonly AmbiguityAxis[];
+export declare function createInitialLedger(goalId: string, isoDate?: string): AmbiguityLedger;
+export declare function selectMostUnclearAxis(ledger: AmbiguityLedger): AmbiguityAxis;
+export declare function updateAxisScore(ledger: AmbiguityLedger, axis: AmbiguityAxis, clarity: number, evidence: string, isoDate?: string): AmbiguityLedger;
+export declare function loadLedger(projectRoot: string): Promise<AmbiguityLedger | null>;
+export declare function isConverged(ledger: AmbiguityLedger, threshold: number): boolean;
+export declare function unresolvedAxes(ledger: AmbiguityLedger, threshold: number): AmbiguityAxis[];

package/dist/core/scoring.js

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { STATE_FILES } from "./constants.js";
+import { AmbiguityAxisSchema, AmbiguityLedgerSchema } from "./schemas.js";
+export const ANSWERED_CLARITY = 0.8;
+// Question priority for equally-unclear axes: the why layer (purpose,
+// philosophical_intent) leads a fresh session before goal shaping and
+// implementation planning.
+export const AXIS_PRIORITY = [
+    "purpose",
+    "philosophical_intent",
+    "current_goal",
+    "target_users",
+    "scope",
+    "non_goals",
+    "constraints",
+    "success_criteria",
+    "implementation_plan",
+    "qa_criteria",
+    "handoff_readiness"
+];
+const priorityIndex = new Map(AXIS_PRIORITY.map((axis, index) => [axis, index]));
+function axisPriority(axis) {
+    return priorityIndex.get(axis) ?? AXIS_PRIORITY.length;
+}
+export function createInitialLedger(goalId, isoDate = new Date().toISOString()) {
+    return {
+        version: 1,
+        goalId,
+        axes: AmbiguityAxisSchema.options.map((axis) => ({
+            axis,
+            clarity: 0,
+            evidence: [],
+            updatedAt: isoDate
+        }))
+    };
+}
+export function selectMostUnclearAxis(ledger) {
+    const sorted = [...ledger.axes].sort((a, b) => a.clarity - b.clarity || axisPriority(a.axis) - axisPriority(b.axis));
+    return sorted[0]?.axis ?? "purpose";
+}
+export function updateAxisScore(ledger, axis, clarity, evidence, isoDate = new Date().toISOString()) {
+    return {
+        ...ledger,
+        axes: ledger.axes.map((entry) => entry.axis === axis
+            ? {
+                ...entry,
+                clarity: Math.max(0, Math.min(1, clarity)),
+                evidence: evidence ? [...entry.evidence, evidence] : entry.evidence,
+                updatedAt: isoDate
+            }
+            : entry)
+    };
+}
+export async function loadLedger(projectRoot) {
+    try {
+        const raw = await readFile(join(projectRoot, STATE_FILES.ambiguityLedger), "utf8");
+        return AmbiguityLedgerSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+export function isConverged(ledger, threshold) {
+    return ledger.axes.every((entry) => entry.clarity >= threshold);
+}
+export function unresolvedAxes(ledger, threshold) {
+    return ledger.axes
+        .filter((entry) => entry.clarity < threshold)
+        .sort((a, b) => a.clarity - b.clarity || axisPriority(a.axis) - axisPriority(b.axis))
+        .map((entry) => entry.axis);
+}

package/dist/core/session.d.ts

@@ -0,0 +1,6 @@
+import { type CommandLogInput } from "./commandLog.js";
+import { type SessionState } from "./schemas.js";
+export declare function createSessionState(activeGoalId: string | null, isoDate?: string): SessionState;
+export declare function loadSessionState(projectRoot: string): Promise<SessionState | null>;
+export declare function goalIdFromDate(isoDate?: string): string;
+export declare function archiveGoal(projectRoot: string, goalId: string, log?: CommandLogInput): Promise<void>;

package/dist/core/session.js

@@ -0,0 +1,88 @@
+import { access, copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { appendCommandLogInLock } from "./commandLog.js";
+import { CORE_DOCUMENTS, LAZY_DOCUMENTS, STATE_FILES } from "./constants.js";
+import { replaceManagedRegion } from "./documents.js";
+import { ensureStateGitignore } from "./gitPolicy.js";
+import { withFileLock } from "./lock.js";
+import { SessionStateSchema } from "./schemas.js";
+export function createSessionState(activeGoalId, isoDate = new Date().toISOString()) {
+    return {
+        version: 1,
+        sessionId: randomUUID(),
+        activeGoalId,
+        phase: activeGoalId ? "questioning" : "setup",
+        lastQuestionId: null,
+        answers: [],
+        updatedAt: isoDate
+    };
+}
+export async function loadSessionState(projectRoot) {
+    try {
+        const raw = await readFile(join(projectRoot, STATE_FILES.sessionState), "utf8");
+        return SessionStateSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+// Caller must hold the project write lock or be the locked write-plan path.
+async function persistSessionState(projectRoot, state) {
+    const path = join(projectRoot, STATE_FILES.sessionState);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+export function goalIdFromDate(isoDate = new Date().toISOString()) {
+    return `goal-${isoDate.replace(/[:.]/g, "-")}`;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function archiveGoal(projectRoot, goalId, log) {
+    const safeGoalId = basename(goalId);
+    if (!safeGoalId || safeGoalId === "." || safeGoalId === "..") {
+        throw new Error(`Invalid goal id: ${goalId}`);
+    }
+    await withFileLock(projectRoot, async () => {
+        await ensureStateGitignore(projectRoot);
+        const archiveRoot = join(projectRoot, "koan/archive", safeGoalId);
+        await mkdir(archiveRoot, { recursive: true });
+        const files = [
+            CORE_DOCUMENTS.goal,
+            CORE_DOCUMENTS.plan,
+            CORE_DOCUMENTS.status,
+            LAZY_DOCUMENTS.decisions,
+            LAZY_DOCUMENTS.qa,
+            LAZY_DOCUMENTS.handoff
+        ];
+        for (const relative of files) {
+            const source = join(projectRoot, relative);
+            if (await exists(source)) {
+                await copyFile(source, join(archiveRoot, basename(relative)));
+            }
+        }
+        const goalPath = join(projectRoot, CORE_DOCUMENTS.goal);
+        const currentGoal = await readFile(goalPath, "utf8").catch(() => "# Goal\n");
+        await writeFile(goalPath, replaceManagedRegion(currentGoal, "active-goal", `No active goal yet.\n\nArchived goal: ${safeGoalId}`), "utf8");
+        await rm(join(projectRoot, STATE_FILES.ambiguityLedger), { force: true });
+        const state = await loadSessionState(projectRoot);
+        if (state) {
+            await persistSessionState(projectRoot, {
+                ...state,
+                activeGoalId: null,
+                phase: "archived",
+                updatedAt: new Date().toISOString()
+            });
+        }
+        if (log) {
+            await appendCommandLogInLock(projectRoot, log);
+        }
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./core/constants.js";
+export * from "./core/schemas.js";
+export * from "./core/lock.js";
+export * from "./core/project.js";
+export * from "./core/documents.js";
+export * from "./core/profile.js";
+export * from "./core/profileRef.js";
+export * from "./core/commandLog.js";
+export * from "./core/mcpCache.js";
+export * from "./core/questions.js";
+export * from "./core/scoring.js";
+export * from "./core/session.js";
+export * from "./core/reconstruct.js";
+export * from "./core/answers.js";
+export * from "./core/crystallize.js";
+export * from "./core/commands.js";
+export * from "./core/hostAdapter.js";
+export * from "./core/prd.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+export * from "./core/constants.js";
+export * from "./core/schemas.js";
+export * from "./core/lock.js";
+export * from "./core/project.js";
+export * from "./core/documents.js";
+export * from "./core/profile.js";
+export * from "./core/profileRef.js";
+export * from "./core/commandLog.js";
+export * from "./core/mcpCache.js";
+export * from "./core/questions.js";
+export * from "./core/scoring.js";
+export * from "./core/session.js";
+export * from "./core/reconstruct.js";
+export * from "./core/answers.js";
+export * from "./core/crystallize.js";
+export * from "./core/commands.js";
+export * from "./core/hostAdapter.js";
+export * from "./core/prd.js";

package/dist/mcp/server.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare const toolNames: readonly ["koan_get_profile", "koan_update_profile", "koan_inspect_project", "koan_start_session", "koan_get_next_question", "koan_record_answer", "koan_crystallize_documents", "koan_get_status", "koan_update_status", "koan_record_bright_idea", "koan_record_insight", "koan_synthesize_prd", "koan_prepare_qa", "koan_prepare_handoff"];
+export declare function createServer(): Server;
+export declare function runServer(): Promise<void>;