@longtable/cli 0.1.10 → 0.1.12

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { execSync } from "node:child_process";
 import { emitKeypressEvents } from "node:readline";
 import { createInterface } from "node:readline/promises";
@@ -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",
@@ -39,6 +39,10 @@ const ANSI = {
     cyan: "\u001B[36m",
     green: "\u001B[32m"
 };
+const LONGTABLE_MCP_SERVER_NAME = "longtable-state";
+const LONGTABLE_MCP_PACKAGE_VERSION = "0.1.11";
+const LONGTABLE_MCP_MARKER_START = "# LongTable state MCP START";
+const LONGTABLE_MCP_MARKER_END = "# LongTable state MCP END";
 function style(text, prefix) {
     return `${prefix}${text}${ANSI.reset}`;
 }
@@ -80,7 +84,9 @@ function usage() {
         "  longtable roles [--json]",
         "  longtable show [--json] [--path <file>]",
         "  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]",
@@ -94,6 +100,7 @@ function usage() {
         "  longtable claude install-skills [--dir <path>]",
         "  longtable claude remove-skills [--dir <path>]",
         "  longtable claude status [--dir <path>] [--json]",
+        "  longtable mcp install --provider all",
         "",
         "Examples:",
         "  longtable init --flow interview --provider codex --install-skills",
@@ -113,13 +120,13 @@ 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", "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;
         startIndex = 1;
     }
-    else if (command === "codex" || command === "claude") {
+    else if (command === "codex" || command === "claude" || command === "mcp") {
         startIndex = 2;
     }
     else if (directCommand) {
@@ -778,6 +785,147 @@ async function runInstall(args) {
     }
     console.log(renderInstallSummary(result));
 }
+function resolveMcpProviders(value) {
+    if (value === "codex" || value === "claude") {
+        return [value];
+    }
+    return ["codex", "claude"];
+}
+function resolveMcpPackageSpec(args) {
+    return typeof args.package === "string" && args.package.trim()
+        ? args.package.trim()
+        : `@longtable/mcp@${LONGTABLE_MCP_PACKAGE_VERSION}`;
+}
+function resolveCodexMcpConfigPath(args) {
+    return resolve(normalizeUserPath(typeof args["codex-config"] === "string" && args["codex-config"].trim()
+        ? args["codex-config"].trim()
+        : "~/.codex/config.toml"));
+}
+function resolveClaudeMcpSettingsPath(args) {
+    return resolve(normalizeUserPath(typeof args["claude-settings"] === "string" && args["claude-settings"].trim()
+        ? args["claude-settings"].trim()
+        : "~/.claude/settings.json"));
+}
+function escapeTomlString(value) {
+    return JSON.stringify(value);
+}
+function renderCodexMcpBlock(serverName, command, mcpArgs) {
+    return [
+        LONGTABLE_MCP_MARKER_START,
+        `[mcp_servers.${serverName}]`,
+        `command = ${escapeTomlString(command)}`,
+        `args = [${mcpArgs.map((arg) => escapeTomlString(arg)).join(", ")}]`,
+        LONGTABLE_MCP_MARKER_END
+    ].join("\n");
+}
+function replaceMarkedCodexMcpBlock(existing, block, serverName) {
+    const markerPattern = new RegExp(`${LONGTABLE_MCP_MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${LONGTABLE_MCP_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`, "m");
+    const serverPattern = new RegExp(`\\n?\\[mcp_servers\\.${serverName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\][\\s\\S]*?(?=\\n\\[|$)`, "m");
+    const trimmed = existing.replace(markerPattern, "").replace(serverPattern, "").trimEnd();
+    return trimmed ? `${trimmed}\n\n${block}\n` : `${block}\n`;
+}
+async function writeCodexMcpConfig(path, block, serverName) {
+    const existing = existsSync(path) ? await readFile(path, "utf8") : "";
+    const updated = replaceMarkedCodexMcpBlock(existing, block, serverName);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, updated, "utf8");
+    return updated;
+}
+function renderClaudeMcpJson(serverName, command, mcpArgs) {
+    return JSON.stringify({
+        mcpServers: {
+            [serverName]: {
+                command,
+                args: mcpArgs
+            }
+        }
+    }, null, 2);
+}
+async function writeClaudeMcpSettings(path, serverName, command, mcpArgs) {
+    let settings = {};
+    if (existsSync(path)) {
+        const raw = await readFile(path, "utf8");
+        settings = raw.trim() ? JSON.parse(raw) : {};
+    }
+    const existingServers = typeof settings.mcpServers === "object" && settings.mcpServers !== null && !Array.isArray(settings.mcpServers)
+        ? settings.mcpServers
+        : {};
+    settings.mcpServers = {
+        ...existingServers,
+        [serverName]: {
+            command,
+            args: mcpArgs
+        }
+    };
+    const updated = JSON.stringify(settings, null, 2);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${updated}\n`, "utf8");
+    return `${updated}\n`;
+}
+function renderMcpInstallSummary(result) {
+    const lines = [
+        "LongTable MCP transport",
+        `- server: ${result.serverName}`,
+        `- package: ${result.packageSpec}`,
+        `- command: ${result.command} ${result.args.join(" ")}`,
+        `- mode: ${result.write ? "wrote provider config" : "printed config only"}`,
+        ""
+    ];
+    for (const target of result.targets) {
+        lines.push(`${target.provider} (${target.path})`);
+        lines.push("```" + target.format);
+        lines.push(target.content.trimEnd());
+        lines.push("```");
+        lines.push("");
+    }
+    if (!result.write) {
+        lines.push("Run again with `--write` to update these provider config files.");
+    }
+    return lines.join("\n").trimEnd();
+}
+async function runMcpSubcommand(subcommand, args) {
+    if (!subcommand || subcommand === "install" || subcommand === "print-config") {
+        const serverName = typeof args.name === "string" && args.name.trim()
+            ? args.name.trim()
+            : LONGTABLE_MCP_SERVER_NAME;
+        const packageSpec = resolveMcpPackageSpec(args);
+        const command = typeof args.command === "string" && args.command.trim() ? args.command.trim() : "npx";
+        const mcpArgs = command === "npx" ? ["-y", packageSpec] : [packageSpec];
+        const providers = resolveMcpProviders(args.provider);
+        const write = args.write === true;
+        const targets = [];
+        for (const provider of providers) {
+            if (provider === "codex") {
+                const path = resolveCodexMcpConfigPath(args);
+                const block = renderCodexMcpBlock(serverName, command, mcpArgs);
+                const content = write ? await writeCodexMcpConfig(path, block, serverName) : block;
+                targets.push({ provider, path, format: "toml", content });
+            }
+            if (provider === "claude") {
+                const path = resolveClaudeMcpSettingsPath(args);
+                const content = write
+                    ? await writeClaudeMcpSettings(path, serverName, command, mcpArgs)
+                    : renderClaudeMcpJson(serverName, command, mcpArgs);
+                targets.push({ provider, path, format: "json", content });
+            }
+        }
+        const result = {
+            serverName,
+            packageSpec,
+            command,
+            args: mcpArgs,
+            write,
+            targets
+        };
+        if (args.json === true) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(renderMcpInstallSummary(result));
+        return;
+    }
+    throw new Error("Unknown mcp subcommand.");
+}
 function commandOnPath(command) {
     try {
         execSync(`command -v ${command}`, { stdio: "ignore" });
@@ -1389,6 +1537,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) {
@@ -1402,6 +1716,9 @@ async function runAsk(args) {
         return;
     }
     const mode = inferred === "panel" ? "review" : inferred;
+    if (await runAutomaticClarificationIfNeeded(effectivePrompt, args)) {
+        return;
+    }
     const delegatedArgs = {
         ...args,
         prompt: effectivePrompt
@@ -1728,10 +2045,18 @@ async function main() {
         await runInstall(values);
         return;
     }
+    if (command === "mcp") {
+        await runMcpSubcommand(subcommand, values);
+        return;
+    }
     if (command === "ask") {
         await runAsk(values);
         return;
     }
+    if (command === "clarify") {
+        await runClarify(values);
+        return;
+    }
     if (command === "question") {
         await runQuestion(values);
         return;

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from "./prompt-aliases.js";
 export * from "./personas.js";
 export * from "./persona-router.js";
 export * from "./panel.js";
+export * from "./project-session.js";

package/dist/index.js

@@ -2,3 +2,4 @@ export * from "./prompt-aliases.js";
 export * from "./personas.js";
 export * from "./persona-router.js";
 export * from "./panel.js";
+export * from "./project-session.js";

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 {
@@ -99,10 +99,23 @@ export interface LongTableWorkspaceInspection {
         timestamp: 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;
@@ -120,6 +133,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

@@ -205,6 +205,9 @@ async function loadResearchState(stateFilePath) {
         ...(parsed.studyContract ? { studyContract: parsed.studyContract } : {})
     };
 }
+export async function loadWorkspaceState(context) {
+    return loadResearchState(context.stateFilePath);
+}
 function recentInvocationRecords(state, limit = 3) {
     return (state.invocationLog ?? []).slice(-limit).reverse();
 }
@@ -486,6 +489,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, {
@@ -557,7 +687,7 @@ export async function answerWorkspaceQuestion(options) {
         ...(option || explicitOther ? {} : { otherText: options.answer }),
         ...(options.rationale ? { rationale: options.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 = {

package/package.json

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