@longtable/cli 0.1.47 → 0.1.48

package/dist/cli.js

@@ -18,7 +18,7 @@ import { buildPersonaGuidance, parseInvocationDirective } from "./persona-router
 import { PERSONA_DEFINITIONS, listRoleDefinitions } from "./personas.js";
 import { buildPanelFallback, renderPanelSummary } from "./panel.js";
 import { LONGTABLE_MANAGED_HOOK_EVENTS, codexHooksEnabled, enableCodexHooksFeature, getMissingManagedCodexHookEvents, mergeManagedCodexHooksConfig, removeManagedCodexHooks } from "./codex-hooks.js";
-import { appendInvocationRecordToWorkspace, assertWorkspaceNotBlocked, answerWorkspaceQuestion, buildQuestionOpportunitySpecs, clearWorkspaceQuestion, createWorkspaceFollowUpQuestions, createWorkspaceQuestion, createOrUpdateProjectWorkspace, inspectProjectWorkspace, loadWorkspaceState, loadProjectContextFromDirectory, pruneWorkspaceQuestions, repairWorkspaceStateConsistency, renderProjectWorkspaceSummary, syncCurrentWorkspaceView } from "./project-session.js";
+import { appendInvocationRecordToWorkspace, applyResearchSpecificationPatch, assertWorkspaceNotBlocked, answerWorkspaceQuestion, buildQuestionOpportunitySpecs, clearWorkspaceQuestion, createWorkspaceFollowUpQuestions, createWorkspaceQuestion, createOrUpdateProjectWorkspace, diffResearchSpecifications, inspectProjectWorkspace, loadWorkspaceState, loadProjectContextFromDirectory, findUnincorporatedResearchEvidence, proposeResearchSpecificationPatch, pruneWorkspaceQuestions, readResearchSpecificationHistory, repairWorkspaceStateConsistency, renderProjectWorkspaceSummary, syncCurrentWorkspaceView } from "./project-session.js";
 import { buildTeamDebate, buildTeamReview, renderTeamDebateSummary } from "./debate.js";
 import { createPromptRenderer } from "./prompt-renderer.js";
 const VALID_MODES = new Set([
@@ -62,6 +62,11 @@ const LONGTABLE_MCP_MANAGED_TOOLS = [
     "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",
@@ -76,6 +81,11 @@ const LONGTABLE_MCP_MANAGED_TOOLS = [
 const LONGTABLE_MCP_RESEARCH_SPECIFICATION_TOOLS = [
     "summarize_research_specification",
     "read_research_specification",
+    "propose_research_spec_patch",
+    "apply_research_spec_patch",
+    "diff_research_specification",
+    "read_research_spec_history",
+    "find_unincorporated_evidence",
     "confirm_research_specification"
 ];
 function style(text, prefix) {
@@ -132,6 +142,7 @@ function usage() {
         "  longtable doctor [--cwd <path>] [--fix] [--json] [--codex-dir <path>] [--codex-config <path>] [--hooks-path <path>] [--claude-dir <path>] [--codex-prompts-dir <path>] [--codex-runtime-path <file>] [--claude-runtime-path <file>]",
         "  longtable status [--cwd <path>] [--fix] [--json] [--codex-dir <path>] [--codex-config <path>] [--hooks-path <path>] [--claude-dir <path>] [--codex-prompts-dir <path>] [--codex-runtime-path <file>] [--claude-runtime-path <file>]",
         "  longtable audit [questions|roles] [--json]",
+        "  longtable spec [read|history|diff|unincorporated|apply|propose] [--cwd <path>] [--json] [--spec-file <path>] [--patch-id <id>]",
         "  longtable roles [--json]",
         "  longtable show [--json] [--path <file>]",
         "  longtable install [--json] [--path <file>] [--runtime-path <file>]",
@@ -182,7 +193,7 @@ function parseArgs(argv) {
     const values = {};
     let subcommand = maybeSubcommand;
     const modeCommand = command && VALID_MODES.has(command);
-    const directCommand = command && ["init", "setup", "start", "resume", "doctor", "status", "audit", "roles", "show", "install", "mcp", "codex", "claude", "ask", "clarify", "question", "clear-question", "prune-questions", "panel", "decide", "sentinel", "team", "access", "search"].includes(command);
+    const directCommand = command && ["init", "setup", "start", "resume", "doctor", "status", "audit", "roles", "show", "install", "mcp", "codex", "claude", "ask", "clarify", "question", "clear-question", "prune-questions", "panel", "decide", "sentinel", "team", "access", "search", "spec"].includes(command);
     let startIndex = 1;
     if (modeCommand) {
         subcommand = undefined;
@@ -191,7 +202,7 @@ function parseArgs(argv) {
     else if (command === "codex" || command === "claude" || command === "mcp") {
         startIndex = 2;
     }
-    else if ((command === "access" || command === "search") && maybeSubcommand && !maybeSubcommand.startsWith("--")) {
+    else if ((command === "access" || command === "search" || command === "spec") && maybeSubcommand && !maybeSubcommand.startsWith("--")) {
         subcommand = maybeSubcommand;
         startIndex = 2;
     }
@@ -2851,6 +2862,108 @@ async function runSearch(subcommand, args) {
     }
     console.log(renderEvidenceRunSummary(run, recordedPath));
 }
+async function requireWorkspaceContext(args) {
+    const workingDirectory = typeof args.cwd === "string" ? args.cwd : cwd();
+    const context = await loadProjectContextFromDirectory(workingDirectory);
+    if (!context) {
+        throw new Error("No LongTable workspace was found from the supplied cwd.");
+    }
+    return context;
+}
+async function readResearchSpecificationFile(path) {
+    if (!path) {
+        throw new Error("A Research Specification JSON file is required. Use --spec-file <path>.");
+    }
+    return JSON.parse(await readFile(resolve(path), "utf8"));
+}
+async function runSpec(subcommand, args) {
+    const context = await requireWorkspaceContext(args);
+    const command = subcommand ?? "read";
+    if (command === "read" || command === "history") {
+        const history = await readResearchSpecificationHistory(context);
+        if (args.json === true) {
+            console.log(JSON.stringify(history, null, 2));
+            return;
+        }
+        console.log("LongTable Research Specification");
+        console.log(`- title: ${history.specification?.title ?? "missing"}`);
+        console.log(`- status: ${history.specification?.confirmedAt ? "confirmed" : history.specification?.status ?? "missing"}`);
+        console.log(`- revisions: ${history.revisions.length}`);
+        console.log(`- patches: ${history.patches.length}`);
+        console.log(`- evidence records: ${history.evidenceRecords.length}`);
+        for (const revision of history.revisions.slice(-5).reverse()) {
+            console.log(`- v${revision.index}: ${revision.title} (${revision.changeSummary.slice(0, 2).join("; ")})`);
+        }
+        return;
+    }
+    if (command === "unincorporated") {
+        const evidenceRecords = await findUnincorporatedResearchEvidence(context);
+        if (args.json === true) {
+            console.log(JSON.stringify({ evidenceRecords }, null, 2));
+            return;
+        }
+        console.log("Unincorporated Research Evidence");
+        for (const record of evidenceRecords.slice(-10).reverse()) {
+            console.log(`- ${record.id} [${record.sourceKind}]: ${record.summary}`);
+        }
+        return;
+    }
+    if (command === "diff") {
+        const specification = await readResearchSpecificationFile(typeof args["spec-file"] === "string" ? args["spec-file"] : undefined);
+        const state = await loadWorkspaceState(context);
+        const changes = diffResearchSpecifications(state.researchSpecification, specification);
+        if (args.json === true) {
+            console.log(JSON.stringify({ changes }, null, 2));
+            return;
+        }
+        console.log("Research Specification Diff");
+        for (const change of changes) {
+            console.log(`- ${change.summary}`);
+        }
+        return;
+    }
+    if (command === "propose") {
+        const specification = await readResearchSpecificationFile(typeof args["spec-file"] === "string" ? args["spec-file"] : undefined);
+        const result = await proposeResearchSpecificationPatch({
+            context,
+            specification,
+            source: "manual",
+            rationale: typeof args.rationale === "string" ? args.rationale : undefined
+        });
+        if (args.json === true) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log("Research Specification patch proposed");
+        console.log(`- patch: ${result.patch.id}`);
+        console.log(`- changes: ${result.changes.length}`);
+        console.log(`- apply: longtable spec apply --patch-id ${result.patch.id}`);
+        return;
+    }
+    if (command === "apply") {
+        const specification = typeof args["spec-file"] === "string"
+            ? await readResearchSpecificationFile(args["spec-file"])
+            : undefined;
+        const result = await applyResearchSpecificationPatch({
+            context,
+            patchId: typeof args["patch-id"] === "string" ? args["patch-id"] : undefined,
+            specification,
+            source: "manual",
+            rationale: typeof args.rationale === "string" ? args.rationale : undefined
+        });
+        if (args.json === true) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log("Research Specification patch applied");
+        console.log(`- revision: v${result.revision.index} (${result.revision.id})`);
+        console.log(`- patch: ${result.patch.id}`);
+        console.log(`- decision: ${result.decision?.id ?? result.patch.decisionRecordId ?? "existing/none"}`);
+        console.log(`- current: ${context.currentFilePath}`);
+        return;
+    }
+    throw new Error(`Unknown spec subcommand: ${command}`);
+}
 async function runQuestion(args) {
     const workingDirectory = typeof args.cwd === "string" ? args.cwd : cwd();
     const prompt = await resolvePrompt(typeof args.prompt === "string" ? args.prompt : undefined);
@@ -3807,6 +3920,10 @@ async function main() {
         await runSearch(subcommand, values);
         return;
     }
+    if (command === "spec") {
+        await runSpec(subcommand, values);
+        return;
+    }
     if (command === "ask") {
         await runAsk(values);
         return;

package/dist/project-session.d.ts

@@ -1,4 +1,4 @@
-import type { DecisionRecord, InvocationRecord, LongTableQuestionObligation, ProviderKind, QuestionOption, QuestionCommitmentFamily, QuestionEpistemicBasis, QuestionGenerationResult, QuestionOpportunity, QuestionSurface, QuestionRecord, ResearchState } from "@longtable/core";
+import type { DecisionRecord, EvidenceRecord, InvocationRecord, LongTableQuestionObligation, ProviderKind, QuestionOption, QuestionCommitmentFamily, QuestionEpistemicBasis, QuestionGenerationResult, QuestionOpportunity, QuestionSurface, QuestionRecord, ResearchSpecificationChange, ResearchSpecificationPatch, ResearchSpecificationPatchSource, ResearchSpecificationRevision, ResearchState } from "@longtable/core";
 import type { SetupPersistedOutput } from "@longtable/setup";
 export type ProjectDisagreementPreference = "synthesis_only" | "show_on_conflict" | "always_visible";
 export type StartInterviewSignal = "phenomenon" | "audience" | "artifact" | "evidence" | "assumption" | "decision_risk" | "voice";
@@ -40,6 +40,9 @@ export interface ResearchSpecification {
     createdAt?: string;
     updatedAt?: string;
     sourceHookId?: string;
+    latestRevisionId?: string;
+    sourceEvidenceIds?: string[];
+    sectionEvidence?: Record<string, string[]>;
     researchDirection: {
         question?: string;
         purpose: string;
@@ -121,6 +124,10 @@ export type LongTableWorkspaceState = ResearchState & {
     hooks?: LongTableHookRun[];
     firstResearchShape?: FirstResearchShape;
     researchSpecification?: ResearchSpecification;
+    interviewTurns?: LongTableInterviewTurn[];
+    evidenceRecords?: EvidenceRecord[];
+    specPatches?: ResearchSpecificationPatch[];
+    specRevisions?: ResearchSpecificationRevision[];
 };
 export interface LongTableProjectRecord {
     schemaVersion: 1;
@@ -206,6 +213,10 @@ export interface LongTableWorkspaceInspection {
         pendingObligations: number;
         answeredQuestions: number;
         decisions: number;
+        interviewTurns?: number;
+        evidenceRecords?: number;
+        specPatches?: number;
+        specRevisions?: number;
     };
     recentInvocations?: Array<{
         id: string;
@@ -250,6 +261,25 @@ export interface LongTableWorkspaceInspection {
     }>;
 }
 export declare function loadWorkspaceState(context: LongTableProjectContext): Promise<LongTableWorkspaceState>;
+export declare function diffResearchSpecifications(before: ResearchSpecification | undefined, after: ResearchSpecification): ResearchSpecificationChange[];
+export declare function applyResearchSpecificationAuditUpdate(state: LongTableWorkspaceState, options: {
+    specification: ResearchSpecification;
+    timestamp: string;
+    source: ResearchSpecificationPatchSource;
+    title?: string;
+    rationale?: string;
+    sourceEvidenceIds?: string[];
+    patch?: ResearchSpecificationPatch;
+    questionRecordId?: string;
+    decisionRecordId?: string;
+    createDecisionRecord?: boolean;
+}): {
+    state: LongTableWorkspaceState;
+    specification: ResearchSpecification;
+    patch: ResearchSpecificationPatch;
+    revision: ResearchSpecificationRevision;
+    decision?: DecisionRecord;
+};
 export declare function syncCurrentWorkspaceView(context: LongTableProjectContext): Promise<string>;
 export declare function appendInvocationRecordToWorkspace(context: LongTableProjectContext, invocation: InvocationRecord, questions?: QuestionRecord[]): Promise<LongTableWorkspaceState>;
 export declare function beginLongTableInterview(options: {
@@ -298,6 +328,41 @@ export declare function summarizeLongTableResearchSpecification(options: {
     state: LongTableWorkspaceState;
     session: LongTableSessionRecord;
 }>;
+export declare function proposeResearchSpecificationPatch(options: {
+    context: LongTableProjectContext;
+    specification: ResearchSpecification;
+    source?: ResearchSpecificationPatchSource;
+    rationale?: string;
+    sourceEvidenceIds?: string[];
+}): Promise<{
+    patch: ResearchSpecificationPatch;
+    changes: ResearchSpecificationChange[];
+    state: LongTableWorkspaceState;
+}>;
+export declare function applyResearchSpecificationPatch(options: {
+    context: LongTableProjectContext;
+    patchId?: string;
+    specification?: ResearchSpecification;
+    source?: ResearchSpecificationPatchSource;
+    rationale?: string;
+    sourceEvidenceIds?: string[];
+    questionRecordId?: string;
+    decisionRecordId?: string;
+}): Promise<{
+    patch: ResearchSpecificationPatch;
+    revision: ResearchSpecificationRevision;
+    specification: ResearchSpecification;
+    state: LongTableWorkspaceState;
+    session: LongTableSessionRecord;
+    decision?: DecisionRecord;
+}>;
+export declare function readResearchSpecificationHistory(context: LongTableProjectContext): Promise<{
+    specification?: ResearchSpecification;
+    revisions: ResearchSpecificationRevision[];
+    patches: ResearchSpecificationPatch[];
+    evidenceRecords: EvidenceRecord[];
+}>;
+export declare function findUnincorporatedResearchEvidence(context: LongTableProjectContext): Promise<EvidenceRecord[]>;
 export declare function listBlockingWorkspaceQuestions(context: LongTableProjectContext): Promise<QuestionRecord[]>;
 export declare function listBlockingWorkspaceObligations(context: LongTableProjectContext): Promise<LongTableQuestionObligation[]>;
 export declare function assertWorkspaceNotBlocked(context: LongTableProjectContext): Promise<void>;

package/dist/project-session.js

@@ -200,7 +200,66 @@ function renderResearchSpecificationStatus(session, locale) {
             : "- Next protocol: update the specification, then return to `confirm_research_specification` for another preview confirmation."
     ];
 }
-function buildCurrentGuide(project, session, recentInvocations = [], pendingQuestions = [], pendingObligations = []) {
+function renderResearchSpecificationAudit(state, locale) {
+    const korean = locale === "ko";
+    const revisions = (state.specRevisions ?? []).slice(-5).reverse();
+    const patches = (state.specPatches ?? []).slice(-5).reverse();
+    const evidenceRecords = state.evidenceRecords ?? [];
+    const unincorporated = evidenceRecords
+        .filter((record) => !record.incorporatedByRevisionId)
+        .slice(-5)
+        .reverse();
+    const specification = state.researchSpecification;
+    const sectionEvidence = Object.entries(specification?.sectionEvidence ?? {}).slice(0, 8);
+    if (revisions.length === 0 &&
+        patches.length === 0 &&
+        evidenceRecords.length === 0 &&
+        sectionEvidence.length === 0) {
+        return [];
+    }
+    return [
+        "",
+        korean ? "## Research Specification 감사" : "## Research Specification Audit",
+        ...(specification
+            ? [
+                `- ${korean ? "현재 버전" : "Current revision"}: ${specification.latestRevisionId ?? "unversioned"}`,
+                `- ${korean ? "상태" : "Status"}: ${specification.confirmedAt ? "confirmed" : specification.status ?? "draft"}`
+            ]
+            : []),
+        `- ${korean ? "원문 인터뷰 turn" : "Raw interview turns"}: ${(state.interviewTurns ?? []).length}`,
+        `- ${korean ? "근거 기록" : "Evidence records"}: ${evidenceRecords.length}`,
+        `- ${korean ? "spec patch" : "Spec patches"}: ${(state.specPatches ?? []).length}`,
+        `- ${korean ? "spec revision" : "Spec revisions"}: ${(state.specRevisions ?? []).length}`,
+        ...(revisions.length > 0
+            ? [
+                "",
+                korean ? "### 최근 명세 변경" : "### Recent Specification Changes",
+                ...revisions.map((revision) => `- v${revision.index} ${revision.title}: ${revision.changeSummary.slice(0, 3).join("; ")}`)
+            ]
+            : []),
+        ...(sectionEvidence.length > 0
+            ? [
+                "",
+                korean ? "### 근거 맵" : "### Evidence Map",
+                ...sectionEvidence.map(([path, ids]) => `- ${path}: ${ids.slice(-4).join(", ")}`)
+            ]
+            : []),
+        ...(unincorporated.length > 0
+            ? [
+                "",
+                korean ? "### 아직 반영되지 않은 근거" : "### Unincorporated Evidence",
+                ...unincorporated.map((record) => `- ${record.id} [${record.sourceKind}]: ${compactLine(record.summary, 120)}`)
+            ]
+            : []),
+        ...(patches.some((patch) => patch.status === "proposed")
+            ? [
+                "",
+                korean ? "- 대기 중인 spec patch가 있습니다. 적용하거나 거절해야 합니다." : "- Proposed spec patches are waiting to be applied or rejected."
+            ]
+            : [])
+    ];
+}
+function buildCurrentGuide(project, session, recentInvocations = [], pendingQuestions = [], pendingObligations = [], state = createEmptyResearchState()) {
     const locale = normalizeLocale(session.locale ?? project.locale);
     const openQuestions = session.openQuestions && session.openQuestions.length > 0
         ? session.openQuestions
@@ -229,6 +288,7 @@ function buildCurrentGuide(project, session, recentInvocations = [], pendingQues
             `- 관점: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
             `- disagreement: ${session.disagreementPreference}`,
             ...renderResearchSpecificationStatus(session, locale),
+            ...renderResearchSpecificationAudit(state, locale),
             "",
             "## 열린 질문",
             ...openQuestions.map((question) => `- ${question}`),
@@ -305,6 +365,7 @@ function buildCurrentGuide(project, session, recentInvocations = [], pendingQues
         `- Perspectives: ${session.requestedPerspectives.length > 0 ? session.requestedPerspectives.join(", ") : "auto"}`,
         `- Disagreement: ${session.disagreementPreference}`,
         ...renderResearchSpecificationStatus(session, locale),
+        ...renderResearchSpecificationAudit(state, locale),
         "",
         "## Open Questions",
         ...openQuestions.map((question) => `- ${question}`),
@@ -373,6 +434,10 @@ async function loadResearchState(stateFilePath) {
         hooks: parsed.hooks ?? [],
         ...(parsed.firstResearchShape ? { firstResearchShape: parsed.firstResearchShape } : {}),
         ...(parsed.researchSpecification ? { researchSpecification: parsed.researchSpecification } : {}),
+        interviewTurns: parsed.interviewTurns ?? [],
+        evidenceRecords: parsed.evidenceRecords ?? [],
+        specPatches: parsed.specPatches ?? [],
+        specRevisions: parsed.specRevisions ?? [],
         questionObligations: parsed.questionObligations ?? [],
         inferredHypotheses: parsed.inferredHypotheses ?? [],
         openTensions: parsed.openTensions ?? [],
@@ -421,6 +486,280 @@ function formatQuestionMetadata(record) {
     ].filter(Boolean);
     return parts.length > 0 ? ` [${parts.join("; ")}]` : "";
 }
+function compactLine(value, limit = 160) {
+    const compacted = value.replace(/\s+/g, " ").trim();
+    return compacted.length > limit ? `${compacted.slice(0, limit - 1)}…` : compacted;
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+const SPEC_DIFF_IGNORED_PATHS = new Set([
+    "createdAt",
+    "updatedAt",
+    "latestRevisionId",
+    "sourceEvidenceIds",
+    "sectionEvidence"
+]);
+function flattenSpecificationValue(value, prefix = "") {
+    const flattened = new Map();
+    const record = asRecord(value);
+    if (!record) {
+        if (prefix) {
+            flattened.set(prefix, value);
+        }
+        return flattened;
+    }
+    for (const [key, nested] of Object.entries(record)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (SPEC_DIFF_IGNORED_PATHS.has(path)) {
+            continue;
+        }
+        const nestedRecord = asRecord(nested);
+        if (nestedRecord) {
+            for (const [nestedPath, nestedValue] of flattenSpecificationValue(nestedRecord, path)) {
+                flattened.set(nestedPath, nestedValue);
+            }
+            continue;
+        }
+        flattened.set(path, nested);
+    }
+    return flattened;
+}
+function stableValue(value) {
+    return JSON.stringify(value ?? null);
+}
+export function diffResearchSpecifications(before, after) {
+    const beforeMap = before ? flattenSpecificationValue(before) : new Map();
+    const afterMap = flattenSpecificationValue(after);
+    const paths = new Set([...beforeMap.keys(), ...afterMap.keys()]);
+    const changes = [];
+    for (const path of [...paths].sort()) {
+        const previous = beforeMap.get(path);
+        const next = afterMap.get(path);
+        if (stableValue(previous) === stableValue(next)) {
+            continue;
+        }
+        const kind = previous === undefined
+            ? "set"
+            : next === undefined
+                ? "remove"
+                : "replace";
+        changes.push({
+            path,
+            kind,
+            summary: `${kind} ${path}`,
+            ...(previous !== undefined ? { before: previous } : {}),
+            ...(next !== undefined ? { after: next } : {})
+        });
+    }
+    return changes;
+}
+function cloneResearchSpecification(specification) {
+    return JSON.parse(JSON.stringify(specification));
+}
+function mergeStringLists(...lists) {
+    return [...new Set(lists.flatMap((list) => list ?? []).filter(Boolean))];
+}
+function requiredResearchSpecificationGaps(specification) {
+    const gaps = [];
+    if (!specification.researchDirection.question?.trim()) {
+        gaps.push("research question");
+    }
+    if (specification.constructOntology.coreConstructs.length === 0) {
+        gaps.push("construct map/core constructs");
+    }
+    if (specification.researchDirection.inclusionCriteria?.length === 0 &&
+        specification.researchDirection.exclusionCriteria?.length === 0) {
+        gaps.push("inclusion/exclusion rule");
+    }
+    if (specification.evidenceAccess.requiredSources?.length === 0 &&
+        specification.evidenceAccess.evidenceStandards?.length === 0) {
+        gaps.push("evidence boundary");
+    }
+    if (!specification.methodAnalysis.design?.trim() &&
+        specification.methodAnalysis.analysisOptions.length === 0) {
+        gaps.push("method commitment");
+    }
+    if (specification.openQuestions.length === 0 && specification.protectedDecisions.length === 0) {
+        gaps.push("unresolved decisions/protected decisions");
+    }
+    if (specification.evidenceAccess.accessRequirements?.length === 0 &&
+        specification.evidenceAccess.requiredSources?.length === 0) {
+        gaps.push("search/access assumptions");
+    }
+    return gaps;
+}
+function buildResearchSpecificationGapQuestion(gaps, timestamp, sourceEvidenceIds) {
+    return {
+        id: createId("question"),
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        status: "pending",
+        commitmentFamily: "scope",
+        epistemicBasis: "project_state",
+        prompt: {
+            id: createId("prompt"),
+            checkpointKey: "research_specification_required_sections",
+            title: "Research Specification gaps",
+            question: `Which missing Research Specification section should LongTable resolve first? Missing: ${gaps.join(", ")}.`,
+            type: "single_choice",
+            options: [
+                { value: "ask_researcher", label: "Ask the researcher", description: "Pause and ask for the missing research commitment.", recommended: true },
+                { value: "mark_unresolved", label: "Mark unresolved", description: "Keep the gap visible as an unresolved decision." },
+                { value: "infer_from_evidence", label: "Infer from evidence", description: "Use existing evidence records and keep the inference explicit." },
+                { value: "defer", label: "Defer", description: "Do not treat the specification as complete yet." }
+            ],
+            allowOther: true,
+            otherLabel: "Other resolution",
+            required: true,
+            source: "checkpoint",
+            displayReason: `The current Research Specification is missing: ${gaps.join(", ")}.`,
+            rationale: [
+                "Research Specification is the required durable interview artifact.",
+                "Missing required sections can make later resume, screening, coding, or evidence decisions stale."
+            ],
+            preferredSurfaces: ["mcp_elicitation", "numbered"]
+        },
+        transportStatus: {
+            surface: "mcp_elicitation",
+            status: "not_attempted",
+            updatedAt: timestamp,
+            ...(sourceEvidenceIds.length > 0 ? { message: `Source evidence: ${sourceEvidenceIds.join(", ")}` } : {})
+        }
+    };
+}
+function appendSpecGapQuestionIfNeeded(state, specification, timestamp, sourceEvidenceIds) {
+    const gaps = requiredResearchSpecificationGaps(specification);
+    if (gaps.length === 0) {
+        return state;
+    }
+    const alreadyPending = (state.questionLog ?? []).some((record) => record.status === "pending" &&
+        record.prompt.checkpointKey === "research_specification_required_sections");
+    if (alreadyPending) {
+        return state;
+    }
+    return {
+        ...state,
+        questionLog: [
+            ...(state.questionLog ?? []),
+            buildResearchSpecificationGapQuestion(gaps, timestamp, sourceEvidenceIds)
+        ]
+    };
+}
+function changeSummaryForRevision(changes) {
+    if (changes.length === 0) {
+        return ["No substantive field changes; audit metadata refreshed."];
+    }
+    return changes.slice(0, 12).map((change) => change.summary);
+}
+export function applyResearchSpecificationAuditUpdate(state, options) {
+    const previous = state.researchSpecification;
+    const incomingEvidenceIds = mergeStringLists(options.patch?.sourceEvidenceIds, options.specification.sourceEvidenceIds, options.sourceEvidenceIds);
+    const sourceEvidenceIds = mergeStringLists(previous?.sourceEvidenceIds, incomingEvidenceIds);
+    const changes = diffResearchSpecifications(previous, options.specification)
+        .map((change) => ({
+        ...change,
+        ...(incomingEvidenceIds.length > 0 ? { evidenceRecordIds: incomingEvidenceIds } : {})
+    }));
+    const patchId = options.patch?.id ?? createId("spec_patch");
+    const revisionId = createId("spec_revision");
+    const patchTitle = options.title ?? options.patch?.title ?? `Research Specification update: ${options.specification.title}`;
+    const patchRationale = options.rationale ?? options.patch?.rationale;
+    const sectionEvidence = {
+        ...(previous?.sectionEvidence ?? {}),
+        ...(options.specification.sectionEvidence ?? {})
+    };
+    for (const change of changes) {
+        const fieldEvidenceIds = change.evidenceRecordIds ?? [];
+        if (fieldEvidenceIds.length > 0) {
+            sectionEvidence[change.path] = mergeStringLists(sectionEvidence[change.path], fieldEvidenceIds);
+        }
+    }
+    const specification = {
+        ...cloneResearchSpecification(options.specification),
+        updatedAt: options.timestamp,
+        latestRevisionId: revisionId,
+        sourceEvidenceIds,
+        sectionEvidence
+    };
+    const decision = options.decisionRecordId || options.createDecisionRecord === false
+        ? undefined
+        : {
+            id: createId("decision"),
+            timestamp: options.timestamp,
+            checkpointKey: "research_specification_auto_update",
+            level: "log_only",
+            mode: "commit",
+            summary: `Applied Research Specification update: ${patchTitle}`,
+            commitmentFamily: "scope",
+            epistemicBasis: "mixed",
+            rationale: patchRationale ?? "Automatically applied a source-mapped Research Specification update."
+        };
+    const decisionRecordId = options.decisionRecordId ?? decision?.id;
+    const revision = {
+        id: revisionId,
+        index: (state.specRevisions ?? []).length + 1,
+        createdAt: options.timestamp,
+        source: options.source,
+        title: patchTitle,
+        status: specification.status ?? "draft",
+        patchId,
+        ...(options.questionRecordId ? { questionRecordId: options.questionRecordId } : {}),
+        ...(decisionRecordId ? { decisionRecordId } : {}),
+        sourceEvidenceIds,
+        changeSummary: changeSummaryForRevision(changes),
+        specification
+    };
+    const patch = {
+        id: patchId,
+        createdAt: options.patch?.createdAt ?? options.timestamp,
+        updatedAt: options.timestamp,
+        status: "applied",
+        source: options.source,
+        title: patchTitle,
+        ...(patchRationale ? { rationale: patchRationale } : {}),
+        changes,
+        sourceEvidenceIds,
+        targetSpecification: specification,
+        appliedAt: options.timestamp,
+        appliedRevisionId: revision.id,
+        ...(options.questionRecordId ? { questionRecordId: options.questionRecordId } : {}),
+        ...(decisionRecordId ? { decisionRecordId } : {})
+    };
+    const incorporatedEvidence = (state.evidenceRecords ?? []).map((record) => sourceEvidenceIds.includes(record.id)
+        ? {
+            ...record,
+            incorporatedAt: options.timestamp,
+            incorporatedByPatchId: patch.id,
+            incorporatedByRevisionId: revision.id
+        }
+        : record);
+    const withDecision = decision ? appendDecisionToResearchState(state, decision) : state;
+    const previousPatches = withDecision.specPatches ?? [];
+    const specPatches = previousPatches.some((entry) => entry.id === patch.id)
+        ? previousPatches.map((entry) => entry.id === patch.id ? patch : entry)
+        : [...previousPatches, patch];
+    const nextState = {
+        ...withDecision,
+        researchSpecification: specification,
+        evidenceRecords: incorporatedEvidence,
+        specPatches,
+        specRevisions: [...(withDecision.specRevisions ?? []), revision],
+        workingState: {
+            ...withDecision.workingState,
+            researchSpecification: specification
+        }
+    };
+    return {
+        state: appendSpecGapQuestionIfNeeded(nextState, specification, options.timestamp, sourceEvidenceIds),
+        specification,
+        patch,
+        revision,
+        ...(decision ? { decision } : {})
+    };
+}
 function summarizeWorkspaceInspection(context, state) {
     const questions = state.questionLog ?? [];
     const pendingQuestions = questions.filter((record) => record.status === "pending");
@@ -465,7 +804,11 @@ function summarizeWorkspaceInspection(context, state) {
             pendingQuestions: pendingQuestions.length,
             pendingObligations: pendingObligations.length,
             answeredQuestions: answeredQuestions.length,
-            decisions: (state.decisionLog ?? []).length
+            decisions: (state.decisionLog ?? []).length,
+            interviewTurns: (state.interviewTurns ?? []).length,
+            evidenceRecords: (state.evidenceRecords ?? []).length,
+            specPatches: (state.specPatches ?? []).length,
+            specRevisions: (state.specRevisions ?? []).length
         },
         recentInvocations: recentInvocationRecords(state, 5).map((record) => ({
             id: record.id,
@@ -684,19 +1027,92 @@ export async function syncCurrentWorkspaceView(context) {
             ? { researchSpecification: context.session.researchSpecification ?? state.researchSpecification }
             : {})
     };
-    const body = buildCurrentGuide(context.project, session, recentInvocationRecords(state), recentPendingQuestions(state), recentPendingObligations(state));
+    const body = buildCurrentGuide(context.project, session, recentInvocationRecords(state), recentPendingQuestions(state), recentPendingObligations(state), state);
     await writeFile(context.currentFilePath, body, "utf8");
     return context.currentFilePath;
 }
+function evidenceKindForInvocationRole(role) {
+    const normalized = role?.toLowerCase() ?? "";
+    if (normalized.includes("critic")) {
+        return "critic";
+    }
+    if (normalized.includes("reviewer") || normalized.includes("review")) {
+        return "reviewer";
+    }
+    return "panel";
+}
+function evidenceRecordsForInvocation(invocation, timestamp) {
+    const records = [];
+    if (invocation.panelResult) {
+        for (const member of invocation.panelResult.memberResults) {
+            if (!member.summary && (member.claims ?? []).length === 0 && (member.objections ?? []).length === 0) {
+                continue;
+            }
+            records.push({
+                id: createId("evidence"),
+                createdAt: timestamp,
+                sourceKind: evidenceKindForInvocationRole(member.role),
+                sourceId: `${invocation.id}:${member.role}`,
+                role: member.role,
+                summary: compactLine(member.summary ?? [...(member.claims ?? []), ...(member.objections ?? [])].join(" ")),
+                rawText: [
+                    member.summary ? `Summary: ${member.summary}` : "",
+                    member.claims?.length ? `Claims: ${member.claims.join("; ")}` : "",
+                    member.objections?.length ? `Objections: ${member.objections.join("; ")}` : "",
+                    member.openQuestions?.length ? `Open questions: ${member.openQuestions.join("; ")}` : ""
+                ].filter(Boolean).join("\n"),
+                linkedInvocationRecordIds: [invocation.id],
+                linkedQuestionRecordIds: invocation.panelResult.linkedQuestionRecordIds,
+                linkedDecisionRecordIds: invocation.panelResult.linkedDecisionRecordIds
+            });
+        }
+        if (invocation.panelResult.synthesis || invocation.panelResult.conflictSummary) {
+            records.push({
+                id: createId("evidence"),
+                createdAt: timestamp,
+                sourceKind: "panel",
+                sourceId: invocation.panelResult.id,
+                summary: compactLine(invocation.panelResult.synthesis ?? invocation.panelResult.conflictSummary ?? "Panel result"),
+                rawText: [
+                    invocation.panelResult.synthesis ? `Synthesis: ${invocation.panelResult.synthesis}` : "",
+                    invocation.panelResult.conflictSummary ? `Conflict: ${invocation.panelResult.conflictSummary}` : ""
+                ].filter(Boolean).join("\n"),
+                linkedInvocationRecordIds: [invocation.id],
+                linkedQuestionRecordIds: invocation.panelResult.linkedQuestionRecordIds,
+                linkedDecisionRecordIds: invocation.panelResult.linkedDecisionRecordIds
+            });
+        }
+        return records;
+    }
+    if (invocation.status === "completed" && invocation.intent.prompt.trim()) {
+        records.push({
+            id: createId("evidence"),
+            createdAt: timestamp,
+            sourceKind: "invocation",
+            sourceId: invocation.id,
+            summary: compactLine(`${invocation.intent.kind}/${invocation.intent.mode}: ${invocation.intent.prompt}`),
+            rawText: invocation.intent.prompt,
+            linkedInvocationRecordIds: [invocation.id]
+        });
+    }
+    return records;
+}
 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");
+    const evidenceRecords = evidenceRecordsForInvocation(invocation, nowIso());
+    const withEvidence = evidenceRecords.length > 0
+        ? {
+            ...updated,
+            evidenceRecords: [...(updated.evidenceRecords ?? []), ...evidenceRecords]
+        }
+        : updated;
+    await writeFile(context.stateFilePath, JSON.stringify(withEvidence, null, 2), "utf8");
     await syncCurrentWorkspaceView(context);
-    return updated;
+    return withEvidence;
 }
 function createId(prefix) {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
@@ -842,7 +1258,24 @@ export async function appendLongTableInterviewTurn(options) {
                 : [])
         ]
     };
-    const updated = upsertHook(state, hook);
+    const evidence = {
+        id: createId("evidence"),
+        createdAt: timestamp,
+        sourceKind: "interview_turn",
+        sourceId: turn.id,
+        sourceHookId: existing.id,
+        summary: compactLine(`Interview turn ${turn.index}: ${turn.answer}`),
+        rawText: [
+            `Question: ${turn.question}`,
+            `Answer: ${turn.answer}`,
+            turn.reflection ? `Reflection: ${turn.reflection}` : ""
+        ].filter(Boolean).join("\n")
+    };
+    const updated = {
+        ...upsertHook(state, hook),
+        interviewTurns: [...(state.interviewTurns ?? []), turn],
+        evidenceRecords: [...(state.evidenceRecords ?? []), evidence]
+    };
     await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
     await syncCurrentWorkspaceView(options.context);
     return { hook, turn, state: updated };
@@ -1009,12 +1442,18 @@ export async function summarizeLongTableResearchSpecification(options) {
         resumeHint: `I want to continue from the Research Specification: ${specification.title}.`
     };
     options.context.session = session;
-    let updated = hook ? upsertHook(state, hook) : state;
-    updated.researchSpecification = specification;
-    updated.workingState = {
-        ...updated.workingState,
-        researchSpecification: specification
-    };
+    const sourceEvidenceIds = (state.evidenceRecords ?? [])
+        .filter((record) => record.sourceHookId && record.sourceHookId === (existing?.id ?? sourceHookId))
+        .map((record) => record.id);
+    const audited = applyResearchSpecificationAuditUpdate(hook ? upsertHook(state, hook) : state, {
+        specification,
+        timestamp,
+        source: "interview",
+        title: `Research Specification draft: ${specification.title}`,
+        rationale: "Stored or refreshed the required Research Specification from LongTable interview evidence.",
+        sourceEvidenceIds
+    });
+    let updated = audited.state;
     updated.narrativeTraces.push({
         id: createId("narrative_trace"),
         timestamp,
@@ -1029,6 +1468,93 @@ export async function summarizeLongTableResearchSpecification(options) {
     await syncCurrentWorkspaceView(options.context);
     return { hook, specification, state: updated, session };
 }
+export async function proposeResearchSpecificationPatch(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const timestamp = nowIso();
+    const specification = normalizeResearchSpecification(options.specification, options.specification.sourceHookId ?? state.researchSpecification?.sourceHookId, timestamp);
+    const sourceEvidenceIds = mergeStringLists(options.specification.sourceEvidenceIds, specification.sourceEvidenceIds, options.sourceEvidenceIds);
+    const changes = diffResearchSpecifications(state.researchSpecification, specification)
+        .map((change) => ({
+        ...change,
+        evidenceRecordIds: sourceEvidenceIds
+    }));
+    const patch = {
+        id: createId("spec_patch"),
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        status: "proposed",
+        source: options.source ?? "manual",
+        title: `Proposed Research Specification update: ${specification.title}`,
+        ...(options.rationale ? { rationale: options.rationale } : {}),
+        changes,
+        sourceEvidenceIds,
+        targetSpecification: specification
+    };
+    const updated = {
+        ...state,
+        specPatches: [...(state.specPatches ?? []), patch]
+    };
+    await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return { patch, changes, state: updated };
+}
+export async function applyResearchSpecificationPatch(options) {
+    const state = await loadResearchState(options.context.stateFilePath);
+    const timestamp = nowIso();
+    const storedPatch = options.patchId
+        ? (state.specPatches ?? []).find((patch) => patch.id === options.patchId)
+        : undefined;
+    if (options.patchId && !storedPatch) {
+        throw new Error(`No Research Specification patch found for ${options.patchId}.`);
+    }
+    const inputSpecification = options.specification ?? storedPatch?.targetSpecification;
+    if (!inputSpecification) {
+        throw new Error(options.patchId ? `No target Research Specification found for patch ${options.patchId}.` : "Research Specification is required when no patchId is supplied.");
+    }
+    const specification = normalizeResearchSpecification(inputSpecification, inputSpecification.sourceHookId ?? state.researchSpecification?.sourceHookId, timestamp);
+    const audited = applyResearchSpecificationAuditUpdate(state, {
+        specification,
+        timestamp,
+        source: options.source ?? storedPatch?.source ?? "manual",
+        title: storedPatch?.title ?? `Applied Research Specification update: ${specification.title}`,
+        rationale: options.rationale ?? storedPatch?.rationale,
+        sourceEvidenceIds: mergeStringLists(storedPatch?.sourceEvidenceIds, options.sourceEvidenceIds),
+        patch: storedPatch,
+        questionRecordId: options.questionRecordId ?? storedPatch?.questionRecordId,
+        decisionRecordId: options.decisionRecordId ?? storedPatch?.decisionRecordId
+    });
+    const session = {
+        ...options.context.session,
+        researchSpecification: audited.specification,
+        lastUpdatedAt: timestamp,
+        resumeHint: `I want to continue from the Research Specification: ${audited.specification.title}.`
+    };
+    options.context.session = session;
+    await writeFile(options.context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
+    await writeFile(options.context.stateFilePath, JSON.stringify(audited.state, null, 2), "utf8");
+    await syncCurrentWorkspaceView(options.context);
+    return {
+        patch: audited.patch,
+        revision: audited.revision,
+        specification: audited.specification,
+        state: audited.state,
+        session,
+        ...(audited.decision ? { decision: audited.decision } : {})
+    };
+}
+export async function readResearchSpecificationHistory(context) {
+    const state = await loadResearchState(context.stateFilePath);
+    return {
+        ...(state.researchSpecification ? { specification: state.researchSpecification } : {}),
+        revisions: state.specRevisions ?? [],
+        patches: state.specPatches ?? [],
+        evidenceRecords: state.evidenceRecords ?? []
+    };
+}
+export async function findUnincorporatedResearchEvidence(context) {
+    const state = await loadResearchState(context.stateFilePath);
+    return (state.evidenceRecords ?? []).filter((record) => !record.incorporatedByRevisionId);
+}
 function findQuestionForDecision(state, questionId) {
     const pending = (state.questionLog ?? []).filter((record) => record.status === "pending");
     if (questionId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtable/cli",
-  "version": "0.1.47",
+  "version": "0.1.48",
   "private": false,
   "description": "Researcher-facing LongTable CLI",
   "type": "module",
@@ -29,12 +29,12 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "@longtable/checkpoints": "0.1.47",
-    "@longtable/core": "0.1.47",
-    "@longtable/memory": "0.1.47",
-    "@longtable/provider-claude": "0.1.47",
-    "@longtable/provider-codex": "0.1.47",
-    "@longtable/setup": "0.1.47"
+    "@longtable/checkpoints": "0.1.48",
+    "@longtable/core": "0.1.48",
+    "@longtable/memory": "0.1.48",
+    "@longtable/provider-claude": "0.1.48",
+    "@longtable/provider-codex": "0.1.48",
+    "@longtable/setup": "0.1.48"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",