novel-writer-cli 0.0.3 → 0.1.0

package/dist/next-step.js

@@ -1,12 +1,18 @@
 import { join } from "node:path";
+import { tryResolveVolumeChapterRange } from "./consistency-auditor.js";
+import { NovelCliError } from "./errors.js";
 import { pathExists, readJsonFile, readTextFile } from "./fs-utils.js";
+import { computeGateDecision, detectHighConfidenceViolation } from "./gate-decision.js";
 import { checkHookPolicy } from "./hook-policy.js";
 import { loadPlatformProfile } from "./platform-profile.js";
+import { computeReviewNext } from "./volume-review.js";
 import { computePrejudgeGuardrailsReport, loadPrejudgeGuardrailsReportIfFresh, prejudgeGuardrailsRelPath } from "./prejudge-guardrails.js";
 import { summarizeNamingIssues } from "./naming-lint.js";
 import { summarizeReadabilityIssues } from "./readability-lint.js";
 import { computeTitlePolicyReport } from "./title-policy.js";
 import { chapterRelPaths, formatStepId } from "./steps.js";
+import { isPlainObject } from "./type-guards.js";
+import { computeVolumeNextStep } from "./volume-planning.js";
 function normalizeStage(stage) {
     if (stage === null || stage === undefined)
         return null;
@@ -15,8 +21,7 @@ function normalizeStage(stage) {
     return null;
 }
 async function checkHookPolicyForStage(args) {
-    const loadedProfile = await loadPlatformProfile(args.projectRootDir);
-    const hookPolicy = loadedProfile?.profile.hook_policy;
+    const hookPolicy = args.loadedProfile?.profile.hook_policy;
     if (!hookPolicy?.required)
         return null;
     let evalRaw;
@@ -60,10 +65,9 @@ async function checkHookPolicyForStage(args) {
     return null;
 }
 async function checkTitlePolicyForStage(args) {
-    const loadedProfile = await loadPlatformProfile(args.projectRootDir);
-    if (!loadedProfile)
+    if (!args.loadedProfile)
         return null;
-    const titlePolicy = loadedProfile.profile.retention?.title_policy;
+    const titlePolicy = args.loadedProfile.profile.retention?.title_policy;
     if (!titlePolicy?.enabled)
         return null;
     if (!args.hasChapter) {
@@ -87,7 +91,7 @@ async function checkTitlePolicyForStage(args) {
             evidence: { ...args.evidence, titleFixCount: args.titleFixCount, error: message }
         };
     }
-    const report = computeTitlePolicyReport({ chapter: args.inflightChapter, chapterText, platformProfile: loadedProfile.profile });
+    const report = computeTitlePolicyReport({ chapter: args.inflightChapter, chapterText, platformProfile: args.loadedProfile.profile });
     if (report.status === "pass" || report.status === "skipped")
         return null;
     if (!report.has_hard_violations && !titlePolicy.auto_fix)
@@ -118,8 +122,7 @@ async function checkTitlePolicyForStage(args) {
     };
 }
 async function checkPrejudgeGuardrailsForStage(args) {
-    const loadedProfile = await loadPlatformProfile(args.projectRootDir);
-    if (!loadedProfile)
+    if (!args.loadedProfile)
         return null;
     const chapterAbsPath = join(args.projectRootDir, args.chapterRelPath);
     const cacheRelPath = prejudgeGuardrailsRelPath(args.inflightChapter);
@@ -128,8 +131,8 @@ async function checkPrejudgeGuardrailsForStage(args) {
         rootDir: args.projectRootDir,
         chapter: args.inflightChapter,
         chapterAbsPath,
-        platformProfileRelPath: loadedProfile.relPath,
-        platformProfile: loadedProfile.profile
+        platformProfileRelPath: args.loadedProfile.relPath,
+        platformProfile: args.loadedProfile.profile
     });
     if (report)
         cacheStatus = "hit";
@@ -139,8 +142,8 @@ async function checkPrejudgeGuardrailsForStage(args) {
                 rootDir: args.projectRootDir,
                 chapter: args.inflightChapter,
                 chapterAbsPath,
-                platformProfileRelPath: loadedProfile.relPath,
-                platformProfile: loadedProfile.profile
+                platformProfileRelPath: args.loadedProfile.relPath,
+                platformProfile: args.loadedProfile.profile
             });
         }
         catch (err) {
@@ -193,13 +196,33 @@ async function checkPrejudgeGuardrailsForStage(args) {
         }
     };
 }
-export async function computeNextStep(projectRootDir, checkpoint) {
+async function computeChapterNextStep(projectRootDir, checkpoint) {
     const inflightChapter = typeof checkpoint.inflight_chapter === "number" ? checkpoint.inflight_chapter : null;
     const stage = normalizeStage(checkpoint.pipeline_stage);
     const hookFixCount = typeof checkpoint.hook_fix_count === "number" ? checkpoint.hook_fix_count : 0;
     const titleFixCount = typeof checkpoint.title_fix_count === "number" ? checkpoint.title_fix_count : 0;
-    // Fresh start.
-    if (inflightChapter === null || stage === null || stage === "committed") {
+    if (inflightChapter !== null && inflightChapter < 1) {
+        throw new NovelCliError(".checkpoint.json.inflight_chapter must be an int >= 1 (or null).", 2);
+    }
+    if (stage === null || stage === "committed") {
+        if (inflightChapter !== null) {
+            throw new NovelCliError(`Checkpoint inconsistent: pipeline_stage=${stage ?? "null"} but inflight_chapter=${inflightChapter}. Set inflight_chapter to null.`, 2);
+        }
+        // Volume-end: enter deterministic volume review pipeline (issue #144).
+        if (checkpoint.last_completed_chapter > 0) {
+            let range = null;
+            try {
+                range = await tryResolveVolumeChapterRange({ rootDir: projectRootDir, volume: checkpoint.current_volume });
+            }
+            catch {
+                // Best-effort: if we can't resolve range, fall back to chapter pipeline.
+                range = null;
+            }
+            if (range && checkpoint.last_completed_chapter === range.end) {
+                const next = await computeReviewNext(projectRootDir, checkpoint);
+                return { ...next, reason: `volume_end:${next.reason}` };
+            }
+        }
         const nextChapter = checkpoint.last_completed_chapter + 1;
         return {
             step: formatStepId({ kind: "chapter", chapter: nextChapter, stage: "draft" }),
@@ -207,6 +230,9 @@ export async function computeNextStep(projectRootDir, checkpoint) {
             inflight: { chapter: null, pipeline_stage: stage }
         };
     }
+    if (inflightChapter === null) {
+        throw new NovelCliError(`Checkpoint inconsistent: pipeline_stage=${stage} requires inflight_chapter. Repair .checkpoint.json and rerun.`, 2);
+    }
     const rel = chapterRelPaths(inflightChapter);
     const hasChapter = await pathExists(join(projectRootDir, rel.staging.chapterMd));
     const hasSummary = await pathExists(join(projectRootDir, rel.staging.summaryMd));
@@ -281,6 +307,7 @@ export async function computeNextStep(projectRootDir, checkpoint) {
                 evidence
             };
         }
+        const loadedProfile = await loadPlatformProfile(projectRootDir);
         if (!hasEval) {
             const titleGate = await checkTitlePolicyForStage({
                 projectRootDir,
@@ -290,7 +317,8 @@ export async function computeNextStep(projectRootDir, checkpoint) {
                 evidence,
                 titleFixCount,
                 hasChapter,
-                chapterRelPath: rel.staging.chapterMd
+                chapterRelPath: rel.staging.chapterMd,
+                loadedProfile
             });
             if (titleGate)
                 return titleGate;
@@ -309,7 +337,8 @@ export async function computeNextStep(projectRootDir, checkpoint) {
             evidence,
             titleFixCount,
             hasChapter,
-            chapterRelPath: rel.staging.chapterMd
+            chapterRelPath: rel.staging.chapterMd,
+            loadedProfile
         });
         if (titleGate)
             return titleGate;
@@ -320,7 +349,8 @@ export async function computeNextStep(projectRootDir, checkpoint) {
             pipelineStage: stage,
             evidence,
             hookFixCount,
-            evalRelPath: rel.staging.evalJson
+            evalRelPath: rel.staging.evalJson,
+            loadedProfile
         });
         if (hookGate)
             return hookGate;
@@ -330,7 +360,8 @@ export async function computeNextStep(projectRootDir, checkpoint) {
             inflightChapter,
             pipelineStage: stage,
             evidence,
-            chapterRelPath: rel.staging.chapterMd
+            chapterRelPath: rel.staging.chapterMd,
+            loadedProfile
         });
         if (guardrailsGate)
             return guardrailsGate;
@@ -358,6 +389,7 @@ export async function computeNextStep(projectRootDir, checkpoint) {
                 evidence
             };
         }
+        const loadedProfile = await loadPlatformProfile(projectRootDir);
         const titleGate = await checkTitlePolicyForStage({
             projectRootDir,
             stagePrefix: "judged",
@@ -366,7 +398,8 @@ export async function computeNextStep(projectRootDir, checkpoint) {
             evidence,
             titleFixCount,
             hasChapter,
-            chapterRelPath: rel.staging.chapterMd
+            chapterRelPath: rel.staging.chapterMd,
+            loadedProfile
         });
         if (titleGate)
             return titleGate;
@@ -377,7 +410,8 @@ export async function computeNextStep(projectRootDir, checkpoint) {
             pipelineStage: stage,
             evidence,
             hookFixCount,
-            evalRelPath: rel.staging.evalJson
+            evalRelPath: rel.staging.evalJson,
+            loadedProfile
         });
         if (hookGate)
             return hookGate;
@@ -387,22 +421,152 @@ export async function computeNextStep(projectRootDir, checkpoint) {
             inflightChapter,
             pipelineStage: stage,
             evidence,
-            chapterRelPath: rel.staging.chapterMd
+            chapterRelPath: rel.staging.chapterMd,
+            loadedProfile
         });
         if (guardrailsGate)
             return guardrailsGate;
-        return {
-            step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "commit" }),
-            reason: "judged:ready_commit",
-            inflight: { chapter: inflightChapter, pipeline_stage: stage },
-            evidence
+        // Gate decision: deterministic mapping from QualityJudge outputs → next action.
+        let evalRaw;
+        try {
+            evalRaw = await readJsonFile(join(projectRootDir, rel.staging.evalJson));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "judge" }),
+                reason: `judged:eval_read_failed`,
+                inflight: { chapter: inflightChapter, pipeline_stage: stage },
+                evidence: { ...evidence, error: message }
+            };
+        }
+        if (!isPlainObject(evalRaw)) {
+            return {
+                step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "judge" }),
+                reason: `judged:eval_invalid`,
+                inflight: { chapter: inflightChapter, pipeline_stage: stage },
+                evidence: { ...evidence }
+            };
+        }
+        const evalObj = evalRaw;
+        const overall = typeof evalObj.overall_final === "number" ? evalObj.overall_final : typeof evalObj.overall === "number" ? evalObj.overall : null;
+        if (overall === null || !Number.isFinite(overall)) {
+            return {
+                step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "judge" }),
+                reason: `judged:eval_missing_overall`,
+                inflight: { chapter: inflightChapter, pipeline_stage: stage },
+                evidence: { ...evidence }
+            };
+        }
+        const revisionCount = typeof checkpoint.revision_count === "number" && Number.isInteger(checkpoint.revision_count) && checkpoint.revision_count >= 0
+            ? checkpoint.revision_count
+            : 0;
+        const violation = detectHighConfidenceViolation(evalRaw);
+        const maxRevisions = typeof loadedProfile?.profile.scoring?.max_revisions === "number" &&
+            Number.isInteger(loadedProfile.profile.scoring.max_revisions) &&
+            loadedProfile.profile.scoring.max_revisions >= 0
+            ? loadedProfile.profile.scoring.max_revisions
+            : null;
+        const gateDecision = computeGateDecision({
+            overall_final: overall,
+            revision_count: revisionCount,
+            has_high_confidence_violation: violation.has_high_confidence_violation,
+            ...(maxRevisions === null ? {} : { max_revisions: maxRevisions })
+        });
+        const gateEvidence = {
+            ...evidence,
+            gate: {
+                decision: gateDecision,
+                overall_final: overall,
+                revision_count: revisionCount,
+                max_revisions: maxRevisions,
+                has_high_confidence_violation: violation.has_high_confidence_violation,
+                high_confidence_violations: violation.high_confidence_violations.slice(0, 10)
+            },
+            quality_judge: {
+                recommendation: typeof evalObj.recommendation === "string" ? evalObj.recommendation : null
+            }
         };
+        if (gateDecision === "pass") {
+            return {
+                step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "commit" }),
+                reason: "judged:gate:pass",
+                inflight: { chapter: inflightChapter, pipeline_stage: stage },
+                evidence: gateEvidence
+            };
+        }
+        if (gateDecision === "force_passed") {
+            return {
+                step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "commit" }),
+                reason: "judged:gate:force_passed",
+                inflight: { chapter: inflightChapter, pipeline_stage: stage },
+                evidence: gateEvidence
+            };
+        }
+        if (gateDecision === "polish") {
+            return {
+                step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "refine" }),
+                reason: "judged:gate:polish",
+                inflight: { chapter: inflightChapter, pipeline_stage: stage },
+                evidence: gateEvidence
+            };
+        }
+        if (gateDecision === "revise") {
+            return {
+                step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "draft" }),
+                reason: "judged:gate:revise",
+                inflight: { chapter: inflightChapter, pipeline_stage: stage },
+                evidence: gateEvidence
+            };
+        }
+        if (gateDecision === "pause_for_user" || gateDecision === "pause_for_user_force_rewrite") {
+            return {
+                step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "review" }),
+                reason: `judged:gate:${gateDecision}`,
+                inflight: { chapter: inflightChapter, pipeline_stage: stage },
+                evidence: gateEvidence
+            };
+        }
+        const _exhaustive = gateDecision;
+        throw new NovelCliError(`Unsupported gate decision: ${String(_exhaustive)}`, 2);
+    }
+    // Unknown stage: upstream parseCheckpoint validates enum so this should be unreachable.
+    throw new NovelCliError(`Checkpoint has unexpected pipeline_stage=${stage}. This should not happen; repair .checkpoint.json and rerun.`, 2);
+}
+function notImplementedState(state) {
+    throw new NovelCliError(`Not implemented: orchestrator_state=${state}`, 2);
+}
+export async function computeNextStep(projectRootDir, checkpoint) {
+    switch (checkpoint.orchestrator_state) {
+        case "WRITING":
+        case "CHAPTER_REWRITE":
+            return await computeChapterNextStep(projectRootDir, checkpoint);
+        case "ERROR_RETRY": {
+            const stage = normalizeStage(checkpoint.pipeline_stage);
+            const inflight = typeof checkpoint.inflight_chapter === "number" ? checkpoint.inflight_chapter : null;
+            let normalizedCheckpoint = checkpoint;
+            let healPrefix = "";
+            // Only auto-heal invariants when explicitly in ERROR_RETRY.
+            if ((stage === null || stage === "committed") && inflight !== null) {
+                normalizedCheckpoint = { ...checkpoint, inflight_chapter: null };
+                healPrefix = "healed_drop_inflight:";
+            }
+            else if (stage !== null && stage !== "committed" && inflight === null) {
+                normalizedCheckpoint = { ...checkpoint, inflight_chapter: checkpoint.last_completed_chapter + 1 };
+                healPrefix = "healed_infer_inflight:";
+            }
+            const next = await computeChapterNextStep(projectRootDir, normalizedCheckpoint);
+            return { ...next, reason: `error_retry:${healPrefix}${next.reason}` };
+        }
+        case "INIT":
+            return notImplementedState(checkpoint.orchestrator_state);
+        case "QUICK_START":
+            return notImplementedState(checkpoint.orchestrator_state);
+        case "VOL_PLANNING":
+            return await computeVolumeNextStep(projectRootDir, checkpoint);
+        case "VOL_REVIEW":
+            return await computeReviewNext(projectRootDir, checkpoint);
+        default:
+            return notImplementedState(checkpoint.orchestrator_state);
     }
-    // Unknown stage: fall back to safest.
-    return {
-        step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "draft" }),
-        reason: `unknown_stage:${stage}`,
-        inflight: { chapter: inflightChapter, pipeline_stage: stage },
-        evidence
-    };
 }

package/dist/platform-profile.js

@@ -122,6 +122,9 @@ function parseScoringPolicy(raw, file) {
         genre_drive_type: requireStringField(obj, "genre_drive_type", file),
         weight_profile_id: requireStringField(obj, "weight_profile_id", file)
     };
+    if (obj.max_revisions !== undefined) {
+        out.max_revisions = requireNonNegativeIntValue(obj.max_revisions, file, "scoring.max_revisions");
+    }
     if (obj.weight_overrides !== undefined) {
         if (!isPlainObject(obj.weight_overrides))
             throw new NovelCliError(`Invalid ${file}: 'scoring.weight_overrides' must be an object.`, 2);

package/dist/steps.js

@@ -1,5 +1,17 @@
 import { NovelCliError } from "./errors.js";
+export const ORCHESTRATOR_STATES = [
+    "INIT",
+    "QUICK_START",
+    "VOL_PLANNING",
+    "WRITING",
+    "CHAPTER_REWRITE",
+    "VOL_REVIEW",
+    "ERROR_RETRY"
+];
 export const CHAPTER_STAGES = ["draft", "summarize", "refine", "judge", "title-fix", "hook-fix", "review", "commit"];
+export const VOLUME_PHASES = ["outline", "validate", "commit"];
+export const QUICKSTART_PHASES = ["world", "characters", "style", "trial", "results"];
+export const REVIEW_PHASES = ["collect", "audit", "report", "cleanup", "transition"];
 export function pad3(n) {
     return String(n).padStart(3, "0");
 }
@@ -10,29 +22,60 @@ export function titleFixSnapshotRel(chapter) {
     return `staging/logs/title-fix-chapter-${pad3(chapter)}-before.md`;
 }
 export function formatStepId(step) {
-    if (step.kind !== "chapter")
-        throw new NovelCliError(`Unsupported step kind: ${step.kind}`, 2);
-    return `chapter:${pad3(step.chapter)}:${step.stage}`;
+    switch (step.kind) {
+        case "chapter":
+            return `chapter:${pad3(step.chapter)}:${step.stage}`;
+        case "volume":
+            return `volume:${step.phase}`;
+        case "quickstart":
+            return `quickstart:${step.phase}`;
+        case "review":
+            return `review:${step.phase}`;
+        default:
+            throw new NovelCliError(`Unsupported step kind: ${step.kind}`, 2);
+    }
 }
 export function parseStepId(input) {
     const trimmed = input.trim();
     const parts = trimmed.split(":");
-    if (parts.length !== 3) {
-        throw new NovelCliError(`Invalid step id: ${input}. Expected format: chapter:048:draft`, 2);
-    }
-    const [kind, chapterRaw, stageRaw] = parts;
-    if (kind !== "chapter")
-        throw new NovelCliError(`Invalid step id: ${input}. Only 'chapter' steps are supported.`, 2);
-    if (!/^\d+$/.test(chapterRaw))
-        throw new NovelCliError(`Invalid step id: ${input}. Chapter must be a number.`, 2);
-    const chapter = Number.parseInt(chapterRaw, 10);
-    if (!Number.isInteger(chapter) || chapter <= 0) {
-        throw new NovelCliError(`Invalid step id: ${input}. Chapter must be an int >= 1.`, 2);
+    if (parts.length === 3) {
+        const [kind, chapterRaw, stageRaw] = parts;
+        if (kind !== "chapter")
+            throw new NovelCliError(`Invalid step id: ${input}. Expected kind 'chapter'.`, 2);
+        if (!/^\d+$/.test(chapterRaw))
+            throw new NovelCliError(`Invalid step id: ${input}. Chapter must be a number.`, 2);
+        const chapter = Number.parseInt(chapterRaw, 10);
+        if (!Number.isInteger(chapter) || chapter <= 0) {
+            throw new NovelCliError(`Invalid step id: ${input}. Chapter must be an int >= 1.`, 2);
+        }
+        if (!CHAPTER_STAGES.includes(stageRaw)) {
+            throw new NovelCliError(`Invalid step id: ${input}. Stage must be one of: ${CHAPTER_STAGES.join(", ")}`, 2);
+        }
+        return { kind: "chapter", chapter, stage: stageRaw };
     }
-    if (!CHAPTER_STAGES.includes(stageRaw)) {
-        throw new NovelCliError(`Invalid step id: ${input}. Stage must be one of: ${CHAPTER_STAGES.join(", ")}`, 2);
+    if (parts.length === 2) {
+        const [kind, phaseRaw] = parts;
+        if (kind === "volume") {
+            if (!VOLUME_PHASES.includes(phaseRaw)) {
+                throw new NovelCliError(`Invalid step id: ${input}. Phase must be one of: ${VOLUME_PHASES.join(", ")}`, 2);
+            }
+            return { kind: "volume", phase: phaseRaw };
+        }
+        if (kind === "quickstart") {
+            if (!QUICKSTART_PHASES.includes(phaseRaw)) {
+                throw new NovelCliError(`Invalid step id: ${input}. Phase must be one of: ${QUICKSTART_PHASES.join(", ")}`, 2);
+            }
+            return { kind: "quickstart", phase: phaseRaw };
+        }
+        if (kind === "review") {
+            if (!REVIEW_PHASES.includes(phaseRaw)) {
+                throw new NovelCliError(`Invalid step id: ${input}. Phase must be one of: ${REVIEW_PHASES.join(", ")}`, 2);
+            }
+            return { kind: "review", phase: phaseRaw };
+        }
+        throw new NovelCliError(`Invalid step id: ${input}. Supported kinds: chapter, volume, quickstart, review.`, 2);
     }
-    return { kind: "chapter", chapter, stage: stageRaw };
+    throw new NovelCliError(`Invalid step id: ${input}. Expected format: chapter:048:draft (or quickstart:world).`, 2);
 }
 export function chapterRelPaths(chapter, storylineId) {
     const id = pad3(chapter);