@longtable/cli 0.1.11 → 0.1.12

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;
@@ -1536,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) {
@@ -1549,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
@@ -1883,6 +2053,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 {
@@ -104,6 +104,18 @@ export declare function syncCurrentWorkspaceView(context: LongTableProjectContex
 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 +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

@@ -489,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, {
@@ -560,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.11",
+  "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.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.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",