novelforge-agent 0.1.1 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 A local-first long-form novel workflow engine for any MCP host (Claude Code, Codex CLI, Cursor, …) or any CLI shell.
 
-**The host's LLM writes the prose. This package does everything else** — it manages a 9-step state machine, returns the exact instruction and packed context the host should follow next, validates returned content against zod schemas, persists Markdown + JSON to a project directory, archives chapter versions on revision, and provides BM25 lexical retrieval over every word the project has ever produced.
+**The host's LLM writes the prose. This package does everything else** — it manages a gated long-form state machine, returns the exact instruction and packed context the host should follow next, validates returned content against zod schemas, persists Markdown + JSON to a project directory, archives chapter versions on revision, and provides BM25 lexical retrieval over every word the project has ever produced.
 
 No external API. No LLM dependency. No vendor lock-in.
 
@@ -57,15 +57,18 @@ The installer is **idempotent and safe**: it never overwrites an existing entry
 |-------|------|---------------------|----------------------|
 | Setup | `novel_metadata` | Output JSON: title, genre, premise, cast | `novel.json` |
 |  | `story_bible` | Output Markdown: characters, world rules, plot threads | `story-bible.md` |
-|  | `architecture` | Output JSON: full / volume / chapter outlines | `architecture/{full.md, volumes.json, chapters.json}` |
+|  | `style_guide` | Output JSON: narrative voice, pacing, diction, dialogue rules, prohibited patterns, prose rhythm, sample prose | `style-guide.json` |
+|  | `architecture` | Output JSON: full / volume / pacing / chapter outlines | `architecture/{full.md, volumes.json, volume-pacing.json, chapters.json}` |
 | Loop  | `chapter` | Write chapter N Markdown | `chapters/NNN.md` |
-|  | `memory_card` | Extract chapter N memory JSON | `memory/chapter-NNN.json` |
+|  | `chapter_review` | Enforce the chapter acceptance gate: required beats, plot/character/thread progress, story-bible consistency, ending hook, repetition check | `reviews/chapter/chapter-NNN.json` |
+|  | `chapter_revision` | If review finds issues, rewrite the chapter; previous version is archived | `chapters/.versions/NNN.<ts>.md` |
+|  | `memory_card` | After a clean review, extract chapter N memory JSON and update character/thread state | `memory/chapter-NNN.json`, `characters.json`, `threads.json` |
 | Wrap  | `continuity_review` | Audit chapters 1..N for conflicts | `reviews/continuity-S-E.json` |
 | Side-track | `chapter_review` | Single-chapter editorial review | `reviews/chapter/chapter-NNN.json` |
 |  | `chapter_revision` | Rewrite a chapter; previous version auto-archived | `chapters/.versions/NNN.<ts>.md` |
 |  | `cross_chapter_review` | Cross-chapter continuity audit | `reviews/cross/cross-S-E.json` |
 
-Each chapter / bible / memory write also feeds a per-project BM25 index (`.index/`) so the agent can hand the host semantically relevant snippets when later chapters are generated, or answer ad-hoc `retrieve` queries from the host.
+Each chapter / bible / memory write also feeds a per-project BM25 index (`.index/`) so the agent can hand the host semantically relevant snippets when later chapters are generated, or answer ad-hoc `retrieve` queries from the host. Chapter generation context also includes the style guide (`style-guide.json`), independent character state table (`characters.json`), and current volume pacing board (`architecture/volume-pacing.json`) when available. The style guide includes `proseRhythm`, which checks rhythm anti-patterns such as excessive short-sentence density, consecutive one-sentence paragraphs, fake rhythm through line breaks, overly direct interior explanation, and repeated sentence patterns.
 
 ## Install
 
@@ -165,10 +168,10 @@ NOVELFORGE_WORKSPACE = "/absolute/path/where/projects/should/live"
 
 `list_projects` finds every project under `NOVELFORGE_WORKSPACE/novels/`, sorted newest first. The host should call it before anything else when a session opens; pick the desired `projectPath` from the result, then `get_project_status` for a one-screen briefing, then `get_next_step` to resume.
 
-## Tool reference (13 MCP tools)
+## Tool reference
 
 ### Project lifecycle
-- **`start_novel_project`** `(prompt, language?, outputDir?, targetChapters?)` — create a new project under `<workspaceRoot>/<outputDir>/<slug>-<rand6>/` and return the first step's instruction.
+- **`start_novel_project`** `(prompt, language?, outputDir?, targetChapters?, plannedTotalChapters?)` — create a new project under `<workspaceRoot>/<outputDir>/<slug>-<rand6>/` and return the first step's instruction. `targetChapters` is the per-batch planning size; MCP defaults to 5. `plannedTotalChapters` is the whole-book target; MCP defaults to 12.
 - **`list_projects`** `(outputDir?)` — list all projects in the workspace, newest first.
 - **`get_project_status`** `(projectPath)` — compact summary: current step, chapters written, open threads, latest review verdict.
 - **`get_next_step`** `(projectPath)` — return the prompt + packed context for whatever the workflow expects next.
@@ -177,13 +180,24 @@ NOVELFORGE_WORKSPACE = "/absolute/path/where/projects/should/live"
 - **`submit_step_result`** `(projectPath, step, content)` — validate `content` against the step's zod schema, persist it, advance the state machine. On failure the bad submission is written to `.agent-recovery/failed-*.txt` and the state does not advance.
 - **`get_context`** `(projectPath, purpose, chapterNumber?, start?, end?)` — build purpose-specific context without changing state. Useful when the host wants to read what the agent *would* have packed.
 
+Dynamic planning is built into the state machine: after each accepted chapter and memory card, the agent checks `plannedTotalChapters` and the highest chapter covered by `architecture/chapters.json`. If the next chapter is still inside the whole-book target but not yet planned, the next step becomes `architecture_extension`; after the host submits that JSON, generation resumes at `chapter`.
+
 ### Semantic actions (verb-style; safe to call any time)
 - **`generate_chapter`** `(projectPath, chapterNumber)` — return generation context for a specific chapter.
 - **`extract_memory_card`** `(projectPath, chapterNumber)` — return memory-extraction context for a specific chapter.
 - **`review_chapter`** `(projectPath, chapterNumber)` — switch into a single-chapter editorial review side-track and return its prompt. After `submit_step_result(step="chapter_review")`, the workflow resumes its prior step automatically.
 - **`revise_chapter`** `(projectPath, chapterNumber, feedback?)` — switch into a chapter-revision side-track. Submitting `chapter_revision` content auto-archives the previous version under `chapters/.versions/`.
 - **`cross_chapter_review`** `(projectPath, start?, end?)` — switch into a cross-chapter audit side-track over the given range (defaults to all generated chapters).
-- **`save_chapter`** `(projectPath, chapterNumber, title, content)` — write a chapter Markdown file directly, without going through the state machine.
+- **`save_chapter`** `(projectPath, chapterNumber, title, content)` — submit the current chapter through the state machine; it requires `currentStep="chapter"` and then advances to mandatory `chapter_review`.
+
+### Project operations
+- **`amend_story_bible`** `(projectPath, content, reason?)` — replace `story-bible.md`, archive the previous version, and rebuild the bible index.
+- **`list_bible_versions`** `(projectPath)` — list archived story-bible versions.
+- **`list_threads`** `(projectPath, status?)` — list foreshadow threads collected from memory cards.
+- **`update_thread`** `(projectPath, id, patch)` — update one foreshadow thread.
+- **`fork_project`** `(sourceProjectPath, label?)` — copy a project to a sibling fork with a new project id.
+- **`delete_chapter`** `(projectPath, chapterNumber)` — remove a chapter, its memory, reviews, archived versions, and index entries.
+- **`redo_step`** `(projectPath, step, chapterNumber?)` — roll the workflow back to regenerate an artifact.
 
 ### Retrieval
 - **`retrieve`** `(projectPath, query, topK?, types?, chapterStart?, chapterEnd?)` — BM25-style lexical retrieval over indexed paragraphs (chapters), bible H2 sections, and memory cards. Supports CJK + Latin queries via a built-in CJK bigram tokenizer; no external embedding model.
@@ -196,10 +210,13 @@ A project on disk:
 novels/<slug>-<rand6>/
 ├── agent-state.json              # workflow state (currentStep, currentChapter, files map, …)
 ├── novel.json                    # metadata (NovelMetadataSchema)
+├── characters.json               # independent character state table
 ├── story-bible.md
+├── style-guide.json              # enforceable prose style guide
 ├── architecture/
 │   ├── full.md
 │   ├── volumes.json
+│   ├── volume-pacing.json
 │   └── chapters.json
 ├── chapters/
 │   ├── 001.md
@@ -224,19 +241,28 @@ The whole directory is self-contained — copy it, share it, delete it.
 ## How the workflow advances
 
 ```
-novel_metadata → story_bible → architecture → chapter
-                                              ↓
-                                          memory_card
-                                              ↓
-                              ┌───────────────┴───────────────┐
-                  (more chapters)                       (all done)
-                              ↓                               ↓
-                          chapter                    continuity_review
-                                                              ↓
-                                                          complete
+novel_metadata → story_bible → style_guide → architecture → chapter
+                                                            ↓
+                                                       chapter_review
+                                                            ↓
+                                                 ┌──────────┴──────────┐
+                                               clean             issues_found
+                                                 ↓                    ↓
+                                            memory_card       chapter_revision
+                                                 ↓                    ↓
+                     ┌─────────────┴─────────────┐      │
+             (more chapters)                (all done)   │
+                     ↓                            ↓       │
+                  chapter                continuity_review│
+                                                  ↓       │
+                                              complete    │
+                                                       (back to
+                                                    chapter_review)
 ```
 
-Side-track steps (`chapter_review`, `chapter_revision`, `cross_chapter_review`) can be triggered at any moment via the semantic-action tools. When the side-track completes via `submit_step_result`, the workflow returns to whatever `currentStep` it was on before the side-track started.
+`chapter_review` is both a manual side-track and the automatic chapter acceptance gate. In the normal chapter loop, the workflow cannot advance to `memory_card` until the review status is `clean`. If the review returns `issues_found`, the workflow forces `chapter_revision`, then returns to `chapter_review` for another pass.
+
+Side-track steps (`chapter_review`, `chapter_revision`, `cross_chapter_review`) can still be triggered at any moment via the semantic-action tools. When a manual side-track completes via `submit_step_result`, the workflow returns to whatever `currentStep` it was on before the side-track started.
 
 The full transition map lives in the `next:` declaration of each handler under [src/core/steps/](src/core/steps/). To change the workflow, edit those files — that is the entire state machine, there is no graph engine.
 
@@ -249,6 +275,7 @@ src/
 │   ├── schemas.ts                # zod schemas (the only validator)
 │   ├── projectStore.ts           # filesystem persistence
 │   ├── projectDiscovery.ts       # list / status
+│   ├── characterStore.ts         # independent character state table
 │   ├── prompts/                  # per-language prompt packs (zh-CN, en-US)
 │   ├── steps/                    # one file per WorkflowStep handler
 │   ├── retrieval/                # BM25 index + CJK tokenizer + chunker

package/dist/src/cli/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
-import { buildContext, createProject, getNextStep, getProjectStatus, listProjects, requestSideTrack, retrieve, submitStepResult, } from '../core/index.js';
+import { amendStoryBible, buildContext, createProject, deleteChapter, forkProject, getNextStep, getProjectStatus, listProjects, loadThreads, redoStep, requestSideTrack, retrieve, submitStepResult, updateThread, } from '../core/index.js';
 import { formatInstallResult, runInstall } from './install.js';
 function valueAfter(args, name) {
     const index = args.indexOf(name);
@@ -38,9 +38,17 @@ export async function runCli(argv = process.argv.slice(2), cwd = process.cwd())
         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;
@@ -136,7 +144,76 @@ export async function runCli(argv = process.argv.slice(2), cwd = process.cwd())
         console.log(JSON.stringify({ query, hits }, null, 2));
         return;
     }
-    throw new Error('Usage: novelforge-agent install|start|list|status|next|submit|context|review|revise|cross-review|retrieve');
+    if (command === 'amend-bible') {
+        if (!projectPath)
+            throw new Error('Missing projectPath');
+        const file = valueAfter(argv, '--file');
+        const reason = valueAfter(argv, '--reason');
+        if (!file)
+            throw new Error('Missing --file with new bible Markdown');
+        const content = await readFile(file, 'utf8');
+        console.log(JSON.stringify(await amendStoryBible({ projectPath, content, reason }), null, 2));
+        return;
+    }
+    if (command === 'threads') {
+        if (!projectPath)
+            throw new Error('Missing projectPath');
+        const status = valueAfter(argv, '--status');
+        const all = await loadThreads(projectPath);
+        const filtered = status ? all.filter((t) => t.status === status) : all;
+        console.log(JSON.stringify(filtered, null, 2));
+        return;
+    }
+    if (command === 'update-thread') {
+        if (!projectPath)
+            throw new Error('Missing projectPath');
+        const id = valueAfter(argv, '--id');
+        if (!id)
+            throw new Error('Missing --id');
+        const status = valueAfter(argv, '--status');
+        const plannedPayoffAt = valueAfter(argv, '--planned-payoff');
+        const description = valueAfter(argv, '--description');
+        const notes = valueAfter(argv, '--notes');
+        const updated = await updateThread(projectPath, id, {
+            status,
+            plannedPayoffAt: plannedPayoffAt ? Number(plannedPayoffAt) : undefined,
+            description,
+            notes,
+        });
+        console.log(JSON.stringify(updated, null, 2));
+        return;
+    }
+    if (command === 'fork') {
+        if (!projectPath)
+            throw new Error('Missing projectPath');
+        const label = valueAfter(argv, '--label');
+        console.log(JSON.stringify(await forkProject({ sourceProjectPath: projectPath, label }), null, 2));
+        return;
+    }
+    if (command === 'delete-chapter') {
+        if (!projectPath)
+            throw new Error('Missing projectPath');
+        const chapter = valueAfter(argv, '--chapter');
+        if (!chapter)
+            throw new Error('Missing --chapter');
+        console.log(JSON.stringify(await deleteChapter({ projectPath, chapterNumber: Number(chapter) }), null, 2));
+        return;
+    }
+    if (command === 'redo') {
+        if (!projectPath)
+            throw new Error('Missing projectPath');
+        const step = valueAfter(argv, '--step');
+        if (!step)
+            throw new Error('Missing --step');
+        const chapter = valueAfter(argv, '--chapter');
+        console.log(JSON.stringify(await redoStep({
+            projectPath,
+            step,
+            chapterNumber: chapter ? Number(chapter) : undefined,
+        }), null, 2));
+        return;
+    }
+    throw new Error('Usage: novelforge-agent install|start|list|status|next|submit|context|review|revise|cross-review|retrieve|amend-bible|threads|update-thread|fork|delete-chapter|redo');
 }
 if (import.meta.url === `file://${process.argv[1]}`) {
     runCli().catch((error) => {

package/dist/src/core/bibleStore.js

@@ -0,0 +1,36 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { archiveStoryBible, loadState, saveMarkdownFile, saveState, } from './projectStore.js';
+import { storyBibleVersionFileName } from './fileNames.js';
+import { indexStoryBible } from './retrieval/index.js';
+function isEmpty(content) {
+    return !content || !content.trim();
+}
+export async function amendStoryBible(input) {
+    if (isEmpty(input.content))
+        throw new Error('Amended story bible content is empty');
+    const state = await loadState(input.projectPath);
+    // Archive current
+    const archived = await archiveStoryBible(state.projectPath, join('story-bible-versions', storyBibleVersionFileName(new Date().toISOString())));
+    // Save new
+    const savedPath = await saveMarkdownFile(state.projectPath, 'story-bible.md', input.content);
+    // Re-index
+    await indexStoryBible(state.projectPath, input.content);
+    // Track in state
+    const bibleVersion = (state.completedSteps.filter((s) => s === 'story_bible_amend').length ?? 0) + 1;
+    await saveState({
+        ...state,
+        completedSteps: [...state.completedSteps, 'story_bible_amend'],
+        files: { ...state.files, storyBible: 'story-bible.md' },
+    });
+    return { archivedPath: archived, bibleVersion, savedPath };
+}
+export async function listStoryBibleVersions(projectPath) {
+    try {
+        const items = await readdir(join(projectPath, 'story-bible-versions'));
+        return items.filter((f) => f.endsWith('.md')).sort();
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/core/characterStore.js

@@ -0,0 +1,74 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const CHARACTERS_FILE = 'characters.json';
+function emptyState(member, chapterNumber = 0) {
+    return {
+        name: member.name,
+        role: member.role,
+        goal: '未确认',
+        belief: '未确认',
+        relationships: [],
+        abilities: [],
+        secrets: [],
+        emotionalState: member.description,
+        lastUpdatedAt: chapterNumber,
+    };
+}
+export async function loadCharacterStates(projectPath) {
+    try {
+        const raw = await readFile(join(projectPath, CHARACTERS_FILE), 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.characters) ? parsed.characters : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function saveCharacterStates(projectPath, characters) {
+    const fullPath = join(projectPath, CHARACTERS_FILE);
+    await writeFile(fullPath, `${JSON.stringify({ characters }, null, 2)}\n`, 'utf8');
+    return fullPath;
+}
+export async function initializeCharacterStates(projectPath, coreCast) {
+    const existing = await loadCharacterStates(projectPath);
+    const byName = new Map(existing.map((c) => [c.name, c]));
+    for (const member of coreCast) {
+        if (!byName.has(member.name)) {
+            byName.set(member.name, emptyState(member));
+        }
+    }
+    return saveCharacterStates(projectPath, Array.from(byName.values()));
+}
+export async function applyCharacterUpdates(projectPath, chapterNumber, updates) {
+    const existing = await loadCharacterStates(projectPath);
+    if (!updates || !updates.length)
+        return existing;
+    const byName = new Map(existing.map((c) => [c.name, { ...c }]));
+    for (const update of updates) {
+        const current = byName.get(update.name) ?? {
+            name: update.name,
+            role: update.role,
+            goal: '未确认',
+            belief: '未确认',
+            relationships: [],
+            abilities: [],
+            secrets: [],
+            emotionalState: '未确认',
+            lastUpdatedAt: chapterNumber,
+        };
+        byName.set(update.name, {
+            ...current,
+            role: update.role ?? current.role,
+            goal: update.goal ?? current.goal,
+            belief: update.belief ?? current.belief,
+            relationships: update.relationships ?? current.relationships,
+            abilities: update.abilities ?? current.abilities,
+            secrets: update.secrets ?? current.secrets,
+            emotionalState: update.emotionalState ?? current.emotionalState,
+            lastUpdatedAt: chapterNumber,
+        });
+    }
+    const next = Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+    await saveCharacterStates(projectPath, next);
+    return next;
+}

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');
@@ -14,11 +15,30 @@ export async function buildContext(input) {
     const parts = [];
     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) {
+        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 +47,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 +75,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) {
@@ -73,12 +107,43 @@ export async function buildContext(input) {
         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 = [];
+        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 = [`#${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);
             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 +158,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/projectDiscovery.js

@@ -36,6 +36,7 @@ async function summarizeOne(projectPath) {
         currentStep: state.currentStep,
         currentChapter: state.currentChapter,
         targetChapters: state.targetChapters,
+        plannedTotalChapters: state.plannedTotalChapters ?? state.targetChapters,
         completedSteps: state.completedSteps.length,
         chaptersWritten: countChapters(state),
         updatedAt: state.updatedAt,