novelforge-agent 0.1.1 → 0.3.0

package/src/core/steps/chapter.ts

@@ -12,6 +12,16 @@ export const chapterHandler: StepHandler = async (state, content) => {
   return {
     savedPaths: [path],
     fileEntries: { [`chapter-${state.currentChapter}`]: relative },
-    next: { kind: 'linear', nextStep: 'memory_card' },
+    next: {
+      kind: 'linear',
+      nextStep: 'chapter_review',
+      statePatch: {
+        pendingAction: {
+          step: 'chapter_review',
+          mode: 'gate',
+          chapterNumber: state.currentChapter,
+        },
+      },
+    },
   };
 };

package/src/core/steps/chapterReview.ts

@@ -6,12 +6,39 @@ import { StepHandler, parseJson } from './types.js';
 
 export const chapterReviewHandler: StepHandler = async (state, content) => {
   const parsed = ChapterReviewSchema.parse(parseJson(content));
+  const hasFailedAcceptance = Object.values(parsed.acceptance).some((check) => check.status === 'fail');
   const target = state.pendingAction?.chapterNumber ?? parsed.chapterNumber;
   const relative = join('reviews/chapter', chapterReviewFileName(target));
   const path = await saveJsonFile(state.projectPath, relative, parsed);
+  if (state.pendingAction?.mode === 'side_track') {
+    return {
+      savedPaths: [path],
+      fileEntries: { [`review-chapter-${target}`]: relative },
+      next: { kind: 'sideTrackReturn' },
+    };
+  }
+
+  if (parsed.status === 'clean' && !hasFailedAcceptance) {
+    return {
+      savedPaths: [path],
+      fileEntries: { [`review-chapter-${target}`]: relative },
+      next: { kind: 'linear', nextStep: 'memory_card' },
+    };
+  }
+
   return {
     savedPaths: [path],
     fileEntries: { [`review-chapter-${target}`]: relative },
-    next: { kind: 'sideTrackReturn' },
+    next: {
+      kind: 'linear',
+      nextStep: 'chapter_revision',
+      statePatch: {
+        pendingAction: {
+          step: 'chapter_revision',
+          mode: 'gate',
+          chapterNumber: target,
+        },
+      },
+    },
   };
 };

package/src/core/steps/chapterRevision.ts

@@ -13,6 +13,24 @@ export const chapterRevisionHandler: StepHandler = async (state, content) => {
   const savedPaths = archived ? [archived] : [];
   savedPaths.push(await saveMarkdownFile(state.projectPath, chapterRelative, content));
   await indexChapter(state.projectPath, target, content);
+  if (state.pendingAction?.mode === 'gate') {
+    return {
+      savedPaths,
+      fileEntries: { [`chapter-${target}`]: chapterRelative },
+      next: {
+        kind: 'linear',
+        nextStep: 'chapter_review',
+        statePatch: {
+          pendingAction: {
+            step: 'chapter_review',
+            mode: 'gate',
+            chapterNumber: target,
+          },
+        },
+      },
+    };
+  }
+
   return {
     savedPaths,
     fileEntries: { [`chapter-${target}`]: chapterRelative },

package/src/core/steps/index.ts

@@ -1,4 +1,5 @@
 import { WorkflowStep } from '../types.js';
+import { architectureExtensionHandler } from './architectureExtension.js';
 import { architectureHandler } from './architecture.js';
 import { chapterHandler } from './chapter.js';
 import { chapterReviewHandler } from './chapterReview.js';
@@ -7,6 +8,7 @@ import { continuityReviewHandler } from './continuityReview.js';
 import { crossChapterReviewHandler } from './crossChapterReview.js';
 import { memoryCardHandler } from './memoryCard.js';
 import { novelMetadataHandler } from './novelMetadata.js';
+import { styleGuideHandler } from './styleGuide.js';
 import { storyBibleHandler } from './storyBible.js';
 import { StepHandler } from './types.js';
 
@@ -15,7 +17,9 @@ export type { StepApplyNext, StepApplyResult, StepHandler } from './types.js';
 export const STEP_HANDLERS: Partial<Record<WorkflowStep, StepHandler>> = {
   novel_metadata: novelMetadataHandler,
   story_bible: storyBibleHandler,
+  style_guide: styleGuideHandler,
   architecture: architectureHandler,
+  architecture_extension: architectureExtensionHandler,
   chapter: chapterHandler,
   memory_card: memoryCardHandler,
   continuity_review: continuityReviewHandler,

package/src/core/steps/memoryCard.ts

@@ -1,22 +1,48 @@
+import { readFile } from 'node:fs/promises';
 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 { ingestMemoryCardThreads } from '../threadStore.js';
+import { applyCharacterUpdates } from '../characterStore.js';
 import { StepHandler, parseJson } from './types.js';
 
+async function maxPlannedChapter(projectPath: string): Promise<number> {
+  try {
+    const raw = await readFile(join(projectPath, 'architecture/chapters.json'), 'utf8');
+    const chapters = JSON.parse(raw) as Array<{ chapterNumber?: number }>;
+    return chapters.reduce((max, chapter) => {
+      const value = Number(chapter.chapterNumber);
+      return Number.isFinite(value) && value > max ? value : max;
+    }, 0);
+  } catch {
+    return 0;
+  }
+}
+
 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);
+  await ingestMemoryCardThreads(state.projectPath, state.currentChapter, parsed.threadActions);
+  await applyCharacterUpdates(state.projectPath, state.currentChapter, parsed.characterUpdates);
   const nextChapter = state.currentChapter + 1;
+  const plannedTotalChapters = state.plannedTotalChapters ?? state.targetChapters;
+  const plannedMax = await maxPlannedChapter(state.projectPath);
+  const nextStep =
+    nextChapter > plannedTotalChapters
+      ? 'continuity_review'
+      : nextChapter > plannedMax
+        ? 'architecture_extension'
+        : 'chapter';
   return {
     savedPaths: [path],
     fileEntries: { [`memory-${state.currentChapter}`]: relative },
     next: {
       kind: 'linear',
-      nextStep: nextChapter > state.targetChapters ? 'continuity_review' : 'chapter',
+      nextStep,
       statePatch: { currentChapter: nextChapter },
     },
   };

package/src/core/steps/novelMetadata.ts

@@ -1,13 +1,15 @@
 import { NovelMetadataSchema } from '../schemas.js';
 import { saveJsonFile } from '../projectStore.js';
+import { initializeCharacterStates } from '../characterStore.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);
+  const charactersPath = await initializeCharacterStates(state.projectPath, parsed.coreCast);
   return {
-    savedPaths: [path],
-    fileEntries: { novel: 'novel.json' },
+    savedPaths: [path, charactersPath],
+    fileEntries: { novel: 'novel.json', characters: 'characters.json' },
     next: { kind: 'linear', nextStep: 'story_bible' },
   };
 };

package/src/core/steps/storyBible.ts

@@ -9,6 +9,6 @@ export const storyBibleHandler: StepHandler = async (state, content) => {
   return {
     savedPaths: [path],
     fileEntries: { storyBible: 'story-bible.md' },
-    next: { kind: 'linear', nextStep: 'architecture' },
+    next: { kind: 'linear', nextStep: 'style_guide' },
   };
 };

package/src/core/steps/styleGuide.ts

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

package/src/core/threadStore.ts

@@ -0,0 +1,173 @@
+import { randomBytes } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Thread, ThreadAction, ThreadStatus } from './types.js';
+
+const THREADS_FILE = 'threads.json';
+
+export interface ThreadsBundle {
+  threads: Thread[];
+}
+
+export async function loadThreads(projectPath: string): Promise<Thread[]> {
+  try {
+    const raw = await readFile(join(projectPath, THREADS_FILE), 'utf8');
+    const parsed = JSON.parse(raw) as ThreadsBundle;
+    return Array.isArray(parsed.threads) ? parsed.threads : [];
+  } catch {
+    return [];
+  }
+}
+
+export async function saveThreads(projectPath: string, threads: Thread[]): Promise<string> {
+  const fullPath = join(projectPath, THREADS_FILE);
+  const bundle: ThreadsBundle = { threads };
+  await writeFile(fullPath, `${JSON.stringify(bundle, null, 2)}\n`, 'utf8');
+  return fullPath;
+}
+
+function newThreadId(existing: Set<string>): string {
+  let candidate = `t_${randomBytes(3).toString('hex')}`;
+  while (existing.has(candidate)) {
+    candidate = `t_${randomBytes(3).toString('hex')}`;
+  }
+  return candidate;
+}
+
+function findByDescription(threads: Thread[], description: string): Thread | undefined {
+  const target = description.trim();
+  return threads.find((t) => t.description.trim() === target);
+}
+
+/**
+ * Apply the threadActions emitted by a memory_card for chapter `chapterNumber`.
+ * Behavior:
+ *  - 'plant'   → create new thread (or reuse if identical description already planted)
+ *  - 'build'   → mark existing thread status = 'building', bump lastTouchedAt
+ *  - 'pay'     → mark existing thread status = 'paid', set paidOffAt
+ *  - 'drop'    → mark existing thread status = 'dropped', set droppedAt
+ *  Unknown threadIds for non-plant actions are tolerated (a new thread is created and marked appropriately, so we never lose user intent).
+ */
+export function applyThreadActions(
+  existing: Thread[],
+  chapterNumber: number,
+  actions: ThreadAction[]
+): Thread[] {
+  if (!actions || !actions.length) return existing;
+  const next: Thread[] = existing.map((t) => ({ ...t }));
+  const byId = new Map(next.map((t) => [t.id, t]));
+  const usedIds = new Set(next.map((t) => t.id));
+
+  for (const action of actions) {
+    if (action.kind === 'plant') {
+      const dup = findByDescription(next, action.description);
+      if (dup) {
+        dup.lastTouchedAt = Math.max(dup.lastTouchedAt, chapterNumber);
+        continue;
+      }
+      const id = action.threadId && !usedIds.has(action.threadId)
+        ? action.threadId
+        : newThreadId(usedIds);
+      usedIds.add(id);
+      const planted: Thread = {
+        id,
+        description: action.description.trim(),
+        status: 'planted',
+        plantedAt: chapterNumber,
+        lastTouchedAt: chapterNumber,
+      };
+      next.push(planted);
+      byId.set(id, planted);
+      continue;
+    }
+
+    // build / pay / drop need an existing thread
+    let target = action.threadId ? byId.get(action.threadId) : undefined;
+    if (!target) {
+      target = findByDescription(next, action.description);
+    }
+    if (!target) {
+      // Create a placeholder so the user intent is captured; mark planted+touched on this chapter
+      const id = newThreadId(usedIds);
+      usedIds.add(id);
+      target = {
+        id,
+        description: action.description.trim(),
+        status: 'planted',
+        plantedAt: chapterNumber,
+        lastTouchedAt: chapterNumber,
+        notes: `Auto-created from a ${action.kind} action without a known threadId.`,
+      };
+      next.push(target);
+      byId.set(id, target);
+    }
+
+    target.lastTouchedAt = chapterNumber;
+    if (action.kind === 'build') {
+      target.status = 'building';
+    } else if (action.kind === 'pay') {
+      target.status = 'paid';
+      target.paidOffAt = chapterNumber;
+    } else if (action.kind === 'drop') {
+      target.status = 'dropped';
+      target.droppedAt = chapterNumber;
+    }
+  }
+
+  return next;
+}
+
+export function activeThreads(threads: Thread[]): Thread[] {
+  return threads.filter((t) => t.status === 'planted' || t.status === 'building');
+}
+
+export async function ingestMemoryCardThreads(
+  projectPath: string,
+  chapterNumber: number,
+  actions: ThreadAction[] | undefined
+): Promise<Thread[]> {
+  if (!actions || !actions.length) return loadThreads(projectPath);
+  const existing = await loadThreads(projectPath);
+  const next = applyThreadActions(existing, chapterNumber, actions);
+  await saveThreads(projectPath, next);
+  return next;
+}
+
+export interface UpdateThreadPatch {
+  status?: ThreadStatus;
+  plannedPayoffAt?: number | null;
+  paidOffAt?: number | null;
+  droppedAt?: number | null;
+  description?: string;
+  notes?: string | null;
+}
+
+export async function updateThread(
+  projectPath: string,
+  id: string,
+  patch: UpdateThreadPatch
+): Promise<Thread> {
+  const existing = await loadThreads(projectPath);
+  const target = existing.find((t) => t.id === id);
+  if (!target) throw new Error(`Thread not found: ${id}`);
+  if (patch.status) target.status = patch.status;
+  if (patch.description) target.description = patch.description.trim();
+  if (Object.prototype.hasOwnProperty.call(patch, 'plannedPayoffAt')) {
+    if (patch.plannedPayoffAt === null) delete target.plannedPayoffAt;
+    else if (typeof patch.plannedPayoffAt === 'number') target.plannedPayoffAt = patch.plannedPayoffAt;
+  }
+  if (Object.prototype.hasOwnProperty.call(patch, 'paidOffAt')) {
+    if (patch.paidOffAt === null) delete target.paidOffAt;
+    else if (typeof patch.paidOffAt === 'number') target.paidOffAt = patch.paidOffAt;
+  }
+  if (Object.prototype.hasOwnProperty.call(patch, 'droppedAt')) {
+    if (patch.droppedAt === null) delete target.droppedAt;
+    else if (typeof patch.droppedAt === 'number') target.droppedAt = patch.droppedAt;
+  }
+  if (Object.prototype.hasOwnProperty.call(patch, 'notes')) {
+    if (patch.notes === null) delete target.notes;
+    else if (typeof patch.notes === 'string') target.notes = patch.notes;
+  }
+  await saveThreads(projectPath, existing);
+  return target;
+}

package/src/core/types.ts

@@ -1,28 +1,60 @@
 export type WorkflowStep =
   | 'novel_metadata'
   | 'story_bible'
+  | 'style_guide'
   | 'architecture'
+  | 'architecture_extension'
   | 'chapter'
   | 'memory_card'
   | 'continuity_review'
   | 'chapter_review'
   | 'chapter_revision'
   | 'cross_chapter_review'
+  | 'story_bible_amend'
   | 'complete';
 
 export type ReviewSeverity = 'low' | 'medium' | 'high';
 
 export interface ChapterReviewIssue {
   severity: ReviewSeverity;
-  category: 'character' | 'world' | 'timeline' | 'item' | 'knowledge' | 'pacing' | 'style' | 'architecture';
+  category:
+    | 'character'
+    | 'world'
+    | 'timeline'
+    | 'item'
+    | 'knowledge'
+    | 'pacing'
+    | 'style'
+    | 'architecture'
+    | 'plot'
+    | 'foreshadow'
+    | 'hook'
+    | 'repetition';
   description: string;
   evidence: string;
   suggestion: string;
 }
 
+export interface ChapterAcceptanceCheck {
+  status: 'pass' | 'fail';
+  evidence: string;
+}
+
+export interface ChapterAcceptanceGate {
+  requiredBeats: ChapterAcceptanceCheck & { missingBeats: string[] };
+  narrativeProgress: ChapterAcceptanceCheck;
+  characterProgress: ChapterAcceptanceCheck;
+  foreshadowProgress: ChapterAcceptanceCheck;
+  storyBibleConsistency: ChapterAcceptanceCheck;
+  proseRhythm: ChapterAcceptanceCheck;
+  endingHook: ChapterAcceptanceCheck;
+  repetition: ChapterAcceptanceCheck;
+}
+
 export interface ChapterReview {
   chapterNumber: number;
   status: 'clean' | 'issues_found';
+  acceptance: ChapterAcceptanceGate;
   issues: ChapterReviewIssue[];
 }
 
@@ -53,6 +85,23 @@ export interface NovelMetadata {
   coreCast: CoreCastMember[];
 }
 
+export interface StyleGuide {
+  narrativeVoice: string;
+  pacing: string;
+  diction: string;
+  dialogueRules: string[];
+  prohibitedPatterns: string[];
+  proseRhythm: {
+    sentenceRhythm: string;
+    paragraphing: string;
+    interiorityMode: string;
+    emphasisBudget: string;
+    antiPatterns: string[];
+  };
+  sampleParagraph: string;
+  consistencyChecks: string[];
+}
+
 export interface VolumeArchitecture {
   id: string;
   title: string;
@@ -60,20 +109,95 @@ export interface VolumeArchitecture {
   order: number;
 }
 
+export interface VolumePacingBoard {
+  volumeId: string;
+  start: string;
+  promise: string;
+  keyTurns: string[];
+  midpoint: string;
+  climax: string;
+  payoffs: string[];
+  lingeringMysteries: string[];
+}
+
+export type EndHookFocus = 'cliffhanger' | 'mystery' | 'emotional' | 'reveal' | 'volume_close' | 'gentle';
+
 export interface ChapterArchitecture {
   chapterNumber: number;
   title: string;
   volumeId: string;
   summary: string;
   requiredBeats: string[];
+  targetWords?: number;
+  requireRecap?: boolean;
+  endHookFocus?: EndHookFocus;
+  povCharacter?: string;
 }
 
 export interface ArchitecturePayload {
   full: string;
   volumes: VolumeArchitecture[];
+  volumePacing?: VolumePacingBoard[];
+  chapters: ChapterArchitecture[];
+}
+
+export interface ArchitectureExtensionPayload {
+  fullUpdate?: string;
+  volumes?: VolumeArchitecture[];
+  volumePacing?: VolumePacingBoard[];
   chapters: ChapterArchitecture[];
 }
 
+export type ThreadStatus = 'planted' | 'building' | 'paid' | 'dropped';
+
+export type ThreadActionKind = 'plant' | 'build' | 'pay' | 'drop';
+
+export interface ThreadAction {
+  kind: ThreadActionKind;
+  threadId?: string;     // existing thread id; required for build/pay/drop
+  description: string;   // for plant: the new thread description; for others: how this chapter touched it
+}
+
+export interface Thread {
+  id: string;
+  description: string;
+  status: ThreadStatus;
+  plantedAt: number;
+  lastTouchedAt: number;
+  plannedPayoffAt?: number;
+  paidOffAt?: number;
+  droppedAt?: number;
+  notes?: string;
+}
+
+export interface CharacterRelationshipState {
+  name: string;
+  dynamic: string;
+}
+
+export interface CharacterState {
+  name: string;
+  role?: string;
+  goal: string;
+  belief: string;
+  relationships: CharacterRelationshipState[];
+  abilities: string[];
+  secrets: string[];
+  emotionalState: string;
+  lastUpdatedAt: number;
+}
+
+export interface CharacterStateUpdate {
+  name: string;
+  role?: string;
+  goal?: string;
+  belief?: string;
+  relationships?: CharacterRelationshipState[];
+  abilities?: string[];
+  secrets?: string[];
+  emotionalState?: string;
+}
+
 export interface MemoryCard {
   summary: string;
   keyEvents: string[];
@@ -81,10 +205,14 @@ export interface MemoryCard {
   facts: Array<{ subject: string; predicate: string; object: string }>;
   stateChanges: Array<{ entity: string; before: string; after: string }>;
   openThreads: string[];
+  wordCount?: number;
+  threadActions?: ThreadAction[];
+  characterUpdates?: CharacterStateUpdate[];
 }
 
 export interface PendingAction {
   step: 'chapter_review' | 'chapter_revision' | 'cross_chapter_review';
+  mode?: 'side_track' | 'gate';
   chapterNumber?: number;
   range?: { start: number; end: number };
   feedback?: string;
@@ -95,7 +223,12 @@ export interface AgentState {
   projectPath: string;
   initialPrompt: string;
   language: 'zh-CN' | 'en-US';
+  /**
+   * Number of chapters to plan in each architecture batch.
+   * The whole-book target lives in plannedTotalChapters.
+   */
   targetChapters: number;
+  plannedTotalChapters: number;
   currentStep: WorkflowStep;
   currentChapter: number;
   completedSteps: WorkflowStep[];

package/src/core/workflow.ts

@@ -37,6 +37,8 @@ export interface RequestSideTrackInput {
 type ContextRecipe = (state: AgentState) => Omit<BuildContextInput, 'projectPath'>;
 
 const CONTEXT_RECIPES: Partial<Record<WorkflowStep, ContextRecipe>> = {
+  style_guide: () => ({ purpose: 'style_guide' }),
+  architecture_extension: (s) => ({ purpose: 'architecture_extension', chapterNumber: s.currentChapter }),
   chapter: (s) => ({ purpose: 'chapter_generation', chapterNumber: s.currentChapter }),
   memory_card: (s) => ({ purpose: 'memory_extraction', chapterNumber: s.currentChapter }),
   continuity_review: () => ({ purpose: 'continuity_review' }),
@@ -132,17 +134,17 @@ function buildPendingAction(state: AgentState, input: RequestSideTrackInput): Pe
   switch (input.step) {
     case 'chapter_review': {
       if (!input.chapterNumber) throw new Error('chapter_review requires chapterNumber');
-      return { step: 'chapter_review', chapterNumber: input.chapterNumber };
+      return { step: 'chapter_review', mode: 'side_track', 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 };
+      return { step: 'chapter_revision', mode: 'side_track', 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 };
+      return { step: 'cross_chapter_review', mode: 'side_track', range };
     }
     default:
       throw new Error(`Unknown side-track step: ${(input as RequestSideTrackInput).step}`);