@longtable/cli 0.1.11 → 0.1.13

package/dist/cli.js

@@ -14,7 +14,7 @@ import { installCodexPromptAliases, listInstalledCodexPromptAliases, removeCodex
 import { buildPersonaGuidance, parseInvocationDirective } from "./persona-router.js";
 import { PERSONA_DEFINITIONS, listRoleDefinitions } from "./personas.js";
 import { buildPanelFallback, renderPanelSummary } from "./panel.js";
-import { appendInvocationRecordToWorkspace, assertWorkspaceNotBlocked, answerWorkspaceQuestion, createWorkspaceQuestion, createOrUpdateProjectWorkspace, inspectProjectWorkspace, loadProjectContextFromDirectory, renderProjectWorkspaceSummary, syncCurrentWorkspaceView } from "./project-session.js";
+import { appendInvocationRecordToWorkspace, assertWorkspaceNotBlocked, answerWorkspaceQuestion, createWorkspaceClarificationCard, createWorkspaceQuestion, createOrUpdateProjectWorkspace, inspectProjectWorkspace, loadProjectContextFromDirectory, renderProjectWorkspaceSummary, syncCurrentWorkspaceView } from "./project-session.js";
 const VALID_MODES = new Set([
     "explore",
     "review",
@@ -86,6 +86,7 @@ function usage() {
         "  longtable install [--json] [--path <file>] [--runtime-path <file>]",
         "  longtable mcp install [--provider codex|claude|all] [--write] [--json] [--codex-config <path>] [--claude-settings <path>] [--package <spec>]",
         "  longtable ask [--prompt <text>] [--print] [--json] [--setup <path>] [--cwd <path>]",
+        "  longtable clarify --prompt <task-context> [--provider codex|claude] [--required|--advisory] [--print] [--cwd <path>] [--json] [--force]",
         "  longtable question --prompt <decision-context> [--title <text>] [--text <question>] [--provider codex|claude] [--required|--advisory] [--print] [--cwd <path>] [--json]",
         "  longtable panel [--prompt <text>] [--role <role[,role]>] [--mode review|critique|draft|commit] [--visibility synthesis_only|show_on_conflict|always_visible] [--print] [--json] [--setup <path>] [--cwd <path>]",
         "  longtable decide [--question <id>] --answer <value-or-text> [--rationale <text>] [--provider codex|claude] [--cwd <path>] [--json]",
@@ -119,7 +120,7 @@ function parseArgs(argv) {
     const values = {};
     let subcommand = maybeSubcommand;
     const modeCommand = command && VALID_MODES.has(command);
-    const directCommand = command && ["init", "start", "resume", "doctor", "status", "roles", "show", "install", "mcp", "codex", "claude", "ask", "question", "panel", "decide"].includes(command);
+    const directCommand = command && ["init", "start", "resume", "doctor", "status", "roles", "show", "install", "mcp", "codex", "claude", "ask", "clarify", "question", "panel", "decide"].includes(command);
     let startIndex = 1;
     if (modeCommand) {
         subcommand = undefined;
@@ -1074,6 +1075,15 @@ function renderDoctorStatus(status) {
                 lines.push(`  - ${question.id}: ${question.question} (${question.options.join("/")})`);
             }
         }
+        if ((workspace.answerWarnings ?? []).length > 0) {
+            lines.push("- answer warnings:");
+            for (const warning of workspace.answerWarnings ?? []) {
+                lines.push(`  - ${warning.questionId}: ${warning.issue}`);
+                if (warning.suggestion) {
+                    lines.push(`    ${warning.suggestion}`);
+                }
+            }
+        }
     }
     const nextActions = [];
     const canFix = status.providers.codex.missingSkills.length > 0 ||
@@ -1524,6 +1534,32 @@ async function runQuestion(args) {
         }
         return;
     }
+    if (isInteractiveTerminal()) {
+        const rl = createInterface({ input, output });
+        try {
+            console.log(renderBrandBanner("LongTable", "Researcher Checkpoint"));
+            console.log("");
+            const answer = await promptChoice(rl, renderQuestionHeader(1, 1, result.question.prompt.title, result.question.prompt.question), questionRecordToChoices(result.question));
+            const decision = await answerWorkspaceQuestion({
+                context,
+                questionId: result.question.id,
+                answer,
+                provider,
+                surface: "terminal_selector"
+            });
+            console.log("");
+            console.log("LongTable checkpoint decision recorded");
+            console.log(`- question: ${decision.question.id}`);
+            console.log(`- decision: ${decision.decision.id}`);
+            console.log(`- answer: ${decision.decision.selectedOption ?? answer}`);
+            console.log(`- state: ${context.stateFilePath}`);
+            console.log(`- current: ${context.currentFilePath}`);
+            return;
+        }
+        finally {
+            rl.close();
+        }
+    }
     const optionValues = [
         ...result.question.prompt.options.map((option) => option.value),
         ...(result.question.prompt.allowOther ? ["other"] : [])
@@ -1536,6 +1572,172 @@ async function runQuestion(args) {
     console.log(`- answer: longtable decide --question ${result.question.id} --answer <value>`);
     console.log(`- current: ${context.currentFilePath}`);
 }
+function isInteractiveTerminal() {
+    return Boolean(input.isTTY && output.isTTY);
+}
+function questionRecordToChoices(record) {
+    return [
+        ...record.prompt.options.map((option) => ({
+            id: option.value,
+            label: option.recommended ? `${option.label} (Recommended)` : option.label,
+            description: option.description ?? "Select this option."
+        })),
+        ...(record.prompt.allowOther
+            ? [{
+                    id: "other",
+                    label: record.prompt.otherLabel ?? "Other",
+                    description: "Type a custom answer.",
+                    fallbackToText: true
+                }]
+            : [])
+    ];
+}
+function renderClarificationCard(questions) {
+    if (questions.length === 0) {
+        return "No new clarification questions are pending for this prompt.";
+    }
+    const width = 44;
+    const boxLine = (text = "") => `│ ${text.padEnd(width, " ")} │`;
+    const wrap = (text) => {
+        const words = text.split(/\s+/).filter(Boolean);
+        const wrapped = [];
+        let line = "";
+        for (const word of words) {
+            if (!line) {
+                line = word;
+                continue;
+            }
+            if (`${line} ${word}`.length > width) {
+                wrapped.push(line);
+                line = word;
+                continue;
+            }
+            line = `${line} ${word}`;
+        }
+        if (line) {
+            wrapped.push(line);
+        }
+        return wrapped.length > 0 ? wrapped : [""];
+    };
+    const lines = [
+        "I want to make sure I handle this in the way you actually want, so here are the choices LongTable should not infer silently:",
+        "",
+        "┌──────────────────────────────────────────────┐"
+    ];
+    for (const question of questions) {
+        lines.push(boxLine(question.prompt.title));
+        for (const line of wrap(question.prompt.question)) {
+            lines.push(boxLine(line));
+        }
+        for (const option of question.prompt.options) {
+            const suffix = option.recommended ? " (Recommended)" : "";
+            for (const line of wrap(`- ${option.label}${suffix}`)) {
+                lines.push(boxLine(line));
+            }
+        }
+        if (question.prompt.allowOther) {
+            lines.push(boxLine(`- ${question.prompt.otherLabel ?? "Other"}`));
+        }
+        lines.push(boxLine());
+    }
+    lines.push("└──────────────────────────────────────────────┘");
+    lines.push("");
+    lines.push("Answer in a terminal with `longtable clarify --prompt ...`, or record choices with `longtable decide --question <id> --answer <value>`.");
+    return lines.join("\n");
+}
+async function answerClarificationCardInTerminal(context, questions, provider) {
+    if (questions.length === 0) {
+        return;
+    }
+    const rl = createInterface({ input, output });
+    try {
+        console.log(renderBrandBanner("LongTable", "Clarification Card"));
+        console.log("");
+        for (let index = 0; index < questions.length; index += 1) {
+            const question = questions[index];
+            const prompt = renderQuestionHeader(index + 1, questions.length, question.prompt.title, question.prompt.question);
+            const answer = await promptChoice(rl, prompt, questionRecordToChoices(question));
+            await answerWorkspaceQuestion({
+                context,
+                questionId: question.id,
+                answer,
+                provider,
+                surface: "terminal_selector"
+            });
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+async function runClarify(args) {
+    const workingDirectory = typeof args.cwd === "string" ? args.cwd : cwd();
+    const prompt = await resolvePrompt(typeof args.prompt === "string" ? args.prompt : undefined);
+    if (!prompt) {
+        throw new Error("A task context is required. Pass --prompt <text>.");
+    }
+    const context = await loadProjectContextFromDirectory(workingDirectory);
+    if (!context) {
+        throw new Error("No LongTable project workspace was found here. Run this inside a project or pass --cwd.");
+    }
+    const provider = args.provider === "claude" ? "claude" : args.provider === "codex" ? "codex" : undefined;
+    const required = args.required === true ? true : args.advisory === true ? false : undefined;
+    const result = await createWorkspaceClarificationCard({
+        context,
+        prompt,
+        provider,
+        required,
+        force: args.force === true
+    });
+    if (args.json === true) {
+        console.log(JSON.stringify({
+            questions: result.questions,
+            created: result.created,
+            alreadyAnswered: result.alreadyAnswered,
+            files: {
+                state: context.stateFilePath,
+                current: context.currentFilePath
+            }
+        }, null, 2));
+        return;
+    }
+    if (args.print === true || !isInteractiveTerminal()) {
+        console.log(renderClarificationCard(result.questions));
+        return;
+    }
+    await answerClarificationCardInTerminal(context, result.questions, provider);
+    console.log("");
+    console.log("LongTable clarification decisions recorded");
+    console.log(`- answered: ${result.questions.length}`);
+    console.log(`- state: ${context.stateFilePath}`);
+    console.log(`- current: ${context.currentFilePath}`);
+}
+async function runAutomaticClarificationIfNeeded(prompt, args) {
+    if (args["no-clarify"] === true || args.print === true || args.json === true) {
+        return false;
+    }
+    const workingDirectory = typeof args.cwd === "string" ? args.cwd : cwd();
+    const context = await loadProjectContextFromDirectory(workingDirectory);
+    if (!context) {
+        return false;
+    }
+    const provider = args.provider === "claude" ? "claude" : args.provider === "codex" ? "codex" : undefined;
+    const result = await createWorkspaceClarificationCard({
+        context,
+        prompt,
+        provider,
+        required: true
+    });
+    if (result.questions.length === 0) {
+        return false;
+    }
+    if (!isInteractiveTerminal()) {
+        console.log(renderClarificationCard(result.questions));
+        return true;
+    }
+    await answerClarificationCardInTerminal(context, result.questions, provider);
+    return false;
+}
 async function runAsk(args) {
     const prompt = await resolvePrompt(typeof args.prompt === "string" ? args.prompt : undefined);
     if (!prompt) {
@@ -1549,6 +1751,9 @@ async function runAsk(args) {
         return;
     }
     const mode = inferred === "panel" ? "review" : inferred;
+    if (await runAutomaticClarificationIfNeeded(effectivePrompt, args)) {
+        return;
+    }
     const delegatedArgs = {
         ...args,
         prompt: effectivePrompt
@@ -1883,6 +2088,10 @@ async function main() {
         await runAsk(values);
         return;
     }
+    if (command === "clarify") {
+        await runClarify(values);
+        return;
+    }
     if (command === "question") {
         await runQuestion(values);
         return;

package/dist/project-session.d.ts

@@ -1,4 +1,4 @@
-import type { DecisionRecord, InvocationRecord, ProviderKind, QuestionRecord, ResearchState } from "@longtable/core";
+import type { DecisionRecord, InvocationRecord, ProviderKind, QuestionSurface, QuestionRecord, ResearchState } from "@longtable/core";
 import type { SetupPersistedOutput } from "@longtable/setup";
 export type ProjectDisagreementPreference = "synthesis_only" | "show_on_conflict" | "always_visible";
 export interface LongTableProjectRecord {
@@ -98,12 +98,30 @@ export interface LongTableWorkspaceInspection {
         selectedOption?: string;
         timestamp: string;
     }>;
+    answerWarnings?: Array<{
+        questionId: string;
+        decisionRecordId?: string;
+        issue: string;
+        suggestion?: string;
+    }>;
 }
 export declare function loadWorkspaceState(context: LongTableProjectContext): Promise<ResearchState>;
 export declare function syncCurrentWorkspaceView(context: LongTableProjectContext): Promise<string>;
 export declare function appendInvocationRecordToWorkspace(context: LongTableProjectContext, invocation: InvocationRecord, questions?: QuestionRecord[]): Promise<ResearchState>;
 export declare function listBlockingWorkspaceQuestions(context: LongTableProjectContext): Promise<QuestionRecord[]>;
 export declare function assertWorkspaceNotBlocked(context: LongTableProjectContext): Promise<void>;
+export declare function createWorkspaceClarificationCard(options: {
+    context: LongTableProjectContext;
+    prompt: string;
+    provider?: ProviderKind;
+    required?: boolean;
+    force?: boolean;
+}): Promise<{
+    questions: QuestionRecord[];
+    state: ResearchState;
+    created: boolean;
+    alreadyAnswered: boolean;
+}>;
 export declare function createWorkspaceQuestion(options: {
     context: LongTableProjectContext;
     prompt: string;
@@ -121,6 +139,7 @@ export declare function answerWorkspaceQuestion(options: {
     answer: string;
     rationale?: string;
     provider?: "codex" | "claude";
+    surface?: QuestionSurface;
 }): Promise<{
     question: QuestionRecord;
     decision: DecisionRecord;

package/dist/project-session.js

@@ -280,7 +280,23 @@ function summarizeWorkspaceInspection(context, state) {
             summary: record.summary,
             ...(record.selectedOption ? { selectedOption: record.selectedOption } : {}),
             timestamp: record.timestamp
-        }))
+        })),
+        answerWarnings: questions
+            .filter((record) => record.status === "answered" && record.answer?.selectedValues.includes("other"))
+            .flatMap((record) => {
+            const raw = record.answer?.otherText ?? record.answer?.selectedLabels[0] ?? "";
+            if (!/^\d+$/.test(raw.trim())) {
+                return [];
+            }
+            const index = Number(raw.trim()) - 1;
+            const option = record.prompt.options[index];
+            return [{
+                    questionId: record.id,
+                    ...(record.decisionRecordId ? { decisionRecordId: record.decisionRecordId } : {}),
+                    issue: `Numeric answer "${raw.trim()}" was stored as other text.`,
+                    ...(option ? { suggestion: `Use "${option.value}" (${option.label}) for this checkpoint option.` } : {})
+                }];
+        })
     };
 }
 function buildProjectAgentsMd(project, session) {
@@ -457,7 +473,7 @@ function questionTextForCheckpoint(family, prompt) {
             return `What should LongTable decide before proceeding with: ${prompt}`;
     }
 }
-function optionsForCheckpointFamily(family) {
+function optionsForCheckpointTrigger(family, checkpointKey) {
     if (family === "evidence") {
         return [
             { value: "verify", label: "Verify evidence first", description: "Check whether the source supports the specific claim." },
@@ -482,6 +498,72 @@ function optionsForCheckpointFamily(family) {
             { value: "defer", label: "Do not submit yet", description: "Keep the submission decision open." }
         ];
     }
+    if (family === "authorship") {
+        return [
+            { value: "preserve_voice", label: "Preserve the researcher's voice", description: "Keep the current authorship trace visible before rewriting or smoothing." },
+            { value: "revise_with_trace", label: "Revise with an explicit authorship trace", description: "Change the text, but record what came from the researcher." },
+            { value: "ask_researcher", label: "Ask the researcher for wording first", description: "Do not infer the intended voice or narrative stance." },
+            { value: "defer", label: "Keep authorship open", description: "Do not settle the voice or authorship decision yet." }
+        ];
+    }
+    if (family === "exploration") {
+        return [
+            { value: "surface_tensions", label: "Surface tensions first", description: "Ask what is unresolved before narrowing the project." },
+            { value: "narrow_scope", label: "Narrow the research scope", description: "Move toward a smaller question while keeping the choice visible." },
+            { value: "gather_context", label: "Gather context before narrowing", description: "Check materials, constraints, or evidence before choosing a direction." },
+            { value: "defer", label: "Keep exploration open", description: "Do not collapse the problem space yet." }
+        ];
+    }
+    if (family === "review") {
+        return [
+            { value: "revise", label: "Revise before accepting the review", description: "Change the claim, design, or draft before treating the critique as resolved." },
+            { value: "evidence", label: "Check evidence for the objection", description: "Verify whether the review concern is actually supported." },
+            { value: "proceed", label: "Proceed while logging the risk", description: "Accept the objection profile and continue with the decision recorded." },
+            { value: "defer", label: "Keep the objection open", description: "Do not convert the review into closure yet." }
+        ];
+    }
+    if (family === "commitment") {
+        if (checkpointKey === "research_question_freeze") {
+            return [
+                { value: "revise", label: "Revise the research question", description: "Change the framing before treating the question as settled." },
+                { value: "scope", label: "Choose the scope boundary", description: "Commit only the boundary, not the full study design." },
+                { value: "evidence", label: "Gather support before freezing", description: "Check literature, feasibility, or data fit before locking the question." },
+                { value: "defer", label: "Keep the question open", description: "Do not freeze the research question yet." }
+            ];
+        }
+        if (checkpointKey === "theory_selection") {
+            return [
+                { value: "revise", label: "Revise the theory anchor", description: "Change the conceptual frame before treating it as settled." },
+                { value: "compare", label: "Compare candidate theories first", description: "Keep alternatives visible before choosing one anchor." },
+                { value: "evidence", label: "Check construct fit first", description: "Verify that the theory supports the constructs and claims." },
+                { value: "defer", label: "Keep theory selection open", description: "Do not commit to a theory anchor yet." }
+            ];
+        }
+        if (checkpointKey === "method_design_commitment") {
+            return [
+                { value: "revise", label: "Revise the study design", description: "Change method, sample, or design before treating it as settled." },
+                { value: "ethics", label: "Check participant and ethics implications", description: "Pause for consent, representation, or trust concerns." },
+                { value: "evidence", label: "Check feasibility and evidence first", description: "Verify that the method can support the intended claims." },
+                { value: "defer", label: "Keep method design open", description: "Do not commit the design yet." }
+            ];
+        }
+        if (checkpointKey === "measurement_validity") {
+            return [
+                { value: "revise", label: "Revise the measurement plan", description: "Change scales, constructs, or instruments before treating them as settled." },
+                { value: "evidence", label: "Verify construct validity first", description: "Check whether the instrument supports the construct." },
+                { value: "pilot", label: "Pilot or inspect the measure", description: "Gather local evidence before committing the measurement." },
+                { value: "defer", label: "Keep measurement open", description: "Do not settle the measurement plan yet." }
+            ];
+        }
+        if (checkpointKey === "analysis_plan") {
+            return [
+                { value: "revise", label: "Revise the analysis plan", description: "Change model, coding, or inference strategy before committing." },
+                { value: "assumptions", label: "Check assumptions first", description: "Inspect data, model assumptions, or coding validity before closure." },
+                { value: "evidence", label: "Verify analysis fit", description: "Confirm the analysis can answer the research question." },
+                { value: "defer", label: "Keep analysis open", description: "Do not commit the analysis plan yet." }
+            ];
+        }
+    }
     return [
         { value: "revise", label: "Revise before proceeding", description: "Change the framing, design, or draft before treating this as settled." },
         { value: "evidence", label: "Gather or verify evidence first", description: "Do not proceed until the relevant evidence is checked." },
@@ -489,6 +571,133 @@ function optionsForCheckpointFamily(family) {
         { value: "defer", label: "Keep this open", description: "Do not commit yet; keep the issue visible as an open tension." }
     ];
 }
+function includesAny(prompt, patterns) {
+    return patterns.some((pattern) => pattern.test(prompt));
+}
+function clarificationOptions(first, second, third, fourth) {
+    return [first, second, third, ...(fourth ? [fourth] : [])];
+}
+function buildClarificationQuestionSpecs(prompt) {
+    const normalized = prompt.toLowerCase();
+    const specs = [];
+    function push(spec) {
+        if (!specs.some((candidate) => candidate.key === spec.key)) {
+            specs.push(spec);
+        }
+    }
+    if (includesAny(normalized, [/\brubrics?\b/, /루브릭|채점기준/])) {
+        push({
+            key: "rubric_update_basis",
+            title: "Rubric update basis",
+            question: "How should LongTable use the available materials to update the rubric?",
+            whyNow: "Rubric updates can silently change grading criteria if LongTable guesses the calibration basis.",
+            options: clarificationOptions({ value: "calibrate_to_exemplars", label: "Calibrate criteria to exemplars", description: "Use strong submissions to refine what each criterion means.", recommended: true }, { value: "polish_existing", label: "Polish existing rubric only", description: "Keep criteria stable and improve wording or consistency." }, { value: "rewrite_structure", label: "Restructure the rubric", description: "Change categories or levels where the materials suggest a better structure." })
+        });
+    }
+    if (includesAny(normalized, [/\bexemplar\b/, /\bbest submission\b/, /\bselected submission\b/, /\bTA\b/i, /우수\s*답안|예시|선정|조교/])) {
+        push({
+            key: "exemplar_use",
+            title: "Exemplar use",
+            question: "How should LongTable use selected exemplars or TA guidance?",
+            whyNow: "Exemplars can either calibrate criteria privately or become visible evidence inside the output.",
+            options: clarificationOptions({ value: "calibrate_only", label: "Use as private calibration", description: "Adjust criteria using exemplars without quoting them.", recommended: true }, { value: "include_deidentified_excerpts", label: "Include de-identified excerpts", description: "Add short anonymized examples where they clarify quality." }, { value: "separate_notes", label: "Keep examples in separate notes", description: "Use exemplars outside the main artifact." })
+        });
+    }
+    if (includesAny(normalized, [/\binstruction/, /\bguidance\b/, /\bsource\b/, /\bfile\b/, /\bdocx?\b/, /지침|가이드|문서|파일|자료/])) {
+        push({
+            key: "source_authority",
+            title: "Source authority",
+            question: "If sources conflict or leave gaps, which source should LongTable privilege?",
+            whyNow: "Without an authority rule, LongTable may resolve conflicts by convenience rather than researcher intent.",
+            options: clarificationOptions({ value: "explicit_user_instruction", label: "Your explicit instruction", description: "Use the researcher's current instruction as the highest authority.", recommended: true }, { value: "project_files", label: "Project files", description: "Treat supplied files or existing artifacts as authoritative." }, { value: "external_guidance", label: "TA or external guidance", description: "Prioritize instructor, TA, venue, or policy guidance." })
+        });
+    }
+    if (includesAny(normalized, [/\bdeliver\b/, /\boutput\b/, /\btracked?[- ]?change/, /\bdocx?\b/, /\bmarkdown\b/, /\btable\b/, /전달|산출물|결과물|수정\s*표시|트랙|형식|포맷/])) {
+        push({
+            key: "delivery_format",
+            title: "Delivery format",
+            question: "How should LongTable deliver the clarified output?",
+            whyNow: "Format and change-tracking choices affect whether the result is usable for review or handoff.",
+            options: clarificationOptions({ value: "tracked_changes", label: "Tracked-change artifact", description: "Produce a reviewable changed version where possible.", recommended: true }, { value: "clean_final", label: "Clean final artifact", description: "Deliver the final version without change markup." }, { value: "summary_plus_artifact", label: "Summary plus artifact", description: "Include a concise change summary with the output." })
+        });
+    }
+    if (includesAny(normalized, [/\bupdate\b/, /\bchange\b/, /\bedit\b/, /\bfix\b/, /\bimplement\b/, /\bbuild\b/, /\bcreate\b/, /업데이트|수정|변경|구현|만들|고쳐/])) {
+        push({
+            key: "autonomy_boundary",
+            title: "Autonomy boundary",
+            question: "How much should LongTable do before checking back with you?",
+            whyNow: "Execution requests can move from advice to authorship or artifact ownership unless the boundary is explicit.",
+            options: clarificationOptions({ value: "ask_then_act", label: "Clarify first, then act", description: "Ask needed questions before changing the artifact.", recommended: true }, { value: "act_with_defaults", label: "Act with visible defaults", description: "Proceed using recommended defaults and record them." }, { value: "recommend_only", label: "Recommend only", description: "Describe changes but do not alter artifacts." })
+        });
+    }
+    if (includesAny(normalized, [/\bperformance\b/, /\btest\b/, /\bevaluate\b/, /\bcheck\b/, /\bbenchmark\b/, /성능|테스트|평가|체크|검증/])) {
+        push({
+            key: "evaluation_target",
+            title: "Evaluation target",
+            question: "What should LongTable treat as the main performance target?",
+            whyNow: "Performance checks can optimize for UX, correctness, trigger sensitivity, or delivery reliability.",
+            options: clarificationOptions({ value: "question_sensitivity", label: "Question sensitivity", description: "Check whether LongTable asks at the right knowledge-gap moments.", recommended: true }, { value: "renderer_convenience", label: "Renderer convenience", description: "Check whether the most convenient question UI is used." }, { value: "state_reliability", label: "State reliability", description: "Check whether questions and answers persist correctly." })
+        });
+    }
+    if (specs.length === 0) {
+        push({
+            key: "general_missing_context",
+            title: "Missing context",
+            question: "What should LongTable clarify before proceeding?",
+            whyNow: "The request can be answered in multiple ways, and choosing silently would hide a researcher judgment.",
+            options: clarificationOptions({ value: "scope", label: "Clarify scope first", description: "Ask what is included and excluded before acting.", recommended: true }, { value: "criteria", label: "Clarify success criteria", description: "Ask what would count as a good result." }, { value: "proceed", label: "Proceed with visible assumptions", description: "Continue, but make assumptions explicit." })
+        });
+    }
+    return specs;
+}
+const CLARIFICATION_PROMPT_PREFIX = "Clarification prompt:";
+function hasClarificationPrompt(record, prompt) {
+    return record.prompt.rationale.includes(`${CLARIFICATION_PROMPT_PREFIX} ${prompt}`);
+}
+export async function createWorkspaceClarificationCard(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    if (!options.force) {
+        const existing = (state.questionLog ?? []).filter((record) => hasClarificationPrompt(record, options.prompt));
+        const pending = existing.filter((record) => record.status === "pending");
+        if (pending.length > 0) {
+            return { questions: pending, state, created: false, alreadyAnswered: false };
+        }
+        if (existing.some((record) => record.status === "answered")) {
+            return { questions: [], state, created: false, alreadyAnswered: true };
+        }
+    }
+    const createdAt = nowIso();
+    const preferredSurfaces = options.provider === "claude"
+        ? ["native_structured", "terminal_selector", "numbered"]
+        : ["terminal_selector", "numbered", "native_structured"];
+    const questions = buildClarificationQuestionSpecs(options.prompt).map((spec) => ({
+        id: createId("question_record"),
+        createdAt,
+        updatedAt: createdAt,
+        status: "pending",
+        prompt: {
+            id: createId("question_prompt"),
+            checkpointKey: `clarification_${spec.key}`,
+            title: spec.title,
+            question: spec.question,
+            type: "single_choice",
+            options: spec.options,
+            allowOther: true,
+            otherLabel: "Other",
+            required: options.required ?? true,
+            source: "runtime_guidance",
+            rationale: [
+                spec.whyNow,
+                `${CLARIFICATION_PROMPT_PREFIX} ${options.prompt}`
+            ],
+            preferredSurfaces: preferredSurfaces
+        }
+    }));
+    const updated = appendQuestionRecords(state, questions);
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return { questions, state: updated, created: true, alreadyAnswered: false };
+}
 export async function createWorkspaceQuestion(options) {
     const state = await loadResearchState(options.context.stateFilePath);
     const trigger = classifyCheckpointTrigger(options.prompt, {
@@ -507,7 +716,7 @@ export async function createWorkspaceQuestion(options) {
             title: options.title ?? questionTitleForCheckpoint(trigger.family),
             question: options.question ?? questionTextForCheckpoint(trigger.family, options.prompt),
             type: "single_choice",
-            options: optionsForCheckpointFamily(trigger.family),
+            options: optionsForCheckpointTrigger(trigger.family, trigger.signal.checkpointKey),
             allowOther: true,
             otherLabel: "Other decision",
             required: options.required ?? trigger.requiresQuestionBeforeClosure,
@@ -545,22 +754,95 @@ function updateInvocationWithDecision(invocation, questionId, decisionId) {
         }
     };
 }
+function normalizeAnswerToken(value) {
+    return value.trim().replace(/\s+/g, " ").toLowerCase();
+}
+function optionAnswerCandidates(option) {
+    return [
+        option.value,
+        option.label,
+        ...(option.description
+            ? [
+                `${option.label} - ${option.description}`,
+                `${option.label} — ${option.description}`
+            ]
+            : [])
+    ].map(normalizeAnswerToken);
+}
+function splitAnswerAndRationale(rawAnswer) {
+    const [firstLine = "", ...restLines] = rawAnswer.trim().split(/\r?\n/);
+    const rationale = restLines.join("\n").trim();
+    return {
+        selection: firstLine.trim(),
+        ...(rationale ? { rationale } : {})
+    };
+}
+function normalizeQuestionAnswerSelection(question, rawAnswer) {
+    const trimmed = rawAnswer.trim();
+    const { selection, rationale } = splitAnswerAndRationale(trimmed);
+    const numeric = Number(selection);
+    if (/^\d+$/.test(selection) && Number.isInteger(numeric)) {
+        const option = question.prompt.options[numeric - 1];
+        if (option) {
+            return {
+                selectedValue: option.value,
+                selectedLabel: option.label,
+                ...(rationale ? { inlineRationale: rationale } : {})
+            };
+        }
+        if (question.prompt.allowOther && numeric === question.prompt.options.length + 1) {
+            return {
+                selectedValue: "other",
+                selectedLabel: question.prompt.otherLabel ?? "Other",
+                ...(rationale ? { inlineRationale: rationale } : {})
+            };
+        }
+        throw new Error(`Answer ${selection} is outside the available LongTable question options.`);
+    }
+    const normalizedSelection = normalizeAnswerToken(selection);
+    const option = question.prompt.options.find((candidate) => optionAnswerCandidates(candidate).includes(normalizedSelection));
+    if (option) {
+        return {
+            selectedValue: option.value,
+            selectedLabel: option.label,
+            ...(rationale ? { inlineRationale: rationale } : {})
+        };
+    }
+    if (normalizedSelection === "other" && question.prompt.allowOther) {
+        return {
+            selectedValue: "other",
+            selectedLabel: question.prompt.otherLabel ?? "Other",
+            ...(rationale ? { inlineRationale: rationale } : {})
+        };
+    }
+    if (question.prompt.allowOther) {
+        return {
+            selectedValue: "other",
+            selectedLabel: selection,
+            otherText: trimmed,
+            ...(rationale ? { inlineRationale: rationale } : {})
+        };
+    }
+    throw new Error(`Answer "${selection}" does not match a LongTable question option.`);
+}
 export async function answerWorkspaceQuestion(options) {
     const state = await loadResearchState(options.context.stateFilePath);
     const question = findQuestionForDecision(state, options.questionId);
     if (!question) {
         throw new Error(options.questionId ? `No pending LongTable question found for ${options.questionId}.` : "No pending LongTable question was found.");
     }
-    const option = question.prompt.options.find((candidate) => candidate.value === options.answer);
-    const explicitOther = options.answer === "other" && question.prompt.allowOther;
+    const normalized = normalizeQuestionAnswerSelection(question, options.answer);
+    const rationale = [normalized.inlineRationale, options.rationale]
+        .filter((entry) => Boolean(entry && entry.trim()))
+        .join("\n");
     const answer = {
         promptId: question.prompt.id,
-        selectedValues: [option?.value ?? "other"],
-        selectedLabels: [option?.label ?? (explicitOther ? question.prompt.otherLabel ?? "Other" : options.answer)],
-        ...(option || explicitOther ? {} : { otherText: options.answer }),
-        ...(options.rationale ? { rationale: options.rationale } : {}),
+        selectedValues: [normalized.selectedValue],
+        selectedLabels: [normalized.selectedLabel],
+        ...(normalized.otherText ? { otherText: normalized.otherText } : {}),
+        ...(rationale ? { rationale } : {}),
         ...(options.provider ? { provider: options.provider } : {}),
-        surface: options.provider === "claude" ? "native_structured" : "numbered"
+        surface: options.surface ?? (options.provider === "claude" ? "native_structured" : "numbered")
     };
     const timestamp = nowIso();
     const decision = {
@@ -571,7 +853,7 @@ export async function answerWorkspaceQuestion(options) {
         mode: "commit",
         summary: `Answered ${question.prompt.title}: ${answer.selectedLabels.join(", ")}`,
         selectedOption: answer.selectedValues[0],
-        ...(options.rationale ? { rationale: options.rationale } : {})
+        ...(rationale ? { rationale } : {})
     };
     const answeredQuestion = {
         ...question,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtable/cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "private": false,
   "description": "Researcher-facing LongTable CLI",
   "type": "module",
@@ -28,12 +28,12 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@longtable/checkpoints": "0.1.11",
-    "@longtable/core": "0.1.11",
-    "@longtable/memory": "0.1.11",
-    "@longtable/provider-claude": "0.1.11",
-    "@longtable/provider-codex": "0.1.11",
-    "@longtable/setup": "0.1.11"
+    "@longtable/checkpoints": "0.1.13",
+    "@longtable/core": "0.1.13",
+    "@longtable/memory": "0.1.13",
+    "@longtable/provider-claude": "0.1.13",
+    "@longtable/provider-codex": "0.1.13",
+    "@longtable/setup": "0.1.13"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",