novel-writer-cli 0.0.3 → 0.2.0

package/dist/next-step.js

@@ -1,12 +1,21 @@
+import { readdir } from "node:fs/promises";
 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 { QUICKSTART_STAGING_RELS } from "./quickstart.js";
+import { validateQuickstartRulesSchema, validateQuickstartStyleProfileSchema } from "./quickstart-validators.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 { QUICKSTART_PHASES, 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 +24,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 +68,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 +94,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 +125,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 +134,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 +145,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 +199,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 +233,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 +310,7 @@ export async function computeNextStep(projectRootDir, checkpoint) {
                 evidence
             };
         }
+        const loadedProfile = await loadPlatformProfile(projectRootDir);
         if (!hasEval) {
             const titleGate = await checkTitlePolicyForStage({
                 projectRootDir,
@@ -290,7 +320,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 +340,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 +352,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 +363,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 +392,7 @@ export async function computeNextStep(projectRootDir, checkpoint) {
                 evidence
             };
         }
+        const loadedProfile = await loadPlatformProfile(projectRootDir);
         const titleGate = await checkTitlePolicyForStage({
             projectRootDir,
             stagePrefix: "judged",
@@ -366,7 +401,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 +413,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 +424,372 @@ 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: fall back to safest.
-    return {
-        step: formatStepId({ kind: "chapter", chapter: inflightChapter, stage: "draft" }),
-        reason: `unknown_stage:${stage}`,
-        inflight: { chapter: inflightChapter, pipeline_stage: stage },
-        evidence
+    // 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);
+}
+async function countContractArtifacts(rootDir) {
+    const absDir = join(rootDir, QUICKSTART_STAGING_RELS.contractsDir);
+    const hasDir = await pathExists(absDir);
+    if (!hasDir)
+        return { hasDir, fileCount: 0, sample: [], degraded: false };
+    try {
+        const entries = await readdir(absDir, { withFileTypes: true });
+        const files = entries.filter((e) => e.isFile()).map((e) => e.name);
+        const sample = files
+            .filter((n) => n.endsWith(".json"))
+            .sort()
+            .slice(0, 3);
+        const fileCount = files.filter((n) => n.endsWith(".json")).length;
+        return { hasDir, fileCount, sample, degraded: false };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // If the dir exists but is unreadable, treat as present but degraded.
+        return { hasDir, fileCount: 0, sample: [], degraded: true, error: message };
+    }
+}
+async function computeQuickStartNextStep(projectRootDir, checkpoint) {
+    const stage = normalizeStage(checkpoint.pipeline_stage);
+    const inflight = typeof checkpoint.inflight_chapter === "number" ? checkpoint.inflight_chapter : null;
+    if ((stage === null || stage === "committed") && inflight !== null) {
+        throw new NovelCliError(`Checkpoint inconsistent for QUICK_START: pipeline_stage=${stage ?? "null"} but inflight_chapter=${inflight}. Set inflight_chapter to null.`, 2);
+    }
+    if (stage !== null && stage !== "committed") {
+        throw new NovelCliError(`Checkpoint inconsistent for QUICK_START: pipeline_stage=${stage} (expected null or committed). Finish the chapter pipeline or repair .checkpoint.json.`, 2);
+    }
+    const rulesAbs = join(projectRootDir, QUICKSTART_STAGING_RELS.rulesJson);
+    const styleAbs = join(projectRootDir, QUICKSTART_STAGING_RELS.styleProfileJson);
+    const trialAbs = join(projectRootDir, QUICKSTART_STAGING_RELS.trialChapterMd);
+    const evalAbs = join(projectRootDir, QUICKSTART_STAGING_RELS.evaluationJson);
+    const rulesExists = await pathExists(rulesAbs);
+    const contracts = await countContractArtifacts(projectRootDir);
+    const styleExists = await pathExists(styleAbs);
+    const trialExists = await pathExists(trialAbs);
+    const evalExists = await pathExists(evalAbs);
+    let rulesOk = false;
+    let rulesError = null;
+    if (rulesExists) {
+        try {
+            await validateQuickstartRulesSchema(rulesAbs, { trimRequiredStrings: true });
+            rulesOk = true;
+        }
+        catch (err) {
+            rulesError = err instanceof Error ? err.message : String(err);
+            rulesOk = false;
+        }
+    }
+    let styleOk = false;
+    let styleError = null;
+    if (styleExists) {
+        try {
+            await validateQuickstartStyleProfileSchema(styleAbs);
+            styleOk = true;
+        }
+        catch (err) {
+            styleError = err instanceof Error ? err.message : String(err);
+            styleOk = false;
+        }
+    }
+    let trialOk = false;
+    let trialError = null;
+    if (trialExists) {
+        try {
+            const text = await readTextFile(trialAbs);
+            if (text.trim().length === 0)
+                throw new Error("empty trial chapter");
+            trialOk = true;
+        }
+        catch (err) {
+            trialError = err instanceof Error ? err.message : String(err);
+            trialOk = false;
+        }
+    }
+    let evalOk = false;
+    let evalError = null;
+    if (evalExists) {
+        try {
+            const raw = await readJsonFile(evalAbs);
+            if (!isPlainObject(raw))
+                throw new Error("expected JSON object");
+            evalOk = true;
+        }
+        catch (err) {
+            evalError = err instanceof Error ? err.message : String(err);
+            evalOk = false;
+        }
+    }
+    const evidence = {
+        checkpoint: {
+            quickstart_phase: (checkpoint.quickstart_phase ?? null)
+        },
+        staging: {
+            rulesExists,
+            rulesOk,
+            ...(rulesError ? { rulesError } : {}),
+            contracts: {
+                hasDir: contracts.hasDir,
+                jsonFileCount: contracts.fileCount,
+                sample: contracts.sample,
+                degraded: contracts.degraded,
+                ...(contracts.error ? { error: contracts.error } : {})
+            },
+            styleExists,
+            styleOk,
+            ...(styleError ? { styleError } : {}),
+            trialExists,
+            trialOk,
+            ...(trialError ? { trialError } : {}),
+            evalExists,
+            evalOk,
+            ...(evalError ? { evalError } : {})
+        }
     };
+    let selected;
+    let selectedPhase;
+    if (!rulesOk) {
+        selectedPhase = "world";
+        selected = {
+            step: formatStepId({ kind: "quickstart", phase: "world" }),
+            reason: "quickstart:world",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence
+        };
+    }
+    else if (!contracts.hasDir || contracts.fileCount === 0) {
+        selectedPhase = "characters";
+        selected = {
+            step: formatStepId({ kind: "quickstart", phase: "characters" }),
+            reason: "quickstart:characters",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence
+        };
+    }
+    else if (!styleOk) {
+        selectedPhase = "style";
+        selected = {
+            step: formatStepId({ kind: "quickstart", phase: "style" }),
+            reason: "quickstart:style",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence
+        };
+    }
+    else if (!trialOk) {
+        selectedPhase = "trial";
+        selected = {
+            step: formatStepId({ kind: "quickstart", phase: "trial" }),
+            reason: "quickstart:trial",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence
+        };
+    }
+    else if (!evalOk) {
+        selectedPhase = "results";
+        selected = {
+            step: formatStepId({ kind: "quickstart", phase: "results" }),
+            reason: "quickstart:results",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence
+        };
+    }
+    else {
+        selectedPhase = "results";
+        selected = {
+            step: formatStepId({ kind: "quickstart", phase: "results" }),
+            reason: "quickstart:results:artifacts_present",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence
+        };
+    }
+    const selectedPhaseIdx = QUICKSTART_PHASES.indexOf(selectedPhase);
+    if (selectedPhaseIdx < 0) {
+        throw new NovelCliError(`Internal error: invalid quickstart phase=${selectedPhase}`, 2);
+    }
+    const checkpointPhase = checkpoint.quickstart_phase ?? null;
+    if (checkpointPhase) {
+        const checkpointIdx = QUICKSTART_PHASES.indexOf(checkpointPhase);
+        if (checkpointIdx >= 0 && selectedPhaseIdx < checkpointIdx) {
+            const expectedPath = (() => {
+                switch (selectedPhase) {
+                    case "world":
+                        return QUICKSTART_STAGING_RELS.rulesJson;
+                    case "characters":
+                        return QUICKSTART_STAGING_RELS.contractsDir;
+                    case "style":
+                        return QUICKSTART_STAGING_RELS.styleProfileJson;
+                    case "trial":
+                        return QUICKSTART_STAGING_RELS.trialChapterMd;
+                    case "results":
+                        return QUICKSTART_STAGING_RELS.evaluationJson;
+                    default: {
+                        const _exhaustive = selectedPhase;
+                        return String(_exhaustive);
+                    }
+                }
+            })();
+            return {
+                ...selected,
+                reason: `quickstart:recovery_blocked:${checkpointPhase}`,
+                evidence: {
+                    ...evidence,
+                    recovery_blocked: {
+                        checkpoint_phase: checkpointPhase,
+                        checkpoint_phase_idx: checkpointIdx,
+                        inferred_phase: selectedPhase,
+                        inferred_phase_idx: selectedPhaseIdx,
+                        inferred_reason: selected.reason,
+                        expected_path: expectedPath
+                    }
+                }
+            };
+        }
+    }
+    return selected;
+}
+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": {
+            const next = await computeQuickStartNextStep(projectRootDir, checkpoint);
+            return { ...next, reason: `init:${next.reason}` };
+        }
+        case "QUICK_START":
+            return await computeQuickStartNextStep(projectRootDir, checkpoint);
+        case "VOL_PLANNING":
+            return await computeVolumeNextStep(projectRootDir, checkpoint);
+        case "VOL_REVIEW":
+            return await computeReviewNext(projectRootDir, checkpoint);
+        default:
+            return notImplementedState(checkpoint.orchestrator_state);
+    }
 }

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/quickstart-validators.js

@@ -0,0 +1,84 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { NovelCliError } from "./errors.js";
+import { readJsonFile, readTextFile } from "./fs-utils.js";
+import { QUICKSTART_STAGING_RELS } from "./quickstart.js";
+import { isPlainObject } from "./type-guards.js";
+function requireStringField(obj, field, file, opts) {
+    const v = obj[field];
+    if (typeof v !== "string" || (opts?.trim ? v.trim().length === 0 : v.length === 0)) {
+        throw new NovelCliError(`Invalid ${file}: missing string field '${field}'.`, 2);
+    }
+    return v;
+}
+export async function validateQuickstartRulesSchema(absPath, options) {
+    const raw = await readJsonFile(absPath);
+    if (!isPlainObject(raw))
+        throw new NovelCliError(`Invalid ${QUICKSTART_STAGING_RELS.rulesJson}: expected JSON object.`, 2);
+    const obj = raw;
+    const rules = obj.rules;
+    if (!Array.isArray(rules))
+        throw new NovelCliError(`Invalid ${QUICKSTART_STAGING_RELS.rulesJson}: missing 'rules' array.`, 2);
+    const trimRequiredStrings = options?.trimRequiredStrings === true;
+    for (const [idx, rule] of rules.entries()) {
+        if (!isPlainObject(rule))
+            throw new NovelCliError(`Invalid ${QUICKSTART_STAGING_RELS.rulesJson}: rules[${idx}] must be an object.`, 2);
+        const r = rule;
+        requireStringField(r, "id", QUICKSTART_STAGING_RELS.rulesJson, { trim: trimRequiredStrings });
+        requireStringField(r, "category", QUICKSTART_STAGING_RELS.rulesJson, { trim: trimRequiredStrings });
+        requireStringField(r, "rule", QUICKSTART_STAGING_RELS.rulesJson, { trim: trimRequiredStrings });
+        const ct = requireStringField(r, "constraint_type", QUICKSTART_STAGING_RELS.rulesJson, { trim: false });
+        if (ct !== "hard" && ct !== "soft") {
+            throw new NovelCliError(`Invalid ${QUICKSTART_STAGING_RELS.rulesJson}: rules[${idx}].constraint_type must be hard|soft.`, 2);
+        }
+        if (!Array.isArray(r.exceptions)) {
+            throw new NovelCliError(`Invalid ${QUICKSTART_STAGING_RELS.rulesJson}: rules[${idx}].exceptions must be an array.`, 2);
+        }
+    }
+    return rules.length;
+}
+export async function listQuickstartContractJsonFiles(absContractsDir) {
+    const entries = await readdir(absContractsDir, { withFileTypes: true });
+    const jsonFiles = entries
+        .filter((e) => e.isFile() && e.name.endsWith(".json"))
+        .map((e) => e.name)
+        .sort();
+    if (jsonFiles.length === 0) {
+        throw new NovelCliError(`Invalid ${QUICKSTART_STAGING_RELS.contractsDir}: expected at least 1 *.json contract file.`, 2);
+    }
+    return jsonFiles;
+}
+export async function validateQuickstartContractJsonFiles(absContractsDir, jsonFiles) {
+    for (const file of jsonFiles) {
+        const raw = await readJsonFile(join(absContractsDir, file));
+        if (!isPlainObject(raw)) {
+            throw new NovelCliError(`Invalid contract JSON: ${QUICKSTART_STAGING_RELS.contractsDir}/${file} must be an object.`, 2);
+        }
+    }
+}
+export async function validateQuickstartContractsDir(absContractsDir) {
+    const jsonFiles = await listQuickstartContractJsonFiles(absContractsDir);
+    await validateQuickstartContractJsonFiles(absContractsDir, jsonFiles);
+}
+export async function validateQuickstartStyleProfileSchema(absPath) {
+    const raw = await readJsonFile(absPath);
+    if (!isPlainObject(raw))
+        throw new NovelCliError(`Invalid ${QUICKSTART_STAGING_RELS.styleProfileJson}: expected JSON object.`, 2);
+    const obj = raw;
+    const sourceType = obj.source_type;
+    if (typeof sourceType !== "string" || sourceType.trim().length === 0) {
+        throw new NovelCliError(`Invalid ${QUICKSTART_STAGING_RELS.styleProfileJson}: source_type must be a non-empty string.`, 2);
+    }
+    if (sourceType !== "original" && sourceType !== "reference" && sourceType !== "template" && sourceType !== "write_then_extract") {
+        throw new NovelCliError(`Invalid ${QUICKSTART_STAGING_RELS.styleProfileJson}: source_type must be one of: original, reference, template, write_then_extract.`, 2);
+    }
+}
+export async function validateQuickstartTrialChapter(absPath) {
+    const text = await readTextFile(absPath);
+    if (text.trim().length === 0)
+        throw new NovelCliError(`Empty draft file: ${QUICKSTART_STAGING_RELS.trialChapterMd}`, 2);
+    if (!text.trimStart().startsWith("#")) {
+        return `Trial chapter does not start with a Markdown H1 (# ...): ${QUICKSTART_STAGING_RELS.trialChapterMd}`;
+    }
+    return null;
+}