@longtable/cli 0.1.53 → 0.1.55

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

@@ -1,5 +1,5 @@
 import { pathToFileURL } from "node:url";
-import { collectHardStopBlockers } from "@longtable/core";
+import { collectHardStopBlockers, evaluateResearchSpecificationReadiness } from "@longtable/core";
 import { createWorkspaceFollowUpQuestions, loadProjectContextFromDirectory, loadWorkspaceState, pendingQuestionObligations } from "./index.js";
 function safeString(value) {
     return typeof value === "string" ? value : "";
@@ -237,13 +237,22 @@ async function loadLongTableRuntime(startPath) {
 }
 function buildWorkspaceSummary(runtime, detail = "compact") {
     const { context, state } = runtime;
+    const readiness = evaluateResearchSpecificationReadiness({
+        firstResearchShape: state.firstResearchShape ?? context.session.firstResearchShape,
+        researchSpecification: state.researchSpecification ?? context.session.researchSpecification,
+        questionLog: state.questionLog,
+        questionObligations: state.questionObligations
+    });
     if (detail === "compact") {
-        const primaryContext = state.firstResearchShape
-            ? `First research shape: ${compactContextValue(state.firstResearchShape.handle, 96)}.`
-            : `Current goal: ${compactContextValue(context.session.currentGoal, 120)}.`;
+        const primaryContext = state.researchSpecification
+            ? `Research Specification: ${compactContextValue(state.researchSpecification.title, 96)} (${readiness.status}).`
+            : state.firstResearchShape
+                ? `First research shape: ${compactContextValue(state.firstResearchShape.handle, 96)}.`
+                : `Current goal: ${compactContextValue(context.session.currentGoal, 120)}.`;
         return [
             "LongTable workspace detected; research context restored.",
             primaryContext,
+            readiness.usableForInterview || readiness.status === "no_spec" ? "" : `Research Specification readiness: ${readiness.status}; next action: ${readiness.nextAction}.`,
             context.session.nextAction ? `Next action: ${compactContextValue(context.session.nextAction)}.` : "",
             context.session.protectedDecision ? "Protected decision: active; full text is in `.longtable/` and `CURRENT.md`." : ""
         ].filter(Boolean);
@@ -254,6 +263,8 @@ function buildWorkspaceSummary(runtime, detail = "compact") {
         context.session.currentBlocker ? `Current blocker: ${context.session.currentBlocker}.` : "",
         context.session.protectedDecision ? `Protected decision: ${context.session.protectedDecision}.` : "",
         state.firstResearchShape ? `First research shape: ${state.firstResearchShape.handle}.` : "",
+        state.researchSpecification ? `Research Specification: ${state.researchSpecification.title} (${readiness.status}).` : "",
+        readiness.usableForInterview || readiness.status === "no_spec" ? "" : `Research Specification readiness: ${readiness.status}; next action: ${readiness.nextAction}; gaps: ${readiness.blockingGaps.join("; ")}.`,
         context.session.nextAction ? `Next action: ${context.session.nextAction}.` : ""
     ].filter(Boolean);
     return lines;
@@ -339,7 +350,7 @@ function buildActiveInterviewContext(hook) {
         "A LongTable interview is currently active.",
         `Interview status: ${hook.status}.`,
         `Turns recorded: ${turnCount}.`,
-        "Do not finalize the research direction until the interview is either summarized into a First Research Shape or explicitly cleared."
+        "Do not finalize the research direction until the interview has created a Research Specification and either confirmed it or left an explicit pending/deferred confirmation."
     ].join("\n");
 }
 function sessionStartContext(runtime) {

package/dist/project-session.d.ts

@@ -1,4 +1,4 @@
-import type { DecisionRecord, EvidenceRecord, InvocationRecord, LongTableQuestionObligation, ProviderKind, QuestionOption, HardStopScope, QuestionCommitmentFamily, QuestionEpistemicBasis, QuestionGenerationResult, QuestionOpportunity, QuestionSurface, QuestionPromptType, QuestionRecord, ResearchSpecificationChange, ResearchSpecificationPatch, ResearchSpecificationPatchSource, ResearchSpecificationRevision, ResearchState } from "@longtable/core";
+import type { DecisionRecord, EvidenceRecord, InvocationRecord, LongTableQuestionObligation, ProviderKind, QuestionOption, HardStopScope, QuestionCommitmentFamily, QuestionEpistemicBasis, QuestionGenerationResult, QuestionOpportunity, QuestionSurface, QuestionPromptType, QuestionRecord, ResearchSpecificationChange, ResearchSpecificationPatch, ResearchSpecificationPatchSource, ResearchSpecificationReadiness, ResearchSpecificationRevision, ResearchState } from "@longtable/core";
 import type { SetupPersistedOutput } from "@longtable/setup";
 import { type HardStopVerdict } from "@longtable/core";
 export type ProjectDisagreementPreference = "synthesis_only" | "show_on_conflict" | "always_visible";
@@ -222,6 +222,7 @@ export interface LongTableWorkspaceInspection {
         specRevisions?: number;
     };
     hardStop?: HardStopVerdict;
+    researchSpecificationReadiness?: ResearchSpecificationReadiness;
     recentInvocations?: Array<{
         id: string;
         kind: string;

package/dist/project-session.js

@@ -4,7 +4,7 @@ import { execSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
 import { appendDecisionRecord as appendDecisionToResearchState, appendInvocationRecord as appendInvocationToResearchState, appendQuestionRecords, createEmptyResearchState } from "@longtable/memory";
 import { classifyCheckpointTrigger } from "@longtable/checkpoints";
-import { collectHardStopBlockers } from "@longtable/core";
+import { collectHardStopBlockers, evaluateResearchSpecificationReadiness, requiredResearchSpecificationGaps } from "@longtable/core";
 import { ensureRequiredQuestionObligation, pendingQuestionObligations, resolveQuestionObligationByQuestionId } from "./question-obligations.js";
 const CURRENT_FILE_NAME = "CURRENT.md";
 const LEGACY_ROOT_FILES = ["LONGTABLE.md", "START-HERE.md", "NEXT-STEPS.md", "SESSION-SNAPSHOT.md"];
@@ -165,11 +165,15 @@ function renderResearchSpecificationSummary(specification, locale) {
     return lines;
 }
 function renderResearchSpecificationStatus(session, locale) {
-    if (!session.firstResearchShape && !session.researchSpecification) {
+    const readiness = evaluateResearchSpecificationReadiness({
+        firstResearchShape: session.firstResearchShape,
+        researchSpecification: session.researchSpecification
+    });
+    if (readiness.status === "no_spec") {
         return [];
     }
     const korean = locale === "ko";
-    if (!session.researchSpecification) {
+    if (readiness.status === "shape_only") {
         return [
             "",
             korean ? "## Research Specification 상태" : "## Research Specification Status",
@@ -184,21 +188,27 @@ function renderResearchSpecificationStatus(session, locale) {
                 : "- Next protocol: when enough detail exists, run `summarize_research_specification` to create the preview, then `confirm_research_specification` to confirm, ask one more question, revise a section, or keep it open."
         ];
     }
-    const status = session.researchSpecification.confirmedAt
-        ? "confirmed"
-        : session.researchSpecification.status ?? "draft";
-    if (status === "confirmed") {
+    if (readiness.status === "confirmed") {
         return [];
     }
     return [
         "",
         korean ? "## Research Specification 상태" : "## Research Specification Status",
         korean
-            ? `- 상태: ${status}. Research Specification은 저장되어 있지만 아직 확정된 종료 지점이 아닙니다.`
-            : `- Status: ${status}. Research Specification exists, but it is not a confirmed closure point yet.`,
+            ? `- 상태: ${readiness.status}. Research Specification은 저장되어 있지만 아직 확정된 종료 지점이 아닙니다.`
+            : `- Status: ${readiness.status}. Research Specification exists, but it is not a confirmed closure point yet.`,
+        ...(readiness.blockingGaps.length > 0
+            ? [korean
+                    ? `- 남은 gap: ${readiness.blockingGaps.join("; ")}.`
+                    : `- Remaining gaps: ${readiness.blockingGaps.join("; ")}.`]
+            : []),
         korean
-            ? "- 다음 프로토콜: 명세를 업데이트한 뒤 `confirm_research_specification`으로 다시 preview 확인을 받아야 합니다."
-            : "- Next protocol: update the specification, then return to `confirm_research_specification` for another preview confirmation."
+            ? readiness.nextAction === "start"
+                ? "- 다음 프로토콜: `$longtable-start`에서 빠진 섹션을 더 묻고 Research Specification을 업데이트해야 합니다."
+                : "- 다음 프로토콜: `confirm_research_specification`으로 preview 확인을 받아야 합니다."
+            : readiness.nextAction === "start"
+                ? "- Next protocol: stay in `$longtable-start`, ask for the missing sections, and update the Research Specification."
+                : "- Next protocol: return to `confirm_research_specification` for preview confirmation."
     ];
 }
 function renderResearchSpecificationAudit(state, locale) {
@@ -563,35 +573,6 @@ function cloneResearchSpecification(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"),
@@ -655,6 +636,18 @@ function changeSummaryForRevision(changes) {
     }
     return changes.slice(0, 12).map((change) => change.summary);
 }
+function researchSpecificationAnswerConfirms(answer) {
+    return answer === "confirm_specification";
+}
+function researchSpecificationAnswerStatus(answer) {
+    if (researchSpecificationAnswerConfirms(answer)) {
+        return "confirmed";
+    }
+    if (answer === "keep_open") {
+        return "deferred";
+    }
+    return "draft";
+}
 export function applyResearchSpecificationAuditUpdate(state, options) {
     const previous = state.researchSpecification;
     const incomingEvidenceIds = mergeStringLists(options.patch?.sourceEvidenceIds, options.specification.sourceEvidenceIds, options.sourceEvidenceIds);
@@ -767,6 +760,12 @@ function summarizeWorkspaceInspection(context, state) {
     const answeredQuestions = questions.filter((record) => record.status === "answered");
     const pendingObligations = visiblePendingObligations(state);
     const hardStop = collectHardStopBlockers(state);
+    const researchSpecificationReadiness = evaluateResearchSpecificationReadiness({
+        firstResearchShape: state.firstResearchShape ?? context.session.firstResearchShape,
+        researchSpecification: state.researchSpecification ?? context.session.researchSpecification,
+        questionLog: state.questionLog,
+        questionObligations: state.questionObligations
+    });
     return {
         found: true,
         rootPath: context.project.projectPath,
@@ -815,6 +814,7 @@ function summarizeWorkspaceInspection(context, state) {
             specRevisions: (state.specRevisions ?? []).length
         },
         hardStop,
+        researchSpecificationReadiness,
         recentInvocations: recentInvocationRecords(state, 5).map((record) => ({
             id: record.id,
             kind: record.intent.kind,
@@ -2735,7 +2735,56 @@ export async function answerWorkspaceQuestion(options) {
         invocationLog: (state.invocationLog ?? []).map((record) => updateInvocationWithDecision(record, question.id, decision.id))
     };
     const withDecision = appendDecisionToResearchState(withQuestion, decision);
-    const updated = resolveQuestionObligationByQuestionId(withDecision, question.id, decision.id);
+    let updated = resolveQuestionObligationByQuestionId(withDecision, question.id, decision.id);
+    if (question.prompt.checkpointKey === "research_specification_confirmation") {
+        const specification = updated.researchSpecification ?? options.context.session.researchSpecification;
+        const selectedAnswer = answer.selectedValues[0];
+        if (specification) {
+            const nextStatus = researchSpecificationAnswerStatus(selectedAnswer);
+            const confirmedSpecification = {
+                ...specification,
+                status: nextStatus,
+                updatedAt: timestamp,
+                ...(nextStatus === "confirmed" ? { confirmedAt: specification.confirmedAt ?? timestamp } : {})
+            };
+            const withHookStatus = {
+                ...updated,
+                hooks: (updated.hooks ?? []).map((hook) => {
+                    if (hook.id !== confirmedSpecification.sourceHookId) {
+                        return hook;
+                    }
+                    return {
+                        ...hook,
+                        status: nextStatus === "draft" ? "active" : nextStatus,
+                        updatedAt: timestamp,
+                        researchSpecification: confirmedSpecification,
+                        linkedQuestionRecordIds: mergeStringLists(hook.linkedQuestionRecordIds, [question.id]),
+                        linkedDecisionRecordIds: mergeStringLists(hook.linkedDecisionRecordIds, [decision.id])
+                    };
+                })
+            };
+            const sourceEvidenceIds = (withHookStatus.evidenceRecords ?? [])
+                .filter((record) => record.sourceHookId && record.sourceHookId === confirmedSpecification.sourceHookId)
+                .map((record) => record.id);
+            updated = applyResearchSpecificationAuditUpdate(withHookStatus, {
+                specification: confirmedSpecification,
+                timestamp,
+                source: "decision",
+                title: `Research Specification confirmation: ${confirmedSpecification.title}`,
+                rationale: `Research Specification confirmation answer: ${selectedAnswer}`,
+                sourceEvidenceIds,
+                questionRecordId: question.id,
+                decisionRecordId: decision.id,
+                createDecisionRecord: false
+            }).state;
+            options.context.session = {
+                ...options.context.session,
+                researchSpecification: confirmedSpecification,
+                lastUpdatedAt: timestamp
+            };
+            await writeFile(options.context.sessionFilePath, JSON.stringify(options.context.session, null, 2), "utf8");
+        }
+    }
     await writeFile(options.context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
     await syncCurrentWorkspaceView(options.context);
     return {

package/package.json

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