@koan-labs/koan 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kwon Dong-in
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# Koan
+
+Koan is a local-first philosophical PRD tool. It helps you clarify why a
+product should exist — before asking humans or AI agents to build it — and
+crystallizes that intent into readable project documents: philosophy, goals,
+plans, status, QA criteria, bright ideas, and handoff notes.
+
+Named after the Zen practice, Koan asks one reflective question at a time,
+starting from purpose and philosophy rather than feature lists. The result is
+durable project memory that people can read and that AI agents — Codex,
+Claude, and any MCP-capable agent — can consume to build faithfully without
+losing your intent.
+
+Koan is MCP-first, but not LLM-provider-first. It never calls an LLM API and
+never transmits project data over the network. The core tool is deterministic;
+host agents provide semantic reasoning through MCP.
+
+## Install
+
+Requires Node.js 20+.
+
+```bash
+npm install -g @koan-labs/koan
+```
+
+## CLI
+
+The CLI works standalone with deterministic question templates; no host agent
+or API key is required.
+
+- `koan hello` — initialize or resume a session; runs the question loop on a
+  TTY (force it with `--interactive`).
+- `koan hello --setup` — guided profile setup.
+- `koan hello --profile` — print the global profile (read-only).
+- `koan hello --reset-profile [--yes]` — delete the global profile (`--yes`
+  skips confirmation).
+- `koan status` — show goal, status, and next action without writing.
+- `koan status --update <text>` — record a status update.
+- `koan status --archive` — archive the active goal to `koan/archive/<goal-id>/`.
+- `koan answer <axis> <text>` — record an answer for one ambiguity axis.
+- `koan enough` — accept current clarity and stop questioning.
+- `koan crystallize [--dry-run]` — write recorded answers into documents;
+  `--dry-run` previews the write plan.
+- `koan bright-idea [--classify <type>] <text>` — record an idea without
+  changing the plan; types: `clarify`, `change-goal`, `later-follow-up`, `reject`.
+- `koan insight <text>` — append a product realization (the moment the real
+  product turns out to differ from the surface request) to `koan/philosophy.md`.
+- `koan prd [--dry-run]` — synthesize `koan/prd.md` from recorded answers,
+  philosophy first.
+- `koan qa` — create or refresh the QA checklist.
+- `koan handoff <summary>` — create a document-based handoff.
+
+## MCP Server
+
+Run `koan-mcp` (stdio transport) and register it with your MCP-capable agent.
+From a checkout, `npm run mcp` starts the same server.
+
+| Tool | Purpose |
+| ---- | ------- |
+| `koan_get_profile` | Read the global profile, learning mode, and per-project overrides. |
+| `koan_update_profile` | Apply a partial profile update; reports changed fields. |
+| `koan_inspect_project` | Report Koan state, bootstrap markers, document paths, and git policy. |
+| `koan_start_session` | Initialize or resume a session; optionally captures raw intent and echoes the stored `rawIntent`. |
+| `koan_get_next_question` | Return the question for the most unclear axis and cache it. |
+| `koan_record_answer` | Record an answer (axis from input or the cached question) with optional host interpretation; returns a crystallize preview. |
+| `koan_crystallize_documents` | Write recorded answers into managed document regions (`dryRun` supported). |
+| `koan_get_status` | Summarize goal, status, next action, stale-state warnings, and the stored `rawIntent`. |
+| `koan_update_status` | Write a status update into `koan/status.md` and the handoff document; reports the affected files. |
+| `koan_record_bright_idea` | Record a classified idea plus a deterministic recommendation. |
+| `koan_record_insight` | Append a product realization to `koan/philosophy.md` (append-only insight log). |
+| `koan_synthesize_prd` | Synthesize `koan/prd.md`; hosts may supply vision, core value, problem/anti-problem, and user stories grounded in recorded answers. |
+| `koan_prepare_qa` | Generate `koan/qa.md` with spec-compliance and quality checks; embeds an optional implementation summary and returns the checklist. |
+| `koan_prepare_handoff` | Generate `koan/handoff.md` (summary text optional); returns the document and next action; touchless handoff stays disabled. |
+
+All tool results are JSON in the first text content block; inputs are
+zod-validated and failures surface as MCP errors.
+
+Koan uses a semantic-host model: the core stays deterministic (state, scoring,
+managed document writes) while the host agent supplies interpretation —
+rephrasing questions, structuring answers, and scoring clarity through
+`interpretation.clarity` on `koan_record_answer`. Without a host, the CLI runs
+the same flow with built-in templates.
+
+## Project Files
+
+Human-facing memory lives in `koan/`; machine state lives in `.koan/`.
+
+- Core documents (always created): `koan/README.md`, `koan/goal.md`,
+  `koan/status.md`, `koan/plan.md`.
+- Lazy documents (created on first use): `koan/philosophy.md`,
+  `koan/decisions.md`, `koan/open-questions.md`, `koan/qa.md`,
+  `koan/handoff.md`, `koan/bright-ideas.md`, `koan/prd.md`.
+- State: `.koan/project.json` is intended to be committed; session state, the
+  ambiguity ledger, command log, MCP cache, and lock files are ignored through
+  a generated `.koan/.gitignore`.
+
+Koan only rewrites its own managed regions (`<!-- koan:section:start ... -->`);
+manual edits outside the markers are preserved.
+
+## Question Model
+
+Koan tracks clarity across 11 ambiguity axes: `purpose`, `target_users`,
+`current_goal`, `scope`, `non_goals`, `constraints`, `success_criteria`,
+`philosophical_intent`, `implementation_plan`, `qa_criteria`, and
+`handoff_readiness`.
+
+A new session starts at the why layer: `purpose` and `philosophical_intent`
+are asked before goal shaping and implementation planning, so the deeper
+reason behind the product is captured before features are specified. Users
+who want a shorter path can answer briefly and run `koan enough` at any time
+to accept the current clarity and move on.
+
+Question phrasing adapts to the user profile: language (`ko`, `en`, `mixed`)
+crossed with four development-understanding levels. A goal converges when every
+axis reaches the convergence threshold (default `0.7`), configurable as
+`settings.convergenceThreshold` in `.koan/project.json`. Crystallized
+documents put philosophy first; `koan/philosophy.md` is the document future
+contributors and agents should read before changing scope.
+
+`koan prd` synthesizes the answers into a single PRD (`koan/prd.md`) ordered
+philosophy-first: the deterministic core fills every section it has answers
+for, and host agents may enrich the vision, core-value, problem/anti-problem,
+and user-story sections through `koan_synthesize_prd` — always grounded in
+what the user actually said. `koan insight` keeps an append-only log of the
+moments when the real product turned out to differ from the surface request.
+
+Instructions to host agents adapt to the connected MCP client (detected
+locally from the MCP handshake — Claude, Codex/OpenAI, or generic): the
+phrasing follows each model family's prompting guidance while the contract
+stays identical across hosts. See `docs/host-adapters.md`.
+
+## Privacy
+
+Koan has no telemetry and does not transmit profile, project, or answer data
+over the network. The global user profile is stored at `~/.koan/profile.json`.
+Profile inference is allowlist-only: hosts may propose updates to the declared
+profile fields and nothing else, and the default `approval_required` learning
+mode keeps changes user-approved.

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/main.js

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { acceptClarity, recordAnswer } from "../core/answers.js";
+import { archive, brightIdea, handoff, hello, qa, recordInsight, status, updateStatus } from "../core/commands.js";
+import { crystallize } from "../core/crystallize.js";
+import { buildPrd } from "../core/prd.js";
+import { defaultProfile, loadProfile, resetProfile, saveProfile } from "../core/profile.js";
+import { getQuestion } from "../core/questions.js";
+import { ANSWERED_CLARITY } from "../core/scoring.js";
+import { createPrompter } from "./prompt.js";
+const BRIGHT_IDEA_CLASSIFICATIONS = [
+    "clarify",
+    "change-goal",
+    "later-follow-up",
+    "reject"
+];
+const DEVELOPMENT_UNDERSTANDING_OPTIONS = ["non_technical", "beginner", "intermediate", "expert"];
+const EXPLANATION_STYLE_OPTIONS = ["short", "example_first", "step_by_step", "technical_ok"];
+const LANGUAGE_OPTIONS = ["ko", "en", "mixed"];
+const OUTPUT_USE_OPTIONS = ["self_implementation", "agent_execution", "team_sharing", "learning"];
+const LEARNING_MODE_OPTIONS = ["approval_required", "auto_with_review"];
+const COMMAND_CONTRACTS = {
+    hello: {
+        flags: ["--interactive", "--setup", "--profile", "--reset-profile", "--yes"],
+        positionals: "none",
+        requires: { "--yes": "--reset-profile" }
+    },
+    status: { flags: ["--update", "--archive"], positionals: "none-unless-update-text" },
+    answer: { flags: [], positionals: "axis-then-text" },
+    enough: { flags: [], positionals: "none" },
+    crystallize: { flags: ["--dry-run"], positionals: "none" },
+    "bright-idea": { flags: ["--classify"], positionals: "text" },
+    insight: { flags: [], positionals: "text" },
+    prd: { flags: ["--dry-run"], positionals: "none" },
+    qa: { flags: [], positionals: "none" },
+    handoff: { flags: [], positionals: "text" }
+};
+let prompter = null;
+function getPrompter() {
+    prompter ??= createPrompter();
+    return prompter;
+}
+function usage() {
+    return [
+        "Usage: koan <command>",
+        "",
+        "Commands:",
+        "  hello [--interactive]      initialize or resume Koan; run the question loop",
+        "  hello --setup              run guided profile setup",
+        "  hello --profile            print the global profile (read-only)",
+        "  hello --reset-profile      delete the global profile (--yes skips confirmation)",
+        "  status                     show project status without writing by default",
+        "  status --update <text>     record a status update",
+        "  status --archive           archive the active goal",
+        "  answer <axis> <text>       record an answer for an ambiguity axis",
+        "  enough                     accept current clarity and stop questioning",
+        "  crystallize [--dry-run]    write recorded answers into project documents",
+        "  bright-idea [--classify <type>] <text>",
+        "                             record a new idea without changing the plan",
+        "  insight <text>             append a product realization to philosophy.md",
+        "  prd [--dry-run]            synthesize koan/prd.md from recorded answers",
+        "  qa                         create or refresh QA checklist",
+        "  handoff <summary>          create document-based handoff",
+        "                             (summaries beginning with \"--\" are unsupported)"
+    ].join("\n");
+}
+async function runProfileSetup(prompt, homeDir) {
+    const profile = defaultProfile();
+    let ended = false;
+    const choose = async (question, options, fallback) => {
+        if (ended)
+            return fallback;
+        const line = await prompt.ask(question);
+        if (line === null) {
+            ended = true;
+            return fallback;
+        }
+        if (/^[0-9]+$/.test(line))
+            return options[Number.parseInt(line, 10) - 1] ?? fallback;
+        return options.find((option) => option === line) ?? fallback;
+    };
+    profile.developmentUnderstanding = await choose("Development understanding [1 non_technical / 2 beginner / 3 intermediate / 4 expert] (2): ", DEVELOPMENT_UNDERSTANDING_OPTIONS, profile.developmentUnderstanding);
+    profile.explanationStyle = await choose("Explanation style [1 short / 2 example_first / 3 step_by_step / 4 technical_ok] (2): ", EXPLANATION_STYLE_OPTIONS, profile.explanationStyle);
+    profile.language = await choose("Language [1 ko / 2 en / 3 mixed] (1): ", LANGUAGE_OPTIONS, profile.language);
+    profile.outputUse = await choose("Output use [1 self_implementation / 2 agent_execution / 3 team_sharing / 4 learning] (2): ", OUTPUT_USE_OPTIONS, profile.outputUse);
+    if (!ended) {
+        const background = await prompt.ask("Domain background (free text, empty ok): ");
+        if (background === null)
+            ended = true;
+        else
+            profile.domainBackground = background;
+    }
+    profile.learningMode = await choose("Learning mode [1 approval_required / 2 auto_with_review] (1): ", LEARNING_MODE_OPTIONS, profile.learningMode);
+    await saveProfile(homeDir, profile);
+    console.log("Profile saved.");
+}
+async function runInteractiveHello(input) {
+    const { cwd, homeDir, result, prompt } = input;
+    if (input.firstRun)
+        await runProfileSetup(prompt, homeDir);
+    const profile = (await loadProfile(homeDir)) ?? defaultProfile();
+    let question = result.nextQuestion
+        ? getQuestion(result.nextQuestion.axis, profile)
+        : null;
+    if (result.resumed && result.lastAnswer) {
+        console.log(`Last answer (${result.lastAnswer.axis}): ${result.lastAnswer.answer}`);
+        let resumeChoice = null;
+        while (resumeChoice === null) {
+            const choice = await prompt.ask("Resume: [c]ontinue, [r]evise last answer, [s]top? ");
+            if (choice === null || choice === "s")
+                resumeChoice = "stop";
+            else if (choice === "r")
+                resumeChoice = "revise";
+            else if (choice === "c" || choice === "")
+                resumeChoice = "continue";
+            else
+                console.log(`Unrecognized choice: ${choice}`);
+        }
+        if (resumeChoice === "stop") {
+            console.log("Stopped. Run koan hello to continue.");
+            return 0;
+        }
+        if (resumeChoice === "revise")
+            question = getQuestion(result.lastAnswer.axis, profile);
+    }
+    while (question) {
+        console.log(question.userFacingQuestion);
+        const line = await prompt.ask("> ");
+        if (line === null || line === "stop" || line === "quit") {
+            console.log("Stopped. Run koan hello to continue.");
+            return 0;
+        }
+        if (line === "enough") {
+            await acceptClarity({ cwd });
+            console.log("Accepted current clarity.");
+            break;
+        }
+        if (line === "")
+            continue;
+        const recorded = await recordAnswer({ cwd, homeDir, axis: question.axis, answer: line });
+        console.log(`Recorded ${question.axis} (clarity ${ANSWERED_CLARITY}).`);
+        if (recorded.converged)
+            console.log("All axes converged.");
+        question = recorded.nextQuestion;
+    }
+    const crystallized = await crystallize({ cwd, homeDir });
+    console.log(`Crystallized ${crystallized.crystallizedAxes.length} axes.`);
+    console.log("Session complete.");
+    return 0;
+}
+function parseLeadingFlags(args, known) {
+    const flags = [];
+    let index = 0;
+    while (index < args.length && args[index].startsWith("--")) {
+        const token = args[index];
+        if (!known.includes(token))
+            return { flags, text: args.slice(index), unknown: token };
+        flags.push(token);
+        index += 1;
+    }
+    return { flags, text: args.slice(index), unknown: null };
+}
+function contractViolation(message) {
+    console.error(message);
+    console.error(usage());
+    return null;
+}
+// Shared contract enforcement for every command: unknown leading flags,
+// unexpected positional operands, and flag dependencies are all rejected here
+// (null is returned after printing the error) before any handler runs.
+function parseCommandArgs(command, args) {
+    const contract = COMMAND_CONTRACTS[command];
+    const parsed = parseLeadingFlags(args, contract.flags);
+    if (parsed.unknown !== null) {
+        return contractViolation(`Unknown flag for koan ${command}: ${parsed.unknown}`);
+    }
+    const textAllowed = contract.positionals === "text" ||
+        contract.positionals === "axis-then-text" ||
+        (contract.positionals === "none-unless-update-text" && parsed.flags.includes("--update"));
+    if (!textAllowed && parsed.text.length > 0) {
+        return contractViolation(`Unexpected argument for koan ${command}: ${parsed.text[0]}`);
+    }
+    for (const [flag, dependency] of Object.entries(contract.requires ?? {})) {
+        if (parsed.flags.includes(flag) && !parsed.flags.includes(dependency)) {
+            console.error(`${flag} requires ${dependency}.`);
+            return null;
+        }
+    }
+    return { flags: parsed.flags, text: parsed.text };
+}
+// hello mode flags select one exclusive behavior; --interactive only applies
+// to the question loop, so combining it with any mode flag is an error too
+// (--setup exits after saving the profile and never enters the loop).
+const HELLO_MODE_FLAGS = ["--setup", "--profile", "--reset-profile"];
+async function main(argv) {
+    const [command, ...rest] = argv;
+    const cwd = process.cwd();
+    const homeDir = process.env.HOME ?? homedir();
+    if (command === "hello") {
+        const parsed = parseCommandArgs("hello", rest);
+        if (parsed === null)
+            return 1;
+        const flags = parsed.flags;
+        const modeFlags = HELLO_MODE_FLAGS.filter((flag) => flags.includes(flag));
+        if (modeFlags.length > 1 || (modeFlags.length > 0 && flags.includes("--interactive"))) {
+            console.error("Use only one of --setup, --profile, --reset-profile.");
+            return 1;
+        }
+        const interactive = process.stdin.isTTY === true || flags.includes("--interactive");
+        if (flags.includes("--profile")) {
+            const profile = await loadProfile(homeDir);
+            console.log(JSON.stringify(profile ?? defaultProfile(), null, 2));
+            return 0;
+        }
+        if (flags.includes("--reset-profile")) {
+            if (!flags.includes("--yes")) {
+                if (process.stdin.isTTY !== true) {
+                    console.error("Refusing to reset the profile without --yes in non-interactive mode.");
+                    return 1;
+                }
+                const confirmation = await getPrompter().ask("Delete the global profile? [y/N] ");
+                if (confirmation !== "y" && confirmation !== "yes")
+                    return 0;
+            }
+            await resetProfile(homeDir);
+            console.log("Profile reset.");
+            return 0;
+        }
+        if (flags.includes("--setup")) {
+            await runProfileSetup(getPrompter(), homeDir);
+            return 0;
+        }
+        const hadProfile = (await loadProfile(homeDir)) !== null;
+        const result = await hello({ cwd, homeDir });
+        console.log(`Koan ready: ${result.projectRoot}`);
+        if (!interactive) {
+            if (result.nextQuestion)
+                console.log(result.nextQuestion.userFacingQuestion);
+            return 0;
+        }
+        return runInteractiveHello({ cwd, homeDir, result, firstRun: !hadProfile, prompt: getPrompter() });
+    }
+    if (command === "status") {
+        const parsed = parseCommandArgs("status", rest);
+        if (parsed === null)
+            return 1;
+        const wantsArchive = parsed.flags.includes("--archive");
+        const wantsUpdate = parsed.flags.includes("--update");
+        if (wantsArchive && wantsUpdate) {
+            console.error("Use either --update or --archive, not both.");
+            return 1;
+        }
+        if (wantsArchive) {
+            const result = await archive({ cwd });
+            console.log(`Archived ${result.archivedGoalId}.`);
+            return 0;
+        }
+        if (wantsUpdate) {
+            let update = parsed.text.join(" ").trim();
+            if (!update) {
+                if (process.stdin.isTTY !== true) {
+                    console.error("Usage: koan status --update <text>");
+                    return 1;
+                }
+                update = (await getPrompter().ask("Status update: ")) ?? "";
+            }
+            await updateStatus({ cwd, update });
+            console.log("Status updated.");
+            return 0;
+        }
+        const result = await status({ cwd });
+        console.log(result.summary);
+        return 0;
+    }
+    if (command === "answer") {
+        // No leading flags: the axis is the first positional and everything after
+        // it is free text verbatim (flag-like tokens included).
+        const parsed = parseCommandArgs("answer", rest);
+        if (parsed === null)
+            return 1;
+        const [axis, ...answerWords] = parsed.text;
+        const answer = answerWords.join(" ").trim();
+        if (!axis || !answer) {
+            console.error("Usage: koan answer <axis> <text>");
+            return 1;
+        }
+        const result = await recordAnswer({ cwd, homeDir, axis: axis, answer });
+        console.log(`Recorded ${result.answer.axis}. Next: ${result.nextQuestion?.axis ?? "converged"}.`);
+        return 0;
+    }
+    if (command === "enough") {
+        if (parseCommandArgs("enough", rest) === null)
+            return 1;
+        await acceptClarity({ cwd });
+        console.log("Accepted current clarity.");
+        return 0;
+    }
+    if (command === "crystallize") {
+        const parsed = parseCommandArgs("crystallize", rest);
+        if (parsed === null)
+            return 1;
+        const dryRun = parsed.flags.includes("--dry-run");
+        const result = await crystallize({ cwd, homeDir, dryRun });
+        if (dryRun) {
+            console.log(`Dry run: ${result.plan.operations.length} operations planned.`);
+            return 0;
+        }
+        console.log(`Crystallized ${result.crystallizedAxes.length} axes.`);
+        return 0;
+    }
+    if (command === "bright-idea") {
+        // --classify is the only leading flag; its value is the first non-flag
+        // token, and everything after that value is idea text verbatim.
+        const parsed = parseCommandArgs("bright-idea", rest);
+        if (parsed === null)
+            return 1;
+        let classification;
+        let ideaWords = parsed.text;
+        if (parsed.flags.includes("--classify")) {
+            const value = ideaWords[0];
+            if (!BRIGHT_IDEA_CLASSIFICATIONS.includes(value)) {
+                console.error(`Invalid classification: ${value}`);
+                return 1;
+            }
+            classification = value;
+            ideaWords = ideaWords.slice(1);
+        }
+        const idea = ideaWords.join(" ").trim();
+        if (!idea) {
+            console.error("Usage: koan bright-idea <text>");
+            return 1;
+        }
+        const result = await brightIdea({ cwd, idea, classification });
+        console.log(`Bright idea recorded (${result.classification}). ${result.recommendation}`);
+        return 0;
+    }
+    if (command === "insight") {
+        const parsed = parseCommandArgs("insight", rest);
+        if (parsed === null)
+            return 1;
+        const text = parsed.text.join(" ").trim();
+        if (!text) {
+            console.error("Usage: koan insight <text>");
+            return 1;
+        }
+        const result = await recordInsight({ cwd, text });
+        console.log(`Insight recorded in ${result.path}.`);
+        return 0;
+    }
+    if (command === "prd") {
+        const parsed = parseCommandArgs("prd", rest);
+        if (parsed === null)
+            return 1;
+        const dryRun = parsed.flags.includes("--dry-run");
+        const result = await buildPrd({ cwd, homeDir, dryRun });
+        if (dryRun) {
+            console.log(`Dry run: ${result.plan.operations.length} operations planned.`);
+            return 0;
+        }
+        console.log(`PRD synthesized at ${result.path}.`);
+        return 0;
+    }
+    if (command === "qa") {
+        if (parseCommandArgs("qa", rest) === null)
+            return 1;
+        await qa({ cwd });
+        console.log("QA checklist ready.");
+        return 0;
+    }
+    if (command === "handoff") {
+        // No leading flags; the summary is everything after them, verbatim. A
+        // summary that itself begins with "--" is therefore unsupported (see
+        // usage), but later tokens may look like flags.
+        const parsed = parseCommandArgs("handoff", rest);
+        if (parsed === null)
+            return 1;
+        const summary = parsed.text.join(" ").trim();
+        if (!summary) {
+            console.error("Usage: koan handoff <summary>");
+            return 1;
+        }
+        await handoff({ cwd, summary });
+        console.log("Handoff ready.");
+        return 0;
+    }
+    console.error(usage());
+    return 1;
+}
+main(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+})
+    .finally(() => {
+    prompter?.close();
+});

package/dist/cli/prompt.d.ts

@@ -0,0 +1,5 @@
+export interface Prompter {
+    ask(question: string): Promise<string | null>;
+    close(): void;
+}
+export declare function createPrompter(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Prompter;

package/dist/cli/prompt.js

@@ -0,0 +1,48 @@
+import { createInterface } from "node:readline";
+// Lines are buffered as they arrive so piped stdin that delivers several
+// lines in one chunk (or closes early) never loses input between asks.
+export function createPrompter(input = process.stdin, output = process.stdout) {
+    const rl = createInterface({ input, output });
+    const lines = [];
+    let closed = false;
+    // FIFO queue so concurrent asks each get their own line instead of a later
+    // ask overwriting an earlier resolver (which would leave it forever pending).
+    const pending = [];
+    rl.on("line", (line) => {
+        const resolve = pending.shift();
+        if (resolve) {
+            resolve(line.trim());
+        }
+        else {
+            lines.push(line);
+        }
+    });
+    rl.on("close", () => {
+        closed = true;
+        const waiting = pending.splice(0, pending.length);
+        for (const resolve of waiting)
+            resolve(null);
+    });
+    return {
+        ask(question) {
+            const buffered = lines.shift();
+            if (buffered !== undefined) {
+                output.write(question);
+                return Promise.resolve(buffered.trim());
+            }
+            if (closed) {
+                output.write(question);
+                return Promise.resolve(null);
+            }
+            rl.setPrompt(question);
+            rl.prompt();
+            return new Promise((resolve) => {
+                pending.push(resolve);
+            });
+        },
+        close() {
+            if (!closed)
+                rl.close();
+        }
+    };
+}

package/dist/core/answers.d.ts

@@ -0,0 +1,27 @@
+import { type KoanQuestion } from "./questions.js";
+import { type AmbiguityAxis, type AmbiguityLedger, type AnswerRecord } from "./schemas.js";
+export interface RecordAnswerInput {
+    cwd: string;
+    homeDir: string;
+    axis: AmbiguityAxis;
+    answer: string;
+    clarity?: number;
+    question?: string;
+    isoDate?: string;
+    source?: string;
+}
+export interface RecordAnswerResult {
+    projectRoot: string;
+    ledger: AmbiguityLedger;
+    answer: AnswerRecord;
+    converged: boolean;
+    unresolved: AmbiguityAxis[];
+    nextQuestion: KoanQuestion | null;
+}
+export declare function recordAnswer(input: RecordAnswerInput): Promise<RecordAnswerResult>;
+export declare function acceptClarity(input: {
+    cwd: string;
+    isoDate?: string;
+}): Promise<{
+    projectRoot: string;
+}>;