novelforge-agent 0.1.0 → 0.2.0

package/dist/src/core/prompts/zh-CN.js

@@ -101,6 +101,18 @@ ${input.context ? `## 已有上下文\n${input.context}\n` : ''}## 输出要求
       "order": 1
     }
   ],
+  "volumePacing": [
+    {
+      "volumeId": "v1",
+      "start": "本卷起点：主角/世界/冲突处于什么状态",
+      "promise": "本卷向读者承诺的核心看点或问题",
+      "keyTurns": ["关键转折1", "关键转折2"],
+      "midpoint": "本卷中点转折或认知变化",
+      "climax": "本卷高潮",
+      "payoffs": ["本卷计划回收的伏笔或承诺"],
+      "lingeringMysteries": ["卷末仍要保留的悬念"]
+    }
+  ],
   "chapters": [
     {
       "chapterNumber": 1,
@@ -116,35 +128,49 @@ ${input.context ? `## 已有上下文\n${input.context}\n` : ''}## 输出要求
 - chapters.length 必须大于等于 ${input.state.targetChapters}。
 - chapterNumber 从 1 开始连续递增。
 - volumeId 必须引用 volumes 中存在的 id。
+- volumePacing 必须为每个 volume 提供节奏板。
 - requiredBeats 至少 1 条，且必须具体可执行。
 ${strictJsonOutputRules()}`,
     };
 }
 function buildChapterPrompt(input) {
+    const ch = input.state.currentChapter;
+    const isFirstChapter = ch <= 1;
     return {
         purpose: 'chapter',
         expectedFormat: 'Markdown',
-        prompt: `你是一位擅长创作长篇网络小说的职业作者。请直接完成第 ${input.state.currentChapter} 章正文。
+        prompt: `你是一位擅长创作长篇网络小说的职业作者。请直接完成第 ${ch} 章正文。
 
 ## 执行优先级
-1. 先严格遵守“本章架构、用户补充要求、故事圣经硬约束、上一章承接”。
-2. 再参考“历史相关记忆、历史原文证据”保证一致性。
-3. 最后才参考“全本/本卷远场规划”，且不得提前写出尚未发生的情节。
+1. 先严格遵守"本章架构、用户补充要求、故事圣经硬约束、上一章承接"。
+2. 再参考"历史相关记忆、历史原文证据、活跃伏笔"保证一致性。
+3. 最后才参考"全本/本卷远场规划"，且不得提前写出尚未发生的情节。
+
+## 字数目标
+- 默认目标 3000 字（±20%）。如果本章架构里指定了 targetWords，按那个目标。
+- 不要为了凑字数注水；也不要为了简洁牺牲冲突推进。
 
-## 风格与字数
+## 结构要求
+${isFirstChapter
+            ? '- 这是第 1 章，不需要"上回提要"。开篇直接立人物、立情境。'
+            : '- 章首需要 2-3 句"上回提要"或"承接段"，让没读上一章的读者能续上（除非本章架构 requireRecap=false）。要自然带入，不要写成"上一章里……"的元叙述。'}
+- 章末必须有清晰的"钩子"：可以是悬念、反转、剧情承诺、情绪余韵或卷末高潮——按本章架构 endHookFocus 字段决定。如果未指定，默认用悬念。
+
+## 风格
 - 文风必须与本书题材、世界观、人物身份、情感基调一致。
-- 语言要自然、稳定、可读，优先服务叙事推进、人物塑造和情绪积累。
-- 对话必须符合人物身份、关系和处境；重要情绪尽量通过动作、神态、节奏、潜台词体现。
-- 场景描写要有必要的感官细节与氛围支撑，但篇幅服务剧情，不要空转。
-- 冲突、转折、悬念和章末钩子要清晰，保证阅读推进感。
+- 语言自然、稳定、可读，优先服务叙事推进、人物塑造和情绪积累。
+- 对话符合人物身份、关系和处境；重要情绪通过动作、神态、节奏、潜台词体现。
+- 场景描写有必要的感官细节与氛围支撑，但篇幅服务剧情。
+- POV 严格按本章架构 povCharacter（如有），中途不切换视角。
 
 ## 执行规则
 - 只写本章架构明确覆盖的内容，不得提前写后续章节具体事件或人物揭示。
-- 不得新增本章架构未授权的主要人物；功能性角色只能轻描淡写。
+- 不得新增本章架构未授权的主要人物；功能性角色轻描淡写。
 - 所有人物称谓、物品、场景、能力、时间线必须与既有设定一致。
 - 如果上一章结尾仍在动作、对话或同一场景中，本章开头必须连续衔接。
+- 活跃伏笔列表中的条目本章可以"推进"或"回收"，但**不得无声无息地删除**——若选择不触碰也要让它仍然成立。
 - 禁止无代价越级碾压、强行降智配角、突兀机械反转、硬灌设定、空洞抒情。
-- 禁止总结腔、条目腔、说教腔，不要输出解释性前言。
+- 禁止总结腔、条目腔、说教腔，不要输出解释性前言或"我修改了什么"之类的元文本。
 
 ${input.context ? `## 生成上下文\n${input.context}\n` : ''}## 输出要求
 - 输出 Markdown。
@@ -184,13 +210,41 @@ ${input.context ? `## 当前章上下文\n${input.context}\n` : ''}## 输出要
       "after": "变化后"
     }
   ],
-  "openThreads": ["尚未解决的伏笔、承诺、危险或疑问"]
+  "openThreads": ["尚未解决的伏笔、承诺、危险或疑问"],
+  "wordCount": 本章实际字数（整数估算即可）,
+  "threadActions": [
+    {
+      "kind": "plant | build | pay | drop",
+      "threadId": "已有伏笔的 id（如果是 plant 留空让系统分配；build/pay/drop 必须填活跃伏笔列表里的 id）",
+      "description": "新伏笔的描述（plant 时必填）或本章如何推进/回收/丢弃这条伏笔的一句话"
+    }
+  ],
+  "characterUpdates": [
+    {
+      "name": "人物姓名",
+      "role": "角色定位（如本章确认或改变）",
+      "goal": "本章结束时的当前目标",
+      "belief": "本章结束时影响其行动的核心认知/信念",
+      "relationships": [
+        { "name": "相关人物", "dynamic": "本章结束时的关系状态" }
+      ],
+      "abilities": ["本章结束时确认拥有的能力、资源或限制"],
+      "secrets": ["本章结束时仍未公开或只被部分人知道的秘密"],
+      "emotionalState": "本章结束时的情绪状态"
+    }
+  ]
 }
 
 要求：
 - 只记录已经在本章发生或被确认的信息。
 - 不要推测后续剧情。
 - facts 和 stateChanges 要具体，便于后续章节引用。
+- wordCount 用中文字符数（去掉空格和 Markdown 标记），近似估算即可。
+- threadActions 是关键：
+  · 任何"上下文里 Active Foreshadow Threads"列出的活跃伏笔，如果本章推进了，请发 kind="build"；如果本章正式回收/兑现，请发 kind="pay"；如果本章决定放弃，请发 kind="drop"。这三种情况 threadId 必填。
+  · 本章新埋设的伏笔，请发 kind="plant"，description 写清楚是什么伏笔。
+  · 活跃伏笔本章没动也没关系，不需要为它发动作；但**不要悄悄删除**——只要不发 drop，它就继续保留活跃。
+- characterUpdates 用于维护独立角色状态表：只输出本章有明确变化或被重新确认的重要人物；目标、信念、关系、能力、秘密、情绪状态必须以本章结尾为准。
 ${strictJsonOutputRules()}`,
     };
 }
@@ -240,6 +294,12 @@ function buildChapterReviewPrompt(input) {
         prompt: `你是一名严格的章节审稿编辑。请审阅指定章节是否存在内部问题以及与既有设定的冲突。
 
 ${input.context ? `## 审阅上下文\n${input.context}\n` : ''}## 审阅重点
+- 这是强制章节验收门槛：只要任一验收项 fail，status 必须是 "issues_found"，不能进入下一章。
+- requiredBeats 是否全部完成；缺失项必须写入 acceptance.requiredBeats.missingBeats。
+- 本章是否推进主线、人物状态或活跃伏笔；如果完全原地踏步，narrativeProgress/characterProgress/foreshadowProgress 至少一项必须 fail。
+- 是否违反故事圣经、角色状态表、卷级节奏板或历史记忆。
+- 章末是否有清晰钩子，且符合本章 endHookFocus。
+- 是否重复之前章节已经完成的桥段、冲突结构、信息揭示或对话功能。
 - 人物声音、动机、状态是否符合故事圣经与历史记忆。
 - 世界规则、物品归属、能力边界是否被破坏。
 - 时间线、地点、与上一章结尾的衔接是否一致。
@@ -251,6 +311,37 @@ ${input.context ? `## 审阅上下文\n${input.context}\n` : ''}## 审阅重点
 {
   "chapterNumber": ${chapter},
   "status": "clean",
+  "acceptance": {
+    "requiredBeats": {
+      "status": "pass | fail",
+      "evidence": "逐条说明 requiredBeats 完成证据",
+      "missingBeats": []
+    },
+    "narrativeProgress": {
+      "status": "pass | fail",
+      "evidence": "本章如何推进主线/阶段目标"
+    },
+    "characterProgress": {
+      "status": "pass | fail",
+      "evidence": "本章如何改变或确认关键人物目标、信念、关系、能力、秘密或情绪"
+    },
+    "foreshadowProgress": {
+      "status": "pass | fail",
+      "evidence": "本章如何埋设、推进、回收或有意识保留伏笔"
+    },
+    "storyBibleConsistency": {
+      "status": "pass | fail",
+      "evidence": "是否符合故事圣经、角色状态表和世界规则"
+    },
+    "endingHook": {
+      "status": "pass | fail",
+      "evidence": "章末钩子的具体段落和作用"
+    },
+    "repetition": {
+      "status": "pass | fail",
+      "evidence": "是否重复既有桥段；无重复也要说明依据"
+    }
+  },
   "issues": [
     {
       "severity": "low | medium | high",
@@ -265,6 +356,8 @@ ${input.context ? `## 审阅上下文\n${input.context}\n` : ''}## 审阅重点
 要求：
 - 没有问题时 status 为 "clean"，issues 输出空数组。
 - 有问题时 status 为 "issues_found"。
+- 只有所有 acceptance 项都是 "pass" 时，status 才能为 "clean"。
+- 任一 acceptance 项为 "fail" 时，必须在 issues 中写出对应问题与修复建议。
 - evidence 必须具体，不能写"疑似"、"可能"。
 ${strictJsonOutputRules()}`,
     };
@@ -348,6 +441,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: `请基于当前已有故事圣经与本次反馈，输出"修订后的完整故事圣经 Markdown"。
+
+${input.context ? `## 修订上下文\n${input.context}\n` : ''}## 输出要求
+- 输出完整的 story-bible.md 内容，覆盖式替换旧版（旧版会自动归档到 story-bible-versions/）。
+- 保留旧版仍然成立的内容，仅修改 / 新增 / 删除有明确依据的部分。
+- 不要输出 diff、变更说明、bullet 总结，直接输出新 bible 全文。`,
+            };
         case 'complete':
             return {
                 purpose: 'continuity_review',

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

@@ -82,6 +82,14 @@ export async function indexMemoryCard(projectPath, chapterNumber, card) {
     const id = `memory:${chapterNumber}`;
     await upsert(projectPath, (existing) => existing === id, chunkMemoryCard(chapterNumber, card));
 }
+export async function removeChapterFromIndex(projectPath, chapterNumber) {
+    const prefix = `chapter:${chapterNumber}:`;
+    await upsert(projectPath, (id) => id.startsWith(prefix), []);
+}
+export async function removeMemoryCardFromIndex(projectPath, chapterNumber) {
+    const id = `memory:${chapterNumber}`;
+    await upsert(projectPath, (existing) => existing === id, []);
+}
 export async function retrieve(projectPath, query, options = {}) {
     if (!query.trim())
         return [];

package/dist/src/core/schemas.js

@@ -18,18 +18,83 @@ export const VolumeArchitectureSchema = z.object({
     summary: z.string().min(1),
     order: z.number().int().positive(),
 });
+export const VolumePacingBoardSchema = z.object({
+    volumeId: z.string().min(1),
+    start: z.string().min(1),
+    promise: z.string().min(1),
+    keyTurns: z.array(z.string().min(1)).min(1),
+    midpoint: z.string().min(1),
+    climax: z.string().min(1),
+    payoffs: z.array(z.string().min(1)),
+    lingeringMysteries: z.array(z.string().min(1)),
+});
+export const EndHookFocusSchema = z.enum([
+    'cliffhanger',
+    'mystery',
+    'emotional',
+    'reveal',
+    'volume_close',
+    'gentle',
+]);
 export const ChapterArchitectureSchema = z.object({
     chapterNumber: z.number().int().positive(),
     title: z.string().min(1),
     volumeId: z.string().min(1),
     summary: z.string().min(1),
     requiredBeats: z.array(z.string().min(1)).min(1),
+    targetWords: z.number().int().positive().optional(),
+    requireRecap: z.boolean().optional(),
+    endHookFocus: EndHookFocusSchema.optional(),
+    povCharacter: z.string().min(1).optional(),
 });
 export const ArchitecturePayloadSchema = z.object({
     full: z.string().min(1),
     volumes: z.array(VolumeArchitectureSchema).min(1),
+    volumePacing: z.array(VolumePacingBoardSchema).optional(),
     chapters: z.array(ChapterArchitectureSchema).min(1),
 });
+export const ThreadActionSchema = z.object({
+    kind: z.enum(['plant', 'build', 'pay', 'drop']),
+    threadId: z.string().min(1).optional(),
+    description: z.string().min(1),
+});
+export const ThreadStatusSchema = z.enum(['planted', 'building', 'paid', 'dropped']);
+export const ThreadSchema = z.object({
+    id: z.string().min(1),
+    description: z.string().min(1),
+    status: ThreadStatusSchema,
+    plantedAt: z.number().int().positive(),
+    lastTouchedAt: z.number().int().positive(),
+    plannedPayoffAt: z.number().int().positive().optional(),
+    paidOffAt: z.number().int().positive().optional(),
+    droppedAt: z.number().int().positive().optional(),
+    notes: z.string().optional(),
+});
+export const CharacterRelationshipStateSchema = z.object({
+    name: z.string().min(1),
+    dynamic: z.string().min(1),
+});
+export const CharacterStateSchema = z.object({
+    name: z.string().min(1),
+    role: z.string().min(1).optional(),
+    goal: z.string().min(1),
+    belief: z.string().min(1),
+    relationships: z.array(CharacterRelationshipStateSchema),
+    abilities: z.array(z.string().min(1)),
+    secrets: z.array(z.string().min(1)),
+    emotionalState: z.string().min(1),
+    lastUpdatedAt: z.number().int().nonnegative(),
+});
+export const CharacterStateUpdateSchema = z.object({
+    name: z.string().min(1),
+    role: z.string().min(1).optional(),
+    goal: z.string().min(1).optional(),
+    belief: z.string().min(1).optional(),
+    relationships: z.array(CharacterRelationshipStateSchema).optional(),
+    abilities: z.array(z.string().min(1)).optional(),
+    secrets: z.array(z.string().min(1)).optional(),
+    emotionalState: z.string().min(1).optional(),
+});
 export const MemoryCardSchema = z.object({
     summary: z.string().min(1),
     keyEvents: z.array(z.string().min(1)),
@@ -49,6 +114,9 @@ export const MemoryCardSchema = z.object({
         after: z.string().min(1),
     })),
     openThreads: z.array(z.string().min(1)),
+    wordCount: z.number().int().nonnegative().optional(),
+    threadActions: z.array(ThreadActionSchema).optional(),
+    characterUpdates: z.array(CharacterStateUpdateSchema).optional(),
 });
 export const ContinuityReviewSchema = z.object({
     range: z.object({
@@ -65,14 +133,43 @@ export const ContinuityReviewSchema = z.object({
 });
 export const ChapterReviewIssueSchema = z.object({
     severity: z.enum(['low', 'medium', 'high']),
-    category: z.enum(['character', 'world', 'timeline', 'item', 'knowledge', 'pacing', 'style', 'architecture']),
+    category: z.enum([
+        'character',
+        'world',
+        'timeline',
+        'item',
+        'knowledge',
+        'pacing',
+        'style',
+        'architecture',
+        'plot',
+        'foreshadow',
+        'hook',
+        'repetition',
+    ]),
     description: z.string().min(1),
     evidence: z.string().min(1),
     suggestion: z.string().min(1),
 });
+export const ChapterAcceptanceCheckSchema = z.object({
+    status: z.enum(['pass', 'fail']),
+    evidence: z.string().min(1),
+});
+export const ChapterAcceptanceGateSchema = z.object({
+    requiredBeats: ChapterAcceptanceCheckSchema.extend({
+        missingBeats: z.array(z.string().min(1)),
+    }),
+    narrativeProgress: ChapterAcceptanceCheckSchema,
+    characterProgress: ChapterAcceptanceCheckSchema,
+    foreshadowProgress: ChapterAcceptanceCheckSchema,
+    storyBibleConsistency: ChapterAcceptanceCheckSchema,
+    endingHook: ChapterAcceptanceCheckSchema,
+    repetition: ChapterAcceptanceCheckSchema,
+});
 export const ChapterReviewSchema = z.object({
     chapterNumber: z.number().int().positive(),
     status: z.enum(['clean', 'issues_found']),
+    acceptance: ChapterAcceptanceGateSchema,
     issues: z.array(ChapterReviewIssueSchema),
 });
 export const CrossChapterReviewSchema = z.object({

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

@@ -8,9 +8,15 @@ export const architectureHandler = async (state, content) => {
         await saveJsonFile(state.projectPath, 'architecture/volumes.json', parsed.volumes),
         await saveJsonFile(state.projectPath, 'architecture/chapters.json', parsed.chapters),
     ];
+    if (parsed.volumePacing) {
+        savedPaths.push(await saveJsonFile(state.projectPath, 'architecture/volume-pacing.json', parsed.volumePacing));
+    }
     return {
         savedPaths,
-        fileEntries: { architecture: 'architecture/chapters.json' },
+        fileEntries: {
+            architecture: 'architecture/chapters.json',
+            ...(parsed.volumePacing ? { volumePacing: 'architecture/volume-pacing.json' } : {}),
+        },
         next: { kind: 'linear', nextStep: 'chapter' },
     };
 };

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

@@ -11,6 +11,16 @@ export const chapterHandler = 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/dist/src/core/steps/chapterReview.js

@@ -8,9 +8,33 @@ export const chapterReviewHandler = async (state, content) => {
     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') {
+        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/dist/src/core/steps/chapterRevision.js

@@ -12,6 +12,23 @@ export const chapterRevisionHandler = 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/dist/src/core/steps/memoryCard.js

@@ -3,12 +3,16 @@ 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 { parseJson } from './types.js';
 export const memoryCardHandler = 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;
     return {
         savedPaths: [path],

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

@@ -1,12 +1,14 @@
 import { NovelMetadataSchema } from '../schemas.js';
 import { saveJsonFile } from '../projectStore.js';
+import { initializeCharacterStates } from '../characterStore.js';
 import { parseJson } from './types.js';
 export const novelMetadataHandler = 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/dist/src/core/threadStore.js

@@ -0,0 +1,150 @@
+import { randomBytes } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const THREADS_FILE = 'threads.json';
+export async function loadThreads(projectPath) {
+    try {
+        const raw = await readFile(join(projectPath, THREADS_FILE), 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.threads) ? parsed.threads : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function saveThreads(projectPath, threads) {
+    const fullPath = join(projectPath, THREADS_FILE);
+    const bundle = { threads };
+    await writeFile(fullPath, `${JSON.stringify(bundle, null, 2)}\n`, 'utf8');
+    return fullPath;
+}
+function newThreadId(existing) {
+    let candidate = `t_${randomBytes(3).toString('hex')}`;
+    while (existing.has(candidate)) {
+        candidate = `t_${randomBytes(3).toString('hex')}`;
+    }
+    return candidate;
+}
+function findByDescription(threads, description) {
+    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, chapterNumber, actions) {
+    if (!actions || !actions.length)
+        return existing;
+    const next = 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 = {
+                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) {
+    return threads.filter((t) => t.status === 'planted' || t.status === 'building');
+}
+export async function ingestMemoryCardThreads(projectPath, chapterNumber, actions) {
+    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 async function updateThread(projectPath, id, patch) {
+    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/dist/src/core/workflow.js

@@ -83,19 +83,19 @@ function buildPendingAction(state, input) {
         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.step}`);