@longtable/cli 0.1.32 → 0.1.34

package/dist/longtable-codex-native-hook.js

@@ -0,0 +1,329 @@
+import { pathToFileURL } from "node:url";
+import { loadProjectContextFromDirectory, loadWorkspaceState, pendingQuestionObligations } from "./index.js";
+function safeString(value) {
+    return typeof value === "string" ? value : "";
+}
+function safeInteger(value) {
+    if (typeof value === "number" && Number.isInteger(value)) {
+        return value;
+    }
+    if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+        return Number.parseInt(value.trim(), 10);
+    }
+    return null;
+}
+function readHookEventName(payload) {
+    const candidate = safeString(payload.hook_event_name ??
+        payload.hookEventName ??
+        payload.event ??
+        payload.name).trim();
+    if (candidate === "SessionStart" ||
+        candidate === "PreToolUse" ||
+        candidate === "PostToolUse" ||
+        candidate === "UserPromptSubmit" ||
+        candidate === "Stop") {
+        return candidate;
+    }
+    return null;
+}
+function readPromptText(payload) {
+    return safeString(payload.prompt ?? payload.user_prompt ?? payload.userPrompt).trim();
+}
+function readToolName(payload) {
+    return safeString(payload.tool_name ?? payload.toolName).trim();
+}
+function readCommandText(payload) {
+    const direct = safeString(payload.command ?? payload.input ?? payload.tool_input ?? payload.toolInput).trim();
+    if (direct) {
+        return direct;
+    }
+    const toolInput = payload.tool_input ?? payload.toolInput;
+    if (toolInput && typeof toolInput === "object") {
+        const objectInput = toolInput;
+        return safeString(objectInput.command ?? objectInput.input ?? objectInput.cmd).trim();
+    }
+    return "";
+}
+function readExitCode(payload) {
+    return safeInteger(payload.exit_code ?? payload.exitCode);
+}
+function readCombinedOutput(payload) {
+    return [
+        safeString(payload.stderr),
+        safeString(payload.stdout),
+        safeString(payload.output)
+    ].filter(Boolean).join("\n").trim();
+}
+function formatQuestionOptions(question) {
+    const options = question.prompt.options.map((option) => option.value);
+    if (question.prompt.allowOther) {
+        options.push("other");
+    }
+    return options.join("/");
+}
+function pendingRequiredQuestions(state) {
+    return (state.questionLog ?? []).filter((question) => question.status === "pending" && question.prompt.required);
+}
+function pendingObligations(state) {
+    return pendingQuestionObligations(state);
+}
+function activeInterviewHook(state) {
+    return [...(state.hooks ?? [])].reverse().find((hook) => hook.kind === "longtable_interview" &&
+        (hook.status === "pending" || hook.status === "active" || hook.status === "ready_to_confirm"));
+}
+function compactContextValue(value, maxLength = 160) {
+    const compact = value.replace(/\s+/g, " ").trim();
+    if (compact.length <= maxLength) {
+        return compact;
+    }
+    return `${compact.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+function buildAdditionalContextOutput(hookEventName, additionalContext) {
+    return {
+        hookSpecificOutput: {
+            hookEventName,
+            additionalContext
+        }
+    };
+}
+function buildBlockOutput(hookEventName, reason, additionalContext) {
+    return {
+        hookSpecificOutput: {
+            hookEventName,
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+            additionalContext
+        }
+    };
+}
+function buildStopBlockOutput(reason) {
+    return {
+        decision: "block",
+        reason
+    };
+}
+function looksLikeClosurePrompt(prompt) {
+    const normalized = prompt.trim();
+    if (!normalized) {
+        return false;
+    }
+    return /\b(final|finalize|commit|ship|submit|revise|rewrite|draft|publish|implement|fix)\b/i.test(normalized)
+        || /최종|확정|커밋|제출|수정|초안|구현|진행|고쳐/.test(normalized);
+}
+function isStateChangingBash(command) {
+    const normalized = command.trim();
+    if (!normalized) {
+        return false;
+    }
+    return /\b(git\s+commit|npm\s+version|mv|cp|rm|sed\s+-i|perl\s+-i|tee|touch|mkdir|rmdir|apply_patch|patch)\b/.test(normalized)
+        || />\s*\S+/.test(normalized);
+}
+async function loadLongTableRuntime(startPath) {
+    const context = await loadProjectContextFromDirectory(startPath);
+    if (!context) {
+        return null;
+    }
+    const state = await loadWorkspaceState(context);
+    return { context, state };
+}
+function buildWorkspaceSummary(runtime, detail = "compact") {
+    const { context, state } = runtime;
+    if (detail === "compact") {
+        const primaryContext = state.firstResearchShape
+            ? `First research shape: ${compactContextValue(state.firstResearchShape.handle, 96)}.`
+            : `Current goal: ${compactContextValue(context.session.currentGoal, 120)}.`;
+        return [
+            "LongTable workspace detected; research context restored.",
+            primaryContext,
+            context.session.nextAction ? `Next action: ${compactContextValue(context.session.nextAction)}.` : "",
+            context.session.protectedDecision ? "Protected decision: active; full text is in `.longtable/` and `CURRENT.md`." : ""
+        ].filter(Boolean);
+    }
+    const lines = [
+        "LongTable workspace detected.",
+        `Current goal: ${context.session.currentGoal}.`,
+        context.session.currentBlocker ? `Current blocker: ${context.session.currentBlocker}.` : "",
+        context.session.protectedDecision ? `Protected decision: ${context.session.protectedDecision}.` : "",
+        state.firstResearchShape ? `First research shape: ${state.firstResearchShape.handle}.` : "",
+        context.session.nextAction ? `Next action: ${context.session.nextAction}.` : ""
+    ].filter(Boolean);
+    return lines;
+}
+function buildPendingQuestionContext(question) {
+    return [
+        `Required Researcher Checkpoint is still pending: ${question.prompt.question}`,
+        `Options: ${formatQuestionOptions(question)}`,
+        `Record it with longtable decide --question ${question.id} --answer <value> if you are outside MCP elicitation.`
+    ].join("\n");
+}
+function buildPendingObligationContext(obligation) {
+    return [
+        `Pending LongTable research obligation: ${obligation.prompt}`,
+        obligation.reason,
+        obligation.questionId
+            ? `This obligation is linked to question ${obligation.questionId}; answer it before treating the direction as settled.`
+            : "Resume the LongTable interview and let it ask the next research-facing checkpoint before settling the direction."
+    ].join("\n");
+}
+function buildActiveInterviewContext(hook) {
+    const turnCount = hook.turns?.length ?? 0;
+    return [
+        "A LongTable interview is currently active.",
+        `Interview status: ${hook.status}.`,
+        `Turns recorded: ${turnCount}.`,
+        "Do not finalize the research direction until the interview is either summarized into a First Research Shape or explicitly cleared."
+    ].join("\n");
+}
+function sessionStartContext(runtime) {
+    const blockingQuestion = pendingRequiredQuestions(runtime.state)[0];
+    const blockingObligation = pendingObligations(runtime.state)[0];
+    const interview = activeInterviewHook(runtime.state);
+    const needsDetailedSummary = Boolean(blockingQuestion || blockingObligation);
+    const sections = [buildWorkspaceSummary(runtime, needsDetailedSummary ? "full" : "compact").join("\n")];
+    if (blockingQuestion) {
+        sections.push(buildPendingQuestionContext(blockingQuestion));
+    }
+    else if (blockingObligation) {
+        sections.push(buildPendingObligationContext(blockingObligation));
+    }
+    else if (interview) {
+        sections.push(buildActiveInterviewContext(interview));
+    }
+    sections.push("Treat `.longtable/` state and `CURRENT.md` as the source of truth for this workspace.");
+    return sections.filter(Boolean).join("\n\n");
+}
+function userPromptSubmitContext(runtime, prompt) {
+    const blockingQuestion = pendingRequiredQuestions(runtime.state)[0];
+    if (blockingQuestion) {
+        return buildPendingQuestionContext(blockingQuestion);
+    }
+    const blockingObligation = pendingObligations(runtime.state)[0];
+    if (blockingObligation) {
+        return buildPendingObligationContext(blockingObligation);
+    }
+    const interview = activeInterviewHook(runtime.state);
+    if (interview) {
+        return buildActiveInterviewContext(interview);
+    }
+    if (runtime.context.session.protectedDecision && looksLikeClosurePrompt(prompt)) {
+        return [
+            `This workspace marks ${runtime.context.session.protectedDecision} as a protected decision.`,
+            "Before you settle it through drafting, revision, or closure, surface one researcher-facing checkpoint grounded in the current blocker or open questions."
+        ].join("\n");
+    }
+    return null;
+}
+function preToolUseOutput(runtime, payload) {
+    if (readToolName(payload) !== "Bash") {
+        return null;
+    }
+    const command = readCommandText(payload);
+    if (!isStateChangingBash(command)) {
+        return null;
+    }
+    const blockingQuestion = pendingRequiredQuestions(runtime.state)[0];
+    if (blockingQuestion) {
+        return buildBlockOutput("PreToolUse", "A required LongTable checkpoint is still pending before a state-changing Bash command.", buildPendingQuestionContext(blockingQuestion));
+    }
+    const blockingObligation = pendingObligations(runtime.state)[0];
+    if (blockingObligation) {
+        return buildBlockOutput("PreToolUse", "A LongTable research obligation is still pending before a state-changing Bash command.", buildPendingObligationContext(blockingObligation));
+    }
+    return null;
+}
+function postToolUseOutput(runtime, payload) {
+    if (readToolName(payload) !== "Bash") {
+        return null;
+    }
+    const command = readCommandText(payload);
+    const exitCode = readExitCode(payload);
+    const output = readCombinedOutput(payload);
+    const blockingQuestion = pendingRequiredQuestions(runtime.state)[0];
+    const blockingObligation = pendingObligations(runtime.state)[0];
+    if ((blockingQuestion || blockingObligation) && isStateChangingBash(command)) {
+        return buildBlockOutput("PostToolUse", "A state-changing Bash command completed while LongTable still had an unresolved checkpoint or obligation.", blockingQuestion
+            ? buildPendingQuestionContext(blockingQuestion)
+            : buildPendingObligationContext(blockingObligation));
+    }
+    if (exitCode !== null && exitCode !== 0 && output) {
+        return buildBlockOutput("PostToolUse", "The Bash command returned a non-zero exit code and should be reviewed before LongTable continues.", "Review the command output and explain what failed before retrying or continuing.");
+    }
+    return null;
+}
+function stopOutput(runtime) {
+    const blockingQuestion = pendingRequiredQuestions(runtime.state)[0];
+    if (blockingQuestion) {
+        return buildStopBlockOutput("A required LongTable Researcher Checkpoint is still pending.");
+    }
+    const blockingObligation = pendingObligations(runtime.state)[0];
+    if (blockingObligation) {
+        return buildStopBlockOutput("A LongTable research obligation is still pending.");
+    }
+    return null;
+}
+export async function dispatchCodexHook(payload, cwdOverride) {
+    const hookEventName = readHookEventName(payload);
+    if (!hookEventName) {
+        return null;
+    }
+    const runtime = await loadLongTableRuntime(cwdOverride ?? process.cwd());
+    if (!runtime) {
+        return null;
+    }
+    if (hookEventName === "SessionStart") {
+        return buildAdditionalContextOutput(hookEventName, sessionStartContext(runtime));
+    }
+    if (hookEventName === "UserPromptSubmit") {
+        const additionalContext = userPromptSubmitContext(runtime, readPromptText(payload));
+        return additionalContext
+            ? buildAdditionalContextOutput(hookEventName, additionalContext)
+            : null;
+    }
+    if (hookEventName === "PreToolUse") {
+        return preToolUseOutput(runtime, payload);
+    }
+    if (hookEventName === "PostToolUse") {
+        return postToolUseOutput(runtime, payload);
+    }
+    if (hookEventName === "Stop") {
+        return stopOutput(runtime);
+    }
+    return null;
+}
+async function readStdinJson() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    if (!raw) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function isCodexNativeHookMainModule(moduleUrl, argv1) {
+    if (!argv1) {
+        return false;
+    }
+    return moduleUrl === pathToFileURL(argv1).href;
+}
+async function main() {
+    const payload = await readStdinJson();
+    const output = await dispatchCodexHook(payload);
+    if (output) {
+        process.stdout.write(JSON.stringify(output));
+    }
+}
+if (isCodexNativeHookMainModule(import.meta.url, process.argv[1])) {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        process.exit(1);
+    });
+}

package/dist/project-session.d.ts

@@ -1,4 +1,4 @@
-import type { DecisionRecord, InvocationRecord, ProviderKind, QuestionOption, QuestionSurface, QuestionRecord, ResearchState } from "@longtable/core";
+import type { DecisionRecord, InvocationRecord, LongTableQuestionObligation, ProviderKind, QuestionOption, QuestionSurface, QuestionRecord, ResearchState } from "@longtable/core";
 import type { SetupPersistedOutput } from "@longtable/setup";
 export type ProjectDisagreementPreference = "synthesis_only" | "show_on_conflict" | "always_visible";
 export type StartInterviewSignal = "phenomenon" | "audience" | "artifact" | "evidence" | "assumption" | "decision_risk" | "voice";
@@ -141,6 +141,7 @@ export interface LongTableWorkspaceInspection {
         invocations: number;
         questions: number;
         pendingQuestions: number;
+        pendingObligations: number;
         answeredQuestions: number;
         decisions: number;
     };
@@ -161,6 +162,13 @@ export interface LongTableWorkspaceInspection {
         options: string[];
         required: boolean;
     }>;
+    pendingObligations?: Array<{
+        id: string;
+        kind: string;
+        prompt: string;
+        reason: string;
+        questionId?: string;
+    }>;
     recentDecisions?: Array<{
         id: string;
         checkpointKey: string;
@@ -213,6 +221,7 @@ export declare function summarizeLongTableInterview(options: {
     session: LongTableSessionRecord;
 }>;
 export declare function listBlockingWorkspaceQuestions(context: LongTableProjectContext): Promise<QuestionRecord[]>;
+export declare function listBlockingWorkspaceObligations(context: LongTableProjectContext): Promise<LongTableQuestionObligation[]>;
 export declare function assertWorkspaceNotBlocked(context: LongTableProjectContext): Promise<void>;
 export declare function createWorkspaceFollowUpQuestions(options: {
     context: LongTableProjectContext;
@@ -252,6 +261,20 @@ export declare function answerWorkspaceQuestion(options: {
     decision: DecisionRecord;
     state: ResearchState;
 }>;
+export declare function clearWorkspaceQuestion(options: {
+    context: LongTableProjectContext;
+    questionId: string;
+    reason: string;
+}): Promise<{
+    question: QuestionRecord;
+    state: ResearchState;
+}>;
+export declare function repairWorkspaceStateConsistency(options: {
+    context: LongTableProjectContext;
+}): Promise<{
+    state: ResearchState;
+    repaired: string[];
+}>;
 export declare function createOrUpdateProjectWorkspace(options: {
     projectName: string;
     projectPath: string;

package/dist/project-session.js

@@ -4,6 +4,7 @@ import { execSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
 import { appendDecisionRecord as appendDecisionToResearchState, appendInvocationRecord as appendInvocationToResearchState, appendQuestionRecords, createEmptyResearchState } from "@longtable/memory";
 import { classifyCheckpointTrigger } from "@longtable/checkpoints";
+import { ensureRequiredQuestionObligation, pendingQuestionObligations, resolveQuestionObligationByQuestionId } from "./question-obligations.js";
 const CURRENT_FILE_NAME = "CURRENT.md";
 const LEGACY_ROOT_FILES = ["LONGTABLE.md", "START-HERE.md", "NEXT-STEPS.md", "SESSION-SNAPSHOT.md"];
 function nowIso() {
@@ -105,7 +106,7 @@ function buildResumeHint(session) {
         ? `I want to continue ${session.currentGoal}. The unresolved blocker is ${session.currentBlocker}.`
         : `I want to continue ${session.currentGoal}.`;
 }
-function buildCurrentGuide(project, session, recentInvocations = [], pendingQuestions = []) {
+function buildCurrentGuide(project, session, recentInvocations = [], pendingQuestions = [], pendingObligations = []) {
     const locale = normalizeLocale(session.locale ?? project.locale);
     const openQuestions = session.openQuestions && session.openQuestions.length > 0
         ? session.openQuestions
@@ -156,6 +157,16 @@ function buildCurrentGuide(project, session, recentInvocations = [], pendingQues
                     "- 답변 기록: `longtable decide --question <id> --answer <value>`"
                 ]
                 : []),
+            ...(pendingObligations.length > 0
+                ? [
+                    "",
+                    "## 대기 중인 연구 의무",
+                    ...pendingObligations.map((obligation) => {
+                        const linked = obligation.questionId ? ` [question: ${obligation.questionId}]` : "";
+                        return `- ${obligation.prompt}${linked}: ${obligation.reason}`;
+                    })
+                ]
+                : []),
             "",
             "## 다시 시작 문장",
             `- "${resumeHint}"`,
@@ -219,6 +230,16 @@ function buildCurrentGuide(project, session, recentInvocations = [], pendingQues
                 "- Record an answer: `longtable decide --question <id> --answer <value>`"
             ]
             : []),
+        ...(pendingObligations.length > 0
+            ? [
+                "",
+                "## Pending Research Obligations",
+                ...pendingObligations.map((obligation) => {
+                    const linked = obligation.questionId ? ` [question: ${obligation.questionId}]` : "";
+                    return `- ${obligation.prompt}${linked}: ${obligation.reason}`;
+                })
+            ]
+            : []),
         "",
         "## Restart Prompt",
         `- "${resumeHint}"`,
@@ -251,6 +272,7 @@ async function loadResearchState(stateFilePath) {
         workingState: parsed.workingState ?? {},
         hooks: parsed.hooks ?? [],
         ...(parsed.firstResearchShape ? { firstResearchShape: parsed.firstResearchShape } : {}),
+        questionObligations: parsed.questionObligations ?? [],
         inferredHypotheses: parsed.inferredHypotheses ?? [],
         openTensions: parsed.openTensions ?? [],
         decisionLog: parsed.decisionLog ?? [],
@@ -273,6 +295,17 @@ function recentPendingQuestions(state, limit = 3) {
         .slice(-limit)
         .reverse();
 }
+function visiblePendingObligations(state) {
+    const pendingQuestionIds = new Set((state.questionLog ?? [])
+        .filter((record) => record.status === "pending")
+        .map((record) => record.id));
+    return pendingQuestionObligations(state).filter((obligation) => !obligation.questionId || !pendingQuestionIds.has(obligation.questionId));
+}
+function recentPendingObligations(state, limit = 3) {
+    return visiblePendingObligations(state)
+        .slice(-limit)
+        .reverse();
+}
 function formatQuestionOptionValues(record) {
     const values = record.prompt.options.map((option) => option.value);
     if (record.prompt.allowOther) {
@@ -284,6 +317,7 @@ function summarizeWorkspaceInspection(context, state) {
     const questions = state.questionLog ?? [];
     const pendingQuestions = questions.filter((record) => record.status === "pending");
     const answeredQuestions = questions.filter((record) => record.status === "answered");
+    const pendingObligations = visiblePendingObligations(state);
     return {
         found: true,
         rootPath: context.project.projectPath,
@@ -310,6 +344,7 @@ function summarizeWorkspaceInspection(context, state) {
             invocations: (state.invocationLog ?? []).length,
             questions: questions.length,
             pendingQuestions: pendingQuestions.length,
+            pendingObligations: pendingObligations.length,
             answeredQuestions: answeredQuestions.length,
             decisions: (state.decisionLog ?? []).length
         },
@@ -330,6 +365,13 @@ function summarizeWorkspaceInspection(context, state) {
             options: formatQuestionOptionValues(record),
             required: record.prompt.required
         })),
+        pendingObligations: pendingObligations.slice(-5).reverse().map((obligation) => ({
+            id: obligation.id,
+            kind: obligation.kind,
+            prompt: obligation.prompt,
+            reason: obligation.reason,
+            ...(obligation.questionId ? { questionId: obligation.questionId } : {})
+        })),
         recentDecisions: (state.decisionLog ?? []).slice(-5).reverse().map((record) => ({
             id: record.id,
             checkpointKey: record.checkpointKey,
@@ -499,7 +541,7 @@ async function removeLegacyRootFiles(projectPath) {
 }
 export async function syncCurrentWorkspaceView(context) {
     const state = await loadResearchState(context.stateFilePath);
-    const body = buildCurrentGuide(context.project, context.session, recentInvocationRecords(state), recentPendingQuestions(state));
+    const body = buildCurrentGuide(context.project, context.session, recentInvocationRecords(state), recentPendingQuestions(state), recentPendingObligations(state));
     await writeFile(context.currentFilePath, body, "utf8");
     return context.currentFilePath;
 }
@@ -717,6 +759,9 @@ function findQuestionForDecision(state, questionId) {
     }
     return pending.at(-1) ?? null;
 }
+function findPendingQuestionForClear(state, questionId) {
+    return (state.questionLog ?? []).find((record) => record.id === questionId && record.status === "pending") ?? null;
+}
 function pendingRequiredQuestions(state) {
     return (state.questionLog ?? []).filter((record) => record.status === "pending" && record.prompt.required);
 }
@@ -724,19 +769,36 @@ export async function listBlockingWorkspaceQuestions(context) {
     const state = await loadResearchState(context.stateFilePath);
     return pendingRequiredQuestions(state);
 }
+export async function listBlockingWorkspaceObligations(context) {
+    const state = await loadResearchState(context.stateFilePath);
+    return pendingQuestionObligations(state);
+}
 export async function assertWorkspaceNotBlocked(context) {
-    const blocking = await listBlockingWorkspaceQuestions(context);
-    if (blocking.length === 0) {
-        return;
-    }
-    const first = blocking[0];
-    const options = formatQuestionOptionValues(first).join("/");
-    throw new Error([
-        `LongTable is blocked by a required Researcher Checkpoint: ${first.id}`,
-        first.prompt.question,
-        `Options: ${options}`,
-        `Record an answer with: longtable decide --question ${first.id} --answer <value>`
-    ].join("\n"));
+    const [blockingQuestions, blockingObligations] = await Promise.all([
+        listBlockingWorkspaceQuestions(context),
+        listBlockingWorkspaceObligations(context)
+    ]);
+    if (blockingQuestions.length > 0) {
+        const first = blockingQuestions[0];
+        const options = formatQuestionOptionValues(first).join("/");
+        throw new Error([
+            `LongTable is blocked by a required Researcher Checkpoint: ${first.id}`,
+            first.prompt.question,
+            `Options: ${options}`,
+            `Record an answer with: longtable decide --question ${first.id} --answer <value>`
+        ].join("\n"));
+    }
+    if (blockingObligations.length > 0) {
+        const first = blockingObligations[0];
+        throw new Error([
+            `LongTable is blocked by a pending research obligation: ${first.id}`,
+            first.prompt,
+            first.reason,
+            ...(first.questionId
+                ? [`If a question was already issued, answer it with: longtable decide --question ${first.questionId} --answer <value>`]
+                : ["Resume the LongTable interview and answer the next researcher-facing checkpoint before proceeding."])
+        ].join("\n"));
+    }
 }
 function questionTitleForCheckpoint(family, checkpointKey) {
     if (checkpointKey === "knowledge_gap_probe") {
@@ -1080,9 +1142,10 @@ export async function createWorkspaceQuestion(options) {
         }
     };
     const updated = appendQuestionRecords(state, [question]);
-    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    const withObligation = ensureRequiredQuestionObligation(updated, question);
+    await writeFile(options.context.stateFilePath, JSON.stringify(withObligation, null, 2), "utf8");
     await syncCurrentWorkspaceView(options.context);
-    return { question, state: updated };
+    return { question, state: withObligation };
 }
 function updateInvocationWithDecision(invocation, questionId, decisionId) {
     if (!invocation.panelResult?.linkedQuestionRecordIds.includes(questionId)) {
@@ -1214,7 +1277,8 @@ export async function answerWorkspaceQuestion(options) {
         questionLog: (state.questionLog ?? []).map((record) => record.id === question.id ? answeredQuestion : record),
         invocationLog: (state.invocationLog ?? []).map((record) => updateInvocationWithDecision(record, question.id, decision.id))
     };
-    const updated = appendDecisionToResearchState(withQuestion, decision);
+    const withDecision = appendDecisionToResearchState(withQuestion, decision);
+    const updated = resolveQuestionObligationByQuestionId(withDecision, question.id, decision.id);
     await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
     await syncCurrentWorkspaceView(options.context);
     return {
@@ -1223,6 +1287,105 @@ export async function answerWorkspaceQuestion(options) {
         state: updated
     };
 }
+export async function clearWorkspaceQuestion(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const question = findPendingQuestionForClear(state, options.questionId);
+    if (!question) {
+        throw new Error(`No pending LongTable question found for ${options.questionId}.`);
+    }
+    const timestamp = nowIso();
+    const clearedQuestion = {
+        ...question,
+        updatedAt: timestamp,
+        status: "cleared",
+        clearedReason: options.reason.trim()
+    };
+    const withQuestion = {
+        ...state,
+        questionLog: (state.questionLog ?? []).map((record) => record.id === question.id ? clearedQuestion : record)
+    };
+    const updated = resolveQuestionObligationByQuestionId(withQuestion, question.id, undefined, "cleared");
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return {
+        question: clearedQuestion,
+        state: updated
+    };
+}
+export async function repairWorkspaceStateConsistency(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const repaired = [];
+    const hooks = state.hooks ?? [];
+    const hookMatchedByHandle = state.firstResearchShape?.confirmedAt
+        ? hooks.find((hook) => hook.kind === "longtable_interview" &&
+            hook.firstResearchShape?.handle === state.firstResearchShape?.handle)
+        : undefined;
+    const confirmedShape = state.firstResearchShape?.confirmedAt
+        ? {
+            ...state.firstResearchShape,
+            ...(state.firstResearchShape.sourceHookId
+                ? {}
+                : hookMatchedByHandle?.id
+                    ? { sourceHookId: hookMatchedByHandle.id }
+                    : {})
+        }
+        : undefined;
+    let updated = state;
+    if (confirmedShape && confirmedShape.sourceHookId && !state.firstResearchShape?.sourceHookId) {
+        repaired.push(`restored sourceHookId ${confirmedShape.sourceHookId} on confirmed first research shape`);
+        updated = {
+            ...updated,
+            firstResearchShape: confirmedShape,
+            workingState: {
+                ...updated.workingState,
+                firstResearchShape: confirmedShape
+            }
+        };
+    }
+    if (confirmedShape?.sourceHookId) {
+        const hooks = (updated.hooks ?? []).map((hook) => {
+            if (hook.id === confirmedShape.sourceHookId &&
+                hook.kind === "longtable_interview" &&
+                hook.status !== "confirmed") {
+                repaired.push(`confirmed interview hook ${hook.id}`);
+                return {
+                    ...hook,
+                    status: "confirmed",
+                    updatedAt: nowIso(),
+                    firstResearchShape: confirmedShape
+                };
+            }
+            return hook;
+        });
+        updated = {
+            ...updated,
+            hooks
+        };
+    }
+    if (confirmedShape?.sourceHookId) {
+        updated = {
+            ...updated,
+            questionObligations: (updated.questionObligations ?? []).map((obligation) => {
+                if (obligation.kind === "first_research_shape_confirmation" &&
+                    obligation.status === "pending" &&
+                    obligation.sourceHookId === confirmedShape.sourceHookId) {
+                    repaired.push(`cleared first research shape obligation ${obligation.id}`);
+                    return {
+                        ...obligation,
+                        status: "satisfied",
+                        updatedAt: nowIso()
+                    };
+                }
+                return obligation;
+            })
+        };
+    }
+    if (repaired.length > 0) {
+        await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+        await syncCurrentWorkspaceView(options.context);
+    }
+    return { state: updated, repaired };
+}
 export async function createOrUpdateProjectWorkspace(options) {
     const projectPath = resolve(options.projectPath);
     const metaDir = resolveMetaDir(projectPath);