novel-writer-cli 0.3.0 → 0.5.0

package/dist/validate.js

@@ -1,5 +1,7 @@
+import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { NovelCliError } from "./errors.js";
+import { normalizeExcitementType } from "./excitement-type.js";
 import { pathExists, readJsonFile, readTextFile } from "./fs-utils.js";
 import { checkHookPolicy } from "./hook-policy.js";
 import { loadPlatformProfile } from "./platform-profile.js";
@@ -9,7 +11,7 @@ import { QUICKSTART_PHASES, chapterRelPaths, formatStepId, titleFixSnapshotRel }
 import { assertTitleFixOnlyChangedTitleLine, extractChapterTitleFromMarkdown } from "./title-policy.js";
 import { isPlainObject } from "./type-guards.js";
 import { VOL_REVIEW_RELS } from "./volume-review.js";
-import { computeVolumeChapterRange, volumeFinalRelPaths, volumeForChapter, volumeStagingRelPaths } from "./volume-planning.js";
+import { hasQuickstartMiniPlanningArtifacts, QUICKSTART_MINI_PLANNING_RANGE, resolveVolumeChapterRange, volumeFinalRelPaths, volumeForChapter, volumeStagingRelPaths } from "./volume-planning.js";
 import { validateQuickstartContractsDir, validateQuickstartRulesSchema, validateQuickstartStyleProfileSchema, validateQuickstartTrialChapter } from "./quickstart-validators.js";
 function requireFile(exists, relPath) {
     if (!exists)
@@ -27,6 +29,265 @@ function requireNumberField(obj, field, file) {
         throw new NovelCliError(`Invalid ${file}: missing number field '${field}'.`, 2);
     return v;
 }
+function assertOutlineHasNoOutOfRangeChapters(args) {
+    const extras = Array.from(args.seen)
+        .filter((chapter) => chapter < args.range.start || chapter > args.range.end)
+        .sort((left, right) => left - right);
+    if (extras.length === 0)
+        return;
+    throw new NovelCliError(`Invalid outline: unexpected chapter block(s) ${extras.join(", ")} outside required range (${args.range.start}-${args.range.end}). File: ${args.relPath}`, 2);
+}
+async function assertContractDirMatchesRange(args) {
+    requireFile(await pathExists(join(args.rootDir, args.rels.chapterContractsDir)), args.rels.chapterContractsDir);
+    const entries = await readdir(join(args.rootDir, args.rels.chapterContractsDir), { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const match = /^chapter-(\d+)\.json$/u.exec(entry.name);
+        if (!match) {
+            throw new NovelCliError(`Invalid ${args.rels.chapterContractsDir}: unexpected filename '${entry.name}'.`, 2);
+        }
+        const chapter = Number.parseInt(match[1] ?? "", 10);
+        if (chapter < args.range.start || chapter > args.range.end) {
+            throw new NovelCliError(`Invalid ${args.rels.chapterContractsDir}: unexpected contract chapter ${chapter} outside required range (${args.range.start}-${args.range.end}).`, 2);
+        }
+    }
+}
+async function requireCommittedQuickstartMiniPlanning(rootDir) {
+    if (await hasQuickstartMiniPlanningArtifacts(rootDir))
+        return;
+    throw new NovelCliError(`Missing committed quickstart mini-planning artifacts required before trial/results: ${volumeFinalRelPaths(1).outlineMd}`, 2);
+}
+async function validateVolumePlanArtifacts(args) {
+    const { rootDir, volume, range, rels, warnings } = args;
+    const requireVolumePlanArtifacts = async () => {
+        requireFile(await pathExists(join(rootDir, rels.outlineMd)), rels.outlineMd);
+        requireFile(await pathExists(join(rootDir, rels.storylineScheduleJson)), rels.storylineScheduleJson);
+        requireFile(await pathExists(join(rootDir, rels.foreshadowingJson)), rels.foreshadowingJson);
+        requireFile(await pathExists(join(rootDir, rels.newCharactersJson)), rels.newCharactersJson);
+        requireFile(await pathExists(join(rootDir, rels.chapterContractsDir)), rels.chapterContractsDir);
+        for (let ch = range.start; ch <= range.end; ch++) {
+            requireFile(await pathExists(join(rootDir, rels.chapterContractJson(ch))), rels.chapterContractJson(ch));
+        }
+    };
+    const outlineAbs = join(rootDir, rels.outlineMd);
+    const parseOutlineChapterMetadata = async () => {
+        const text = await readTextFile(outlineAbs);
+        if (text.trim().length === 0)
+            throw new NovelCliError(`Empty outline file: ${rels.outlineMd}`, 2);
+        const lines = text.split(/\r?\n/u);
+        const chapterRe = /^###\s*第\s*(\d+)\s*章/u;
+        const chapters = [];
+        for (let i = 0; i < lines.length; i++) {
+            const m = chapterRe.exec(lines[i] ?? "");
+            if (!m)
+                continue;
+            const chapter = Number.parseInt(m[1] ?? "", 10);
+            if (!Number.isInteger(chapter) || chapter <= 0)
+                continue;
+            chapters.push({ chapter, startLine: i, endLine: lines.length });
+        }
+        if (chapters.length === 0) {
+            throw new NovelCliError(`Invalid outline: could not parse any chapter headings. Expected lines like "### 第 1 章" (spaces are flexible). File: ${rels.outlineMd}`, 2);
+        }
+        const seen = new Set();
+        for (let i = 0; i < chapters.length; i++) {
+            const c = chapters[i];
+            const next = chapters[i + 1];
+            if (seen.has(c.chapter))
+                throw new NovelCliError(`Invalid outline: duplicate chapter block for chapter ${c.chapter} (${rels.outlineMd}).`, 2);
+            seen.add(c.chapter);
+            c.endLine = next ? next.startLine : lines.length;
+        }
+        for (let ch = range.start; ch <= range.end; ch++) {
+            if (!seen.has(ch)) {
+                throw new NovelCliError(`Invalid outline: missing chapter block for chapter ${ch} (expected continuous coverage ${range.start}-${range.end}). File: ${rels.outlineMd}`, 2);
+            }
+        }
+        assertOutlineHasNoOutOfRangeChapters({ seen, relPath: rels.outlineMd, range });
+        const requiredKeys = [
+            "Storyline",
+            "POV",
+            "Location",
+            "Conflict",
+            "Arc",
+            "Foreshadowing",
+            "StateChanges",
+            "TransitionHint"
+        ];
+        const excitementPrefix = "- **ExcitementType**:";
+        const chapterMetadata = new Map();
+        for (const c of chapters) {
+            if (c.chapter < range.start || c.chapter > range.end)
+                continue;
+            const blockLines = lines.slice(c.startLine, c.endLine);
+            const keyFound = new Set();
+            let storylineId = null;
+            let excitementType = null;
+            for (const line of blockLines) {
+                for (const key of requiredKeys) {
+                    const prefix = `- **${key}**:`;
+                    if (line.startsWith(prefix)) {
+                        keyFound.add(key);
+                        if (key === "Storyline") {
+                            const value = line.slice(prefix.length).trim();
+                            if (value.length > 0)
+                                storylineId = value;
+                        }
+                    }
+                }
+                if (line.startsWith(excitementPrefix)) {
+                    const rawExcitementType = line.slice(excitementPrefix.length).trim();
+                    const normalizedExcitementType = normalizeExcitementType(rawExcitementType);
+                    if (normalizedExcitementType === undefined) {
+                        warnings.push(`Outline chapter ${c.chapter} has unknown ExcitementType '${rawExcitementType}' in ${rels.outlineMd}; treating as null.`);
+                    }
+                    else {
+                        excitementType = normalizedExcitementType;
+                    }
+                }
+            }
+            for (const key of requiredKeys) {
+                if (!keyFound.has(key)) {
+                    throw new NovelCliError(`Invalid outline: chapter ${c.chapter} block missing required key '${key}' line. File: ${rels.outlineMd}`, 2);
+                }
+            }
+            if (!storylineId) {
+                throw new NovelCliError(`Invalid outline: chapter ${c.chapter} missing non-empty Storyline value. File: ${rels.outlineMd}`, 2);
+            }
+            chapterMetadata.set(c.chapter, { storylineId, excitementType });
+        }
+        return chapterMetadata;
+    };
+    const validateNewCharacters = (raw) => {
+        if (!Array.isArray(raw))
+            throw new NovelCliError(`Invalid ${rels.newCharactersJson}: expected an array.`, 2);
+        for (const [idx, item] of raw.entries()) {
+            if (!isPlainObject(item))
+                throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} must be an object.`, 2);
+            const obj = item;
+            const name = typeof obj.name === "string" ? obj.name.trim() : "";
+            const role = typeof obj.role === "string" ? obj.role.trim() : "";
+            const brief = typeof obj.brief === "string" ? obj.brief.trim() : "";
+            const firstChapter = typeof obj.first_chapter === "number" && Number.isInteger(obj.first_chapter) ? obj.first_chapter : null;
+            if (name.length === 0)
+                throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} missing name.`, 2);
+            if (brief.length === 0)
+                throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} missing brief.`, 2);
+            if (firstChapter === null || firstChapter < range.start || firstChapter > range.end) {
+                throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} first_chapter=${String(obj.first_chapter)} out of range (${range.start}-${range.end}).`, 2);
+            }
+            if (role !== "antagonist" && role !== "supporting" && role !== "minor") {
+                throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} role must be one of: antagonist, supporting, minor.`, 2);
+            }
+        }
+    };
+    const validateSchedule = (raw, chapterMetadata) => {
+        if (!isPlainObject(raw))
+            throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: must be an object.`, 2);
+        const obj = raw;
+        const active = obj.active_storylines;
+        if (!Array.isArray(active))
+            throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: missing active_storylines array.`, 2);
+        const activeIds = [];
+        for (const [idx, value] of active.entries()) {
+            if (typeof value !== "string") {
+                warnings.push(`WARN ${rels.storylineScheduleJson}: active_storylines[${idx}] is not a string; ignoring.`);
+                continue;
+            }
+            const id = value.trim();
+            if (id.length > 0)
+                activeIds.push(id);
+        }
+        if (activeIds.length === 0)
+            throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: active_storylines must be non-empty.`, 2);
+        if (activeIds.length > 4)
+            throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: active_storylines length must be <= 4.`, 2);
+        const activeSet = new Set(activeIds);
+        for (const [chapter, metadata] of chapterMetadata.entries()) {
+            if (!activeSet.has(metadata.storylineId)) {
+                throw new NovelCliError(`Invalid volume plan: outline chapter ${chapter} Storyline=${metadata.storylineId} not in storyline-schedule.json.active_storylines.`, 2);
+            }
+        }
+    };
+    const validateForeshadowingPlan = (raw) => {
+        if (!isPlainObject(raw)) {
+            throw new NovelCliError(`Invalid ${rels.foreshadowingJson}: expected JSON object with {schema_version, items}.`, 2);
+        }
+        const obj = raw;
+        if (obj.schema_version !== 1)
+            warnings.push(`Unexpected schema_version in ${rels.foreshadowingJson}.`);
+        if (!Array.isArray(obj.items))
+            throw new NovelCliError(`Invalid ${rels.foreshadowingJson}: items must be an array.`, 2);
+    };
+    const validateContracts = async (chapterMetadata) => {
+        await assertContractDirMatchesRange({ rootDir, rels, range });
+        for (let ch = range.start; ch <= range.end; ch++) {
+            const rel = rels.chapterContractJson(ch);
+            const raw = await readJsonFile(join(rootDir, rel));
+            if (!isPlainObject(raw))
+                throw new NovelCliError(`Invalid ${rel}: must be an object.`, 2);
+            const obj = raw;
+            const chapter = requireNumberField(obj, "chapter", rel);
+            if (!Number.isInteger(chapter) || chapter !== ch)
+                throw new NovelCliError(`Invalid ${rel}: chapter=${chapter} expected ${ch}.`, 2);
+            const storylineId = requireStringField(obj, "storyline_id", rel).trim();
+            const expectedStorylineId = chapterMetadata.get(ch)?.storylineId ?? null;
+            if (!expectedStorylineId || storylineId !== expectedStorylineId) {
+                throw new NovelCliError(`Invalid ${rel}: storyline_id=${storylineId} expected ${expectedStorylineId ?? "(missing in outline)"}.`, 2);
+            }
+            if (!Object.prototype.hasOwnProperty.call(obj, "excitement_type")) {
+                warnings.push(`Missing optional excitement_type in ${rel}; treating as null.`);
+            }
+            else {
+                const normalizedExcitementType = normalizeExcitementType(obj.excitement_type);
+                if (normalizedExcitementType === undefined) {
+                    warnings.push(`Unknown excitement_type '${String(obj.excitement_type)}' in ${rel}; treating as null.`);
+                }
+            }
+            const objectivesRaw = obj.objectives;
+            if (!Array.isArray(objectivesRaw))
+                throw new NovelCliError(`Invalid ${rel}: objectives must be an array.`, 2);
+            const hasRequired = objectivesRaw.some((it) => isPlainObject(it) && it.required === true);
+            if (!hasRequired)
+                throw new NovelCliError(`Invalid ${rel}: objectives must include at least one entry with required=true.`, 2);
+            const prevChapter = ch - 1;
+            if (prevChapter >= 1) {
+                const prevRel = prevChapter >= range.start
+                    ? rels.chapterContractJson(prevChapter)
+                    : volumeFinalRelPaths(volumeForChapter(prevChapter)).chapterContractJson(prevChapter);
+                if (await pathExists(join(rootDir, prevRel))) {
+                    const prevRaw = await readJsonFile(join(rootDir, prevRel));
+                    if (isPlainObject(prevRaw)) {
+                        const prevObj = prevRaw;
+                        const post = isPlainObject(prevObj.postconditions) ? prevObj.postconditions : null;
+                        const stateChanges = post && isPlainObject(post.state_changes) ? post.state_changes : null;
+                        const pre = isPlainObject(obj.preconditions) ? obj.preconditions : null;
+                        const characterStates = pre && isPlainObject(pre.character_states) ? pre.character_states : null;
+                        if (stateChanges && Object.keys(stateChanges).length > 0) {
+                            if (!characterStates) {
+                                throw new NovelCliError(`Invalid ${rel}: missing preconditions.character_states required by chain propagation from ${prevRel}.`, 2);
+                            }
+                            for (const characterKey of Object.keys(stateChanges)) {
+                                if (!(characterKey in characterStates)) {
+                                    throw new NovelCliError(`Invalid ${rel}: preconditions.character_states missing '${characterKey}' (required by ${prevRel}.postconditions.state_changes).`, 2);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    };
+    await requireVolumePlanArtifacts();
+    const chapterMetadata = await parseOutlineChapterMetadata();
+    validateSchedule(await readJsonFile(join(rootDir, rels.storylineScheduleJson)), chapterMetadata);
+    validateForeshadowingPlan(await readJsonFile(join(rootDir, rels.foreshadowingJson)));
+    validateNewCharacters(await readJsonFile(join(rootDir, rels.newCharactersJson)));
+    await validateContracts(chapterMetadata);
+}
 export async function validateStep(args) {
     const warnings = [];
     const stepId = formatStepId(args.step);
@@ -84,222 +345,17 @@ export async function validateStep(args) {
     }
     if (args.step.kind === "volume") {
         const volume = args.checkpoint.current_volume;
-        const range = computeVolumeChapterRange({ current_volume: volume, last_completed_chapter: args.checkpoint.last_completed_chapter });
-        const rels = volumeStagingRelPaths(volume);
-        const requireVolumePlanArtifacts = async () => {
-            requireFile(await pathExists(join(args.rootDir, rels.outlineMd)), rels.outlineMd);
-            requireFile(await pathExists(join(args.rootDir, rels.storylineScheduleJson)), rels.storylineScheduleJson);
-            requireFile(await pathExists(join(args.rootDir, rels.foreshadowingJson)), rels.foreshadowingJson);
-            requireFile(await pathExists(join(args.rootDir, rels.newCharactersJson)), rels.newCharactersJson);
-            for (let ch = range.start; ch <= range.end; ch++) {
-                requireFile(await pathExists(join(args.rootDir, rels.chapterContractJson(ch))), rels.chapterContractJson(ch));
-            }
-        };
-        const outlineAbs = join(args.rootDir, rels.outlineMd);
-        const parseOutlineStorylineIds = async () => {
-            const text = await readTextFile(outlineAbs);
-            if (text.trim().length === 0)
-                throw new NovelCliError(`Empty outline file: ${rels.outlineMd}`, 2);
-            const lines = text.split(/\r?\n/u);
-            const chapters = [];
-            const chapterHeadingRe = /^###\s*第\s*(\d+)\s*章/u;
-            for (let i = 0; i < lines.length; i++) {
-                const m = chapterHeadingRe.exec(lines[i] ?? "");
-                if (!m)
-                    continue;
-                const chapter = Number.parseInt(m[1] ?? "", 10);
-                if (!Number.isInteger(chapter) || chapter < 1)
-                    continue;
-                chapters.push({ chapter, startLine: i, endLine: lines.length });
-            }
-            if (chapters.length === 0) {
-                throw new NovelCliError(`Invalid outline: could not parse any chapter headings. Expected lines like "### 第 1 章" (spaces are flexible). File: ${rels.outlineMd}`, 2);
-            }
-            for (let i = 0; i < chapters.length; i++) {
-                const cur = chapters[i];
-                const next = chapters[i + 1];
-                if (next)
-                    cur.endLine = next.startLine;
-            }
-            const seen = new Set();
-            for (const c of chapters) {
-                if (seen.has(c.chapter))
-                    throw new NovelCliError(`Invalid outline: duplicate chapter block for chapter ${c.chapter} (${rels.outlineMd}).`, 2);
-                seen.add(c.chapter);
-            }
-            for (let ch = range.start; ch <= range.end; ch++) {
-                if (!seen.has(ch)) {
-                    throw new NovelCliError(`Invalid outline: missing chapter block for chapter ${ch} (expected continuous coverage ${range.start}-${range.end}). File: ${rels.outlineMd}`, 2);
-                }
-            }
-            const requiredKeys = [
-                "Storyline",
-                "POV",
-                "Location",
-                "Conflict",
-                "Arc",
-                "Foreshadowing",
-                "StateChanges",
-                "TransitionHint"
-            ];
-            const storylinesByChapter = new Map();
-            for (const c of chapters) {
-                if (c.chapter < range.start || c.chapter > range.end)
-                    continue;
-                const blockLines = lines.slice(c.startLine, c.endLine);
-                const keyFound = new Set();
-                let storylineId = null;
-                for (const line of blockLines) {
-                    for (const k of requiredKeys) {
-                        const prefix = `- **${k}**:`;
-                        if (line.startsWith(prefix)) {
-                            keyFound.add(k);
-                            if (k === "Storyline") {
-                                const val = line.slice(prefix.length).trim();
-                                if (val.length > 0)
-                                    storylineId = val;
-                            }
-                        }
-                    }
-                }
-                for (const k of requiredKeys) {
-                    if (!keyFound.has(k)) {
-                        throw new NovelCliError(`Invalid outline: chapter ${c.chapter} block missing required key '${k}' line. File: ${rels.outlineMd}`, 2);
-                    }
-                }
-                if (!storylineId) {
-                    throw new NovelCliError(`Invalid outline: chapter ${c.chapter} missing non-empty Storyline value. File: ${rels.outlineMd}`, 2);
-                }
-                storylinesByChapter.set(c.chapter, storylineId);
-            }
-            return storylinesByChapter;
-        };
-        const validateNewCharacters = (raw) => {
-            if (!Array.isArray(raw))
-                throw new NovelCliError(`Invalid ${rels.newCharactersJson}: expected an array.`, 2);
-            for (const [idx, item] of raw.entries()) {
-                if (!isPlainObject(item))
-                    throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} must be an object.`, 2);
-                const obj = item;
-                const name = typeof obj.name === "string" ? obj.name.trim() : "";
-                const role = typeof obj.role === "string" ? obj.role.trim() : "";
-                const brief = typeof obj.brief === "string" ? obj.brief.trim() : "";
-                const firstChapter = typeof obj.first_chapter === "number" && Number.isInteger(obj.first_chapter) ? obj.first_chapter : null;
-                if (name.length === 0)
-                    throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} missing name.`, 2);
-                if (brief.length === 0)
-                    throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} missing brief.`, 2);
-                if (firstChapter === null || firstChapter < range.start || firstChapter > range.end) {
-                    throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} first_chapter=${String(obj.first_chapter)} out of range (${range.start}-${range.end}).`, 2);
-                }
-                if (role !== "antagonist" && role !== "supporting" && role !== "minor") {
-                    throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} role must be one of: antagonist, supporting, minor.`, 2);
-                }
-            }
-        };
-        const validateSchedule = (raw, storylinesByChapter) => {
-            if (!isPlainObject(raw))
-                throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: must be an object.`, 2);
-            const obj = raw;
-            const active = obj.active_storylines;
-            if (!Array.isArray(active))
-                throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: missing active_storylines array.`, 2);
-            const activeIds = [];
-            for (const [idx, v] of active.entries()) {
-                if (typeof v !== "string") {
-                    warnings.push(`WARN ${rels.storylineScheduleJson}: active_storylines[${idx}] is not a string; ignoring.`);
-                    continue;
-                }
-                const id = v.trim();
-                if (id.length > 0)
-                    activeIds.push(id);
-            }
-            if (activeIds.length === 0)
-                throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: active_storylines must be non-empty.`, 2);
-            if (activeIds.length > 4)
-                throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: active_storylines length must be <= 4.`, 2);
-            const activeSet = new Set(activeIds);
-            for (const [ch, storylineId] of storylinesByChapter.entries()) {
-                if (!activeSet.has(storylineId)) {
-                    throw new NovelCliError(`Invalid volume plan: outline chapter ${ch} Storyline=${storylineId} not in storyline-schedule.json.active_storylines.`, 2);
-                }
-            }
-        };
-        const validateForeshadowingPlan = (raw) => {
-            if (!isPlainObject(raw)) {
-                throw new NovelCliError(`Invalid ${rels.foreshadowingJson}: expected JSON object with {schema_version, items}.`, 2);
-            }
-            const obj = raw;
-            const schema = obj.schema_version;
-            if (schema !== 1)
-                warnings.push(`Unexpected schema_version in ${rels.foreshadowingJson}.`);
-            const items = obj.items;
-            if (!Array.isArray(items))
-                throw new NovelCliError(`Invalid ${rels.foreshadowingJson}: items must be an array.`, 2);
-        };
-        const validateContracts = async (storylinesByChapter) => {
-            for (let ch = range.start; ch <= range.end; ch++) {
-                const rel = rels.chapterContractJson(ch);
-                const raw = await readJsonFile(join(args.rootDir, rel));
-                if (!isPlainObject(raw))
-                    throw new NovelCliError(`Invalid ${rel}: must be an object.`, 2);
-                const obj = raw;
-                const chapter = requireNumberField(obj, "chapter", rel);
-                if (!Number.isInteger(chapter) || chapter !== ch)
-                    throw new NovelCliError(`Invalid ${rel}: chapter=${chapter} expected ${ch}.`, 2);
-                const storylineId = requireStringField(obj, "storyline_id", rel).trim();
-                const expectedStorylineId = storylinesByChapter.get(ch) ?? null;
-                if (!expectedStorylineId || storylineId !== expectedStorylineId) {
-                    throw new NovelCliError(`Invalid ${rel}: storyline_id=${storylineId} expected ${expectedStorylineId ?? "(missing in outline)"}.`, 2);
-                }
-                const objectivesRaw = obj.objectives;
-                if (!Array.isArray(objectivesRaw))
-                    throw new NovelCliError(`Invalid ${rel}: objectives must be an array.`, 2);
-                const hasRequired = objectivesRaw.some((it) => isPlainObject(it) && it.required === true);
-                if (!hasRequired)
-                    throw new NovelCliError(`Invalid ${rel}: objectives must include at least one entry with required=true.`, 2);
-                // Chain propagation (minimal): prev.postconditions.state_changes keys must exist in current.preconditions.character_states.
-                const prevChapter = ch - 1;
-                if (prevChapter >= 1) {
-                    const prevRel = prevChapter >= range.start
-                        ? rels.chapterContractJson(prevChapter)
-                        : volumeFinalRelPaths(volumeForChapter(prevChapter)).chapterContractJson(prevChapter);
-                    if (await pathExists(join(args.rootDir, prevRel))) {
-                        const prevRaw = await readJsonFile(join(args.rootDir, prevRel));
-                        if (isPlainObject(prevRaw)) {
-                            const prevObj = prevRaw;
-                            const post = isPlainObject(prevObj.postconditions) ? prevObj.postconditions : null;
-                            const stateChanges = post && isPlainObject(post.state_changes) ? post.state_changes : null;
-                            const pre = isPlainObject(obj.preconditions) ? obj.preconditions : null;
-                            const characterStates = pre && isPlainObject(pre.character_states) ? pre.character_states : null;
-                            if (stateChanges && Object.keys(stateChanges).length > 0) {
-                                if (!characterStates) {
-                                    throw new NovelCliError(`Invalid ${rel}: missing preconditions.character_states required by chain propagation from ${prevRel}.`, 2);
-                                }
-                                for (const characterKey of Object.keys(stateChanges)) {
-                                    if (!(characterKey in characterStates)) {
-                                        throw new NovelCliError(`Invalid ${rel}: preconditions.character_states missing '${characterKey}' (required by ${prevRel}.postconditions.state_changes).`, 2);
-                                    }
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        };
+        const range = await resolveVolumeChapterRange({ rootDir: args.rootDir, current_volume: volume, last_completed_chapter: args.checkpoint.last_completed_chapter });
         if (args.step.phase === "commit") {
             throw new NovelCliError(`Use 'novel commit --volume ${volume}' for commit.`, 2);
         }
-        await requireVolumePlanArtifacts();
-        const storylinesByChapter = await parseOutlineStorylineIds();
-        const scheduleRaw = await readJsonFile(join(args.rootDir, rels.storylineScheduleJson));
-        validateSchedule(scheduleRaw, storylinesByChapter);
-        // JSON existence + basic schema.
-        const foreshadowingRaw = await readJsonFile(join(args.rootDir, rels.foreshadowingJson));
-        validateForeshadowingPlan(foreshadowingRaw);
-        const newCharsRaw = await readJsonFile(join(args.rootDir, rels.newCharactersJson));
-        validateNewCharacters(newCharsRaw);
-        await validateContracts(storylinesByChapter);
+        await validateVolumePlanArtifacts({
+            rootDir: args.rootDir,
+            volume,
+            range,
+            rels: volumeStagingRelPaths(volume),
+            warnings
+        });
         return { ok: true, step: stepId, warnings };
     }
     if (args.step.kind === "quickstart") {
@@ -308,10 +364,29 @@ export async function validateStep(args) {
         const styleAbs = join(args.rootDir, QUICKSTART_STAGING_RELS.styleProfileJson);
         const trialAbs = join(args.rootDir, QUICKSTART_STAGING_RELS.trialChapterMd);
         const evalAbs = join(args.rootDir, QUICKSTART_STAGING_RELS.evaluationJson);
+        if (args.step.phase === "f0") {
+            requireFile(await pathExists(rulesAbs), QUICKSTART_STAGING_RELS.rulesJson);
+            requireFile(await pathExists(contractsAbs), QUICKSTART_STAGING_RELS.contractsDir);
+            requireFile(await pathExists(styleAbs), QUICKSTART_STAGING_RELS.styleProfileJson);
+            const rulesCount = await validateQuickstartRulesSchema(rulesAbs);
+            if (rulesCount === 0)
+                warnings.push(`Empty rules list in ${QUICKSTART_STAGING_RELS.rulesJson}.`);
+            await validateQuickstartContractsDir(contractsAbs);
+            await validateQuickstartStyleProfileSchema(styleAbs);
+            await validateVolumePlanArtifacts({
+                rootDir: args.rootDir,
+                volume: 1,
+                range: QUICKSTART_MINI_PLANNING_RANGE,
+                rels: volumeStagingRelPaths(1),
+                warnings
+            });
+            return { ok: true, step: stepId, warnings };
+        }
         if (args.step.phase === "results") {
             requireFile(await pathExists(rulesAbs), QUICKSTART_STAGING_RELS.rulesJson);
             requireFile(await pathExists(contractsAbs), QUICKSTART_STAGING_RELS.contractsDir);
             requireFile(await pathExists(styleAbs), QUICKSTART_STAGING_RELS.styleProfileJson);
+            await requireCommittedQuickstartMiniPlanning(args.rootDir);
             requireFile(await pathExists(trialAbs), QUICKSTART_STAGING_RELS.trialChapterMd);
             requireFile(await pathExists(evalAbs), QUICKSTART_STAGING_RELS.evaluationJson);
             // Re-validate the whole quickstart staging set before committing to final dirs.
@@ -361,6 +436,10 @@ export async function validateStep(args) {
                         warnings.push(warning);
                     break;
                 }
+                case "f0": {
+                    await requireCommittedQuickstartMiniPlanning(args.rootDir);
+                    break;
+                }
                 case "results":
                     break;
                 default: {