@longtable/mcp 0.1.45 → 0.1.48

package/README.md

@@ -15,7 +15,7 @@ longtable-state
 Run:
 
 ```bash
-npx -y @longtable/mcp@0.1.41
+npx -y @longtable/mcp@0.1.47
 ```
 
 Self-test:

package/dist/research-specification.d.ts

@@ -62,4 +62,5 @@ export interface ResearchSpecificationQuestionSpec {
 export declare function renderResearchSpecificationPreview(specification: ResearchSpecification): string;
 export declare function buildResearchSpecificationQuestion(specification: ResearchSpecification): ResearchSpecificationQuestionSpec;
 export declare function researchSpecificationAnswerConfirms(answer: string): boolean;
+export declare function researchSpecificationAnswerNeedsFollowUp(answer: string): boolean;
 export declare function researchSpecificationAnswerStatus(answer: string): "confirmed" | "active" | "deferred";

package/dist/research-specification.js

@@ -116,6 +116,9 @@ export function buildResearchSpecificationQuestion(specification) {
 export function researchSpecificationAnswerConfirms(answer) {
     return answer === "confirm_specification";
 }
+export function researchSpecificationAnswerNeedsFollowUp(answer) {
+    return answer === "ask_one_more" || answer === "revise_section";
+}
 export function researchSpecificationAnswerStatus(answer) {
     if (researchSpecificationAnswerConfirms(answer)) {
         return "confirmed";

package/dist/server.js

@@ -11,9 +11,9 @@ import { classifyCheckpointTrigger } from "@longtable/checkpoints";
 import { renderQuestionRecordInput } from "@longtable/provider-claude";
 import { renderQuestionRecordPrompt } from "@longtable/provider-codex";
 import { loadSetupOutput } from "@longtable/setup";
-import { answerWorkspaceQuestion, clearWorkspaceQuestion, createOrUpdateProjectWorkspace, createWorkspaceQuestion, inspectProjectWorkspace, loadProjectContextFromDirectory, loadWorkspaceState, syncCurrentWorkspaceView } from "@longtable/cli";
+import { answerWorkspaceQuestion, applyResearchSpecificationAuditUpdate, applyResearchSpecificationPatch, clearWorkspaceQuestion, createOrUpdateProjectWorkspace, createWorkspaceQuestion, diffResearchSpecifications, findUnincorporatedResearchEvidence, inspectProjectWorkspace, loadProjectContextFromDirectory, loadWorkspaceState, proposeResearchSpecificationPatch, readResearchSpecificationHistory, syncCurrentWorkspaceView } from "@longtable/cli";
 import { buildFirstResearchShapeQuestion, firstResearchShapeAnswerConfirms, firstResearchShapeAnswerStatus } from "./first-research-shape.js";
-import { buildResearchSpecificationQuestion, renderResearchSpecificationPreview, researchSpecificationAnswerConfirms, researchSpecificationAnswerStatus } from "./research-specification.js";
+import { buildResearchSpecificationQuestion, renderResearchSpecificationPreview, researchSpecificationAnswerConfirms, researchSpecificationAnswerNeedsFollowUp, researchSpecificationAnswerStatus } from "./research-specification.js";
 const SERVER_NAME = "longtable-state";
 const require = createRequire(import.meta.url);
 const SERVER_VERSION = String(require("../package.json").version ?? "0.0.0");
@@ -27,6 +27,11 @@ const TOOL_NAMES = [
     "summarize_interview",
     "summarize_research_specification",
     "read_research_specification",
+    "propose_research_spec_patch",
+    "apply_research_spec_patch",
+    "diff_research_specification",
+    "read_research_spec_history",
+    "find_unincorporated_evidence",
     "cancel_interview",
     "confirm_first_research_shape",
     "confirm_research_specification",
@@ -47,6 +52,22 @@ const questionOptionSchema = z.object({
     description: z.string().optional(),
     recommended: z.boolean().optional()
 });
+const commitmentFamilySchema = z.enum([
+    "scope",
+    "construct",
+    "coding",
+    "method",
+    "evidence",
+    "epistemic_authority",
+    "product_policy"
+]);
+const epistemicBasisSchema = z.enum([
+    "researcher_knowledge",
+    "project_state",
+    "external_evidence",
+    "ai_inference",
+    "mixed"
+]);
 const firstResearchShapeSchema = z.object({
     handle: z.string().min(1),
     currentGoal: z.string().min(1),
@@ -67,6 +88,9 @@ const researchSpecificationSchema = z.object({
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
     sourceHookId: z.string().optional(),
+    latestRevisionId: z.string().optional(),
+    sourceEvidenceIds: z.array(z.string()).optional(),
+    sectionEvidence: z.record(z.string(), z.array(z.string())).optional(),
     researchDirection: z.object({
         question: z.string().optional(),
         purpose: z.string().min(1),
@@ -113,6 +137,15 @@ const researchSpecificationSchema = z.object({
     confidence: z.enum(["low", "medium", "high"]).default("medium"),
     confirmedAt: z.string().optional()
 });
+const researchSpecificationPatchSourceSchema = z.enum([
+    "interview",
+    "panel",
+    "critic",
+    "reviewer",
+    "decision",
+    "manual",
+    "system"
+]);
 function textResult(structuredContent) {
     return {
         content: [
@@ -228,6 +261,57 @@ function resolveFirstResearchShapeObligation(state, options) {
         })
     };
 }
+function researchSpecificationFollowUpReason(answer) {
+    if (answer === "ask_one_more") {
+        return "The researcher chose one more question before saving; after that answer, LongTable must update or read the Research Specification and return to confirmation.";
+    }
+    if (answer === "revise_section") {
+        return "The researcher chose section revision; after the section is revised, LongTable must return to the Research Specification Preview for confirmation.";
+    }
+    return "Research Specification confirmation remains open.";
+}
+function ensureResearchSpecificationConfirmationObligation(state, specification, options) {
+    const existing = (state.questionObligations ?? []).find((obligation) => obligation.kind === "research_specification_confirmation" &&
+        obligation.status === "pending" &&
+        ((specification.sourceHookId && obligation.sourceHookId === specification.sourceHookId) ||
+            (!specification.sourceHookId && obligation.prompt.includes(specification.title))));
+    const timestamp = new Date().toISOString();
+    const next = {
+        ...(existing ?? {
+            id: createId("question_obligation"),
+            kind: "research_specification_confirmation",
+            status: "pending",
+            createdAt: timestamp
+        }),
+        updatedAt: timestamp,
+        prompt: `Return to Research Specification Preview before ending the interview: ${specification.title}`,
+        reason: researchSpecificationFollowUpReason(options.answer),
+        ...(specification.sourceHookId ? { sourceHookId: specification.sourceHookId } : {}),
+        ...(options.questionId ? { questionId: options.questionId } : existing?.questionId ? { questionId: existing.questionId } : {}),
+        ...(options.decisionId ? { decisionId: options.decisionId } : existing?.decisionId ? { decisionId: existing.decisionId } : {})
+    };
+    return upsertQuestionObligation(state, next);
+}
+function resolveResearchSpecificationConfirmationObligation(state, specification, options = {}) {
+    return {
+        ...state,
+        questionObligations: (state.questionObligations ?? []).map((obligation) => {
+            const matches = obligation.kind === "research_specification_confirmation" && ((specification.sourceHookId && obligation.sourceHookId === specification.sourceHookId) ||
+                (options.questionId && obligation.questionId === options.questionId) ||
+                (!specification.sourceHookId && obligation.prompt.includes(specification.title)));
+            if (!matches || obligation.status !== "pending") {
+                return obligation;
+            }
+            return {
+                ...obligation,
+                status: options.status ?? "satisfied",
+                updatedAt: new Date().toISOString(),
+                ...(options.questionId ? { questionId: options.questionId } : obligation.questionId ? { questionId: obligation.questionId } : {}),
+                ...(options.decisionId ? { decisionId: options.decisionId } : obligation.decisionId ? { decisionId: obligation.decisionId } : {})
+            };
+        })
+    };
+}
 function interviewDepth(turns) {
     if (turns.some((turn) => turn.readyToSummarize === true && turn.quality !== "thin")) {
         return "ready_to_summarize";
@@ -772,11 +856,6 @@ async function markResearchSpecificationConfirmation(context, specification, ans
             status: researchSpecificationAnswerStatus(answer) === "deferred" ? "deferred" : "draft",
             updatedAt: timestamp
         };
-    state.researchSpecification = confirmedSpecification;
-    state.workingState = {
-        ...state.workingState,
-        researchSpecification: confirmedSpecification
-    };
     state.hooks = (state.hooks ?? []).map((hook) => {
         if (hook.id !== specification.sourceHookId || !isInterviewHookRun(hook)) {
             return hook;
@@ -794,6 +873,37 @@ async function markResearchSpecificationConfirmation(context, specification, ans
                 : hook.linkedDecisionRecordIds
         };
     });
+    const sourceEvidenceIds = (state.evidenceRecords ?? [])
+        .filter((record) => record.sourceHookId && record.sourceHookId === specification.sourceHookId)
+        .map((record) => record.id);
+    const audited = applyResearchSpecificationAuditUpdate(state, {
+        specification: confirmedSpecification,
+        timestamp,
+        source: "decision",
+        title: `Research Specification confirmation: ${confirmedSpecification.title}`,
+        rationale: `Research Specification confirmation answer: ${answer}`,
+        sourceEvidenceIds,
+        questionRecordId: questionId,
+        decisionRecordId: decisionId,
+        createDecisionRecord: false
+    });
+    const nextState = researchSpecificationAnswerConfirms(answer)
+        ? resolveResearchSpecificationConfirmationObligation(audited.state, confirmedSpecification, {
+            questionId,
+            decisionId,
+            status: "satisfied"
+        })
+        : researchSpecificationAnswerNeedsFollowUp(answer)
+            ? ensureResearchSpecificationConfirmationObligation(audited.state, confirmedSpecification, {
+                answer,
+                questionId,
+                decisionId
+            })
+            : resolveResearchSpecificationConfirmationObligation(audited.state, confirmedSpecification, {
+                questionId,
+                decisionId,
+                status: "cleared"
+            });
     const session = {
         ...context.session,
         researchSpecification: confirmedSpecification,
@@ -801,9 +911,9 @@ async function markResearchSpecificationConfirmation(context, specification, ans
     };
     context.session = session;
     await writeFile(context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
-    await writeFile(context.stateFilePath, JSON.stringify(state, null, 2), "utf8");
+    await writeFile(context.stateFilePath, JSON.stringify(nextState, null, 2), "utf8");
     await syncCurrentWorkspaceView(context);
-    return { state, session, specification: confirmedSpecification };
+    return { state: nextState, session, specification: confirmedSpecification };
 }
 async function markAlreadyConfirmedResearchSpecification(context, specification) {
     const state = asInterviewState(await loadWorkspaceState(context));
@@ -832,6 +942,9 @@ async function markAlreadyConfirmedResearchSpecification(context, specification)
             researchSpecification: confirmedSpecification
         };
     });
+    const nextState = resolveResearchSpecificationConfirmationObligation(state, confirmedSpecification, {
+        status: "satisfied"
+    });
     const session = {
         ...context.session,
         researchSpecification: confirmedSpecification,
@@ -839,9 +952,9 @@ async function markAlreadyConfirmedResearchSpecification(context, specification)
     };
     context.session = session;
     await writeFile(context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
-    await writeFile(context.stateFilePath, JSON.stringify(state, null, 2), "utf8");
+    await writeFile(context.stateFilePath, JSON.stringify(nextState, null, 2), "utf8");
     await syncCurrentWorkspaceView(context);
-    return { state, session, specification: confirmedSpecification };
+    return { state: nextState, session, specification: confirmedSpecification };
 }
 function statusForElicitationError(error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -1132,6 +1245,126 @@ export function createLongTableMcpServer() {
             return errorResult(error instanceof Error ? error.message : String(error));
         }
     });
+    server.registerTool("propose_research_spec_patch", {
+        title: "Propose Research Specification Patch",
+        description: "Store a reviewable Research Specification patch without applying it.",
+        inputSchema: cwdSchema.extend({
+            specification: researchSpecificationSchema,
+            source: researchSpecificationPatchSourceSchema.default("manual"),
+            rationale: z.string().optional(),
+            sourceEvidenceIds: z.array(z.string()).optional()
+        })
+    }, async ({ cwd: inputCwd, specification, source, rationale, sourceEvidenceIds }) => {
+        try {
+            const context = await requireContext(inputCwd);
+            const result = await proposeResearchSpecificationPatch({
+                context,
+                specification: specification,
+                source,
+                rationale,
+                sourceEvidenceIds
+            });
+            return textResult({
+                patch: result.patch,
+                changes: result.changes,
+                nextAction: `apply_research_spec_patch patchId=${result.patch.id}`
+            });
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+    });
+    server.registerTool("apply_research_spec_patch", {
+        title: "Apply Research Specification Patch",
+        description: "Automatically apply a proposed or inline Research Specification update and record a revision.",
+        inputSchema: cwdSchema.extend({
+            patchId: z.string().optional(),
+            specification: researchSpecificationSchema.optional(),
+            source: researchSpecificationPatchSourceSchema.default("manual"),
+            rationale: z.string().optional(),
+            sourceEvidenceIds: z.array(z.string()).optional(),
+            questionRecordId: z.string().optional(),
+            decisionRecordId: z.string().optional()
+        })
+    }, async ({ cwd: inputCwd, patchId, specification, source, rationale, sourceEvidenceIds, questionRecordId, decisionRecordId }) => {
+        try {
+            const context = await requireContext(inputCwd);
+            const result = await applyResearchSpecificationPatch({
+                context,
+                patchId,
+                specification: specification,
+                source,
+                rationale,
+                sourceEvidenceIds,
+                questionRecordId,
+                decisionRecordId
+            });
+            return textResult({
+                patch: result.patch,
+                revision: result.revision,
+                specification: result.specification,
+                decision: result.decision,
+                session: {
+                    currentGoal: result.session.currentGoal,
+                    researchSpecification: result.session.researchSpecification
+                }
+            });
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+    });
+    server.registerTool("diff_research_specification", {
+        title: "Diff Research Specification",
+        description: "Compare an inline Research Specification against the current workspace specification without writing state.",
+        inputSchema: cwdSchema.extend({
+            specification: researchSpecificationSchema
+        }),
+        annotations: { readOnlyHint: true }
+    }, async ({ cwd: inputCwd, specification }) => {
+        try {
+            const context = await requireContext(inputCwd);
+            const state = asInterviewState(await loadWorkspaceState(context));
+            const current = state.researchSpecification ?? context.session.researchSpecification;
+            return textResult({
+                current,
+                changes: diffResearchSpecifications(current, specification)
+            });
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+    });
+    server.registerTool("read_research_spec_history", {
+        title: "Read Research Specification History",
+        description: "Read specification revisions, patches, and evidence records for audit or resume.",
+        inputSchema: cwdSchema,
+        annotations: { readOnlyHint: true }
+    }, async ({ cwd: inputCwd }) => {
+        try {
+            const context = await requireContext(inputCwd);
+            return textResult(await readResearchSpecificationHistory(context));
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+    });
+    server.registerTool("find_unincorporated_evidence", {
+        title: "Find Unincorporated Research Evidence",
+        description: "List interview, panel, critic, reviewer, or invocation evidence not yet incorporated into a Research Specification revision.",
+        inputSchema: cwdSchema,
+        annotations: { readOnlyHint: true }
+    }, async ({ cwd: inputCwd }) => {
+        try {
+            const context = await requireContext(inputCwd);
+            return textResult({
+                evidenceRecords: await findUnincorporatedResearchEvidence(context)
+            });
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error));
+        }
+    });
     server.registerTool("cancel_interview", {
         title: "Cancel LongTable Interview",
         description: "Explicitly cancel the active $longtable-interview hook without confirming a First Research Shape.",
@@ -1428,9 +1661,11 @@ export function createLongTableMcpServer() {
             options: z.array(questionOptionSchema).optional(),
             displayReason: z.string().optional(),
             provider: z.enum(["codex", "claude"]).optional(),
-            required: z.boolean().optional()
+            required: z.boolean().optional(),
+            commitmentFamily: commitmentFamilySchema.optional(),
+            epistemicBasis: epistemicBasisSchema.optional()
         })
-    }, async ({ cwd: inputCwd, prompt, title, question, checkpointKey, options, displayReason, provider, required }) => {
+    }, async ({ cwd: inputCwd, prompt, title, question, checkpointKey, options, displayReason, provider, required, commitmentFamily, epistemicBasis }) => {
         try {
             const context = await requireContext(inputCwd);
             const result = await createWorkspaceQuestion({
@@ -1442,7 +1677,9 @@ export function createLongTableMcpServer() {
                 questionOptions: options,
                 displayReason,
                 provider,
-                required
+                required,
+                commitmentFamily: commitmentFamily,
+                epistemicBasis: epistemicBasis
             });
             return textResult({
                 question: result.question,
@@ -1465,9 +1702,11 @@ export function createLongTableMcpServer() {
             displayReason: z.string().optional(),
             provider: z.enum(["codex", "claude"]).default("codex"),
             required: z.boolean().optional(),
+            commitmentFamily: commitmentFamilySchema.optional(),
+            epistemicBasis: epistemicBasisSchema.optional(),
             fallbackOnly: z.boolean().default(false).describe("Create and render the checkpoint without calling MCP elicitation.")
         })
-    }, async ({ cwd: inputCwd, prompt, title, question, checkpointKey, options, displayReason, provider, required, fallbackOnly }) => {
+    }, async ({ cwd: inputCwd, prompt, title, question, checkpointKey, options, displayReason, provider, required, commitmentFamily, epistemicBasis, fallbackOnly }) => {
         try {
             const context = await requireContext(inputCwd);
             const created = await createWorkspaceQuestion({
@@ -1479,7 +1718,9 @@ export function createLongTableMcpServer() {
                 questionOptions: options,
                 displayReason,
                 provider,
-                required
+                required,
+                commitmentFamily: commitmentFamily,
+                epistemicBasis: epistemicBasis
             });
             const fallback = renderQuestionFallback(created.question, provider);
             if (fallbackOnly) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtable/mcp",
-  "version": "0.1.45",
+  "version": "0.1.48",
   "private": false,
   "description": "LongTable MCP transport for workspace state and Researcher Checkpoints",
   "type": "module",
@@ -26,12 +26,12 @@
     "self-test": "node ./dist/server.js --self-test"
   },
   "dependencies": {
-    "@longtable/checkpoints": "0.1.45",
-    "@longtable/cli": "0.1.45",
-    "@longtable/core": "0.1.45",
-    "@longtable/provider-claude": "0.1.45",
-    "@longtable/provider-codex": "0.1.45",
-    "@longtable/setup": "0.1.45",
+    "@longtable/checkpoints": "0.1.48",
+    "@longtable/cli": "0.1.48",
+    "@longtable/core": "0.1.48",
+    "@longtable/provider-claude": "0.1.48",
+    "@longtable/provider-codex": "0.1.48",
+    "@longtable/setup": "0.1.48",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.0"
   },