@longtable/cli 0.1.31 → 0.1.33

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() {
@@ -54,6 +55,9 @@ function resolveUserLocale() {
     return normalizeLocale(Intl.DateTimeFormat().resolvedOptions().locale);
 }
 function buildFirstQuestion(session) {
+    if (session.firstResearchShape?.openQuestions?.[0]) {
+        return session.firstResearchShape.openQuestions[0];
+    }
     return session.currentBlocker
         ? `Where does "${session.currentBlocker}" show up most concretely in the scene, material, or evidence?`
         : `What scene, case, text, data, or draft would make "${session.currentGoal}" easiest to inspect first?`;
@@ -63,20 +67,23 @@ function buildOpenQuestions(session) {
     if (session.startInterview) {
         return [
             firstQuestion,
-            `What would a reader need to understand differently if "${session.currentGoal}" becomes a strong research project?`
+            `What still feels hardest to name or make concrete in "${session.currentGoal}"?`
         ];
     }
     return session.currentBlocker
         ? [
             firstQuestion,
-            `What would a reader need to understand differently if "${session.currentBlocker}" becomes a strong research problem?`
+            `What would give "${session.currentBlocker}" a usable first research handle without forcing a final research question yet?`
         ]
         : [
             firstQuestion,
-            `What would count as a good first outcome for "${session.currentGoal}" in this session?`
+            `What would give this project a usable first research handle without pretending the question is settled?`
         ];
 }
 function buildNextAction(session) {
+    if (session.firstResearchShape) {
+        return session.firstResearchShape.nextAction;
+    }
     if (session.startInterview) {
         return session.currentBlocker
             ? `Begin from the start-interview brief, then make "${session.currentBlocker}" concrete with one scene, source, case, or dataset.`
@@ -87,6 +94,9 @@ function buildNextAction(session) {
         : "Open with your current goal in one sentence, then ask LongTable for the first concrete research move.";
 }
 function buildResumeHint(session) {
+    if (session.firstResearchShape) {
+        return `I want to continue from the First Research Shape: ${session.firstResearchShape.handle}.`;
+    }
     if (session.startInterview) {
         return session.currentBlocker
             ? `I want to continue from the LongTable start interview. The first unresolved issue is ${session.currentBlocker}.`
@@ -96,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
@@ -118,6 +128,7 @@ function buildCurrentGuide(project, session, recentInvocations = [], pendingQues
             ...(session.researchObject ? [`- 연구 객체: ${session.researchObject}`] : []),
             ...(session.gapRisk ? [`- 공백/암묵지 위험: ${session.gapRisk}`] : []),
             ...(session.protectedDecision ? [`- 보호할 결정: ${session.protectedDecision}`] : []),
+            ...(session.firstResearchShape ? [`- First Research Shape: ${session.firstResearchShape.handle}`] : []),
             ...(session.startInterview ? [`- start interview: ${session.startInterview.summary}`] : []),
             `- 다음 액션: ${nextAction}`,
             `- 관점: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
@@ -146,13 +157,32 @@ 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}"`,
+            ...(session.firstResearchShape
+                ? [
+                    "",
+                    "## First Research Shape",
+                    `- Handle: ${session.firstResearchShape.handle}`,
+                    `- Confidence: ${session.firstResearchShape.confidence}`,
+                    ...session.firstResearchShape.openQuestions.map((question) => `- Open question: ${question}`)
+                ]
+                : []),
             "",
             "## 빠른 시작",
             "- 이 디렉토리에서 `codex`를 엽니다.",
-            `- 첫 메시지는 보통 \`${suggestedPrompt}\` 정도면 충분합니다.`,
+            `- 첫 메시지는 보통 \`${session.firstResearchShape ? suggestedPrompt : "$longtable-interview"}\` 정도면 충분합니다.`,
             "",
             "## 증거 규칙",
             "- 외부 사실이나 현재 정보는 source를 붙이거나 inference로 낮춥니다."
@@ -171,6 +201,7 @@ function buildCurrentGuide(project, session, recentInvocations = [], pendingQues
         ...(session.researchObject ? [`- Research object: ${session.researchObject}`] : []),
         ...(session.gapRisk ? [`- Gap/tacit risk: ${session.gapRisk}`] : []),
         ...(session.protectedDecision ? [`- Protected decision: ${session.protectedDecision}`] : []),
+        ...(session.firstResearchShape ? [`- First Research Shape: ${session.firstResearchShape.handle}`] : []),
         ...(session.startInterview ? [`- Start interview: ${session.startInterview.summary}`] : []),
         `- Next action: ${nextAction}`,
         `- Perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
@@ -199,13 +230,32 @@ 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}"`,
+        ...(session.firstResearchShape
+            ? [
+                "",
+                "## First Research Shape",
+                `- Handle: ${session.firstResearchShape.handle}`,
+                `- Confidence: ${session.firstResearchShape.confidence}`,
+                ...session.firstResearchShape.openQuestions.map((question) => `- Open question: ${question}`)
+            ]
+            : []),
         "",
         "## Quick Start",
         "- Open `codex` in this directory.",
-        `- A good first message is usually \`${suggestedPrompt}\`.`,
+        `- A good first message is usually \`${session.firstResearchShape ? suggestedPrompt : "$longtable-interview"}\`.`,
         "",
         "## Evidence Rule",
         "- External or current claims should carry a source link or be labeled as inference."
@@ -220,6 +270,9 @@ async function loadResearchState(stateFilePath) {
         ...parsed,
         explicitState: parsed.explicitState ?? {},
         workingState: parsed.workingState ?? {},
+        hooks: parsed.hooks ?? [],
+        ...(parsed.firstResearchShape ? { firstResearchShape: parsed.firstResearchShape } : {}),
+        questionObligations: parsed.questionObligations ?? [],
         inferredHypotheses: parsed.inferredHypotheses ?? [],
         openTensions: parsed.openTensions ?? [],
         decisionLog: parsed.decisionLog ?? [],
@@ -242,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) {
@@ -253,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,
@@ -279,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
         },
@@ -299,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,
@@ -339,13 +412,16 @@ function buildProjectAgentsMd(project, session) {
         "- Treat `AGENTS.md` as runtime guidance, not as the researcher-facing resume artifact.",
         "",
         "## Invocation Rules",
+        "- If the user message starts with `$longtable-interview`, run the LongTable interview flow before generic research advice.",
         "- If the user message starts with `lt `, `longtable `, `long table `, or `롱테이블 ` followed by a directive and `:`, treat it as an explicit LongTable invocation.",
-        "- Supported explicit directives are: explore, review, critique, draft, commit, panel, status, editor, reviewer, methods, theory, measurement, ethics, voice, venue.",
+        "- Supported explicit directives are: interview, explore, review, critique, draft, commit, panel, status, editor, reviewer, methods, theory, measurement, ethics, voice, venue.",
         "- For explicit LongTable invocations, do not begin by scanning the workspace. Use the current session files first and answer as LongTable immediately.",
         "- For general research requests in this workspace, prefer LongTable behavior before generic coding behavior.",
         "",
         "## Research Behavior",
         "- Begin exploratory work with clarifying or tension questions before recommending a direction.",
+        "- For `$longtable-interview`, ask one natural-language question at a time, reflect with `LongTable hears: ...`, and avoid early reader/reviewer or theory/method/measurement classification.",
+        "- Use structured options only at the final First Research Shape confirmation or at true checkpoint boundaries.",
         "- If you foreground role perspectives, disclose them with `LongTable consulted: ...`.",
         "- Keep one accountable synthesis, but do not hide meaningful disagreement.",
         ...(session.disagreementPreference === "always_visible"
@@ -362,6 +438,7 @@ function buildProjectAgentsMd(project, session) {
         ...(session.researchObject ? [`- Research object: ${session.researchObject}`] : []),
         ...(session.gapRisk ? [`- Gap/tacit risk: ${session.gapRisk}`] : []),
         ...(session.protectedDecision ? [`- Protected decision: ${session.protectedDecision}`] : []),
+        ...(session.firstResearchShape ? [`- First Research Shape: ${session.firstResearchShape.handle}`] : []),
         ...(session.startInterview ? [`- Start interview summary: ${session.startInterview.summary}`] : []),
         `- Requested perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
         `- Disagreement visibility: ${session.disagreementPreference}`,
@@ -390,6 +467,10 @@ function buildStateSeed(project, session, setup) {
         ...(session.startInterview ? { startInterview: session.startInterview } : {}),
         ...(session.resumeHint ? { resumeHint: session.resumeHint } : {})
     };
+    if (session.firstResearchShape) {
+        state.firstResearchShape = session.firstResearchShape;
+        state.workingState.firstResearchShape = session.firstResearchShape;
+    }
     if (session.currentBlocker) {
         state.openTensions.push(session.currentBlocker);
     }
@@ -460,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;
 }
@@ -477,6 +558,200 @@ export async function appendInvocationRecordToWorkspace(context, invocation, que
 function createId(prefix) {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
+function normalizeInterviewQuality(answer, quality) {
+    if (quality) {
+        return quality;
+    }
+    const trimmed = answer.trim();
+    const wordCount = trimmed.split(/\s+/).filter(Boolean).length;
+    if (trimmed.length < 12 || wordCount < 3) {
+        return "thin";
+    }
+    if (trimmed.length > 80 || wordCount >= 12) {
+        return "rich";
+    }
+    return "usable";
+}
+function defaultFollowUpQuestion(answer) {
+    const trimmed = answer.trim();
+    if (trimmed.length < 12) {
+        return "Say one more sentence about where this problem appears or why it matters before LongTable tries to classify it.";
+    }
+    return "What concrete scene, case, material, text, dataset, or decision would make that problem easier to inspect first?";
+}
+function depthForInterview(turns = []) {
+    const usableTurns = turns.filter((turn) => turn.quality !== "thin").length;
+    if (usableTurns >= 3) {
+        return "ready_to_summarize";
+    }
+    if (usableTurns >= 1) {
+        return "forming_first_handle";
+    }
+    return "gathering_context";
+}
+function activeInterviewHook(state, hookId) {
+    const hooks = state.hooks ?? [];
+    if (hookId) {
+        return hooks.find((hook) => hook.id === hookId);
+    }
+    return [...hooks].reverse().find((hook) => hook.kind === "longtable_interview" &&
+        (hook.status === "pending" || hook.status === "active" || hook.status === "ready_to_confirm"));
+}
+function upsertHook(state, hook) {
+    const hooks = state.hooks ?? [];
+    const existingIndex = hooks.findIndex((candidate) => candidate.id === hook.id);
+    const nextHooks = existingIndex >= 0
+        ? hooks.map((candidate) => candidate.id === hook.id ? hook : candidate)
+        : [...hooks, hook];
+    return {
+        ...state,
+        hooks: nextHooks
+    };
+}
+export async function beginLongTableInterview(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const existing = activeInterviewHook(state);
+    if (existing) {
+        return { hook: existing, state };
+    }
+    const timestamp = nowIso();
+    const hook = {
+        id: createId("hook_interview"),
+        kind: "longtable_interview",
+        status: "active",
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        targetOutcome: "first_research_handle",
+        depth: "gathering_context",
+        provider: options.provider,
+        turns: [],
+        qualityNotes: [],
+        rationale: [
+            "Official LongTable research start surface is provider-native `$longtable-interview`, not the CLI start questionnaire.",
+            "The hook keeps early research ambiguity open until a first research handle can be summarized."
+        ]
+    };
+    let updated = upsertHook(state, hook);
+    updated.workingState = {
+        ...updated.workingState,
+        activeInterviewHookId: hook.id,
+        interviewSurface: "$longtable-interview",
+        ...(options.openingQuestion ? { interviewOpeningQuestion: options.openingQuestion } : {}),
+        ...(options.seedAnswer ? { interviewSeedAnswer: options.seedAnswer } : {})
+    };
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return { hook, state: updated };
+}
+export async function appendLongTableInterviewTurn(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const existing = activeInterviewHook(state, options.hookId);
+    if (!existing) {
+        throw new Error("No active LongTable interview hook was found. Run begin_interview first.");
+    }
+    const quality = normalizeInterviewQuality(options.answer, options.quality);
+    const needsFollowUp = options.needsFollowUp ?? quality === "thin";
+    const followUpQuestion = needsFollowUp
+        ? options.followUpQuestion ?? defaultFollowUpQuestion(options.answer)
+        : options.followUpQuestion;
+    const timestamp = nowIso();
+    const turns = existing.turns ?? [];
+    const turn = {
+        id: createId("interview_turn"),
+        index: turns.length + 1,
+        createdAt: timestamp,
+        question: options.question.trim(),
+        answer: options.answer.trim(),
+        ...(options.reflection?.trim() ? { reflection: options.reflection.trim() } : {}),
+        quality,
+        needsFollowUp,
+        ...(followUpQuestion?.trim() ? { followUpQuestion: followUpQuestion.trim() } : {}),
+        ...(options.rationale && options.rationale.length > 0 ? { rationale: options.rationale } : {})
+    };
+    const nextTurns = [...turns, turn];
+    const depth = depthForInterview(nextTurns);
+    const hook = {
+        ...existing,
+        status: depth === "ready_to_summarize" ? "ready_to_confirm" : "active",
+        updatedAt: timestamp,
+        depth,
+        turns: nextTurns,
+        qualityNotes: [
+            ...(existing.qualityNotes ?? []),
+            ...(needsFollowUp ? [`Turn ${turn.index} needs follow-up: ${followUpQuestion}`] : [])
+        ]
+    };
+    const updated = upsertHook(state, hook);
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return { hook, turn, state: updated };
+}
+export async function summarizeLongTableInterview(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const existing = activeInterviewHook(state, options.hookId);
+    if (!existing) {
+        throw new Error("No active LongTable interview hook was found. Run begin_interview first.");
+    }
+    const timestamp = nowIso();
+    const shape = {
+        ...options.shape,
+        handle: options.shape.handle.trim(),
+        currentGoal: options.shape.currentGoal.trim(),
+        openQuestions: options.shape.openQuestions.map((question) => question.trim()).filter(Boolean),
+        nextAction: options.shape.nextAction.trim(),
+        sourceHookId: existing.id
+    };
+    const hook = {
+        ...existing,
+        status: "ready_to_confirm",
+        updatedAt: timestamp,
+        depth: "ready_to_summarize",
+        firstResearchShape: shape
+    };
+    const session = {
+        ...options.context.session,
+        lastUpdatedAt: timestamp,
+        currentGoal: shape.currentGoal,
+        ...(shape.currentBlocker ? { currentBlocker: shape.currentBlocker } : {}),
+        ...(shape.researchObject ? { researchObject: shape.researchObject } : {}),
+        ...(shape.gapRisk ? { gapRisk: shape.gapRisk } : {}),
+        ...(shape.protectedDecision ? { protectedDecision: shape.protectedDecision } : {}),
+        nextAction: shape.nextAction,
+        openQuestions: shape.openQuestions,
+        firstResearchShape: shape,
+        resumeHint: `I want to continue from the First Research Shape: ${shape.handle}.`
+    };
+    options.context.session = session;
+    let updated = upsertHook(state, hook);
+    updated.firstResearchShape = shape;
+    updated.workingState = {
+        ...updated.workingState,
+        currentGoal: shape.currentGoal,
+        ...(shape.currentBlocker ? { currentBlocker: shape.currentBlocker } : {}),
+        ...(shape.researchObject ? { researchObject: shape.researchObject } : {}),
+        ...(shape.gapRisk ? { gapRisk: shape.gapRisk } : {}),
+        ...(shape.protectedDecision ? { protectedDecision: shape.protectedDecision } : {}),
+        openQuestions: shape.openQuestions,
+        nextAction: shape.nextAction,
+        firstResearchShape: shape
+    };
+    if (shape.currentBlocker && !updated.openTensions.includes(shape.currentBlocker)) {
+        updated.openTensions.push(shape.currentBlocker);
+    }
+    updated.narrativeTraces.push({
+        id: createId("narrative_trace"),
+        timestamp,
+        source: "$longtable-interview",
+        traceType: "judgment",
+        summary: `First Research Shape: ${shape.handle}.`,
+        visibility: "explicit",
+        importance: shape.confidence
+    });
+    await writeFile(options.context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return { hook, shape, state: updated, session };
+}
 function findQuestionForDecision(state, questionId) {
     const pending = (state.questionLog ?? []).filter((record) => record.status === "pending");
     if (questionId) {
@@ -484,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);
 }
@@ -491,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") {
@@ -847,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)) {
@@ -981,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 {
@@ -990,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);
@@ -1175,6 +1571,7 @@ export function renderProjectWorkspaceSummary(context) {
         `Goal: ${context.session.currentGoal}`,
         ...(context.session.currentBlocker ? [`Blocker: ${context.session.currentBlocker}`] : []),
         ...(context.session.researchObject ? [`Working object: ${context.session.researchObject}`] : []),
+        ...(context.session.firstResearchShape ? [`First Research Shape: ${context.session.firstResearchShape.handle}`] : []),
         ...(context.session.startInterview ? [`Start interview: ${context.session.startInterview.summary}`] : []),
         "└───────────────────────────────────────────────────────┘",
         "",

package/dist/prompt-aliases.js

@@ -29,18 +29,18 @@ function promptSpec() {
             argumentHint: "[project context or current uncertainty]",
             body: [
                 "You are LongTable setup guidance inside Codex.",
-                "Treat `longtable init` as deprecated. Prefer `longtable setup --provider codex` for runtime permissions, then `longtable start` for the project interview.",
+                "Treat `longtable init` as deprecated. Prefer `longtable setup --provider codex` for runtime permissions, then `$longtable-interview` inside Codex for the project interview.",
                 "Ask exactly one setup question at a time.",
                 "Use numbered choices and include a concise Why / What you get / Tradeoff for each option.",
                 "Do not move to the next question until the researcher answers the current one.",
-                "Runtime setup covers only: provider, install scope, runtime surfaces, intervention strength, and whether to create a workspace now.",
+                "Runtime setup covers only: provider, install scope, runtime surfaces, intervention strength, and whether to show interview launch steps.",
                 "Do not ask for field, career stage, experience level, authorship signal, weakest domain, or panel preference during runtime setup.",
-                "Project start covers: research object, gap/tacit risk, and protected decision area.",
+                "Project interview covers: the first research handle, early uncertainty, first inspectable material, and final structured confirmation.",
                 "After collecting runtime answers, summarize the proposed setup and output the exact `longtable setup --provider codex ...` command.",
-                "If the researcher is ready to create a project workspace, output the exact `longtable start ...` command separately.",
+                "If the researcher is ready to create a project workspace, tell them to open Codex in the research folder and invoke `$longtable-interview`.",
                 "If the researcher asks you to stay inside Codex, keep the conversation in numbered form and do not prematurely close.",
                 "Frame setup as permission and intervention calibration, not a researcher profile interview.",
-                "Do not pretend setup is the full project-start interview. The project-start interview happens in `longtable start`.",
+                "Do not pretend setup is the full project-start interview. The project-start interview happens in `$longtable-interview`.",
                 "Treat any slash-command arguments as context for why setup is being done now."
             ]
         },