novel-writer-cli 0.0.2 → 0.1.0

package/dist/__tests__/volume-pipeline.test.js

@@ -0,0 +1,227 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { advanceCheckpointForStep } from "../advance.js";
+import { commitVolume } from "../volume-commit.js";
+import { readCheckpoint, writeCheckpoint } from "../checkpoint.js";
+import { computeNextStep } from "../next-step.js";
+import { validateStep } from "../validate.js";
+import { computeVolumeChapterRange, volumeStagingRelPaths } from "../volume-planning.js";
+async function writeText(absPath, contents) {
+    await mkdir(dirname(absPath), { recursive: true });
+    await writeFile(absPath, contents, "utf8");
+}
+async function writeJson(absPath, payload) {
+    await writeText(absPath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+async function exists(absPath) {
+    try {
+        await stat(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+test("computeVolumeChapterRange enforces deterministic bounds", () => {
+    assert.deepEqual(computeVolumeChapterRange({ current_volume: 1, last_completed_chapter: 0 }), { start: 1, end: 30 });
+    assert.deepEqual(computeVolumeChapterRange({ current_volume: 2, last_completed_chapter: 58 }), { start: 59, end: 60 });
+    assert.throws(() => computeVolumeChapterRange({ current_volume: 1, last_completed_chapter: 30 }), /plan_start=31 > plan_end=30/);
+});
+test("volume planning pipeline routes outline -> validate -> commit -> writing", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-volume-pipeline-"));
+    try {
+        const initial = {
+            last_completed_chapter: 58,
+            current_volume: 2,
+            orchestrator_state: "VOL_PLANNING",
+            pipeline_stage: null,
+            inflight_chapter: null,
+            volume_pipeline_stage: null
+        };
+        await writeJson(join(rootDir, ".checkpoint.json"), initial);
+        const volume = 2;
+        const range = computeVolumeChapterRange({ current_volume: volume, last_completed_chapter: initial.last_completed_chapter });
+        const rels = volumeStagingRelPaths(volume);
+        // Minimal planning artifacts for a 2-chapter range (59-60)
+        await writeText(join(rootDir, rels.outlineMd), [
+            `## 第 ${volume} 卷大纲`,
+            ``,
+            `### 第${range.start}章: 测试`,
+            `- **Storyline**: main-arc`,
+            `- **POV**: hero`,
+            `- **Location**: city`,
+            `- **Conflict**: test`,
+            `- **Arc**: test`,
+            `- **Foreshadowing**: test`,
+            `- **StateChanges**: test`,
+            `- **TransitionHint**: {}`,
+            ``,
+            `### 第 ${range.end}章: 测试`,
+            `- **Storyline**: main-arc`,
+            `- **POV**: hero`,
+            `- **Location**: city`,
+            `- **Conflict**: test`,
+            `- **Arc**: test`,
+            `- **Foreshadowing**: test`,
+            `- **StateChanges**: test`,
+            `- **TransitionHint**: {}`,
+            ``
+        ].join("\n"));
+        await writeJson(join(rootDir, rels.storylineScheduleJson), { active_storylines: ["main-arc"] });
+        await writeJson(join(rootDir, rels.foreshadowingJson), { schema_version: 1, items: [] });
+        await writeJson(join(rootDir, rels.newCharactersJson), []);
+        const contractBase = {
+            storyline_id: "main-arc",
+            objectives: [{ id: "OBJ", required: true, description: "x" }],
+            preconditions: { character_states: { Alice: { location: "city" } } },
+            postconditions: { state_changes: {} }
+        };
+        await writeJson(join(rootDir, rels.chapterContractJson(range.start)), { chapter: range.start, ...contractBase });
+        await writeJson(join(rootDir, rels.chapterContractJson(range.end)), { chapter: range.end, ...contractBase });
+        // Next step: outline
+        let checkpoint = await readCheckpoint(rootDir);
+        let next = await computeNextStep(rootDir, checkpoint);
+        assert.equal(next.step, "volume:outline");
+        // Validate outputs for outline, then advance outline -> validate stage.
+        await validateStep({ rootDir, checkpoint, step: { kind: "volume", phase: "outline" } });
+        checkpoint = await advanceCheckpointForStep({ rootDir, step: { kind: "volume", phase: "outline" } });
+        next = await computeNextStep(rootDir, checkpoint);
+        assert.equal(next.step, "volume:validate");
+        // Advance validate -> commit stage.
+        await validateStep({ rootDir, checkpoint, step: { kind: "volume", phase: "validate" } });
+        checkpoint = await advanceCheckpointForStep({ rootDir, step: { kind: "volume", phase: "validate" } });
+        next = await computeNextStep(rootDir, checkpoint);
+        assert.equal(next.step, "volume:commit");
+        // Commit volume plan.
+        const result = await commitVolume({ rootDir, volume, dryRun: false });
+        assert.ok(result.plan.length > 0);
+        const after = await readCheckpoint(rootDir);
+        assert.equal(after.orchestrator_state, "WRITING");
+        assert.equal(after.volume_pipeline_stage, null);
+        assert.equal(after.pipeline_stage, "committed");
+        assert.equal(after.inflight_chapter, null);
+        assert.ok(await exists(join(rootDir, `volumes/vol-02/outline.md`)));
+        assert.equal(await exists(join(rootDir, rels.dir)), false);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+test("commitVolume normalizes checkpoint when final dir exists but staging is missing", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-volume-commit-recover-"));
+    try {
+        await writeJson(join(rootDir, ".checkpoint.json"), {
+            last_completed_chapter: 0,
+            current_volume: 1,
+            orchestrator_state: "VOL_PLANNING",
+            pipeline_stage: null,
+            inflight_chapter: null,
+            volume_pipeline_stage: "commit"
+        });
+        await writeText(join(rootDir, "volumes/vol-01/outline.md"), "# vol 1\n");
+        const result = await commitVolume({ rootDir, volume: 1, dryRun: false });
+        assert.ok(result.warnings.some((w) => /already exists/i.test(w)));
+        const after = await readCheckpoint(rootDir);
+        assert.equal(after.orchestrator_state, "WRITING");
+        assert.equal(after.volume_pipeline_stage, null);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+test("advanceCheckpointForStep rejects volume advance outside VOL_PLANNING", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-volume-advance-guard-"));
+    try {
+        await writeCheckpoint(rootDir, {
+            last_completed_chapter: 0,
+            current_volume: 1,
+            orchestrator_state: "WRITING",
+            pipeline_stage: "committed",
+            volume_pipeline_stage: null,
+            inflight_chapter: null
+        });
+        await assert.rejects(() => advanceCheckpointForStep({ rootDir, step: { kind: "volume", phase: "outline" } }), /orchestrator_state=VOL_PLANNING/);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+test("computeNextStep falls back to volume:outline when validate stage is selected but artifacts are missing", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-volume-next-missing-"));
+    try {
+        const next = await computeNextStep(rootDir, {
+            last_completed_chapter: 58,
+            current_volume: 2,
+            orchestrator_state: "VOL_PLANNING",
+            pipeline_stage: null,
+            inflight_chapter: null,
+            volume_pipeline_stage: "validate"
+        });
+        assert.equal(next.step, "volume:outline");
+        assert.equal(next.reason, "vol_planning:validate:missing_artifacts");
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+test("commitVolume dryRun does not touch checkpoint", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-volume-commit-dryrun-"));
+    try {
+        await writeJson(join(rootDir, ".checkpoint.json"), {
+            last_completed_chapter: 0,
+            current_volume: 1,
+            orchestrator_state: "VOL_PLANNING",
+            pipeline_stage: null,
+            inflight_chapter: null,
+            volume_pipeline_stage: "commit"
+        });
+        const before = await readFile(join(rootDir, ".checkpoint.json"), "utf8");
+        const result = await commitVolume({ rootDir, volume: 1, dryRun: true });
+        assert.ok(result.plan.some((l) => l.includes("MOVE")));
+        const after = await readFile(join(rootDir, ".checkpoint.json"), "utf8");
+        assert.equal(after, before);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+test("commitVolume rejects when both staging and final volume dirs exist", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-volume-commit-conflict-"));
+    try {
+        await writeJson(join(rootDir, ".checkpoint.json"), {
+            last_completed_chapter: 0,
+            current_volume: 1,
+            orchestrator_state: "VOL_PLANNING",
+            pipeline_stage: null,
+            inflight_chapter: null,
+            volume_pipeline_stage: "commit"
+        });
+        await mkdir(join(rootDir, "staging/volumes/vol-01"), { recursive: true });
+        await mkdir(join(rootDir, "volumes/vol-01"), { recursive: true });
+        await assert.rejects(() => commitVolume({ rootDir, volume: 1, dryRun: false }), /Commit conflict/);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+test("commitVolume recovery refuses when final dir exists but outline.md is missing", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-volume-commit-recover-missing-outline-"));
+    try {
+        await writeJson(join(rootDir, ".checkpoint.json"), {
+            last_completed_chapter: 0,
+            current_volume: 1,
+            orchestrator_state: "VOL_PLANNING",
+            pipeline_stage: null,
+            inflight_chapter: null,
+            volume_pipeline_stage: "commit"
+        });
+        await mkdir(join(rootDir, "volumes/vol-01"), { recursive: true });
+        await assert.rejects(() => commitVolume({ rootDir, volume: 1, dryRun: false }), /missing .*outline\.md/i);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});

package/dist/__tests__/volume-review-pipeline.test.js

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { advanceCheckpointForStep } from "../advance.js";
+import { computeNextStep } from "../next-step.js";
+async function writeJson(absPath, payload) {
+    await mkdir(dirname(absPath), { recursive: true });
+    await writeFile(absPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+async function exists(absPath) {
+    try {
+        await stat(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+test("computeNextStep progresses through volume review phases based on artifacts", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-vol-review-phases-"));
+    // 1) no artifacts => collect
+    let next = await computeNextStep(rootDir, {
+        last_completed_chapter: 10,
+        current_volume: 1,
+        orchestrator_state: "VOL_REVIEW",
+        pipeline_stage: "committed",
+        inflight_chapter: null
+    });
+    assert.equal(next.step, "review:collect");
+    // 2) quality summary exists => audit
+    await mkdir(join(rootDir, "staging/vol-review"), { recursive: true });
+    await writeJson(join(rootDir, "staging/vol-review/quality-summary.json"), { schema_version: 1, generated_at: new Date().toISOString() });
+    next = await computeNextStep(rootDir, {
+        last_completed_chapter: 10,
+        current_volume: 1,
+        orchestrator_state: "VOL_REVIEW",
+        pipeline_stage: "committed",
+        inflight_chapter: null
+    });
+    assert.equal(next.step, "review:audit");
+    // 3) audit report exists => report
+    await writeJson(join(rootDir, "staging/vol-review/audit-report.json"), { schema_version: 1, generated_at: new Date().toISOString(), stats: {} });
+    next = await computeNextStep(rootDir, {
+        last_completed_chapter: 10,
+        current_volume: 1,
+        orchestrator_state: "VOL_REVIEW",
+        pipeline_stage: "committed",
+        inflight_chapter: null
+    });
+    assert.equal(next.step, "review:report");
+    // 4) review report exists => cleanup
+    await writeFile(join(rootDir, "staging/vol-review/review-report.md"), "# report\n", "utf8");
+    next = await computeNextStep(rootDir, {
+        last_completed_chapter: 10,
+        current_volume: 1,
+        orchestrator_state: "VOL_REVIEW",
+        pipeline_stage: "committed",
+        inflight_chapter: null
+    });
+    assert.equal(next.step, "review:cleanup");
+    // 5) foreshadow status exists => transition
+    await writeJson(join(rootDir, "staging/vol-review/foreshadow-status.json"), { schema_version: 1, generated_at: new Date().toISOString() });
+    next = await computeNextStep(rootDir, {
+        last_completed_chapter: 10,
+        current_volume: 1,
+        orchestrator_state: "VOL_REVIEW",
+        pipeline_stage: "committed",
+        inflight_chapter: null
+    });
+    assert.equal(next.step, "review:transition");
+});
+test("advanceCheckpointForStep(review:transition) increments volume, returns to WRITING, and clears review artifacts", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-vol-review-transition-"));
+    await mkdir(join(rootDir, "staging/vol-review"), { recursive: true });
+    // checkpoint
+    await writeFile(join(rootDir, ".checkpoint.json"), `${JSON.stringify({ last_completed_chapter: 10, current_volume: 1, orchestrator_state: "VOL_REVIEW", pipeline_stage: "committed", inflight_chapter: null }, null, 2)}\n`, "utf8");
+    // required artifacts for transition validation
+    await writeJson(join(rootDir, "staging/vol-review/quality-summary.json"), { schema_version: 1, generated_at: new Date().toISOString() });
+    await writeJson(join(rootDir, "staging/vol-review/audit-report.json"), { schema_version: 1, generated_at: new Date().toISOString(), stats: {} });
+    await writeFile(join(rootDir, "staging/vol-review/review-report.md"), "# report\n", "utf8");
+    await writeJson(join(rootDir, "staging/vol-review/foreshadow-status.json"), { schema_version: 1, generated_at: new Date().toISOString() });
+    const updated = await advanceCheckpointForStep({ rootDir, step: { kind: "review", phase: "transition" } });
+    assert.equal(updated.current_volume, 2);
+    assert.equal(updated.orchestrator_state, "WRITING");
+    assert.equal(updated.pipeline_stage, "committed");
+    assert.equal(updated.inflight_chapter, null);
+    assert.equal(updated.revision_count, 0);
+    assert.equal(updated.hook_fix_count, 0);
+    assert.equal(updated.title_fix_count, 0);
+    assert.equal(await exists(join(rootDir, "staging/vol-review")), false);
+});
+test("advanceCheckpointForStep refuses to advance review steps from CHAPTER_REWRITE", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-vol-review-guard-"));
+    await writeFile(join(rootDir, ".checkpoint.json"), `${JSON.stringify({ last_completed_chapter: 10, current_volume: 1, orchestrator_state: "CHAPTER_REWRITE", pipeline_stage: "revising", inflight_chapter: 11 }, null, 2)}\n`, "utf8");
+    await assert.rejects(() => advanceCheckpointForStep({ rootDir, step: { kind: "review", phase: "collect" } }), /Refusing to advance review step from orchestrator_state=CHAPTER_REWRITE/);
+});
+test("computeNextStep enters volume review after committing volume-end chapter when outline range matches", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-vol-review-enter-"));
+    await mkdir(join(rootDir, "volumes/vol-01"), { recursive: true });
+    await writeFile(join(rootDir, "volumes/vol-01/outline.md"), "### 第 1 章\n\n### 第 2 章\n", "utf8");
+    const next = await computeNextStep(rootDir, {
+        last_completed_chapter: 2,
+        current_volume: 1,
+        orchestrator_state: "WRITING",
+        pipeline_stage: "committed",
+        inflight_chapter: null
+    });
+    assert.equal(next.step, "review:collect");
+    assert.equal(next.reason, "volume_end:vol_review:missing_quality_summary");
+});

package/dist/__tests__/volume-review-storyline-rhythm.test.js

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { computeStorylineRhythm } from "../volume-review.js";
+test("computeStorylineRhythm counts multiple storyline_id entries per chapter (unique per chapter)", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-storyline-rhythm-"));
+    await mkdir(join(rootDir, "summaries"), { recursive: true });
+    await writeFile(join(rootDir, "summaries/chapter-001-summary.md"), `storyline_id: main\nstoryline_id: side\nstoryline_id: side\n`, "utf8");
+    await writeFile(join(rootDir, "summaries/chapter-002-summary.md"), `storyline_id: side\n`, "utf8");
+    const res = await computeStorylineRhythm({ rootDir, volume: 1, chapter_range: [1, 2] });
+    const obj = res;
+    assert.equal(obj.schema_version, 1);
+    assert.deepEqual(obj.appearances, { main: 1, side: 2 });
+    assert.deepEqual(obj.last_seen, { main: 1, side: 2 });
+    assert.ok(Array.isArray(obj.warnings));
+    assert.ok(obj.warnings.some((w) => w.includes("Missing optional file: volumes/vol-01/storyline-schedule.json")));
+});

package/dist/advance.js

@@ -3,11 +3,10 @@ import { readCheckpoint, writeCheckpoint } from "./checkpoint.js";
 import { NovelCliError } from "./errors.js";
 import { removePath } from "./fs-utils.js";
 import { withWriteLock } from "./lock.js";
-import { chapterRelPaths, titleFixSnapshotRel } from "./steps.js";
+import { chapterRelPaths, formatStepId, titleFixSnapshotRel } from "./steps.js";
 import { validateStep } from "./validate.js";
+import { VOL_REVIEW_RELS } from "./volume-review.js";
 function stageForStep(step) {
-    if (step.kind !== "chapter")
-        throw new NovelCliError(`Unsupported step kind: ${step.kind}`, 2);
     switch (step.stage) {
         case "draft":
             return "drafting";
@@ -21,55 +20,153 @@ function stageForStep(step) {
             return "refined";
         case "hook-fix":
             return "refined";
-        default:
-            throw new NovelCliError(`Unsupported step stage: ${step.stage}`, 2);
+        case "review":
+        case "commit":
+            throw new NovelCliError(`Unsupported step stage for advance: ${step.stage}`, 2);
+        default: {
+            const _exhaustive = step.stage;
+            throw new NovelCliError(`Unsupported step stage: ${_exhaustive}`, 2);
+        }
     }
 }
 export async function advanceCheckpointForStep(args) {
-    if (args.step.kind !== "chapter")
-        throw new NovelCliError(`Unsupported step kind: ${args.step.kind}`, 2);
-    if (args.step.stage === "commit")
-        throw new NovelCliError(`Use 'novel commit' for commit.`, 2);
-    if (args.step.stage === "review")
-        throw new NovelCliError(`Review is a manual step; do not advance it.`, 2);
-    return await withWriteLock(args.rootDir, { chapter: args.step.chapter }, async () => {
-        const checkpoint = await readCheckpoint(args.rootDir);
-        // Enforce validate-before-advance to keep deterministic semantics.
-        await validateStep({ rootDir: args.rootDir, checkpoint, step: args.step });
-        const updated = { ...checkpoint };
-        const nextStage = stageForStep(args.step);
-        updated.pipeline_stage = nextStage;
-        updated.inflight_chapter = args.step.chapter;
-        // Ensure revision counter is initialized when starting from draft (revision loops may preserve it).
-        if (args.step.stage === "draft") {
-            if (typeof updated.revision_count !== "number")
+    const step = args.step;
+    if (step.kind === "chapter") {
+        if (step.stage === "commit")
+            throw new NovelCliError(`Use 'novel commit' for commit.`, 2);
+        if (step.stage === "review")
+            throw new NovelCliError(`Review is a manual step; do not advance it.`, 2);
+        return await withWriteLock(args.rootDir, { chapter: step.chapter }, async () => {
+            const checkpoint = await readCheckpoint(args.rootDir);
+            // Enforce validate-before-advance to keep deterministic semantics.
+            await validateStep({ rootDir: args.rootDir, checkpoint, step });
+            const updated = { ...checkpoint };
+            const nextStage = stageForStep(step);
+            updated.pipeline_stage = nextStage;
+            updated.inflight_chapter = step.chapter;
+            updated.orchestrator_state =
+                checkpoint.orchestrator_state === "CHAPTER_REWRITE" || checkpoint.pipeline_stage === "revising" ? "CHAPTER_REWRITE" : "WRITING";
+            // Ensure revision counter is initialized when starting from draft (revision loops may preserve it).
+            if (step.stage === "draft") {
+                if (typeof updated.revision_count !== "number")
+                    updated.revision_count = 0;
+                updated.hook_fix_count = 0;
+                updated.title_fix_count = 0;
+                await removePath(join(args.rootDir, titleFixSnapshotRel(step.chapter)));
+                // If rewinding from a later stage, clear downstream staging artifacts to avoid skipping steps with stale data.
+                const prevStage = checkpoint.pipeline_stage ?? null;
+                const prevInflight = typeof checkpoint.inflight_chapter === "number" ? checkpoint.inflight_chapter : null;
+                if (prevInflight === step.chapter && prevStage && prevStage !== "drafting") {
+                    const rel = chapterRelPaths(step.chapter);
+                    await removePath(join(args.rootDir, rel.staging.summaryMd));
+                    await removePath(join(args.rootDir, rel.staging.deltaJson));
+                    await removePath(join(args.rootDir, rel.staging.crossrefJson));
+                    await removePath(join(args.rootDir, rel.staging.evalJson));
+                    await removePath(join(args.rootDir, rel.staging.styleRefinerChangesJson));
+                    // Revision loops are driven by gate decision after judge.
+                    if (prevStage === "judged") {
+                        const prev = typeof updated.revision_count === "number" ? updated.revision_count : 0;
+                        updated.revision_count = prev + 1;
+                        updated.orchestrator_state = "CHAPTER_REWRITE";
+                    }
+                }
+            }
+            // Title-fix counts as a bounded micro-revision and invalidates the current eval.
+            if (step.stage === "title-fix") {
+                const prev = typeof updated.title_fix_count === "number" ? updated.title_fix_count : 0;
+                if (prev >= 1) {
+                    throw new NovelCliError(`Title-fix already attempted for chapter ${step.chapter}; manual review required.`, 2);
+                }
+                updated.title_fix_count = prev + 1;
+                const rel = chapterRelPaths(step.chapter);
+                await removePath(join(args.rootDir, rel.staging.evalJson));
+            }
+            // Hook-fix counts as a bounded micro-revision and invalidates the current eval.
+            if (step.stage === "hook-fix") {
+                const prev = typeof updated.hook_fix_count === "number" ? updated.hook_fix_count : 0;
+                if (prev >= 1) {
+                    throw new NovelCliError(`Hook-fix already attempted for chapter ${step.chapter}; manual review required.`, 2);
+                }
+                updated.hook_fix_count = prev + 1;
+                const rel = chapterRelPaths(step.chapter);
+                await removePath(join(args.rootDir, rel.staging.evalJson));
+            }
+            // Refine rewrites the chapter draft; invalidate prior eval to force re-judge.
+            if (step.stage === "refine") {
+                const rel = chapterRelPaths(step.chapter);
+                await removePath(join(args.rootDir, rel.staging.evalJson));
+                // If we're polishing after a judged gate decision, count it as a revision loop.
+                const prevStage = checkpoint.pipeline_stage ?? null;
+                const prevInflight = typeof checkpoint.inflight_chapter === "number" ? checkpoint.inflight_chapter : null;
+                if (prevInflight === step.chapter && prevStage === "judged") {
+                    const prev = typeof updated.revision_count === "number" ? updated.revision_count : 0;
+                    updated.revision_count = prev + 1;
+                    updated.orchestrator_state = "CHAPTER_REWRITE";
+                }
+            }
+            updated.last_checkpoint_time = new Date().toISOString();
+            await writeCheckpoint(args.rootDir, updated);
+            return updated;
+        });
+    }
+    if (step.kind === "review") {
+        const reviewStep = step;
+        return await withWriteLock(args.rootDir, {}, async () => {
+            const checkpoint = await readCheckpoint(args.rootDir);
+            if (checkpoint.orchestrator_state !== "WRITING" && checkpoint.orchestrator_state !== "VOL_REVIEW") {
+                throw new NovelCliError(`Refusing to advance review step from orchestrator_state=${checkpoint.orchestrator_state}. Expected WRITING (volume_end) or VOL_REVIEW.`, 2);
+            }
+            // Enforce validate-before-advance to keep deterministic semantics.
+            await validateStep({ rootDir: args.rootDir, checkpoint, step: reviewStep });
+            const updated = { ...checkpoint };
+            updated.inflight_chapter = null;
+            if (reviewStep.phase === "transition") {
+                updated.current_volume = checkpoint.current_volume + 1;
+                updated.orchestrator_state = "WRITING";
+                updated.pipeline_stage = "committed";
                 updated.revision_count = 0;
-            updated.hook_fix_count = 0;
-            updated.title_fix_count = 0;
-            await removePath(join(args.rootDir, titleFixSnapshotRel(args.step.chapter)));
-        }
-        // Title-fix counts as a bounded micro-revision and invalidates the current eval.
-        if (args.step.stage === "title-fix") {
-            const prev = typeof updated.title_fix_count === "number" ? updated.title_fix_count : 0;
-            if (prev >= 1) {
-                throw new NovelCliError(`Title-fix already attempted for chapter ${args.step.chapter}; manual review required.`, 2);
+                updated.hook_fix_count = 0;
+                updated.title_fix_count = 0;
+                await removePath(join(args.rootDir, VOL_REVIEW_RELS.dir));
             }
-            updated.title_fix_count = prev + 1;
-            const rel = chapterRelPaths(args.step.chapter);
-            await removePath(join(args.rootDir, rel.staging.evalJson));
-        }
-        // Hook-fix counts as a bounded micro-revision and invalidates the current eval.
-        if (args.step.stage === "hook-fix") {
-            const prev = typeof updated.hook_fix_count === "number" ? updated.hook_fix_count : 0;
-            if (prev >= 1) {
-                throw new NovelCliError(`Hook-fix already attempted for chapter ${args.step.chapter}; manual review required.`, 2);
+            else {
+                updated.orchestrator_state = "VOL_REVIEW";
             }
-            updated.hook_fix_count = prev + 1;
-            const rel = chapterRelPaths(args.step.chapter);
-            await removePath(join(args.rootDir, rel.staging.evalJson));
-        }
-        updated.last_checkpoint_time = new Date().toISOString();
-        await writeCheckpoint(args.rootDir, updated);
-        return updated;
-    });
+            updated.last_checkpoint_time = new Date().toISOString();
+            await writeCheckpoint(args.rootDir, updated);
+            return updated;
+        });
+    }
+    if (step.kind === "volume") {
+        return await withWriteLock(args.rootDir, {}, async () => {
+            const checkpoint = await readCheckpoint(args.rootDir);
+            if (checkpoint.orchestrator_state !== "VOL_PLANNING") {
+                throw new NovelCliError(`Cannot advance ${formatStepId(step)} unless orchestrator_state=VOL_PLANNING.`, 2);
+            }
+            await validateStep({ rootDir: args.rootDir, checkpoint, step });
+            const updated = { ...checkpoint };
+            updated.orchestrator_state = "VOL_PLANNING";
+            updated.pipeline_stage = "committed";
+            updated.inflight_chapter = null;
+            const phase = step.phase;
+            switch (phase) {
+                case "outline":
+                    updated.volume_pipeline_stage = "validate";
+                    break;
+                case "validate":
+                    updated.volume_pipeline_stage = "commit";
+                    break;
+                case "commit":
+                    throw new NovelCliError(`Use 'novel commit --volume <n>' for volume commit.`, 2);
+                default: {
+                    const _exhaustive = phase;
+                    throw new NovelCliError(`Unsupported volume phase: ${String(_exhaustive)}`, 2);
+                }
+            }
+            updated.last_checkpoint_time = new Date().toISOString();
+            await writeCheckpoint(args.rootDir, updated);
+            return updated;
+        });
+    }
+    throw new NovelCliError(`Unsupported step kind: ${step.kind}`, 2);
 }