novelforge-agent 0.2.0 → 0.3.0

package/dist/src/core/steps/architectureExtension.js

@@ -0,0 +1,72 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ArchitectureExtensionPayloadSchema } from '../schemas.js';
+import { saveJsonFile, saveMarkdownFile } from '../projectStore.js';
+import { parseJson } from './types.js';
+async function readJsonArray(projectPath, relativePath) {
+    try {
+        const raw = await readFile(join(projectPath, relativePath), 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function assertContiguousExtension(state, existing, nextChapters) {
+    const expectedStart = state.currentChapter;
+    const total = state.plannedTotalChapters ?? state.targetChapters;
+    const existingNumbers = new Set(existing.map((chapter) => chapter.chapterNumber));
+    for (let index = 0; index < nextChapters.length; index += 1) {
+        const chapter = nextChapters[index];
+        const expected = expectedStart + index;
+        if (chapter.chapterNumber !== expected) {
+            throw new Error(`architecture_extension chapters must start at chapter ${expectedStart} and be contiguous; expected ${expected}, got ${chapter.chapterNumber}`);
+        }
+        if (chapter.chapterNumber > total) {
+            throw new Error(`architecture_extension chapter ${chapter.chapterNumber} exceeds plannedTotalChapters ${total}`);
+        }
+        if (existingNumbers.has(chapter.chapterNumber)) {
+            throw new Error(`architecture_extension cannot overwrite existing chapter architecture ${chapter.chapterNumber}`);
+        }
+    }
+}
+function mergeByKey(existing, incoming, keyOf) {
+    const map = new Map();
+    for (const item of existing)
+        map.set(keyOf(item), item);
+    for (const item of incoming ?? [])
+        map.set(keyOf(item), item);
+    return [...map.values()];
+}
+export const architectureExtensionHandler = async (state, content) => {
+    const parsed = ArchitectureExtensionPayloadSchema.parse(parseJson(content));
+    const existingChapters = await readJsonArray(state.projectPath, 'architecture/chapters.json');
+    assertContiguousExtension(state, existingChapters, parsed.chapters);
+    const chapters = [...existingChapters, ...parsed.chapters]
+        .sort((a, b) => a.chapterNumber - b.chapterNumber);
+    const existingVolumes = await readJsonArray(state.projectPath, 'architecture/volumes.json');
+    const volumes = mergeByKey(existingVolumes, parsed.volumes, (volume) => volume.id)
+        .sort((a, b) => a.order - b.order);
+    const existingPacing = await readJsonArray(state.projectPath, 'architecture/volume-pacing.json');
+    const volumePacing = mergeByKey(existingPacing, parsed.volumePacing, (board) => board.volumeId);
+    const savedPaths = [
+        await saveJsonFile(state.projectPath, 'architecture/chapters.json', chapters),
+        await saveJsonFile(state.projectPath, 'architecture/volumes.json', volumes),
+    ];
+    const hasVolumePacing = Boolean(parsed.volumePacing || existingPacing.length);
+    if (hasVolumePacing) {
+        savedPaths.push(await saveJsonFile(state.projectPath, 'architecture/volume-pacing.json', volumePacing));
+    }
+    if (parsed.fullUpdate) {
+        savedPaths.push(await saveMarkdownFile(state.projectPath, 'architecture/full.md', parsed.fullUpdate));
+    }
+    return {
+        savedPaths,
+        fileEntries: {
+            architecture: 'architecture/chapters.json',
+            ...(hasVolumePacing ? { volumePacing: 'architecture/volume-pacing.json' } : {}),
+        },
+        next: { kind: 'linear', nextStep: 'chapter' },
+    };
+};

package/dist/src/core/steps/chapterReview.js

@@ -5,6 +5,7 @@ import { chapterReviewFileName } from '../fileNames.js';
 import { parseJson } from './types.js';
 export const chapterReviewHandler = 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);
@@ -15,7 +16,7 @@ export const chapterReviewHandler = async (state, content) => {
             next: { kind: 'sideTrackReturn' },
         };
     }
-    if (parsed.status === 'clean') {
+    if (parsed.status === 'clean' && !hasFailedAcceptance) {
         return {
             savedPaths: [path],
             fileEntries: { [`review-chapter-${target}`]: relative },

package/dist/src/core/steps/index.js

@@ -1,3 +1,4 @@
+import { architectureExtensionHandler } from './architectureExtension.js';
 import { architectureHandler } from './architecture.js';
 import { chapterHandler } from './chapter.js';
 import { chapterReviewHandler } from './chapterReview.js';
@@ -6,11 +7,14 @@ 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';
 export const STEP_HANDLERS = {
     novel_metadata: novelMetadataHandler,
     story_bible: storyBibleHandler,
+    style_guide: styleGuideHandler,
     architecture: architectureHandler,
+    architecture_extension: architectureExtensionHandler,
     chapter: chapterHandler,
     memory_card: memoryCardHandler,
     continuity_review: continuityReviewHandler,

package/dist/src/core/steps/memoryCard.js

@@ -1,3 +1,4 @@
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { MemoryCardSchema } from '../schemas.js';
 import { saveJsonFile } from '../projectStore.js';
@@ -6,6 +7,19 @@ import { indexMemoryCard } from '../retrieval/index.js';
 import { ingestMemoryCardThreads } from '../threadStore.js';
 import { applyCharacterUpdates } from '../characterStore.js';
 import { parseJson } from './types.js';
+async function maxPlannedChapter(projectPath) {
+    try {
+        const raw = await readFile(join(projectPath, 'architecture/chapters.json'), 'utf8');
+        const chapters = JSON.parse(raw);
+        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 = async (state, content) => {
     const parsed = MemoryCardSchema.parse(parseJson(content));
     const relative = join('memory', memoryFileName(state.currentChapter));
@@ -14,12 +28,19 @@ export const memoryCardHandler = async (state, content) => {
     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/dist/src/core/steps/storyBible.js

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

package/dist/src/core/steps/styleGuide.js

@@ -0,0 +1,12 @@
+import { StyleGuideSchema } from '../schemas.js';
+import { saveJsonFile } from '../projectStore.js';
+import { parseJson } from './types.js';
+export const styleGuideHandler = 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/dist/src/core/workflow.js

@@ -5,6 +5,8 @@ import { buildPromptForStep } from './prompts.js';
 import { loadState, saveJsonFile, saveRecoveryFile, saveState } from './projectStore.js';
 import { STEP_HANDLERS } from './steps/index.js';
 const CONTEXT_RECIPES = {
+    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' }),

package/dist/src/mcp/tools.js

@@ -1,8 +1,28 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { amendStoryBible, assertProjectPath, buildContext, createProject, deleteChapter, forkProject, getNextStep, getProjectStatus, listProjects, listStoryBibleVersions, loadState, loadThreads, redoStep, requestSideTrack, retrieve, submitStepResult, updateThread, } from '../core/index.js';
-const MCP_SERVER_VERSION = '0.2.0';
+function packageVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        try {
+            const raw = readFileSync(join(dir, 'package.json'), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.version === 'string' && parsed.version)
+                return parsed.version;
+        }
+        catch {
+            // keep walking upward until the package root is found
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return '0.0.0';
+        dir = parent;
+    }
+}
+const MCP_SERVER_VERSION = packageVersion();
 function textResult(value) {
     return {
         content: [{
@@ -28,14 +48,16 @@ export function createNovelAgentServer(options) {
         prompt: z.string().min(1),
         language: z.enum(['zh-CN', 'en-US']).default('zh-CN'),
         outputDir: z.string().default('novels'),
-        targetChapters: z.number().int().positive().default(3),
-    }, async ({ prompt, language, outputDir, targetChapters }) => {
+        targetChapters: z.number().int().positive().default(5),
+        plannedTotalChapters: z.number().int().positive().default(12),
+    }, async ({ prompt, language, outputDir, targetChapters, plannedTotalChapters }) => {
         const result = await createProject({
             workspaceRoot: options.workspaceRoot,
             prompt,
             language,
             outputDir,
             targetChapters,
+            plannedTotalChapters,
         });
         return textResult({ state: result.state, next: await getNextStep(result.state.projectPath) });
     });
@@ -49,7 +71,9 @@ export function createNovelAgentServer(options) {
         step: z.enum([
             'novel_metadata',
             'story_bible',
+            'style_guide',
             'architecture',
+            'architecture_extension',
             'chapter',
             'memory_card',
             'continuity_review',
@@ -64,6 +88,8 @@ export function createNovelAgentServer(options) {
         projectPath: z.string().min(1),
         purpose: z.enum([
             'chapter_generation',
+            'style_guide',
+            'architecture_extension',
             'memory_extraction',
             'continuity_review',
             'revision',
@@ -177,6 +203,7 @@ export function createNovelAgentServer(options) {
         step: z.enum([
             'novel_metadata',
             'story_bible',
+            'style_guide',
             'architecture',
             'chapter',
             'memory_card',
@@ -187,13 +214,14 @@ export function createNovelAgentServer(options) {
     // ===== MCP Prompts (slash commands) =====
     server.prompt('nf-start', 'Start a brand new novel project under the configured workspace.', {
         prompt: z.string().describe('User idea / premise / genre, in any language.'),
-        chapters: z.string().optional().describe('Target number of chapters as a string. Defaults to 5.'),
-    }, ({ prompt, chapters }) => ({
+        chapters: z.string().optional().describe('Planning batch size as a string. Defaults to 5.'),
+        totalChapters: z.string().optional().describe('Whole-book target chapter count as a string. Defaults to 12.'),
+    }, ({ prompt, chapters, totalChapters }) => ({
         messages: [{
                 role: 'user',
                 content: {
                     type: 'text',
-                    text: `Use the novelforge MCP server. Call start_novel_project with prompt="${prompt}", targetChapters=${chapters ?? '5'}, then enter the autonomous loop: read next.instruction, generate the requested content, call submit_step_result, repeat until currentStep is "complete". Show me the projectPath after start_novel_project returns.`,
+                    text: `Use the novelforge MCP server. Call start_novel_project with prompt="${prompt}", targetChapters=${chapters ?? '5'}, plannedTotalChapters=${totalChapters ?? '12'}, then enter the autonomous loop: read next.instruction, generate the requested content, call submit_step_result, repeat until currentStep is "complete". Show me the projectPath after start_novel_project returns.`,
                 },
             }],
     }));
@@ -213,7 +241,7 @@ export function createNovelAgentServer(options) {
                 role: 'user',
                 content: {
                     type: 'text',
-                    text: 'Use the novelforge MCP server: call list_projects with no arguments. Show me the result in a compact table (title, currentStep, chaptersWritten/targetChapters, updatedAt, projectPath).',
+                    text: 'Use the novelforge MCP server: call list_projects with no arguments. Show me the result in a compact table (title, currentStep, chaptersWritten/plannedTotalChapters, updatedAt, projectPath).',
                 },
             }],
     }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novelforge-agent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local-first long-form novel workflow engine for any MCP host (Claude Code, Codex CLI, …) or CLI. State machine + zod schemas + BM25 retrieval + persistent project state. No LLM dependency.",
   "keywords": [
     "mcp",

package/src/cli/index.ts

@@ -54,9 +54,17 @@ export async function runCli(argv = process.argv.slice(2), cwd = process.cwd()):
     const prompt = valueAfter(argv, '--prompt') || '';
     if (!prompt.trim()) throw new Error('Missing --prompt');
     const language = parseLanguage(valueAfter(argv, '--language') || 'zh-CN');
-    const chapters = Number(valueAfter(argv, '--chapters') || 3);
+    const chapters = Number(valueAfter(argv, '--chapters') || 5);
+    const totalChapters = Number(valueAfter(argv, '--total-chapters') || 12);
     const outputDir = valueAfter(argv, '--output') || 'novels';
-    const result = await createProject({ workspaceRoot: cwd, prompt, language, outputDir, targetChapters: chapters });
+    const result = await createProject({
+      workspaceRoot: cwd,
+      prompt,
+      language,
+      outputDir,
+      targetChapters: chapters,
+      plannedTotalChapters: totalChapters,
+    });
     const next = await getNextStep(result.state.projectPath);
     console.log(JSON.stringify({ state: result.state, next }, null, 2));
     return;
@@ -217,7 +225,7 @@ export async function runCli(argv = process.argv.slice(2), cwd = process.cwd()):
   if (command === 'redo') {
     if (!projectPath) throw new Error('Missing projectPath');
     const step = valueAfter(argv, '--step') as
-      | 'novel_metadata' | 'story_bible' | 'architecture' | 'chapter' | 'memory_card' | 'continuity_review'
+      | 'novel_metadata' | 'story_bible' | 'style_guide' | 'architecture' | 'chapter' | 'memory_card' | 'continuity_review'
       | undefined;
     if (!step) throw new Error('Missing --step');
     const chapter = valueAfter(argv, '--chapter');

package/src/core/contextBuilder.ts

@@ -6,6 +6,8 @@ import { activeThreads, loadThreads } from './threadStore.js';
 
 export type ContextPurpose =
   | 'chapter_generation'
+  | 'style_guide'
+  | 'architecture_extension'
   | 'memory_extraction'
   | 'continuity_review'
   | 'revision'
@@ -32,12 +34,14 @@ export async function buildContext(input: BuildContextInput): Promise<string> {
   const parts: string[] = [];
   const metadata = await readOptional(join(input.projectPath, 'novel.json'));
   const storyBible = await readOptional(join(input.projectPath, 'story-bible.md'));
+  const styleGuideJson = await readOptional(join(input.projectPath, 'style-guide.json'));
   const chaptersJson = await readOptional(join(input.projectPath, 'architecture/chapters.json'));
   const charactersJson = await readOptional(join(input.projectPath, 'characters.json'));
   const volumePacingJson = await readOptional(join(input.projectPath, 'architecture/volume-pacing.json'));
 
   if (metadata) parts.push(`## Novel Metadata\n${metadata}`);
   if (storyBible) parts.push(`## Story Bible\n${storyBible.slice(0, 4000)}`);
+  if (styleGuideJson) parts.push(`## Style Guide\n${styleGuideJson}`);
   if (charactersJson) parts.push(`## Character State Table\n${charactersJson}`);
 
   function addVolumePacing(volumeId?: string): void {
@@ -113,6 +117,32 @@ export async function buildContext(input: BuildContextInput): Promise<string> {
     if (memoryParts.length) parts.push(`## Memory Cards\n${memoryParts.join('\n')}`);
   }
 
+  if (input.purpose === 'architecture_extension') {
+    if (chaptersJson) parts.push(`## Existing Chapter Architecture List\n${chaptersJson}`);
+    if (volumePacingJson) parts.push(`## Existing Volume Pacing Boards\n${volumePacingJson}`);
+
+    const start = Math.max(1, (input.chapterNumber ?? 1) - 5);
+    const end = Math.max(0, (input.chapterNumber ?? 1) - 1);
+    const memoryParts: string[] = [];
+    for (let i = start; i <= end; i += 1) {
+      const memory = await readOptional(join(input.projectPath, 'memory', memoryFileName(i)));
+      if (memory) memoryParts.push(`### Chapter ${i} Memory\n${memory}`);
+    }
+    if (memoryParts.length) parts.push(`## Recent Memory Cards\n${memoryParts.join('\n')}`);
+
+    const allThreads = await loadThreads(input.projectPath);
+    const active = activeThreads(allThreads);
+    if (active.length) {
+      const lines = active.map((t) => {
+        const flags: string[] = [`#${t.id}`, `status=${t.status}`, `planted=ch${t.plantedAt}`];
+        if (t.plannedPayoffAt) flags.push(`payoff=ch${t.plannedPayoffAt}`);
+        if (t.lastTouchedAt !== t.plantedAt) flags.push(`touched=ch${t.lastTouchedAt}`);
+        return `- ${t.description}  (${flags.join(', ')})`;
+      });
+      parts.push(`## Active Foreshadow Threads\n${lines.join('\n')}`);
+    }
+  }
+
   if (input.purpose === 'chapter_review' && input.chapterNumber) {
     if (chaptersJson) {
       const chapters = JSON.parse(chaptersJson) as Array<{ chapterNumber: number; title: string; summary: string; requiredBeats?: string[]; volumeId?: string }>;

package/src/core/projectDiscovery.ts

@@ -12,6 +12,7 @@ export interface ProjectSummary {
   currentStep: WorkflowStep;
   currentChapter: number;
   targetChapters: number;
+  plannedTotalChapters: number;
   completedSteps: number;
   chaptersWritten: number;
   updatedAt: string;
@@ -57,6 +58,7 @@ async function summarizeOne(projectPath: string): Promise<ProjectSummary | undef
     currentStep: state.currentStep,
     currentChapter: state.currentChapter,
     targetChapters: state.targetChapters,
+    plannedTotalChapters: state.plannedTotalChapters ?? state.targetChapters,
     completedSteps: state.completedSteps.length,
     chaptersWritten: countChapters(state),
     updatedAt: state.updatedAt,

package/src/core/projectOps.ts

@@ -164,6 +164,7 @@ export interface RedoStepResult {
 const STEP_FILE_KEYS: Partial<Record<WorkflowStep, string[]>> = {
   novel_metadata: ['novel'],
   story_bible: ['storyBible'],
+  style_guide: ['styleGuide'],
   architecture: ['architecture'],
   continuity_review: ['continuityReview'],
 };
@@ -171,6 +172,7 @@ const STEP_FILE_KEYS: Partial<Record<WorkflowStep, string[]>> = {
 const STEP_FILE_PATHS: Partial<Record<WorkflowStep, string[]>> = {
   novel_metadata: ['novel.json'],
   story_bible: ['story-bible.md'],
+  style_guide: ['style-guide.json'],
   architecture: ['architecture/full.md', 'architecture/volumes.json', 'architecture/chapters.json'],
 };
 
@@ -198,7 +200,13 @@ export async function redoStep(input: RedoStepInput): Promise<RedoStepResult> {
     state.currentChapter = chapter;
     state.currentStep = input.step;
     state.pendingAction = undefined;
-  } else if (input.step === 'novel_metadata' || input.step === 'story_bible' || input.step === 'architecture' || input.step === 'continuity_review') {
+  } else if (
+    input.step === 'novel_metadata'
+    || input.step === 'story_bible'
+    || input.step === 'style_guide'
+    || input.step === 'architecture'
+    || input.step === 'continuity_review'
+  ) {
     const paths = STEP_FILE_PATHS[input.step] ?? [];
     for (const p of paths) {
       if (await tryUnlink(join(state.projectPath, p))) removed.push(p);

package/src/core/projectStore.ts

@@ -10,6 +10,7 @@ export interface CreateProjectInput {
   language?: AgentState['language'];
   outputDir?: string;
   targetChapters?: number;
+  plannedTotalChapters?: number;
 }
 
 export interface CreateProjectResult {
@@ -61,7 +62,12 @@ export async function archiveStoryBible(projectPath: string, versionRelative: st
 export async function createProject(input: CreateProjectInput): Promise<CreateProjectResult> {
   const workspaceRoot = resolve(input.workspaceRoot);
   const baseDir = input.outputDir || 'novels';
-  const targetChapters = Math.max(1, Math.floor(Number(input.targetChapters || 3)));
+  const hasExplicitTargetChapters = input.targetChapters !== undefined;
+  const targetChapters = Math.max(1, Math.floor(Number(input.targetChapters || 5)));
+  const plannedTotalChapters = Math.max(
+    targetChapters,
+    Math.floor(Number(input.plannedTotalChapters ?? (hasExplicitTargetChapters ? targetChapters : 12)))
+  );
   const baseSlug = makeProjectSlug(input.prompt.slice(0, 48));
   const suffix = randomBytes(3).toString('hex');
   const slug = `${baseSlug}-${suffix}`;
@@ -76,6 +82,7 @@ export async function createProject(input: CreateProjectInput): Promise<CreatePr
     initialPrompt: input.prompt,
     language: input.language || 'zh-CN',
     targetChapters,
+    plannedTotalChapters,
     currentStep: 'novel_metadata',
     currentChapter: 1,
     completedSteps: [],