novel-writer-cli 0.1.0 → 0.2.1

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command, CommanderError } from "commander";
 import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
 import { join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { buildCharacterVoiceProfiles, clearCharacterVoiceDriftFile, computeCharacterVoiceDrift, loadActiveCharacterVoiceDriftIds, loadCharacterVoiceProfiles, writeCharacterVoiceDriftFile, writeCharacterVoiceProfilesFile } from "./character-voice.js";
@@ -8,7 +9,7 @@ import { NovelCliError } from "./errors.js";
 import { errJson, okJson, printJson } from "./output.js";
 import { pathExists, readJsonFile, writeJsonFile, writeTextFile } from "./fs-utils.js";
 import { resolveProjectRoot } from "./project.js";
-import { readCheckpoint } from "./checkpoint.js";
+import { readCheckpoint, writeCheckpoint } from "./checkpoint.js";
 import { initProject, normalizePlatformId, resolveInitRootDir } from "./init.js";
 import { advanceCheckpointForStep } from "./advance.js";
 import { commitChapter } from "./commit.js";
@@ -17,16 +18,37 @@ import { buildInstructionPacket } from "./instructions.js";
 import { getLockStatus, clearStaleLock, withWriteLock } from "./lock.js";
 import { computeNextStep } from "./next-step.js";
 import { computeEngagementReport, loadEngagementMetricsStream, writeEngagementLogs } from "./engagement.js";
+import { parseNovelAskQuestionSpec } from "./novel-ask.js";
 import { computePromiseLedgerReport, ensurePromiseLedgerInitialized, loadPromiseLedger, writePromiseLedgerLogs } from "./promise-ledger.js";
 import { pad2, pad3, parseStepId } from "./steps.js";
+import { resolveProjectRelativePath } from "./safe-path.js";
 import { isPlainObject } from "./type-guards.js";
 import { validateStep } from "./validate.js";
 import { VOL_REVIEW_RELS, collectVolumeData, computeBridgeCheck, computeForeshadowingAudit, computeStorylineRhythm } from "./volume-review.js";
 import { tryResolveVolumeChapterRange } from "./consistency-auditor.js";
+const require = createRequire(import.meta.url);
+function resolveCliVersion() {
+    try {
+        const pkg = require("../package.json");
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const CLI_VERSION = resolveCliVersion();
 function detectCommandName(argv) {
-    for (const token of argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
         if (token === "--")
             return "unknown";
+        // Global option: consumes the next token as a value.
+        if (token === "--project") {
+            i++;
+            continue;
+        }
+        if (token.startsWith("--project="))
+            continue;
         if (!token.startsWith("-"))
             return token;
     }
@@ -39,6 +61,7 @@ function buildProgram(argv) {
     const jsonMode = isJsonMode(argv);
     const program = new Command();
     program.name("novel").description("Executor-agnostic novel orchestration CLI.");
+    program.version(CLI_VERSION);
     program.option("--json", "Emit machine-readable JSON (single object).");
     program.option("--project <dir>", "Project root directory (defaults to auto-detect via .checkpoint.json).");
     program.configureOutput({
@@ -124,6 +147,16 @@ function buildProgram(argv) {
             printJson(okJson("next", { rootDir, ...next }));
             return;
         }
+        if (isPlainObject(next.evidence)) {
+            const blocked = next.evidence.recovery_blocked;
+            if (isPlainObject(blocked)) {
+                const obj = blocked;
+                const checkpointPhase = typeof obj.checkpoint_phase === "string" ? obj.checkpoint_phase : "unknown";
+                const inferredPhase = typeof obj.inferred_phase === "string" ? obj.inferred_phase : "unknown";
+                const expectedPath = typeof obj.expected_path === "string" ? obj.expected_path : "unknown";
+                process.stderr.write(`WARN: quickstart recovery blocked (checkpoint_phase=${checkpointPhase}, inferred_phase=${inferredPhase}, expected=${expectedPath}). Run 'novel status' for details.\n`);
+            }
+        }
         process.stdout.write(`${next.step}\n`);
     });
     program
@@ -132,18 +165,34 @@ function buildProgram(argv) {
         .argument("<step>", "Step id, e.g. chapter:048:draft")
         .option("--write-manifest", "Persist packet under staging/manifests/.")
         .option("--embed <mode>", "Optional embed mode (off by default). Example: --embed brief")
+        .option("--novel-ask-file <path>", "Project-relative path to a NOVEL_ASK QuestionSpec JSON file (enables gate).")
+        .option("--answer-path <path>", "Project-relative path to write the NOVEL_ASK AnswerSpec JSON record.")
         .action(async (step, localOpts) => {
         const opts = program.opts();
         const json = Boolean(opts.json);
         const rootDir = await resolveProjectRoot({ cwd: process.cwd(), projectOverride: opts.project });
         const checkpoint = await readCheckpoint(rootDir);
         const parsedStep = parseStepId(step);
+        const novelAskFile = localOpts.novelAskFile ?? null;
+        const answerPath = localOpts.answerPath ?? null;
+        let novelAskGate = null;
+        if (novelAskFile !== null || answerPath !== null) {
+            if (!novelAskFile || !answerPath) {
+                throw new NovelCliError(`Invalid NOVEL_ASK gate: provide both --novel-ask-file and --answer-path.`, 2);
+            }
+            const absAsk = resolveProjectRelativePath(rootDir, novelAskFile, "--novel-ask-file");
+            const rawSpec = await readJsonFile(absAsk);
+            const spec = parseNovelAskQuestionSpec(rawSpec);
+            resolveProjectRelativePath(rootDir, answerPath, "--answer-path");
+            novelAskGate = { novel_ask: spec, answer_path: answerPath };
+        }
         const packet = await buildInstructionPacket({
             rootDir,
             checkpoint,
             step: parsedStep,
             embedMode: localOpts.embed ?? null,
-            writeManifest: Boolean(localOpts.writeManifest)
+            writeManifest: Boolean(localOpts.writeManifest),
+            novelAskGate
         });
         if (json) {
             printJson(okJson("instructions", packet));
@@ -703,6 +752,83 @@ function buildProgram(argv) {
         else if (!localOpts.apply)
             process.stdout.write(`\nPreview-only. Use --apply to write character-voice-drift.json.\n`);
     });
+    program
+        .command("repair")
+        .description("Repair project state (checkpoint recovery helpers).")
+        .option("--reset-quickstart", "Set .checkpoint.json.quickstart_phase to null.")
+        .option("--force", "Apply the repair (otherwise preview only).")
+        .action(async (localOpts) => {
+        const opts = program.opts();
+        const json = Boolean(opts.json);
+        const rootDir = await resolveProjectRoot({ cwd: process.cwd(), projectOverride: opts.project });
+        if (!localOpts.resetQuickstart) {
+            throw new NovelCliError("Invalid repair: no actions specified. Use --reset-quickstart.", 2);
+        }
+        if (!localOpts.force) {
+            const checkpoint = await readCheckpoint(rootDir);
+            const beforePresent = Object.prototype.hasOwnProperty.call(checkpoint, "quickstart_phase");
+            const before = (checkpoint.quickstart_phase ?? null);
+            const wouldChange = !beforePresent || before !== null;
+            if (json) {
+                printJson(okJson("repair", {
+                    rootDir,
+                    applied: false,
+                    actions: ["reset_quickstart"],
+                    before_present: beforePresent,
+                    after_present: true,
+                    changed: false,
+                    would_change: wouldChange,
+                    before,
+                    after: before,
+                    target_after: null
+                }));
+                return;
+            }
+            if (!wouldChange) {
+                process.stdout.write("No changes needed: quickstart_phase is already null.\n");
+                return;
+            }
+            process.stdout.write(`Preview: set quickstart_phase ${beforePresent ? before : "<missing>"} -> null\n`);
+            process.stdout.write("Re-run with --force to apply.\n");
+            return;
+        }
+        const applied = await withWriteLock(rootDir, {}, async () => {
+            const checkpoint = await readCheckpoint(rootDir);
+            const beforePresent = Object.prototype.hasOwnProperty.call(checkpoint, "quickstart_phase");
+            const before = (checkpoint.quickstart_phase ?? null);
+            const wouldChange = !beforePresent || before !== null;
+            if (!wouldChange)
+                return { beforePresent, before, wouldChange, wrote: false, checkpoint };
+            const updated = { ...checkpoint, quickstart_phase: null, last_checkpoint_time: new Date().toISOString() };
+            await writeCheckpoint(rootDir, updated);
+            return { beforePresent, before, wouldChange, wrote: true, checkpoint: await readCheckpoint(rootDir) };
+        });
+        const afterPresent = Object.prototype.hasOwnProperty.call(applied.checkpoint, "quickstart_phase");
+        const after = applied.checkpoint.quickstart_phase ?? null;
+        if (!afterPresent || after !== null) {
+            throw new NovelCliError(`Repair failed: quickstart_phase is still ${String(after)} (expected null).`, 2);
+        }
+        if (json) {
+            printJson(okJson("repair", {
+                rootDir,
+                applied: true,
+                actions: ["reset_quickstart"],
+                before_present: applied.beforePresent,
+                after_present: afterPresent,
+                changed: applied.wrote,
+                would_change: applied.wouldChange,
+                before: applied.before,
+                after: null,
+                target_after: null
+            }));
+            return;
+        }
+        if (!applied.wrote) {
+            process.stdout.write("No changes needed: quickstart_phase is already null.\n");
+            return;
+        }
+        process.stdout.write(`Set quickstart_phase ${applied.beforePresent ? applied.before : "<missing>"} -> null\n`);
+    });
     const lock = program.command("lock").description("Manage project lock (.novel.lock).");
     lock
         .command("status")
@@ -757,7 +883,7 @@ export async function main(argv = process.argv.slice(2)) {
             return err.exitCode;
         }
         if (err instanceof CommanderError) {
-            if (err.code === "commander.helpDisplayed") {
+            if (err.code === "commander.helpDisplayed" || err.code === "commander.version") {
                 return 0;
             }
             if (jsonMode) {

package/dist/init.js

@@ -108,7 +108,8 @@ const STAGING_SUBDIRS = [
     "staging/storylines",
     "staging/volumes",
     "staging/foreshadowing",
-    "staging/manifests"
+    "staging/manifests",
+    "staging/quickstart"
 ];
 export async function initProject(args) {
     const force = Boolean(args.force);

package/dist/instructions.js

@@ -10,6 +10,7 @@ import { parseNovelAskQuestionSpec } from "./novel-ask.js";
 import { loadPlatformProfile } from "./platform-profile.js";
 import { computePrejudgeGuardrailsReport, writePrejudgeGuardrailsReport } from "./prejudge-guardrails.js";
 import { loadPromiseLedgerLatestSummary } from "./promise-ledger.js";
+import { QUICKSTART_STAGING_RELS } from "./quickstart.js";
 import { resolveProjectRelativePath } from "./safe-path.js";
 import { computeTitlePolicyReport } from "./title-policy.js";
 import { chapterRelPaths, formatStepId, pad2, pad3, titleFixSnapshotRel } from "./steps.js";
@@ -187,10 +188,169 @@ async function buildReviewInstructionPacket(args) {
         ...(writtenPath ? { written_manifest_path: writtenPath } : {})
     };
 }
+async function buildQuickStartInstructionPacket(args) {
+    const stepId = formatStepId(args.step);
+    if (args.step.kind !== "quickstart")
+        throw new NovelCliError(`Unsupported quickstart step: ${stepId}`, 2);
+    const step = args.step;
+    const embedMode = safeEmbedMode(args.embedMode);
+    const embed = {};
+    if (embedMode === "brief") {
+        const briefAbs = join(args.rootDir, "brief.md");
+        if (await pathExists(briefAbs)) {
+            const content = await readTextFile(briefAbs);
+            embed.brief_preview = content.slice(0, 2000);
+        }
+        else {
+            embed.brief_preview = null;
+        }
+    }
+    const trialChapter = Math.max(1, args.checkpoint.last_completed_chapter + 1);
+    const isTrialMode = step.phase === "trial" || step.phase === "results";
+    const inline = {
+        quickstart_phase: step.phase,
+        trial_mode: isTrialMode,
+        volume: args.checkpoint.current_volume,
+        ...(isTrialMode ? { chapter: trialChapter } : {})
+    };
+    const paths = {};
+    const maybeAddPath = async (key, relPath) => {
+        const absPath = join(args.rootDir, relPath);
+        if (await pathExists(absPath))
+            paths[key] = relPath;
+    };
+    await maybeAddPath("project_brief", "brief.md");
+    await maybeAddPath("platform_profile", "platform-profile.json");
+    await maybeAddPath("style_profile_template", "style-profile.json");
+    // Attach staging quickstart artifacts when present (for resume/debug).
+    await maybeAddPath("quickstart_rules", QUICKSTART_STAGING_RELS.rulesJson);
+    await maybeAddPath("quickstart_contracts_dir", QUICKSTART_STAGING_RELS.contractsDir);
+    await maybeAddPath("quickstart_style_profile", QUICKSTART_STAGING_RELS.styleProfileJson);
+    await maybeAddPath("quickstart_trial_chapter", QUICKSTART_STAGING_RELS.trialChapterMd);
+    await maybeAddPath("quickstart_evaluation", QUICKSTART_STAGING_RELS.evaluationJson);
+    const asString = (value) => (typeof value === "string" ? value : null);
+    const qsRules = asString(paths.quickstart_rules);
+    const qsContractsDir = asString(paths.quickstart_contracts_dir);
+    const qsStyleProfile = asString(paths.quickstart_style_profile);
+    const qsTrialChapter = asString(paths.quickstart_trial_chapter);
+    const styleTemplate = asString(paths.style_profile_template);
+    // Provide canonical manifest keys in addition to quickstart-scoped aliases.
+    if (qsRules)
+        paths.world_rules = qsRules;
+    if (qsContractsDir)
+        paths.character_contracts_dir = qsContractsDir;
+    if (qsStyleProfile)
+        paths.style_profile = qsStyleProfile;
+    else if (styleTemplate)
+        paths.style_profile = styleTemplate;
+    if (qsTrialChapter)
+        paths.chapter_draft = qsTrialChapter;
+    let agent;
+    const expected_outputs = [];
+    const next_actions = [];
+    if (step.phase === "world") {
+        agent = { kind: "subagent", name: "world-builder" };
+        expected_outputs.push({ path: QUICKSTART_STAGING_RELS.rulesJson, required: true });
+        next_actions.push({ kind: "command", command: `novel validate ${stepId}` });
+        next_actions.push({ kind: "command", command: `novel advance ${stepId}` });
+        next_actions.push({ kind: "command", command: `novel next`, note: "Compute next deterministic step (skips already-generated artifacts)." });
+        next_actions.push({
+            kind: "command",
+            command: `novel instructions quickstart:characters --json`,
+            note: "After advance, proceed to create initial characters/contracts."
+        });
+    }
+    else if (step.phase === "characters") {
+        agent = { kind: "subagent", name: "character-weaver" };
+        inline.contracts_output_dir = QUICKSTART_STAGING_RELS.contractsDir;
+        expected_outputs.push({
+            path: QUICKSTART_STAGING_RELS.contractsDir,
+            required: true,
+            note: "Write at least 1 character contract JSON under this dir."
+        });
+        next_actions.push({ kind: "command", command: `novel validate ${stepId}` });
+        next_actions.push({ kind: "command", command: `novel advance ${stepId}` });
+        next_actions.push({ kind: "command", command: `novel next`, note: "Compute next deterministic step (skips already-generated artifacts)." });
+        next_actions.push({ kind: "command", command: `novel instructions quickstart:style --json`, note: "After advance, proceed to style extraction." });
+    }
+    else if (step.phase === "style") {
+        agent = { kind: "subagent", name: "style-analyzer" };
+        expected_outputs.push({ path: QUICKSTART_STAGING_RELS.styleProfileJson, required: true });
+        next_actions.push({ kind: "command", command: `novel validate ${stepId}` });
+        next_actions.push({ kind: "command", command: `novel advance ${stepId}` });
+        next_actions.push({ kind: "command", command: `novel next`, note: "Compute next deterministic step (skips already-generated artifacts)." });
+        next_actions.push({ kind: "command", command: `novel instructions quickstart:trial --json`, note: "After advance, proceed to trial chapter." });
+    }
+    else if (step.phase === "trial") {
+        agent = { kind: "subagent", name: "chapter-writer" };
+        expected_outputs.push({ path: QUICKSTART_STAGING_RELS.trialChapterMd, required: true });
+        next_actions.push({ kind: "command", command: `novel validate ${stepId}` });
+        next_actions.push({ kind: "command", command: `novel advance ${stepId}` });
+        next_actions.push({ kind: "command", command: `novel next`, note: "Compute next deterministic step (skips already-generated artifacts)." });
+        next_actions.push({ kind: "command", command: `novel instructions quickstart:results --json`, note: "After advance, evaluate trial results." });
+    }
+    else if (step.phase === "results") {
+        agent = { kind: "subagent", name: "quality-judge" };
+        expected_outputs.push({
+            path: QUICKSTART_STAGING_RELS.evaluationJson,
+            required: true,
+            note: "QualityJudge returns JSON; the executor should write it to this path."
+        });
+        next_actions.push({ kind: "command", command: `novel validate ${stepId}` });
+        next_actions.push({ kind: "command", command: `novel advance ${stepId}` });
+        next_actions.push({ kind: "command", command: `novel next`, note: "After advance, the pipeline transitions to VOL_PLANNING." });
+    }
+    else {
+        const _exhaustive = step.phase;
+        throw new NovelCliError(`Unsupported quickstart phase: ${String(_exhaustive)}`, 2);
+    }
+    const gate = args.novelAskGate ?? null;
+    const gateSpec = gate ? parseNovelAskQuestionSpec(gate.novel_ask) : null;
+    if (gate) {
+        resolveProjectRelativePath(args.rootDir, gate.answer_path, "novelAskGate.answer_path");
+        expected_outputs.unshift({
+            path: gate.answer_path,
+            required: true,
+            note: "AnswerSpec JSON record for the NOVEL_ASK gate (written before main step execution)."
+        });
+    }
+    const packet = {
+        version: 1,
+        step: stepId,
+        agent,
+        ...(gate ? { novel_ask: gateSpec, answer_path: gate.answer_path } : {}),
+        manifest: {
+            mode: embedMode === "off" ? "paths" : "paths+embed",
+            inline,
+            paths,
+            ...(embedMode === "off" ? {} : { embed })
+        },
+        expected_outputs,
+        next_actions
+    };
+    let writtenPath = null;
+    if (args.writeManifest) {
+        const manifestsDir = join(args.rootDir, "staging/manifests");
+        await ensureDir(manifestsDir);
+        const fileName = `${stepId.replaceAll(":", "-")}.packet.json`;
+        writtenPath = `staging/manifests/${fileName}`;
+        await writeJsonFile(join(args.rootDir, writtenPath), packet);
+    }
+    return {
+        packet,
+        ...(writtenPath ? { written_manifest_path: writtenPath } : {})
+    };
+}
 export async function buildInstructionPacket(args) {
     const stepId = formatStepId(args.step);
-    if (args.step.kind === "review")
+    if (args.step.kind === "review") {
+        if (args.novelAskGate) {
+            throw new NovelCliError(`NOVEL_ASK gate is not supported for review steps: ${stepId}`, 2);
+        }
         return await buildReviewInstructionPacket(args);
+    }
+    if (args.step.kind === "quickstart")
+        return await buildQuickStartInstructionPacket(args);
     if (args.step.kind === "volume") {
         const step = args.step;
         const volume = args.checkpoint.current_volume;
@@ -661,6 +821,7 @@ export async function buildInstructionPacket(args) {
         agent = { kind: "cli", name: "novel" };
         expected_outputs.push({ path: `chapters/chapter-${String(step.chapter).padStart(3, "0")}.md`, required: true });
         next_actions.push({ kind: "command", command: `novel commit --chapter ${step.chapter}` });
+        next_actions.push({ kind: "command", command: `novel next`, note: "After commit, compute next step." });
     }
     else {
         throw new NovelCliError(`Unsupported step stage: ${step.stage}`, 2);

package/dist/next-step.js

@@ -1,3 +1,4 @@
+import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { tryResolveVolumeChapterRange } from "./consistency-auditor.js";
 import { NovelCliError } from "./errors.js";
@@ -5,12 +6,14 @@ 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) {
@@ -536,6 +539,224 @@ async function computeChapterNextStep(projectRootDir, checkpoint) {
 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":
@@ -558,10 +779,12 @@ export async function computeNextStep(projectRootDir, checkpoint) {
             const next = await computeChapterNextStep(projectRootDir, normalizedCheckpoint);
             return { ...next, reason: `error_retry:${healPrefix}${next.reason}` };
         }
-        case "INIT":
-            return notImplementedState(checkpoint.orchestrator_state);
+        case "INIT": {
+            const next = await computeQuickStartNextStep(projectRootDir, checkpoint);
+            return { ...next, reason: `init:${next.reason}` };
+        }
         case "QUICK_START":
-            return notImplementedState(checkpoint.orchestrator_state);
+            return await computeQuickStartNextStep(projectRootDir, checkpoint);
         case "VOL_PLANNING":
             return await computeVolumeNextStep(projectRootDir, checkpoint);
         case "VOL_REVIEW":