novelforge-agent 0.1.0

package/src/core/schemas.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+
+export const CoreCastMemberSchema = z.object({
+  name: z.string().min(1),
+  role: z.string().min(1),
+  description: z.string().min(1),
+});
+
+export const NovelMetadataSchema = z.object({
+  title: z.string().min(1),
+  genre: z.string().min(1),
+  premise: z.string().min(1),
+  language: z.string().min(1).default('zh-CN'),
+  style: z.string().min(1).default('清晰、连贯、适合长篇连载'),
+  coreCast: z.array(CoreCastMemberSchema).min(1),
+});
+
+export const VolumeArchitectureSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  summary: z.string().min(1),
+  order: z.number().int().positive(),
+});
+
+export const ChapterArchitectureSchema = z.object({
+  chapterNumber: z.number().int().positive(),
+  title: z.string().min(1),
+  volumeId: z.string().min(1),
+  summary: z.string().min(1),
+  requiredBeats: z.array(z.string().min(1)).min(1),
+});
+
+export const ArchitecturePayloadSchema = z.object({
+  full: z.string().min(1),
+  volumes: z.array(VolumeArchitectureSchema).min(1),
+  chapters: z.array(ChapterArchitectureSchema).min(1),
+});
+
+export const MemoryCardSchema = z.object({
+  summary: z.string().min(1),
+  keyEvents: z.array(z.string().min(1)),
+  entities: z.array(z.object({
+    name: z.string().min(1),
+    type: z.string().min(1),
+    state: z.string().min(1),
+  })),
+  facts: z.array(z.object({
+    subject: z.string().min(1),
+    predicate: z.string().min(1),
+    object: z.string().min(1),
+  })),
+  stateChanges: z.array(z.object({
+    entity: z.string().min(1),
+    before: z.string().min(1),
+    after: z.string().min(1),
+  })),
+  openThreads: z.array(z.string().min(1)),
+});
+
+export const ContinuityReviewSchema = z.object({
+  range: z.object({
+    start: z.number().int().positive(),
+    end: z.number().int().positive(),
+  }),
+  status: z.enum(['clean', 'issues_found']),
+  issues: z.array(z.object({
+    severity: z.enum(['low', 'medium', 'high']),
+    description: z.string().min(1),
+    evidence: z.string().min(1),
+    suggestion: z.string().min(1),
+  })),
+});
+
+export const ChapterReviewIssueSchema = z.object({
+  severity: z.enum(['low', 'medium', 'high']),
+  category: z.enum(['character', 'world', 'timeline', 'item', 'knowledge', 'pacing', 'style', 'architecture']),
+  description: z.string().min(1),
+  evidence: z.string().min(1),
+  suggestion: z.string().min(1),
+});
+
+export const ChapterReviewSchema = z.object({
+  chapterNumber: z.number().int().positive(),
+  status: z.enum(['clean', 'issues_found']),
+  issues: z.array(ChapterReviewIssueSchema),
+});
+
+export const CrossChapterReviewSchema = z.object({
+  range: z.object({
+    start: z.number().int().positive(),
+    end: z.number().int().positive(),
+  }),
+  status: z.enum(['clean', 'issues_found']),
+  issues: z.array(z.object({
+    severity: z.enum(['low', 'medium', 'high']),
+    chapters: z.array(z.number().int().positive()).min(1),
+    description: z.string().min(1),
+    evidence: z.string().min(1),
+    suggestion: z.string().min(1),
+  })),
+});

package/src/core/steps/architecture.ts

@@ -0,0 +1,17 @@
+import { ArchitecturePayloadSchema } from '../schemas.js';
+import { saveJsonFile, saveMarkdownFile } from '../projectStore.js';
+import { StepHandler, parseJson } from './types.js';
+
+export const architectureHandler: StepHandler = async (state, content) => {
+  const parsed = ArchitecturePayloadSchema.parse(parseJson(content));
+  const savedPaths = [
+    await saveMarkdownFile(state.projectPath, 'architecture/full.md', parsed.full),
+    await saveJsonFile(state.projectPath, 'architecture/volumes.json', parsed.volumes),
+    await saveJsonFile(state.projectPath, 'architecture/chapters.json', parsed.chapters),
+  ];
+  return {
+    savedPaths,
+    fileEntries: { architecture: 'architecture/chapters.json' },
+    next: { kind: 'linear', nextStep: 'chapter' },
+  };
+};

package/src/core/steps/chapter.ts

@@ -0,0 +1,17 @@
+import { join } from 'node:path';
+import { saveMarkdownFile } from '../projectStore.js';
+import { chapterFileName } from '../fileNames.js';
+import { indexChapter } from '../retrieval/index.js';
+import { StepHandler, requireNonEmpty } from './types.js';
+
+export const chapterHandler: StepHandler = async (state, content) => {
+  requireNonEmpty(content, 'Chapter Markdown');
+  const relative = join('chapters', chapterFileName(state.currentChapter));
+  const path = await saveMarkdownFile(state.projectPath, relative, content);
+  await indexChapter(state.projectPath, state.currentChapter, content);
+  return {
+    savedPaths: [path],
+    fileEntries: { [`chapter-${state.currentChapter}`]: relative },
+    next: { kind: 'linear', nextStep: 'memory_card' },
+  };
+};

package/src/core/steps/chapterReview.ts

@@ -0,0 +1,17 @@
+import { join } from 'node:path';
+import { ChapterReviewSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { chapterReviewFileName } from '../fileNames.js';
+import { StepHandler, parseJson } from './types.js';
+
+export const chapterReviewHandler: StepHandler = async (state, content) => {
+  const parsed = ChapterReviewSchema.parse(parseJson(content));
+  const target = state.pendingAction?.chapterNumber ?? parsed.chapterNumber;
+  const relative = join('reviews/chapter', chapterReviewFileName(target));
+  const path = await saveJsonFile(state.projectPath, relative, parsed);
+  return {
+    savedPaths: [path],
+    fileEntries: { [`review-chapter-${target}`]: relative },
+    next: { kind: 'sideTrackReturn' },
+  };
+};

package/src/core/steps/chapterRevision.ts

@@ -0,0 +1,21 @@
+import { join } from 'node:path';
+import { archiveChapterVersion, saveMarkdownFile } from '../projectStore.js';
+import { chapterFileName, chapterVersionFileName } from '../fileNames.js';
+import { indexChapter } from '../retrieval/index.js';
+import { StepHandler, requireNonEmpty } from './types.js';
+
+export const chapterRevisionHandler: StepHandler = async (state, content) => {
+  requireNonEmpty(content, 'Chapter revision Markdown');
+  const target = state.pendingAction?.chapterNumber ?? state.currentChapter;
+  const chapterRelative = join('chapters', chapterFileName(target));
+  const versionRelative = join('chapters/.versions', chapterVersionFileName(target, new Date().toISOString()));
+  const archived = await archiveChapterVersion(state.projectPath, chapterRelative, versionRelative);
+  const savedPaths = archived ? [archived] : [];
+  savedPaths.push(await saveMarkdownFile(state.projectPath, chapterRelative, content));
+  await indexChapter(state.projectPath, target, content);
+  return {
+    savedPaths,
+    fileEntries: { [`chapter-${target}`]: chapterRelative },
+    next: { kind: 'sideTrackReturn' },
+  };
+};

package/src/core/steps/continuityReview.ts

@@ -0,0 +1,14 @@
+import { ContinuityReviewSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { StepHandler, parseJson } from './types.js';
+
+export const continuityReviewHandler: StepHandler = async (state, content) => {
+  const parsed = ContinuityReviewSchema.parse(parseJson(content));
+  const relative = `reviews/continuity-${parsed.range.start}-${parsed.range.end}.json`;
+  const path = await saveJsonFile(state.projectPath, relative, parsed);
+  return {
+    savedPaths: [path],
+    fileEntries: { continuityReview: relative },
+    next: { kind: 'linear', nextStep: 'complete' },
+  };
+};

package/src/core/steps/crossChapterReview.ts

@@ -0,0 +1,16 @@
+import { join } from 'node:path';
+import { CrossChapterReviewSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { crossChapterReviewFileName } from '../fileNames.js';
+import { StepHandler, parseJson } from './types.js';
+
+export const crossChapterReviewHandler: StepHandler = async (state, content) => {
+  const parsed = CrossChapterReviewSchema.parse(parseJson(content));
+  const relative = join('reviews/cross', crossChapterReviewFileName(parsed.range.start, parsed.range.end));
+  const path = await saveJsonFile(state.projectPath, relative, parsed);
+  return {
+    savedPaths: [path],
+    fileEntries: { [`review-cross-${parsed.range.start}-${parsed.range.end}`]: relative },
+    next: { kind: 'sideTrackReturn' },
+  };
+};

package/src/core/steps/index.ts

@@ -0,0 +1,25 @@
+import { WorkflowStep } from '../types.js';
+import { architectureHandler } from './architecture.js';
+import { chapterHandler } from './chapter.js';
+import { chapterReviewHandler } from './chapterReview.js';
+import { chapterRevisionHandler } from './chapterRevision.js';
+import { continuityReviewHandler } from './continuityReview.js';
+import { crossChapterReviewHandler } from './crossChapterReview.js';
+import { memoryCardHandler } from './memoryCard.js';
+import { novelMetadataHandler } from './novelMetadata.js';
+import { storyBibleHandler } from './storyBible.js';
+import { StepHandler } from './types.js';
+
+export type { StepApplyNext, StepApplyResult, StepHandler } from './types.js';
+
+export const STEP_HANDLERS: Partial<Record<WorkflowStep, StepHandler>> = {
+  novel_metadata: novelMetadataHandler,
+  story_bible: storyBibleHandler,
+  architecture: architectureHandler,
+  chapter: chapterHandler,
+  memory_card: memoryCardHandler,
+  continuity_review: continuityReviewHandler,
+  chapter_review: chapterReviewHandler,
+  chapter_revision: chapterRevisionHandler,
+  cross_chapter_review: crossChapterReviewHandler,
+};

package/src/core/steps/memoryCard.ts

@@ -0,0 +1,23 @@
+import { join } from 'node:path';
+import { MemoryCardSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { memoryFileName } from '../fileNames.js';
+import { indexMemoryCard } from '../retrieval/index.js';
+import { StepHandler, parseJson } from './types.js';
+
+export const memoryCardHandler: StepHandler = async (state, content) => {
+  const parsed = MemoryCardSchema.parse(parseJson(content));
+  const relative = join('memory', memoryFileName(state.currentChapter));
+  const path = await saveJsonFile(state.projectPath, relative, parsed);
+  await indexMemoryCard(state.projectPath, state.currentChapter, parsed);
+  const nextChapter = state.currentChapter + 1;
+  return {
+    savedPaths: [path],
+    fileEntries: { [`memory-${state.currentChapter}`]: relative },
+    next: {
+      kind: 'linear',
+      nextStep: nextChapter > state.targetChapters ? 'continuity_review' : 'chapter',
+      statePatch: { currentChapter: nextChapter },
+    },
+  };
+};

package/src/core/steps/novelMetadata.ts

@@ -0,0 +1,13 @@
+import { NovelMetadataSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { StepHandler, parseJson } from './types.js';
+
+export const novelMetadataHandler: StepHandler = async (state, content) => {
+  const parsed = NovelMetadataSchema.parse(parseJson(content));
+  const path = await saveJsonFile(state.projectPath, 'novel.json', parsed);
+  return {
+    savedPaths: [path],
+    fileEntries: { novel: 'novel.json' },
+    next: { kind: 'linear', nextStep: 'story_bible' },
+  };
+};

package/src/core/steps/storyBible.ts

@@ -0,0 +1,14 @@
+import { saveMarkdownFile } from '../projectStore.js';
+import { indexStoryBible } from '../retrieval/index.js';
+import { StepHandler, requireNonEmpty } from './types.js';
+
+export const storyBibleHandler: StepHandler = async (state, content) => {
+  requireNonEmpty(content, 'Story bible Markdown');
+  const path = await saveMarkdownFile(state.projectPath, 'story-bible.md', content);
+  await indexStoryBible(state.projectPath, content);
+  return {
+    savedPaths: [path],
+    fileEntries: { storyBible: 'story-bible.md' },
+    next: { kind: 'linear', nextStep: 'architecture' },
+  };
+};

package/src/core/steps/types.ts

@@ -0,0 +1,21 @@
+import { AgentState, WorkflowStep } from '../types.js';
+
+export type StepApplyNext =
+  | { kind: 'linear'; nextStep: WorkflowStep; statePatch?: Partial<AgentState> }
+  | { kind: 'sideTrackReturn' };
+
+export interface StepApplyResult {
+  savedPaths: string[];
+  fileEntries?: Record<string, string>;
+  next: StepApplyNext;
+}
+
+export type StepHandler = (state: AgentState, content: string) => Promise<StepApplyResult>;
+
+export function parseJson(content: string): unknown {
+  return JSON.parse(content);
+}
+
+export function requireNonEmpty(content: string, label: string): void {
+  if (!content.trim()) throw new Error(`${label} is empty`);
+}

package/src/core/types.ts

@@ -0,0 +1,115 @@
+export type WorkflowStep =
+  | 'novel_metadata'
+  | 'story_bible'
+  | 'architecture'
+  | 'chapter'
+  | 'memory_card'
+  | 'continuity_review'
+  | 'chapter_review'
+  | 'chapter_revision'
+  | 'cross_chapter_review'
+  | 'complete';
+
+export type ReviewSeverity = 'low' | 'medium' | 'high';
+
+export interface ChapterReviewIssue {
+  severity: ReviewSeverity;
+  category: 'character' | 'world' | 'timeline' | 'item' | 'knowledge' | 'pacing' | 'style' | 'architecture';
+  description: string;
+  evidence: string;
+  suggestion: string;
+}
+
+export interface ChapterReview {
+  chapterNumber: number;
+  status: 'clean' | 'issues_found';
+  issues: ChapterReviewIssue[];
+}
+
+export interface CrossChapterReview {
+  range: { start: number; end: number };
+  status: 'clean' | 'issues_found';
+  issues: Array<{
+    severity: ReviewSeverity;
+    chapters: number[];
+    description: string;
+    evidence: string;
+    suggestion: string;
+  }>;
+}
+
+export interface CoreCastMember {
+  name: string;
+  role: string;
+  description: string;
+}
+
+export interface NovelMetadata {
+  title: string;
+  genre: string;
+  premise: string;
+  language: string;
+  style: string;
+  coreCast: CoreCastMember[];
+}
+
+export interface VolumeArchitecture {
+  id: string;
+  title: string;
+  summary: string;
+  order: number;
+}
+
+export interface ChapterArchitecture {
+  chapterNumber: number;
+  title: string;
+  volumeId: string;
+  summary: string;
+  requiredBeats: string[];
+}
+
+export interface ArchitecturePayload {
+  full: string;
+  volumes: VolumeArchitecture[];
+  chapters: ChapterArchitecture[];
+}
+
+export interface MemoryCard {
+  summary: string;
+  keyEvents: string[];
+  entities: Array<{ name: string; type: string; state: string }>;
+  facts: Array<{ subject: string; predicate: string; object: string }>;
+  stateChanges: Array<{ entity: string; before: string; after: string }>;
+  openThreads: string[];
+}
+
+export interface PendingAction {
+  step: 'chapter_review' | 'chapter_revision' | 'cross_chapter_review';
+  chapterNumber?: number;
+  range?: { start: number; end: number };
+  feedback?: string;
+}
+
+export interface AgentState {
+  projectId: string;
+  projectPath: string;
+  initialPrompt: string;
+  language: 'zh-CN' | 'en-US';
+  targetChapters: number;
+  currentStep: WorkflowStep;
+  currentChapter: number;
+  completedSteps: WorkflowStep[];
+  files: Record<string, string>;
+  pendingAction?: PendingAction;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface StepInstruction {
+  projectId: string;
+  projectPath: string;
+  currentStep: WorkflowStep;
+  instruction: string;
+  expectedFormat: string;
+  context: string;
+}

package/src/core/workflow.ts

@@ -0,0 +1,250 @@
+import { readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { WorkflowStep, AgentState, PendingAction, StepInstruction } from './types.js';
+import { BuildContextInput, buildContext } from './contextBuilder.js';
+import { buildPromptForStep } from './prompts.js';
+import { loadState, saveJsonFile, saveRecoveryFile, saveState } from './projectStore.js';
+import { STEP_HANDLERS } from './steps/index.js';
+
+export interface SubmitStepInput {
+  projectPath: string;
+  step: WorkflowStep;
+  content: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface SubmitStepResult {
+  validation: { ok: boolean; message: string };
+  state: AgentState;
+  savedPaths: string[];
+  recoveryPath?: string;
+  next?: StepInstruction;
+}
+
+export interface RequestSideTrackInput {
+  projectPath: string;
+  step: PendingAction['step'];
+  chapterNumber?: number;
+  range?: { start: number; end: number };
+  feedback?: string;
+}
+
+// =============================================================================
+// Context recipes — one entry per step that needs packed context.
+// Steps not listed here run with an empty context string.
+// =============================================================================
+
+type ContextRecipe = (state: AgentState) => Omit<BuildContextInput, 'projectPath'>;
+
+const CONTEXT_RECIPES: Partial<Record<WorkflowStep, ContextRecipe>> = {
+  chapter: (s) => ({ purpose: 'chapter_generation', chapterNumber: s.currentChapter }),
+  memory_card: (s) => ({ purpose: 'memory_extraction', chapterNumber: s.currentChapter }),
+  continuity_review: () => ({ purpose: 'continuity_review' }),
+  chapter_review: (s) => ({
+    purpose: 'chapter_review',
+    chapterNumber: s.pendingAction?.chapterNumber ?? s.currentChapter,
+  }),
+  chapter_revision: (s) => ({
+    purpose: 'revision',
+    chapterNumber: s.pendingAction?.chapterNumber ?? s.currentChapter,
+    feedback: s.pendingAction?.feedback,
+  }),
+  cross_chapter_review: (s) => ({
+    purpose: 'cross_chapter_review',
+    range: s.pendingAction?.range,
+  }),
+};
+
+async function contextForStep(state: AgentState): Promise<string> {
+  const recipe = CONTEXT_RECIPES[state.currentStep];
+  if (!recipe) return '';
+  return buildContext({ projectPath: state.projectPath, ...recipe(state) });
+}
+
+async function instructionFor(state: AgentState): Promise<StepInstruction> {
+  const base = {
+    projectId: state.projectId,
+    projectPath: state.projectPath,
+    currentStep: state.currentStep,
+  };
+
+  if (state.currentStep === 'complete') {
+    return { ...base, instruction: 'The workflow is complete.', expectedFormat: 'No output required', context: '' };
+  }
+
+  const context = await contextForStep(state);
+  const prompt = buildPromptForStep({ state, context });
+  return { ...base, instruction: prompt.prompt, expectedFormat: prompt.expectedFormat, context };
+}
+
+export async function getNextStep(projectPath: string): Promise<StepInstruction> {
+  return instructionFor(await loadState(projectPath));
+}
+
+// =============================================================================
+// Side-track plumbing
+// =============================================================================
+
+interface SideTrackEntry {
+  step: PendingAction['step'];
+  resumeStep: WorkflowStep;
+  resumeChapter: number;
+  pendingAction: PendingAction;
+}
+
+const SIDE_TRACK_FILE = '.agent-recovery/side-track.json';
+
+async function saveSideTrack(state: AgentState, entry: SideTrackEntry): Promise<void> {
+  await saveState(state);
+  await saveJsonFile(state.projectPath, SIDE_TRACK_FILE, entry);
+}
+
+async function loadSideTrack(projectPath: string): Promise<SideTrackEntry | undefined> {
+  try {
+    const raw = await readFile(join(projectPath, SIDE_TRACK_FILE), 'utf8');
+    return JSON.parse(raw) as SideTrackEntry;
+  } catch {
+    return undefined;
+  }
+}
+
+async function clearSideTrack(projectPath: string): Promise<void> {
+  try {
+    await unlink(join(projectPath, SIDE_TRACK_FILE));
+  } catch {
+    // ignore: nothing to clear
+  }
+}
+
+function maxExistingChapter(state: AgentState): number {
+  let max = 0;
+  for (const key of Object.keys(state.files)) {
+    const match = key.match(/^chapter-(\d+)$/);
+    if (match) {
+      const num = Number(match[1]);
+      if (num > max) max = num;
+    }
+  }
+  return max;
+}
+
+function buildPendingAction(state: AgentState, input: RequestSideTrackInput): PendingAction {
+  switch (input.step) {
+    case 'chapter_review': {
+      if (!input.chapterNumber) throw new Error('chapter_review requires chapterNumber');
+      return { step: 'chapter_review', chapterNumber: input.chapterNumber };
+    }
+    case 'chapter_revision': {
+      if (!input.chapterNumber) throw new Error('chapter_revision requires chapterNumber');
+      return { step: 'chapter_revision', chapterNumber: input.chapterNumber, feedback: input.feedback };
+    }
+    case 'cross_chapter_review': {
+      const max = maxExistingChapter(state);
+      const range = input.range ?? { start: 1, end: max || state.currentChapter };
+      if (range.start < 1 || range.end < range.start) throw new Error('Invalid range');
+      return { step: 'cross_chapter_review', range };
+    }
+    default:
+      throw new Error(`Unknown side-track step: ${(input as RequestSideTrackInput).step}`);
+  }
+}
+
+export async function requestSideTrack(input: RequestSideTrackInput): Promise<StepInstruction> {
+  const state = await loadState(input.projectPath);
+  const pendingAction = buildPendingAction(state, input);
+  const next: AgentState = { ...state, currentStep: input.step, pendingAction };
+  await saveSideTrack(next, {
+    step: input.step,
+    resumeStep: state.currentStep,
+    resumeChapter: state.currentChapter,
+    pendingAction,
+  });
+  return instructionFor(next);
+}
+
+// =============================================================================
+// Submit dispatcher — thin glue over STEP_HANDLERS
+// =============================================================================
+
+function advanceLinear(
+  state: AgentState,
+  nextStep: WorkflowStep,
+  fileEntries: Record<string, string> = {},
+  statePatch: Partial<AgentState> = {}
+): AgentState {
+  const { pendingAction: _pending, ...rest } = state;
+  return {
+    ...rest,
+    ...statePatch,
+    currentStep: nextStep,
+    completedSteps: [...state.completedSteps, state.currentStep],
+    files: { ...state.files, ...fileEntries },
+  };
+}
+
+async function resumeFromSideTrack(
+  state: AgentState,
+  fileEntries: Record<string, string>
+): Promise<AgentState> {
+  const sideTrack = await loadSideTrack(state.projectPath);
+  await clearSideTrack(state.projectPath);
+  return {
+    ...state,
+    currentStep: sideTrack?.resumeStep ?? state.currentStep,
+    currentChapter: sideTrack?.resumeChapter ?? state.currentChapter,
+    completedSteps: [...state.completedSteps, state.currentStep],
+    files: { ...state.files, ...fileEntries },
+    pendingAction: undefined,
+  };
+}
+
+export async function submitStepResult(input: SubmitStepInput): Promise<SubmitStepResult> {
+  const state = await loadState(input.projectPath);
+
+  if (state.currentStep !== input.step) {
+    const recoveryPath = await saveRecoveryFile(state.projectPath, input.step, input.content);
+    return {
+      validation: { ok: false, message: `Expected step ${state.currentStep}, got ${input.step}` },
+      state,
+      savedPaths: [],
+      recoveryPath,
+      next: await instructionFor(state),
+    };
+  }
+
+  const handler = STEP_HANDLERS[input.step];
+  if (!handler) {
+    return {
+      validation: { ok: false, message: `Step ${input.step} accepts no submission` },
+      state,
+      savedPaths: [],
+      next: await instructionFor(state),
+    };
+  }
+
+  try {
+    const result = await handler(state, input.content);
+    const fileEntries = result.fileEntries ?? {};
+    const nextState =
+      result.next.kind === 'linear'
+        ? advanceLinear(state, result.next.nextStep, fileEntries, result.next.statePatch)
+        : await resumeFromSideTrack(state, fileEntries);
+
+    await saveState(nextState);
+    return {
+      validation: { ok: true, message: 'Saved' },
+      state: nextState,
+      savedPaths: result.savedPaths,
+      next: await instructionFor(nextState),
+    };
+  } catch (error) {
+    const recoveryPath = await saveRecoveryFile(state.projectPath, input.step, input.content);
+    return {
+      validation: { ok: false, message: (error as Error).message },
+      state,
+      savedPaths: [],
+      recoveryPath,
+      next: await instructionFor(state),
+    };
+  }
+}