novelforge-agent 0.1.0 → 0.2.0

package/dist/src/core/contextBuilder.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { chapterFileName, chapterReviewFileName, memoryFileName } from './fileNames.js';
 import { formatHits, retrieve } from './retrieval/index.js';
+import { activeThreads, loadThreads } from './threadStore.js';
 async function readOptional(path) {
     try {
         return await readFile(path, 'utf8');
@@ -15,10 +16,26 @@ export async function buildContext(input) {
     const metadata = await readOptional(join(input.projectPath, 'novel.json'));
     const storyBible = await readOptional(join(input.projectPath, 'story-bible.md'));
     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 (charactersJson)
+        parts.push(`## Character State Table\n${charactersJson}`);
+    function addVolumePacing(volumeId) {
+        if (!volumePacingJson)
+            return;
+        try {
+            const boards = JSON.parse(volumePacingJson);
+            const board = volumeId ? boards.find((item) => item.volumeId === volumeId) : undefined;
+            parts.push(`## Volume Pacing Board\n${JSON.stringify(board ?? boards, null, 2)}`);
+        }
+        catch {
+            parts.push(`## Volume Pacing Board\n${volumePacingJson}`);
+        }
+    }
     if (input.purpose === 'chapter_generation' && input.chapterNumber) {
         let currentArchitectureForQuery;
         if (chaptersJson) {
@@ -27,6 +44,7 @@ export async function buildContext(input) {
             if (chapter) {
                 currentArchitectureForQuery = chapter;
                 parts.push(`## Current Chapter Architecture\n${JSON.stringify(chapter, null, 2)}`);
+                addVolumePacing(chapter.volumeId);
             }
         }
         if (input.chapterNumber > 1) {
@@ -54,6 +72,19 @@ export async function buildContext(input) {
                 if (formatted)
                     parts.push(`## Retrieved Relevant Snippets (lexical, BM25-style)\n${formatted}`);
             }
+            const allThreads = await loadThreads(input.projectPath);
+            const active = activeThreads(allThreads);
+            if (active.length) {
+                const lines = active.map((t) => {
+                    const flags = [`#${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 (do not silently drop or contradict)\n${lines.join('\n')}`);
+            }
         }
     }
     if (input.purpose === 'memory_extraction' && input.chapterNumber) {
@@ -77,8 +108,10 @@ export async function buildContext(input) {
         if (chaptersJson) {
             const chapters = JSON.parse(chaptersJson);
             const arch = chapters.find((item) => item.chapterNumber === input.chapterNumber);
-            if (arch)
+            if (arch) {
                 parts.push(`## Target Chapter Architecture\n${JSON.stringify(arch, null, 2)}`);
+                addVolumePacing(arch.volumeId);
+            }
         }
         const chapter = await readOptional(join(input.projectPath, 'chapters', chapterFileName(input.chapterNumber)));
         if (chapter)
@@ -93,6 +126,16 @@ export async function buildContext(input) {
         const chapter = await readOptional(join(input.projectPath, 'chapters', chapterFileName(input.chapterNumber)));
         if (chapter)
             parts.push(`## Current Chapter Text\n${chapter}`);
+        if (chaptersJson) {
+            try {
+                const chapters = JSON.parse(chaptersJson);
+                const arch = chapters.find((item) => item.chapterNumber === input.chapterNumber);
+                addVolumePacing(arch?.volumeId);
+            }
+            catch {
+                // ignore malformed architecture here; review feedback is still useful
+            }
+        }
         const review = await readOptional(join(input.projectPath, 'reviews/chapter', chapterReviewFileName(input.chapterNumber)));
         if (review)
             parts.push(`## Editor Review\n${review}`);

package/dist/src/core/fileNames.js

@@ -39,3 +39,7 @@ export function chapterVersionFileName(chapterNumber, timestamp) {
     const safeTs = timestamp.replace(/[:.]/g, '-');
     return `${padChapterNumber(chapterNumber)}.${safeTs}.md`;
 }
+export function storyBibleVersionFileName(timestamp) {
+    const safeTs = timestamp.replace(/[:.]/g, '-');
+    return `story-bible.${safeTs}.md`;
+}

package/dist/src/core/index.js

@@ -7,3 +7,7 @@ export * from './contextBuilder.js';
 export * from './prompts.js';
 export * from './retrieval/index.js';
 export * from './projectDiscovery.js';
+export * from './threadStore.js';
+export * from './bibleStore.js';
+export * from './projectOps.js';
+export * from './characterStore.js';

package/dist/src/core/projectOps.js

@@ -0,0 +1,187 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { cp, readdir, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { loadState, saveState } from './projectStore.js';
+import { removeChapterFromIndex, removeMemoryCardFromIndex } from './retrieval/index.js';
+import { chapterFileName, memoryFileName } from './fileNames.js';
+export async function forkProject(input) {
+    const source = resolve(input.sourceProjectPath);
+    const state = await loadState(source);
+    const suffix = randomBytes(3).toString('hex');
+    const label = (input.label ?? 'fork').replace(/[^a-z0-9-]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'fork';
+    const targetName = `${basename(source)}-${label}-${suffix}`;
+    const target = join(dirname(source), targetName);
+    await cp(source, target, { recursive: true });
+    const forkedState = {
+        ...state,
+        projectId: randomUUID(),
+        projectPath: target,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    };
+    await saveState(forkedState);
+    return { newProjectPath: target, newProjectId: forkedState.projectId };
+}
+async function tryUnlink(path) {
+    try {
+        await unlink(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function tryRmDirEntry(dirPath, prefix) {
+    const removed = [];
+    try {
+        const items = await readdir(dirPath);
+        for (const item of items) {
+            if (item.startsWith(prefix)) {
+                const full = join(dirPath, item);
+                try {
+                    await unlink(full);
+                    removed.push(full);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    catch {
+        // dir absent
+    }
+    return removed;
+}
+export async function deleteChapter(input) {
+    const state = await loadState(input.projectPath);
+    const n = input.chapterNumber;
+    if (n < 1)
+        throw new Error('chapterNumber must be >= 1');
+    const removed = [];
+    const chapterRel = join('chapters', chapterFileName(n));
+    if (await tryUnlink(join(state.projectPath, chapterRel)))
+        removed.push(chapterRel);
+    const memoryRel = join('memory', memoryFileName(n));
+    if (await tryUnlink(join(state.projectPath, memoryRel)))
+        removed.push(memoryRel);
+    // Versions of this chapter
+    const versionsRemoved = await tryRmDirEntry(join(state.projectPath, 'chapters/.versions'), `${chapterFileName(n).replace(/\.md$/, '')}.`);
+    removed.push(...versionsRemoved);
+    // Per-chapter review
+    const reviewName = `chapter-${String(n).padStart(3, '0')}.json`;
+    if (await tryUnlink(join(state.projectPath, 'reviews/chapter', reviewName))) {
+        removed.push(`reviews/chapter/${reviewName}`);
+    }
+    // Update state.files
+    const nextFiles = { ...state.files };
+    delete nextFiles[`chapter-${n}`];
+    delete nextFiles[`memory-${n}`];
+    delete nextFiles[`review-chapter-${n}`];
+    // Remove this chapter and its memory card from the lexical index
+    await removeChapterFromIndex(state.projectPath, n);
+    await removeMemoryCardFromIndex(state.projectPath, n);
+    // Adjust state.currentChapter & currentStep if needed
+    let newCurrentChapter = state.currentChapter;
+    let newCurrentStep = state.currentStep;
+    if (state.currentChapter > n) {
+        // user deleted an earlier chapter; current pointer becomes the deleted one to be regenerated
+        newCurrentChapter = n;
+        newCurrentStep = 'chapter';
+    }
+    else if (state.currentChapter === n + 1 && (state.currentStep === 'chapter' || state.currentStep === 'memory_card')) {
+        // we just finished chapter n and were about to do n+1; step back
+        newCurrentChapter = n;
+        newCurrentStep = 'chapter';
+    }
+    const nextState = {
+        ...state,
+        files: nextFiles,
+        currentChapter: newCurrentChapter,
+        currentStep: newCurrentStep,
+        pendingAction: undefined,
+    };
+    await saveState(nextState);
+    return { removed, newCurrentChapter, newCurrentStep };
+}
+const STEP_FILE_KEYS = {
+    novel_metadata: ['novel'],
+    story_bible: ['storyBible'],
+    architecture: ['architecture'],
+    continuity_review: ['continuityReview'],
+};
+const STEP_FILE_PATHS = {
+    novel_metadata: ['novel.json'],
+    story_bible: ['story-bible.md'],
+    architecture: ['architecture/full.md', 'architecture/volumes.json', 'architecture/chapters.json'],
+};
+export async function redoStep(input) {
+    const state = await loadState(input.projectPath);
+    const removed = [];
+    if (input.step === 'chapter' || input.step === 'memory_card') {
+        const chapter = input.chapterNumber ?? state.currentChapter;
+        if (input.step === 'memory_card') {
+            const rel = join('memory', memoryFileName(chapter));
+            if (await tryUnlink(join(state.projectPath, rel)))
+                removed.push(rel);
+            delete state.files[`memory-${chapter}`];
+        }
+        else {
+            // chapter: also remove its memory + per-chapter review since they depend on it
+            const cRel = join('chapters', chapterFileName(chapter));
+            if (await tryUnlink(join(state.projectPath, cRel)))
+                removed.push(cRel);
+            const mRel = join('memory', memoryFileName(chapter));
+            if (await tryUnlink(join(state.projectPath, mRel)))
+                removed.push(mRel);
+            delete state.files[`chapter-${chapter}`];
+            delete state.files[`memory-${chapter}`];
+            await removeChapterFromIndex(state.projectPath, chapter);
+            await removeMemoryCardFromIndex(state.projectPath, chapter);
+        }
+        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') {
+        const paths = STEP_FILE_PATHS[input.step] ?? [];
+        for (const p of paths) {
+            if (await tryUnlink(join(state.projectPath, p)))
+                removed.push(p);
+        }
+        const keys = STEP_FILE_KEYS[input.step] ?? [];
+        for (const k of keys) {
+            delete state.files[k];
+        }
+        state.currentStep = input.step;
+        state.pendingAction = undefined;
+        if (input.step === 'novel_metadata')
+            state.currentChapter = 1;
+    }
+    else {
+        throw new Error(`redo_step does not support step: ${input.step}`);
+    }
+    // Trim completedSteps after the redo target
+    const idx = state.completedSteps.lastIndexOf(input.step);
+    if (idx >= 0)
+        state.completedSteps = state.completedSteps.slice(0, idx);
+    await saveState(state);
+    return {
+        removed,
+        currentStep: state.currentStep,
+        currentChapter: state.currentChapter,
+    };
+}
+// =============================================================================
+// guards
+// =============================================================================
+export function assertProjectPath(workspaceRoot, projectPath) {
+    const root = resolve(workspaceRoot);
+    const target = resolve(projectPath);
+    const rel = relative(root, target);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(`Refusing to operate outside workspace: ${target}`);
+    }
+}
+// keep tsc happy if no other refs
+void writeFile;

package/dist/src/core/projectStore.js

@@ -15,6 +15,7 @@ export async function ensureProjectDirectories(projectPath) {
     await mkdir(join(projectPath, 'architecture'), { recursive: true });
     await mkdir(join(projectPath, 'chapters'), { recursive: true });
     await mkdir(join(projectPath, 'chapters/.versions'), { recursive: true });
+    await mkdir(join(projectPath, 'story-bible-versions'), { recursive: true });
     await mkdir(join(projectPath, 'memory'), { recursive: true });
     await mkdir(join(projectPath, 'reviews'), { recursive: true });
     await mkdir(join(projectPath, 'reviews/chapter'), { recursive: true });
@@ -31,6 +32,16 @@ export async function archiveChapterVersion(projectPath, chapterRelative, versio
         return undefined;
     }
 }
+export async function archiveStoryBible(projectPath, versionRelative) {
+    const sourcePath = join(projectPath, 'story-bible.md');
+    try {
+        const existing = await readFile(sourcePath, 'utf8');
+        return saveMarkdownFile(projectPath, versionRelative, existing);
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function createProject(input) {
     const workspaceRoot = resolve(input.workspaceRoot);
     const baseDir = input.outputDir || 'novels';

package/dist/src/core/prompts/en-US.js

@@ -101,6 +101,18 @@ Output valid JSON only, in this shape:
       "order": 1
     }
   ],
+  "volumePacing": [
+    {
+      "volumeId": "v1",
+      "start": "Volume starting state: protagonist/world/conflict",
+      "promise": "Core reader promise or question for this volume",
+      "keyTurns": ["Key turn 1", "Key turn 2"],
+      "midpoint": "Midpoint turn or changed understanding",
+      "climax": "Volume climax",
+      "payoffs": ["Threads or promises this volume plans to pay off"],
+      "lingeringMysteries": ["Mysteries intentionally left open at volume end"]
+    }
+  ],
   "chapters": [
     {
       "chapterNumber": 1,
@@ -116,36 +128,50 @@ Rules:
 - chapters.length must be at least ${input.state.targetChapters}.
 - chapterNumber must start at 1 and increase contiguously.
 - volumeId must reference an id from volumes.
+- volumePacing must provide one pacing board for every volume.
 - requiredBeats must include at least one concrete, actionable beat.
 ${strictJsonOutputRules()}`,
     };
 }
 function buildChapterPrompt(input) {
+    const ch = input.state.currentChapter;
+    const isFirstChapter = ch <= 1;
     return {
         purpose: 'chapter',
         expectedFormat: 'Markdown',
-        prompt: `You are a professional long-form fiction writer. Write chapter ${input.state.currentChapter} directly.
+        prompt: `You are a professional long-form fiction writer. Write chapter ${ch} directly.
 
 ## Priority Order
 1. Strictly follow the current chapter architecture, user additions, story bible hard constraints, and previous-chapter continuity.
-2. Use relevant memory and prior text evidence to preserve consistency.
+2. Use relevant memory, prior text evidence, and active foreshadow threads.
 3. Treat full-book and volume plans as distant planning context only. Do not write concrete future events early.
 
-## Style And Length
+## Length Target
+- Default target: ~2500 words (±20%). If the chapter architecture specifies targetWords, follow it.
+- Do not pad to hit the target; do not under-write to be brief at the cost of conflict.
+
+## Structure
+${isFirstChapter
+            ? '- This is chapter 1. No recap needed. Open with character and situation directly.'
+            : '- Start with a 2-3 sentence recap or bridge so a reader who skipped the last chapter can re-enter (unless the chapter architecture has requireRecap=false). Make it natural, not meta-narration like "previously...".'}
+- The chapter must end on a clear hook: cliffhanger, mystery, emotional resonance, reveal, or volume close — per the chapter architecture endHookFocus. Default: cliffhanger.
+
+## Style
 - Match the novel's genre, world, character identities, and emotional tone.
-- Keep the language natural, stable, and readable. Prioritize narrative progress, character work, and emotional accumulation.
-- Dialogue must fit each character's identity, relationship, and immediate situation.
-- Important emotion should appear through action, body language, pacing, and subtext where possible.
-- Scene description should provide useful sensory and atmospheric detail, but never stall the plot.
-- Conflict, turns, suspense, and the chapter-end hook should be clear.
+- Natural, stable, readable language; prioritize narrative progress, character work, and emotional accumulation.
+- Dialogue fits each character's identity, relationship, and situation.
+- Important emotion comes through action, body language, pacing, and subtext.
+- Scene description has useful sensory detail without stalling.
+- POV: strictly follow the chapter architecture povCharacter (if set). No mid-chapter POV switch.
 
 ## Execution Rules
 - Write only what the current chapter architecture authorizes.
-- Do not introduce unauthorized major characters. Functional background characters should stay light.
-- Keep names, items, places, abilities, timeline, injuries, relationships, and knowledge boundaries consistent.
-- If the previous chapter ends mid-action, mid-dialogue, or in the same scene, this chapter must continue from that point.
+- Do not introduce unauthorized major characters. Functional background characters stay light.
+- Keep names, items, places, abilities, timelines, injuries, relationships, and knowledge boundaries consistent.
+- If the previous chapter ends mid-action or mid-scene, this chapter must continue from that point.
+- Active foreshadow threads may be advanced or paid off this chapter, but **never silently dropped** — even if you choose not to touch them, leave them coherent.
 - Avoid cost-free power jumps, forced stupidity, mechanical twists, info-dumps, and empty lyricism.
-- Do not output summaries, bullet points, lectures, or explanatory prefaces.
+- Do not output summaries, bullet points, lectures, explanatory prefaces, or meta-text like "what I changed".
 
 ${input.context ? `## Generation Context\n${input.context}\n` : ''}## Output Requirements
 - Output Markdown.
@@ -185,13 +211,41 @@ Output valid JSON only, in this shape:
       "after": "After"
     }
   ],
-  "openThreads": ["Unresolved promise, danger, question, or plot thread"]
+  "openThreads": ["Unresolved promise, danger, question, or plot thread"],
+  "wordCount": <approximate word count of this chapter as an integer>,
+  "threadActions": [
+    {
+      "kind": "plant | build | pay | drop",
+      "threadId": "id of an existing active thread (required for build/pay/drop; leave empty for plant — the system will assign one)",
+      "description": "for plant: what the new thread is; for others: one sentence on how this chapter advanced/paid/dropped that thread"
+    }
+  ],
+  "characterUpdates": [
+    {
+      "name": "Character name",
+      "role": "Role if confirmed or changed this chapter",
+      "goal": "Current goal at chapter end",
+      "belief": "Core belief or understanding driving them at chapter end",
+      "relationships": [
+        { "name": "Related character", "dynamic": "Relationship state at chapter end" }
+      ],
+      "abilities": ["Abilities, resources, or limits confirmed at chapter end"],
+      "secrets": ["Secrets still hidden or only partially known at chapter end"],
+      "emotionalState": "Emotional state at chapter end"
+    }
+  ]
 }
 
 Rules:
 - Record only information that happened or was confirmed in this chapter.
 - Do not speculate about future plot.
 - Make facts and stateChanges concrete enough for later chapter reference.
+- wordCount: approximate word count (English) or character count (CJK). An integer estimate is fine.
+- threadActions is critical:
+  · For any active foreshadow thread in the context's "Active Foreshadow Threads" section, if this chapter advanced it emit kind="build"; if this chapter paid it off emit kind="pay"; if this chapter abandoned it emit kind="drop". threadId is required.
+  · For any new thread this chapter plants, emit kind="plant" with a clear description.
+  · If an active thread was not touched, no action needed — but never silently delete it. Without a drop action, the thread stays active.
+- characterUpdates maintains a separate character state table. Emit only important characters whose state changed or was reconfirmed in this chapter; goal, belief, relationships, abilities, secrets, and emotionalState must reflect the chapter ending.
 ${strictJsonOutputRules()}`,
     };
 }
@@ -241,6 +295,12 @@ function buildChapterReviewPrompt(input) {
         prompt: `You are a strict editor reviewing a single chapter of a serial novel for in-chapter problems and conflicts with established context.
 
 ${input.context ? `## Review Context\n${input.context}\n` : ''}## Review Focus
+- This is a mandatory chapter acceptance gate. If any acceptance item fails, status must be "issues_found" and the workflow must revise before continuing.
+- Whether every requiredBeat is fulfilled; missing beats must appear in acceptance.requiredBeats.missingBeats.
+- Whether this chapter advances the main line, character state, or active foreshadow threads. If it is static, at least one of narrativeProgress/characterProgress/foreshadowProgress must fail.
+- Whether it violates the story bible, character state table, volume pacing board, or prior memory.
+- Whether the ending has a clear hook that matches the chapter architecture endHookFocus.
+- Whether it repeats prior chapter beats, conflict patterns, reveals, or dialogue functions.
 - Character voice, motivation, and state vs the story bible and prior memory.
 - World rules, item ownership, and ability limits.
 - Timeline, location, and continuity with the previous chapter ending.
@@ -252,6 +312,37 @@ Output valid JSON only, in this shape:
 {
   "chapterNumber": ${chapter},
   "status": "clean",
+  "acceptance": {
+    "requiredBeats": {
+      "status": "pass | fail",
+      "evidence": "Evidence for each requiredBeat",
+      "missingBeats": []
+    },
+    "narrativeProgress": {
+      "status": "pass | fail",
+      "evidence": "How this chapter advances the main line or phase objective"
+    },
+    "characterProgress": {
+      "status": "pass | fail",
+      "evidence": "How this chapter changes or confirms key character goal, belief, relationship, ability, secret, or emotion"
+    },
+    "foreshadowProgress": {
+      "status": "pass | fail",
+      "evidence": "How this chapter plants, advances, pays, or deliberately preserves foreshadow threads"
+    },
+    "storyBibleConsistency": {
+      "status": "pass | fail",
+      "evidence": "Whether it matches the story bible, character state table, and world rules"
+    },
+    "endingHook": {
+      "status": "pass | fail",
+      "evidence": "The ending hook passage and its function"
+    },
+    "repetition": {
+      "status": "pass | fail",
+      "evidence": "Whether it repeats prior beats; if not, explain why"
+    }
+  },
   "issues": [
     {
       "severity": "low | medium | high",
@@ -266,6 +357,8 @@ Output valid JSON only, in this shape:
 Rules:
 - If there are no issues, use status "clean" with an empty issues array.
 - Otherwise use status "issues_found".
+- status may be "clean" only when every acceptance item is "pass".
+- If any acceptance item is "fail", include a matching issue with a concrete fix.
 - evidence must be specific; do not write "possibly" or "maybe".
 ${strictJsonOutputRules()}`,
     };
@@ -349,6 +442,17 @@ function buildPromptForStep(input) {
             return buildChapterRevisionPrompt(input);
         case 'cross_chapter_review':
             return buildCrossChapterReviewPrompt(input);
+        case 'story_bible_amend':
+            return {
+                purpose: 'story_bible',
+                expectedFormat: 'Markdown',
+                prompt: `Based on the current story bible and the amendment context, output the FULL revised story bible Markdown.
+
+${input.context ? `## Amendment Context\n${input.context}\n` : ''}## Output Requirements
+- Output the entire story-bible.md content — it replaces the old one (old version auto-archived under story-bible-versions/).
+- Preserve everything that still holds; modify / add / remove only what the amendment context justifies.
+- Do not output diff markers, change logs, or bullet summaries — just the new full bible.`,
+            };
         case 'complete':
             return {
                 purpose: 'continuity_review',