@longtable/cli 0.1.8 → 0.1.10

package/dist/project-session.js

@@ -1,7 +1,11 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
-import { createEmptyResearchState } from "@diverga/memory";
+import { appendDecisionRecord as appendDecisionToResearchState, appendInvocationRecord as appendInvocationToResearchState, appendQuestionRecords, createEmptyResearchState } from "@longtable/memory";
+import { classifyCheckpointTrigger } from "@longtable/checkpoints";
+const CURRENT_FILE_NAME = "CURRENT.md";
+const LEGACY_ROOT_FILES = ["LONGTABLE.md", "START-HERE.md", "NEXT-STEPS.md", "SESSION-SNAPSHOT.md"];
 function nowIso() {
     return new Date().toISOString();
 }
@@ -16,160 +20,303 @@ function slugify(input) {
 function resolveMetaDir(projectPath) {
     return join(projectPath, ".longtable");
 }
-function buildWorkspaceGuide(project, session) {
-    const lines = [
-        "# Long Table Workspace",
-        "",
-        "This directory is a Long Table research workspace.",
-        "",
-        "## Current project",
-        `- Project: ${project.projectName}`,
-        `- Goal right now: ${session.currentGoal}`,
-        ...(session.currentBlocker ? [`- Current blocker: ${session.currentBlocker}`] : []),
-        `- Disagreement visibility: ${session.disagreementPreference}`,
-        `- Requested perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
-        "",
-        "## How Codex should behave here",
-        "- Treat this as a researcher-facing Long Table session, not a generic coding task.",
-        "- Ask clarifying or tension questions before closing too early.",
-        "- If you foreground specific roles, disclose them with `Long Table consulted: ...`.",
-        "- Keep one accountable synthesis, but keep disagreement visible by default when it matters.",
-        "- For factual, current, or external claims, attach source links or local file references whenever possible.",
-        "- If you cannot source a statement, label it as an inference or estimate.",
-        "- Do not expose internal tool logs or process commentary in researcher-facing answers.",
-        "",
-        "## Session files",
-        "- `.longtable/project.json` contains project-level metadata.",
-        "- `.longtable/current-session.json` contains the current session goal and blocker."
-    ];
-    return lines.join("\n");
+function resolveStateFilePath(projectPath) {
+    return join(resolveMetaDir(projectPath), "state.json");
 }
-function buildStartHereGuide(project, session) {
-    const lines = [
-        "# Start Here",
-        "",
-        `Project: ${project.projectName}`,
-        "",
-        "This workspace was created by Long Table for a single research project.",
-        "",
-        "## What to do now",
-        "1. Open Codex in this directory.",
-        "2. Start with your current goal, not a shell command.",
-        "3. Let Long Table keep disagreement visible when it matters.",
-        "4. If you ask for factual or current external information, expect sources or an explicit inference label.",
-        "",
-        "## Suggested first message",
-        session.currentBlocker
-            ? `"I want to work on ${session.currentGoal}. My current blocker is: ${session.currentBlocker}."`
-            : `"I want to work on ${session.currentGoal}."`,
-        "",
-        "## Explicit Long Table invocation inside Codex",
-        "- `lt explore: <question>`",
-        "- `lt review: <claim or plan>`",
-        "- `lt panel: <claim or plan>`",
-        "- `lt editor: <draft or positioning question>`",
-        "- `lt reviewer: <claim or section>`",
-        "- `lt methods: <design, measure, or analysis plan>`",
-        "- `lt commit: <decision that needs commitment>`",
-        "",
-        "## What Long Table already knows in this directory",
-        `- Current goal: ${session.currentGoal}`,
-        ...(session.currentBlocker ? [`- Current blocker: ${session.currentBlocker}`] : []),
-        `- Requested perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
-        `- Disagreement visibility: ${session.disagreementPreference}`,
-        "",
-        "## Files",
-        "- `AGENTS.md` tells Codex how to behave in this workspace.",
-        "- `.longtable/current-session.json` stores the current session goal and blocker.",
-        "- `.longtable/project.json` stores the project-level record.",
-        "- `NEXT-STEPS.md` stores the immediate next actions.",
-        "- `SESSION-SNAPSHOT.md` stores the short resume snapshot."
-    ];
-    return lines.join("\n");
+function resolveCurrentFilePath(projectPath) {
+    return join(projectPath, CURRENT_FILE_NAME);
+}
+function normalizeLocale(locale) {
+    if ((locale ?? "").toLowerCase().startsWith("ko")) {
+        return "ko";
+    }
+    return "en";
+}
+function resolveUserLocale() {
+    const envLocale = process.env.LC_ALL ??
+        process.env.LC_MESSAGES ??
+        process.env.LANG ??
+        "";
+    if (envLocale && !["c", "c.utf-8", "posix"].includes(envLocale.toLowerCase())) {
+        return normalizeLocale(envLocale);
+    }
+    if (process.platform === "darwin") {
+        try {
+            const appleLocale = execSync("defaults read -g AppleLocale", { encoding: "utf8" }).trim();
+            if (appleLocale) {
+                return normalizeLocale(appleLocale);
+            }
+        }
+        catch {
+            // Ignore and fall back to Intl below.
+        }
+    }
+    return normalizeLocale(Intl.DateTimeFormat().resolvedOptions().locale);
 }
-function buildNextStepsGuide(project, session) {
-    const firstQuestion = session.currentBlocker
+function buildFirstQuestion(session) {
+    return session.currentBlocker
         ? `What would reduce the uncertainty around "${session.currentBlocker}" first?`
         : `What is the first concrete question that would move "${session.currentGoal}" forward?`;
+}
+function buildOpenQuestions(session) {
+    const firstQuestion = buildFirstQuestion(session);
+    return session.currentBlocker
+        ? [
+            firstQuestion,
+            `What evidence would let you decide whether "${session.currentBlocker}" is a knowledge gap, a coding rule gap, or a data gap?`
+        ]
+        : [
+            firstQuestion,
+            `What would count as a good first outcome for "${session.currentGoal}" in this session?`
+        ];
+}
+function buildNextAction(session) {
+    return session.currentBlocker
+        ? `Open with the blocker, then ask LongTable to surface the first high-leverage uncertainty around "${session.currentBlocker}".`
+        : "Open with your current goal in one sentence, then ask LongTable for the first concrete research move.";
+}
+function buildResumeHint(session) {
+    return session.currentBlocker
+        ? `I want to continue ${session.currentGoal}. The unresolved blocker is ${session.currentBlocker}.`
+        : `I want to continue ${session.currentGoal}.`;
+}
+function buildCurrentGuide(project, session, recentInvocations = [], pendingQuestions = []) {
+    const locale = normalizeLocale(session.locale ?? project.locale);
+    const openQuestions = session.openQuestions && session.openQuestions.length > 0
+        ? session.openQuestions
+        : buildOpenQuestions(session);
+    const nextAction = session.nextAction ?? buildNextAction(session);
+    const resumeHint = session.resumeHint ?? buildResumeHint(session);
+    const suggestedPrompt = `lt explore: ${openQuestions[0]}`;
+    if (locale === "ko") {
+        return [
+            "# CURRENT",
+            "",
+            `Project: ${project.projectName}`,
+            "",
+            "이 파일은 `.longtable/current-session.json`과 `.longtable/state.json`에서 재생성되는 현재 작업 뷰입니다.",
+            "",
+            "## 지금 초점",
+            `- 현재 목표: ${session.currentGoal}`,
+            ...(session.currentBlocker ? [`- 현재 blocker: ${session.currentBlocker}`] : []),
+            `- 다음 액션: ${nextAction}`,
+            `- 관점: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
+            `- disagreement: ${session.disagreementPreference}`,
+            "",
+            "## 열린 질문",
+            ...openQuestions.map((question) => `- ${question}`),
+            ...(recentInvocations.length > 0
+                ? [
+                    "",
+                    "## 최근 LongTable 호출",
+                    ...recentInvocations.map((record) => {
+                        const roles = record.intent.roles.length > 0 ? record.intent.roles.join(", ") : "auto";
+                        return `- ${record.intent.kind}/${record.intent.mode} via ${record.surface}: ${roles}`;
+                    })
+                ]
+                : []),
+            ...(pendingQuestions.length > 0
+                ? [
+                    "",
+                    "## 대기 중인 결정 질문",
+                    ...pendingQuestions.map((record) => {
+                        const options = formatQuestionOptionValues(record).join("/");
+                        return `- ${record.id}: ${record.prompt.question} (${options})`;
+                    }),
+                    "- 답변 기록: `longtable decide --question <id> --answer <value>`"
+                ]
+                : []),
+            "",
+            "## 다시 시작 문장",
+            `- "${resumeHint}"`,
+            "",
+            "## 빠른 시작",
+            "- 이 디렉토리에서 `codex`를 엽니다.",
+            `- 첫 메시지는 보통 \`${suggestedPrompt}\` 정도면 충분합니다.`,
+            "",
+            "## 증거 규칙",
+            "- 외부 사실이나 현재 정보는 source를 붙이거나 inference로 낮춥니다."
+        ].join("\n");
+    }
     return [
-        "# Next Steps",
+        "# CURRENT",
         "",
         `Project: ${project.projectName}`,
         "",
-        "## Immediate actions",
-        "1. Open Codex in this directory.",
-        "2. State your current goal in one sentence.",
-        "3. Ask Long Table to surface disagreement before closing on a plan.",
-        "",
-        "## Suggested openings",
-        `- ${session.currentBlocker ? `"I want to work on ${session.currentGoal}. My current blocker is ${session.currentBlocker}."` : `"I want to work on ${session.currentGoal}."`}`,
-        `- "lt explore: ${firstQuestion}"`,
-        `- "lt panel: Show me the strongest disagreement before I commit."`,
+        "This file is regenerated from `.longtable/current-session.json` and `.longtable/state.json`.",
         "",
-        "## If you come back later",
-        "- Read `SESSION-SNAPSHOT.md` first.",
-        "- Continue from the unresolved blocker rather than restating the whole project.",
+        "## Focus Now",
+        `- Current goal: ${session.currentGoal}`,
+        ...(session.currentBlocker ? [`- Current blocker: ${session.currentBlocker}`] : []),
+        `- Next action: ${nextAction}`,
+        `- Perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
+        `- Disagreement: ${session.disagreementPreference}`,
         "",
-        "## Evidence reminder",
-        "- For factual or current external claims, Long Table should provide a source link or label the statement as inference."
-    ].join("\n");
-}
-function buildSessionSnapshot(project, session) {
-    return [
-        "# Session Snapshot",
+        "## Open Questions",
+        ...openQuestions.map((question) => `- ${question}`),
+        ...(recentInvocations.length > 0
+            ? [
+                "",
+                "## Recent LongTable Invocations",
+                ...recentInvocations.map((record) => {
+                    const roles = record.intent.roles.length > 0 ? record.intent.roles.join(", ") : "auto";
+                    return `- ${record.intent.kind}/${record.intent.mode} via ${record.surface}: ${roles}`;
+                })
+            ]
+            : []),
+        ...(pendingQuestions.length > 0
+            ? [
+                "",
+                "## Pending Decision Questions",
+                ...pendingQuestions.map((record) => {
+                    const options = formatQuestionOptionValues(record).join("/");
+                    return `- ${record.id}: ${record.prompt.question} (${options})`;
+                }),
+                "- Record an answer: `longtable decide --question <id> --answer <value>`"
+            ]
+            : []),
         "",
-        `Project: ${project.projectName}`,
-        `Current goal: ${session.currentGoal}`,
-        ...(session.currentBlocker ? [`Current blocker: ${session.currentBlocker}`] : []),
-        `Requested perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
-        `Disagreement visibility: ${session.disagreementPreference}`,
+        "## Restart Prompt",
+        `- "${resumeHint}"`,
         "",
-        "## Resume prompt",
-        session.currentBlocker
-            ? `"I want to continue ${session.currentGoal}. The unresolved blocker is ${session.currentBlocker}."`
-            : `"I want to continue ${session.currentGoal}."`,
+        "## Quick Start",
+        "- Open `codex` in this directory.",
+        `- A good first message is usually \`${suggestedPrompt}\`.`,
         "",
-        "## Notes",
-        "- This is a short orientation artifact, not a full transcript.",
-        "- If factual or external claims matter, Long Table should cite sources or mark them as inference."
+        "## Evidence Rule",
+        "- External or current claims should carry a source link or be labeled as inference."
     ].join("\n");
 }
+async function loadResearchState(stateFilePath) {
+    if (!existsSync(stateFilePath)) {
+        return createEmptyResearchState();
+    }
+    const parsed = JSON.parse(await readFile(stateFilePath, "utf8"));
+    return {
+        explicitState: parsed.explicitState ?? {},
+        workingState: parsed.workingState ?? {},
+        inferredHypotheses: parsed.inferredHypotheses ?? [],
+        openTensions: parsed.openTensions ?? [],
+        decisionLog: parsed.decisionLog ?? [],
+        invocationLog: parsed.invocationLog ?? [],
+        questionLog: parsed.questionLog ?? [],
+        artifactRecords: parsed.artifactRecords ?? [],
+        narrativeTraces: parsed.narrativeTraces ?? [],
+        ...(parsed.studyContract ? { studyContract: parsed.studyContract } : {})
+    };
+}
+function recentInvocationRecords(state, limit = 3) {
+    return (state.invocationLog ?? []).slice(-limit).reverse();
+}
+function recentPendingQuestions(state, limit = 3) {
+    return (state.questionLog ?? [])
+        .filter((record) => record.status === "pending")
+        .slice(-limit)
+        .reverse();
+}
+function formatQuestionOptionValues(record) {
+    const values = record.prompt.options.map((option) => option.value);
+    if (record.prompt.allowOther) {
+        values.push(record.prompt.otherLabel ? `other:${record.prompt.otherLabel}` : "other");
+    }
+    return values;
+}
+function summarizeWorkspaceInspection(context, state) {
+    const questions = state.questionLog ?? [];
+    const pendingQuestions = questions.filter((record) => record.status === "pending");
+    const answeredQuestions = questions.filter((record) => record.status === "answered");
+    return {
+        found: true,
+        rootPath: context.project.projectPath,
+        project: {
+            name: context.project.projectName,
+            path: context.project.projectPath,
+            field: context.project.globalSetupSummary.field,
+            careerStage: context.project.globalSetupSummary.careerStage,
+            checkpointIntensity: context.project.globalSetupSummary.checkpointIntensity
+        },
+        session: {
+            currentGoal: context.session.currentGoal,
+            ...(context.session.currentBlocker ? { currentBlocker: context.session.currentBlocker } : {}),
+            requestedPerspectives: context.session.requestedPerspectives,
+            disagreementPreference: context.session.disagreementPreference
+        },
+        files: {
+            project: context.projectFilePath,
+            session: context.sessionFilePath,
+            state: context.stateFilePath,
+            current: context.currentFilePath
+        },
+        counts: {
+            invocations: (state.invocationLog ?? []).length,
+            questions: questions.length,
+            pendingQuestions: pendingQuestions.length,
+            answeredQuestions: answeredQuestions.length,
+            decisions: (state.decisionLog ?? []).length
+        },
+        recentInvocations: recentInvocationRecords(state, 5).map((record) => ({
+            id: record.id,
+            kind: record.intent.kind,
+            mode: record.intent.mode,
+            surface: record.surface,
+            status: record.status,
+            roles: record.intent.roles,
+            linkedQuestions: record.panelResult?.linkedQuestionRecordIds.length ?? 0,
+            linkedDecisions: record.panelResult?.linkedDecisionRecordIds.length ?? 0
+        })),
+        pendingQuestions: pendingQuestions.slice(-5).reverse().map((record) => ({
+            id: record.id,
+            title: record.prompt.title,
+            question: record.prompt.question,
+            options: formatQuestionOptionValues(record),
+            required: record.prompt.required
+        })),
+        recentDecisions: (state.decisionLog ?? []).slice(-5).reverse().map((record) => ({
+            id: record.id,
+            checkpointKey: record.checkpointKey,
+            summary: record.summary,
+            ...(record.selectedOption ? { selectedOption: record.selectedOption } : {}),
+            timestamp: record.timestamp
+        }))
+    };
+}
 function buildProjectAgentsMd(project, session) {
     return [
         "# AGENTS.md",
         "",
-        "This directory is a Long Table research workspace.",
-        "",
-        "## Purpose",
-        `- Project name: ${project.projectName}`,
-        `- Current goal: ${session.currentGoal}`,
-        ...(session.currentBlocker ? [`- Current blocker: ${session.currentBlocker}`] : []),
-        `- Requested perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
-        `- Disagreement visibility: ${session.disagreementPreference}`,
+        "This directory is a LongTable research workspace.",
         "",
-        "## Research-facing behavior",
+        "## Runtime Contract",
         "- Treat researcher interaction as the primary task.",
-        "- If the user message starts with `lt `, `longtable `, `long table `, or `롱테이블 ` followed by a directive and `:`, treat it as an explicit Long Table invocation.",
+        "- Read `.longtable/current-session.json` before giving substantial guidance.",
+        "- Use `.longtable/project.json` as stable project context.",
+        "- Use `.longtable/state.json` as layered working memory.",
+        "- Prefer `currentGoal`, `currentBlocker`, `nextAction`, and `openQuestions` over generic assumptions.",
+        "- Treat `AGENTS.md` as runtime guidance, not as the researcher-facing resume artifact.",
+        "",
+        "## Invocation Rules",
+        "- 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.",
-        "- For explicit Long Table invocations, do not begin by scanning the workspace. Use the current session files first and answer as Long Table immediately.",
-        "- For general research requests in this workspace, prefer Long Table behavior before generic coding behavior.",
+        "- 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.",
-        "- If you foreground role perspectives, disclose them with `Long Table consulted: ...`.",
+        "- If you foreground role perspectives, disclose them with `LongTable consulted: ...`.",
         "- Keep one accountable synthesis, but do not hide meaningful disagreement.",
-        "- For factual, current, or external claims, provide source links or file references when possible.",
-        "- If a statement cannot be sourced, label it as an inference or estimate instead of presenting it as a fact.",
         ...(session.disagreementPreference === "always_visible"
-            ? ["- In this workspace, panel disagreement should be visible by default rather than hidden behind a single synthesis."]
+            ? ["- Panel disagreement should be visible by default rather than hidden behind a single synthesis."]
             : []),
+        "- For factual, current, or external claims, provide source links or file references when possible.",
+        "- If a statement cannot be sourced, label it as an inference or estimate instead of presenting it as a fact.",
         "- Do not expose internal tool logs, file-search traces, or process commentary in the researcher-facing answer.",
         "",
-        "## Session memory",
-        "- Read `.longtable/current-session.json` before giving substantial guidance.",
-        "- Use `.longtable/project.json` as the project-level context.",
-        "- Prefer the current goal and blocker over generic assumptions.",
-        "- Do not recursively search unrelated files unless the researcher explicitly asks for file analysis or code changes.",
-        "",
         "## Scope",
+        `- Project: ${project.projectName}`,
+        `- Current goal: ${session.currentGoal}`,
+        ...(session.currentBlocker ? [`- Current blocker: ${session.currentBlocker}`] : []),
+        `- Requested perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
+        `- Disagreement visibility: ${session.disagreementPreference}`,
         "- These instructions apply to this directory and its children."
     ].join("\n");
 }
@@ -180,12 +327,18 @@ function buildStateSeed(project, session, setup) {
         careerStage: setup.profileSeed.careerStage,
         experienceLevel: setup.profileSeed.experienceLevel,
         projectName: project.projectName,
-        currentGoal: session.currentGoal,
         disagreementPreference: session.disagreementPreference,
         requestedPerspectives: session.requestedPerspectives
     };
+    state.workingState = {
+        currentGoal: session.currentGoal,
+        ...(session.currentBlocker ? { currentBlocker: session.currentBlocker } : {}),
+        ...(session.nextAction ? { nextAction: session.nextAction } : {}),
+        openQuestions: session.openQuestions ?? [],
+        activeModes: session.activeModes ?? [],
+        ...(session.resumeHint ? { resumeHint: session.resumeHint } : {})
+    };
     if (session.currentBlocker) {
-        state.explicitState.currentBlocker = session.currentBlocker;
         state.openTensions.push(session.currentBlocker);
     }
     if (setup.profileSeed.humanAuthorshipSignal) {
@@ -213,24 +366,259 @@ function buildStateSeed(project, session, setup) {
     }
     return JSON.stringify(state, null, 2);
 }
+async function removeLegacyRootFiles(projectPath) {
+    await Promise.all(LEGACY_ROOT_FILES.map((file) => rm(join(projectPath, file), { force: true })));
+}
+export async function syncCurrentWorkspaceView(context) {
+    const state = await loadResearchState(context.stateFilePath);
+    const body = buildCurrentGuide(context.project, context.session, recentInvocationRecords(state), recentPendingQuestions(state));
+    await writeFile(context.currentFilePath, body, "utf8");
+    return context.currentFilePath;
+}
+export async function appendInvocationRecordToWorkspace(context, invocation, questions = []) {
+    const state = await loadResearchState(context.stateFilePath);
+    const withInvocation = appendInvocationToResearchState(state, invocation);
+    const updated = questions.length > 0
+        ? appendQuestionRecords(withInvocation, questions)
+        : withInvocation;
+    await writeFile(context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(context);
+    return updated;
+}
+function createId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function findQuestionForDecision(state, questionId) {
+    const pending = (state.questionLog ?? []).filter((record) => record.status === "pending");
+    if (questionId) {
+        return pending.find((record) => record.id === questionId) ?? null;
+    }
+    return pending.at(-1) ?? null;
+}
+function pendingRequiredQuestions(state) {
+    return (state.questionLog ?? []).filter((record) => record.status === "pending" && record.prompt.required);
+}
+export async function listBlockingWorkspaceQuestions(context) {
+    const state = await loadResearchState(context.stateFilePath);
+    return pendingRequiredQuestions(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"));
+}
+function questionTitleForCheckpoint(family) {
+    switch (family) {
+        case "meta_decision":
+            return "Meta-decision checkpoint";
+        case "submission":
+            return "Submission checkpoint";
+        case "commitment":
+            return "Research commitment checkpoint";
+        case "evidence":
+            return "Evidence checkpoint";
+        case "authorship":
+            return "Authorship checkpoint";
+        case "review":
+            return "Review checkpoint";
+        case "exploration":
+            return "Exploration checkpoint";
+        default:
+            return "Researcher Checkpoint";
+    }
+}
+function questionTextForCheckpoint(family, prompt) {
+    switch (family) {
+        case "meta_decision":
+            return "What should LongTable do before treating this platform decision as settled?";
+        case "submission":
+            return "What must happen before this work can move toward external release or submission?";
+        case "commitment":
+            return "What should LongTable treat as the human research commitment here?";
+        case "evidence":
+            return "How should LongTable handle the evidence risk before using this claim?";
+        case "authorship":
+            return "What should LongTable preserve before changing the researcher's voice or authorship trace?";
+        case "exploration":
+            return "What ambiguity should LongTable keep open before recommending a direction?";
+        default:
+            return `What should LongTable decide before proceeding with: ${prompt}`;
+    }
+}
+function optionsForCheckpointFamily(family) {
+    if (family === "evidence") {
+        return [
+            { value: "verify", label: "Verify evidence first", description: "Check whether the source supports the specific claim." },
+            { value: "limit", label: "Limit the claim", description: "Keep the point but narrow it to what the evidence can support." },
+            { value: "rewrite", label: "Rewrite without the claim", description: "Avoid relying on the uncertain citation or claim." },
+            { value: "defer", label: "Keep evidence risk open", description: "Do not settle the claim yet." }
+        ];
+    }
+    if (family === "meta_decision") {
+        return [
+            { value: "revise", label: "Revise the platform decision", description: "Change the term, policy, or README positioning before treating it as settled." },
+            { value: "evidence", label: "Gather implementation evidence first", description: "Inspect behavior or docs before committing the platform decision." },
+            { value: "proceed", label: "Proceed with current decision", description: "Accept the current platform framing and continue." },
+            { value: "defer", label: "Keep the decision open", description: "Do not make this platform language authoritative yet." }
+        ];
+    }
+    if (family === "submission") {
+        return [
+            { value: "review", label: "Review risk first", description: "Check claims, ethics, venue fit, or study contract before external release." },
+            { value: "evidence", label: "Verify evidence first", description: "Confirm source support before submission or public sharing." },
+            { value: "proceed", label: "Proceed toward submission", description: "Accept the remaining risk and continue." },
+            { value: "defer", label: "Do not submit yet", description: "Keep the submission decision open." }
+        ];
+    }
+    return [
+        { value: "revise", label: "Revise before proceeding", description: "Change the framing, design, or draft before treating this as settled." },
+        { value: "evidence", label: "Gather or verify evidence first", description: "Do not proceed until the relevant evidence is checked." },
+        { value: "proceed", label: "Proceed with current direction", description: "Accept the risk profile and continue." },
+        { value: "defer", label: "Keep this open", description: "Do not commit yet; keep the issue visible as an open tension." }
+    ];
+}
+export async function createWorkspaceQuestion(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const trigger = classifyCheckpointTrigger(options.prompt, {
+        unresolvedTensions: state.openTensions ?? [],
+        studyContract: state.studyContract
+    });
+    const createdAt = nowIso();
+    const question = {
+        id: createId("question_record"),
+        createdAt,
+        updatedAt: createdAt,
+        status: "pending",
+        prompt: {
+            id: createId("question_prompt"),
+            checkpointKey: trigger.signal.checkpointKey,
+            title: options.title ?? questionTitleForCheckpoint(trigger.family),
+            question: options.question ?? questionTextForCheckpoint(trigger.family, options.prompt),
+            type: "single_choice",
+            options: optionsForCheckpointFamily(trigger.family),
+            allowOther: true,
+            otherLabel: "Other decision",
+            required: options.required ?? trigger.requiresQuestionBeforeClosure,
+            source: "checkpoint",
+            rationale: [
+                ...trigger.rationale,
+                `Trigger family: ${trigger.family}.`,
+                `Trigger confidence: ${trigger.confidence}.`,
+                `Original prompt: ${options.prompt}`
+            ],
+            preferredSurfaces: options.provider === "claude"
+                ? ["native_structured", "numbered"]
+                : ["numbered", "native_structured"]
+        }
+    };
+    const updated = appendQuestionRecords(state, [question]);
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return { question, state: updated };
+}
+function updateInvocationWithDecision(invocation, questionId, decisionId) {
+    if (!invocation.panelResult?.linkedQuestionRecordIds.includes(questionId)) {
+        return invocation;
+    }
+    const linkedDecisionRecordIds = invocation.panelResult.linkedDecisionRecordIds.includes(decisionId)
+        ? invocation.panelResult.linkedDecisionRecordIds
+        : [...invocation.panelResult.linkedDecisionRecordIds, decisionId];
+    return {
+        ...invocation,
+        updatedAt: nowIso(),
+        panelResult: {
+            ...invocation.panelResult,
+            updatedAt: nowIso(),
+            linkedDecisionRecordIds
+        }
+    };
+}
+export async function answerWorkspaceQuestion(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const question = findQuestionForDecision(state, options.questionId);
+    if (!question) {
+        throw new Error(options.questionId ? `No pending LongTable question found for ${options.questionId}.` : "No pending LongTable question was found.");
+    }
+    const option = question.prompt.options.find((candidate) => candidate.value === options.answer);
+    const explicitOther = options.answer === "other" && question.prompt.allowOther;
+    const answer = {
+        promptId: question.prompt.id,
+        selectedValues: [option?.value ?? "other"],
+        selectedLabels: [option?.label ?? (explicitOther ? question.prompt.otherLabel ?? "Other" : options.answer)],
+        ...(option || explicitOther ? {} : { otherText: options.answer }),
+        ...(options.rationale ? { rationale: options.rationale } : {}),
+        ...(options.provider ? { provider: options.provider } : {}),
+        surface: options.provider === "claude" ? "native_structured" : "numbered"
+    };
+    const timestamp = nowIso();
+    const decision = {
+        id: createId("decision"),
+        timestamp,
+        checkpointKey: question.prompt.checkpointKey ?? "manual",
+        level: question.prompt.required ? "adaptive_required" : "recommended",
+        mode: "commit",
+        summary: `Answered ${question.prompt.title}: ${answer.selectedLabels.join(", ")}`,
+        selectedOption: answer.selectedValues[0],
+        ...(options.rationale ? { rationale: options.rationale } : {})
+    };
+    const answeredQuestion = {
+        ...question,
+        updatedAt: timestamp,
+        status: "answered",
+        answer,
+        decisionRecordId: decision.id
+    };
+    const withQuestion = {
+        ...state,
+        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);
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return {
+        question: answeredQuestion,
+        decision,
+        state: updated
+    };
+}
 export async function createOrUpdateProjectWorkspace(options) {
     const projectPath = resolve(options.projectPath);
     const metaDir = resolveMetaDir(projectPath);
     const sessionsDir = join(metaDir, "sessions");
     const projectFilePath = join(metaDir, "project.json");
     const sessionFilePath = join(metaDir, "current-session.json");
+    const stateFilePath = resolveStateFilePath(projectPath);
+    const currentFilePath = resolveCurrentFilePath(projectPath);
     const sessionId = slugify(`${options.projectName}-${Date.now()}`);
+    const locale = resolveUserLocale();
+    const timestamp = nowIso();
     await mkdir(projectPath, { recursive: true });
     await mkdir(metaDir, { recursive: true });
     await mkdir(sessionsDir, { recursive: true });
     const project = existsSync(projectFilePath)
-        ? JSON.parse(await readFile(projectFilePath, "utf8"))
+        ? {
+            ...JSON.parse(await readFile(projectFilePath, "utf8")),
+            contractVersion: "workspace-v2",
+            locale
+        }
         : {
             schemaVersion: 1,
-            product: "Long Table",
+            product: "LongTable",
             projectName: options.projectName,
             projectPath,
-            createdAt: nowIso(),
+            createdAt: timestamp,
+            contractVersion: "workspace-v2",
+            locale,
             globalSetupSummary: {
                 field: options.setup.profileSeed.field,
                 careerStage: options.setup.profileSeed.careerStage,
@@ -250,30 +638,67 @@ export async function createOrUpdateProjectWorkspace(options) {
     const session = {
         schemaVersion: 1,
         id: sessionId,
-        createdAt: nowIso(),
+        createdAt: timestamp,
+        lastUpdatedAt: timestamp,
         projectName: project.projectName,
         projectPath,
         currentGoal: options.currentGoal,
         ...(options.currentBlocker ? { currentBlocker: options.currentBlocker } : {}),
+        nextAction: buildNextAction({
+            schemaVersion: 1,
+            id: sessionId,
+            createdAt: timestamp,
+            projectName: project.projectName,
+            projectPath,
+            currentGoal: options.currentGoal,
+            ...(options.currentBlocker ? { currentBlocker: options.currentBlocker } : {}),
+            requestedPerspectives: options.requestedPerspectives,
+            disagreementPreference: options.disagreementPreference
+        }),
+        openQuestions: buildOpenQuestions({
+            schemaVersion: 1,
+            id: sessionId,
+            createdAt: timestamp,
+            projectName: project.projectName,
+            projectPath,
+            currentGoal: options.currentGoal,
+            ...(options.currentBlocker ? { currentBlocker: options.currentBlocker } : {}),
+            requestedPerspectives: options.requestedPerspectives,
+            disagreementPreference: options.disagreementPreference
+        }),
         requestedPerspectives: options.requestedPerspectives,
-        disagreementPreference: options.disagreementPreference
+        disagreementPreference: options.disagreementPreference,
+        activeModes: ["explore"],
+        resumeHint: buildResumeHint({
+            schemaVersion: 1,
+            id: sessionId,
+            createdAt: timestamp,
+            projectName: project.projectName,
+            projectPath,
+            currentGoal: options.currentGoal,
+            ...(options.currentBlocker ? { currentBlocker: options.currentBlocker } : {}),
+            requestedPerspectives: options.requestedPerspectives,
+            disagreementPreference: options.disagreementPreference
+        }),
+        locale
     };
-    await writeFile(projectFilePath, JSON.stringify(project, null, 2), "utf8");
-    await writeFile(sessionFilePath, JSON.stringify(session, null, 2), "utf8");
-    await writeFile(join(sessionsDir, `${sessionId}.json`), JSON.stringify(session, null, 2), "utf8");
-    await writeFile(join(metaDir, "state.json"), buildStateSeed(project, session, options.setup), "utf8");
-    await writeFile(join(projectPath, "LONGTABLE.md"), buildWorkspaceGuide(project, session), "utf8");
-    await writeFile(join(projectPath, "START-HERE.md"), buildStartHereGuide(project, session), "utf8");
-    await writeFile(join(projectPath, "NEXT-STEPS.md"), buildNextStepsGuide(project, session), "utf8");
-    await writeFile(join(projectPath, "SESSION-SNAPSHOT.md"), buildSessionSnapshot(project, session), "utf8");
-    await writeFile(join(projectPath, "AGENTS.md"), buildProjectAgentsMd(project, session), "utf8");
-    return {
+    const context = {
         project,
         session,
         projectFilePath,
         sessionFilePath,
+        stateFilePath,
+        currentFilePath,
         metaDir
     };
+    await writeFile(projectFilePath, JSON.stringify(project, null, 2), "utf8");
+    await writeFile(sessionFilePath, JSON.stringify(session, null, 2), "utf8");
+    await writeFile(join(sessionsDir, `${sessionId}.json`), JSON.stringify(session, null, 2), "utf8");
+    await writeFile(stateFilePath, buildStateSeed(project, session, options.setup), "utf8");
+    await writeFile(join(projectPath, "AGENTS.md"), buildProjectAgentsMd(project, session), "utf8");
+    await syncCurrentWorkspaceView(context);
+    await removeLegacyRootFiles(projectPath);
+    return context;
 }
 export async function loadProjectContextFromDirectory(startPath) {
     let current = resolve(startPath);
@@ -282,11 +707,22 @@ export async function loadProjectContextFromDirectory(startPath) {
         const projectFilePath = join(metaDir, "project.json");
         const sessionFilePath = join(metaDir, "current-session.json");
         if (existsSync(projectFilePath) && existsSync(sessionFilePath)) {
+            const project = JSON.parse(await readFile(projectFilePath, "utf8"));
+            const session = JSON.parse(await readFile(sessionFilePath, "utf8"));
             return {
-                project: JSON.parse(await readFile(projectFilePath, "utf8")),
-                session: JSON.parse(await readFile(sessionFilePath, "utf8")),
+                project,
+                session: {
+                    ...session,
+                    locale: session.locale ?? project.locale ?? resolveUserLocale(),
+                    openQuestions: session.openQuestions ?? buildOpenQuestions(session),
+                    nextAction: session.nextAction ?? buildNextAction(session),
+                    resumeHint: session.resumeHint ?? buildResumeHint(session),
+                    activeModes: session.activeModes ?? ["explore"]
+                },
                 projectFilePath,
                 sessionFilePath,
+                stateFilePath: resolveStateFilePath(project.projectPath),
+                currentFilePath: resolveCurrentFilePath(project.projectPath),
                 metaDir
             };
         }
@@ -297,10 +733,18 @@ export async function loadProjectContextFromDirectory(startPath) {
         current = parent;
     }
 }
+export async function inspectProjectWorkspace(startPath) {
+    const context = await loadProjectContextFromDirectory(startPath);
+    if (!context) {
+        return { found: false };
+    }
+    const state = await loadResearchState(context.stateFilePath);
+    return summarizeWorkspaceInspection(context, state);
+}
 export function renderProjectWorkspaceSummary(context) {
     return [
         "┌──────────────────────────────────────────────┐",
-        "│ Long Table Project Workspace               │",
+        "│ LongTable Project Workspace               │",
         "└──────────────────────────────────────────────┘",
         `Project: ${context.project.projectName}`,
         `Path: ${context.project.projectPath}`,
@@ -312,9 +756,8 @@ export function renderProjectWorkspaceSummary(context) {
         "Created files:",
         `- ${context.projectFilePath}`,
         `- ${context.sessionFilePath}`,
-        `- ${join(context.project.projectPath, "START-HERE.md")}`,
-        `- ${join(context.project.projectPath, "NEXT-STEPS.md")}`,
-        `- ${join(context.project.projectPath, "SESSION-SNAPSHOT.md")}`,
+        `- ${context.stateFilePath}`,
+        `- ${context.currentFilePath}`,
         `- ${join(context.project.projectPath, "AGENTS.md")}`
     ].join("\n");
 }