@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/core/src/agents/composer.ts

@@ -0,0 +1,469 @@
+import { readFile, readdir, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { BaseAgent } from "./base.js";
+import type { BookConfig } from "../models/book.js";
+import {
+  ContextPackageSchema,
+  type ChapterTrace,
+  type ContextPackage,
+  type RuleStack,
+} from "../models/input-governance.js";
+import type { PlanChapterOutput } from "./planner.js";
+import {
+  parseChapterSummariesMarkdown,
+  retrieveMemorySelection,
+} from "../utils/memory-retrieval.js";
+import {
+  buildGovernedRuleStack,
+  buildGovernedTrace,
+} from "../utils/context-assembly.js";
+import { writeGovernedRuntimeArtifacts } from "../utils/runtime-writer.js";
+
+export interface ComposeChapterInput {
+  readonly book: BookConfig;
+  readonly bookDir: string;
+  readonly chapterNumber: number;
+  readonly plan: PlanChapterOutput;
+}
+
+export interface ComposeChapterOutput {
+  readonly contextPackage: ContextPackage;
+  readonly ruleStack: RuleStack;
+  readonly trace: ChapterTrace;
+  readonly contextPath: string;
+  readonly ruleStackPath: string;
+  readonly tracePath: string;
+}
+
+export async function composeGovernedChapter(input: ComposeChapterInput): Promise<ComposeChapterOutput> {
+  const storyDir = join(input.bookDir, "story");
+  const runtimeDir = join(storyDir, "runtime");
+  await mkdir(runtimeDir, { recursive: true });
+
+  const selectedContext = await collectSelectedContext(
+    storyDir,
+    input.plan,
+    input.book.language ?? "zh",
+  );
+  const contextPackage = ContextPackageSchema.parse({
+    chapter: input.chapterNumber,
+    selectedContext,
+  });
+
+  const ruleStack = buildGovernedRuleStack(input.plan, input.chapterNumber);
+  const trace = buildGovernedTrace({
+    chapterNumber: input.chapterNumber,
+    plan: input.plan,
+    contextPackage,
+    composerInputs: [input.plan.runtimePath],
+  });
+  const {
+    contextPath,
+    ruleStackPath,
+    tracePath,
+  } = await writeGovernedRuntimeArtifacts({
+    runtimeDir,
+    chapterNumber: input.chapterNumber,
+    contextPackage,
+    ruleStack,
+    trace,
+  });
+
+  return {
+    contextPackage,
+    ruleStack,
+    trace,
+    contextPath,
+    ruleStackPath,
+    tracePath,
+  };
+}
+
+export class ComposerAgent extends BaseAgent {
+  get name(): string {
+    return "composer";
+  }
+
+  async composeChapter(input: ComposeChapterInput): Promise<ComposeChapterOutput> {
+    return composeGovernedChapter(input);
+  }
+}
+
+async function collectSelectedContext(
+  storyDir: string,
+  plan: PlanChapterOutput,
+  language: "zh" | "en",
+): Promise<ContextPackage["selectedContext"]> {
+    const retrievalHints = deriveRetrievalHints(plan);
+    const memoBodyExcerpt = plan.memo.body.trim();
+    const chapterMemoEntry = memoBodyExcerpt.length > 0
+      ? [{
+          source: "runtime/chapter_memo",
+          reason: "Carry the planner's chapter memo into governed writing.",
+          excerpt: [
+            `goal=${plan.memo.goal}`,
+            plan.memo.isGoldenOpening ? "golden-opening=true" : undefined,
+            memoBodyExcerpt,
+          ].filter(Boolean).join(" | "),
+        }]
+      : [{
+          source: "runtime/chapter_memo",
+          reason: "Carry the planner's chapter memo into governed writing.",
+          excerpt: `goal=${plan.memo.goal}`,
+        }];
+
+    const entries = await Promise.all([
+      maybeContextSource(storyDir, "current_focus.md", "Current task focus for this chapter."),
+      maybeContextSource(
+        storyDir,
+        "audit_drift.md",
+        "Carry forward audit drift guidance from the previous chapter without polluting hard state facts.",
+      ),
+      maybeContextSource(
+        storyDir,
+        "current_state.md",
+        "Preserve hard state facts referenced by the active chapter brief or hard constraints.",
+        retrievalHints,
+      ),
+      maybeContextSource(
+        storyDir,
+        "outline/story_frame.md",
+        "Preserve canon constraints referenced by the active chapter brief or hard constraints.",
+        retrievalHints,
+      ),
+      maybeContextSource(
+        storyDir,
+        "outline/volume_map.md",
+        "Anchor the default planning node for this chapter.",
+        plan.intent.outlineNode ? [plan.intent.outlineNode] : [],
+      ),
+      maybeContextSource(
+        storyDir,
+        "parent_canon.md",
+        "Preserve parent canon constraints for governed continuation or fanfic writing.",
+      ),
+      maybeContextSource(
+        storyDir,
+        "fanfic_canon.md",
+        "Preserve extracted fanfic canon constraints for governed writing.",
+      ),
+    ]);
+    const trailEntries = await buildRecentChapterTrailEntries(storyDir, plan.intent.chapter);
+
+    const memorySelection = await retrieveMemorySelection({
+      bookDir: dirname(storyDir),
+      chapterNumber: plan.intent.chapter,
+      goal: plan.intent.goal,
+      outlineNode: plan.intent.outlineNode,
+      mustKeep: retrievalHints,
+    });
+    const hookDebtEntries = await buildHookDebtEntries(
+      storyDir,
+      plan,
+      memorySelection.activeHooks,
+      language,
+    );
+
+    const summaryEntries = memorySelection.summaries.map((summary) => ({
+      source: `story/chapter_summaries.md#${summary.chapter}`,
+      reason: "Relevant episodic memory retrieved for the current chapter goal.",
+      excerpt: [summary.title, summary.events, summary.stateChanges, summary.hookActivity]
+        .filter(Boolean)
+        .join(" | "),
+    }));
+    const factEntries = memorySelection.facts.map((fact) => ({
+      source: `story/current_state.md#${toFactAnchor(fact.predicate)}`,
+      reason: "Relevant current-state fact retrieved for the current chapter goal.",
+      excerpt: `${fact.predicate} | ${fact.object}`,
+    }));
+    const hookEntries = memorySelection.hooks.map((hook) => ({
+      source: `story/pending_hooks.md#${hook.hookId}`,
+      reason: "Carry forward unresolved hooks that match the chapter focus.",
+      excerpt: [hook.type, hook.status, hook.expectedPayoff, hook.payoffTiming, hook.notes]
+        .filter(Boolean)
+        .join(" | "),
+    }));
+    const volumeSummaryEntries = memorySelection.volumeSummaries.map((summary) => ({
+      source: `story/volume_summaries.md#${summary.anchor}`,
+      reason: "Carry forward long-span arc memory compressed from earlier volumes.",
+      excerpt: `${summary.heading} | ${summary.content}`,
+    }));
+
+    return [
+      ...chapterMemoEntry,
+      ...entries.filter((entry): entry is NonNullable<typeof entry> => entry !== null),
+      ...trailEntries,
+      ...hookDebtEntries,
+      ...factEntries,
+      ...summaryEntries,
+      ...volumeSummaryEntries,
+      ...hookEntries,
+    ];
+}
+
+function deriveRetrievalHints(plan: PlanChapterOutput): string[] {
+  return [
+    plan.intent.goal,
+    plan.intent.outlineNode,
+    ...plan.memo.threadRefs,
+  ].filter((value): value is string => Boolean(value));
+}
+
+async function buildRecentChapterTrailEntries(
+  storyDir: string,
+  chapterNumber: number,
+): Promise<ContextPackage["selectedContext"]> {
+    const content = await readFileOrDefault(join(storyDir, "chapter_summaries.md"));
+    if (!content || content === "(文件尚未创建)") {
+      return [];
+    }
+
+    const recentSummaries = parseChapterSummariesMarkdown(content)
+      .filter((summary) => summary.chapter < chapterNumber)
+      .sort((left, right) => right.chapter - left.chapter)
+      .slice(0, 5);
+    if (recentSummaries.length === 0) {
+      return [];
+    }
+
+    const entries: ContextPackage["selectedContext"] = [];
+    const recentTitles = recentSummaries
+      .map((summary) => [summary.chapter, summary.title].filter(Boolean).join(": "))
+      .filter(Boolean)
+      .join(" | ");
+    if (recentTitles) {
+      entries.push({
+        source: "story/chapter_summaries.md#recent_titles",
+        reason: "Keep recent title history visible to avoid repetitive chapter naming.",
+        excerpt: recentTitles,
+      });
+    }
+
+    const moodTrail = recentSummaries
+      .filter((summary) => summary.mood || summary.chapterType)
+      .map((summary) => `${summary.chapter}: ${summary.mood || "(none)"} / ${summary.chapterType || "(none)"}`)
+      .join(" | ");
+    if (moodTrail) {
+      entries.push({
+        source: "story/chapter_summaries.md#recent_mood_type_trail",
+        reason: "Keep recent mood and chapter-type cadence visible before writing the next chapter.",
+        excerpt: moodTrail,
+      });
+    }
+
+    const endingTrail = await buildRecentEndingTrail(storyDir, chapterNumber);
+    if (endingTrail) {
+      entries.push({
+        source: "story/chapters#recent_endings",
+        reason: "Show how recent chapters ended so the writer avoids structural repetition (e.g. 3 consecutive collapse endings).",
+        excerpt: endingTrail,
+      });
+    }
+
+    return entries;
+}
+
+async function buildRecentEndingTrail(
+  storyDir: string,
+  chapterNumber: number,
+): Promise<string | undefined> {
+    const chaptersDir = join(dirname(storyDir), "chapters");
+    try {
+      const files = await readdir(chaptersDir);
+      const chapterFiles = files
+        .filter((file) => file.endsWith(".md"))
+        .map((file) => ({ file, num: parseInt(file.slice(0, 4), 10) }))
+        .filter((entry) => Number.isFinite(entry.num) && entry.num < chapterNumber)
+        .sort((a, b) => b.num - a.num)
+        .slice(0, 3);
+
+      const endings: string[] = [];
+      for (const entry of chapterFiles.reverse()) {
+        const content = await readFile(join(chaptersDir, entry.file), "utf-8");
+        const lastLine = extractLastMeaningfulSentence(content);
+        if (lastLine) {
+          endings.push(`ch${entry.num}: ${lastLine}`);
+        }
+      }
+      return endings.length >= 2 ? endings.join(" | ") : undefined;
+    } catch {
+      return undefined;
+    }
+}
+
+function extractLastMeaningfulSentence(content: string): string | undefined {
+    const lines = content.split("\n").map((line) => line.trim()).filter((line) =>
+      line.length > 5 && !line.startsWith("#") && !line.startsWith("|") && !line.startsWith("==="),
+    );
+    const last = lines.at(-1);
+    if (!last) return undefined;
+    return last.length > 60 ? last.slice(0, 57) + "..." : last;
+}
+
+async function buildHookDebtEntries(
+  storyDir: string,
+  plan: PlanChapterOutput,
+  activeHooks: ReadonlyArray<{
+      readonly hookId: string;
+      readonly startChapter: number;
+      readonly type: string;
+      readonly status: string;
+      readonly lastAdvancedChapter: number;
+      readonly expectedPayoff: string;
+      readonly payoffTiming?: string;
+      readonly notes: string;
+    }>,
+  language: "zh" | "en",
+): Promise<ContextPackage["selectedContext"]> {
+    const targetHookIds = [...new Set(plan.memo.threadRefs)];
+    if (targetHookIds.length === 0) {
+      return [];
+    }
+
+    const summaries = parseChapterSummariesMarkdown(
+      await readFileOrDefault(join(storyDir, "chapter_summaries.md")),
+    );
+
+    return targetHookIds.flatMap((hookId) => {
+      const hook = activeHooks.find((entry) => entry.hookId === hookId);
+      if (!hook) {
+        return [];
+      }
+
+      const seedSummary = findHookSummary(summaries, hook.hookId, hook.startChapter, "seed");
+      const latestSummary = findHookSummary(summaries, hook.hookId, hook.lastAdvancedChapter, "latest");
+      const role = language === "en" ? "memo-referenced debt" : "备忘引用旧债";
+      const promise = hook.expectedPayoff || (language === "en" ? "(unspecified)" : "（未写明）");
+      const seedBeat = seedSummary
+        ? renderHookDebtBeat(seedSummary)
+        : (hook.notes || promise);
+      const latestBeat = latestSummary && latestSummary !== seedSummary
+        ? renderHookDebtBeat(latestSummary)
+        : undefined;
+      const age = Math.max(0, plan.intent.chapter - Math.max(1, hook.startChapter));
+
+      return [{
+        source: `runtime/hook_debt#${hook.hookId}`,
+        reason: language === "en"
+          ? "Narrative debt brief with original seed text for this hook agenda target."
+          : "含原始种子文本的叙事债务简报。",
+        excerpt: language === "en"
+          ? [
+              `${hook.hookId} (${hook.type}, ${role}, open ${age} chapters)`,
+              `reader promise: ${promise}`,
+              `original seed (ch${hook.startChapter}): ${seedBeat}`,
+              latestBeat ? `latest turn (ch${hook.lastAdvancedChapter}): ${latestBeat}` : undefined,
+            ].filter(Boolean).join(" | ")
+          : [
+              `${hook.hookId}（${hook.type}，${role}，已开${age}章）`,
+              `读者承诺：${promise}`,
+              `种于第${hook.startChapter}章：${seedBeat}`,
+              latestBeat ? `推进于第${hook.lastAdvancedChapter}章：${latestBeat}` : undefined,
+            ].filter(Boolean).join(" | "),
+      }];
+    });
+}
+
+async function maybeContextSource(
+  storyDir: string,
+  fileName: string,
+  reason: string,
+  preferredExcerpts: ReadonlyArray<string> = [],
+): Promise<ContextPackage["selectedContext"][number] | null> {
+    const path = join(storyDir, fileName);
+    let content = await readFileOrDefault(path);
+    let resolvedFileName = fileName;
+
+    if ((!content || content === "(文件尚未创建)")) {
+      // Phase 5 back-compat: the new outline/ files may be absent on legacy
+      // books. Fall back to the deprecated paths transparently.
+      const legacyFallback = outlineFallback(fileName);
+      if (legacyFallback) {
+        const legacyPath = join(storyDir, legacyFallback);
+        const legacyContent = await readFileOrDefault(legacyPath);
+        if (legacyContent && legacyContent !== "(文件尚未创建)") {
+          content = legacyContent;
+          resolvedFileName = legacyFallback;
+        }
+      }
+    }
+
+    if (!content || content === "(文件尚未创建)") return null;
+
+    return {
+      source: `story/${resolvedFileName}`,
+      reason,
+      excerpt: pickExcerpt(content, preferredExcerpts),
+    };
+}
+
+function outlineFallback(fileName: string): string | null {
+    if (fileName === "outline/story_frame.md") return "story_bible.md";
+    if (fileName === "outline/volume_map.md") return "volume_outline.md";
+    return null;
+}
+
+function pickExcerpt(content: string, preferredExcerpts: ReadonlyArray<string>): string | undefined {
+    for (const preferred of preferredExcerpts) {
+      if (preferred && content.includes(preferred)) return preferred;
+    }
+
+    return content
+      .split("\n")
+      .map((line) => line.trim())
+      .find((line) => line.length > 0 && !line.startsWith("#"));
+}
+
+function toFactAnchor(predicate: string): string {
+    return predicate
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9\u4e00-\u9fff]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      || "fact";
+}
+
+async function readFileOrDefault(path: string): Promise<string> {
+  try {
+    return await readFile(path, "utf-8");
+  } catch {
+    return "(文件尚未创建)";
+  }
+}
+
+function findHookSummary(
+  summaries: ReadonlyArray<ReturnType<typeof parseChapterSummariesMarkdown>[number]>,
+  hookId: string,
+  chapter: number,
+  mode: "seed" | "latest",
+) {
+  const directChapterHit = summaries.find((summary) => summary.chapter === chapter);
+  const hookMentions = summaries.filter((summary) => summaryMentionsHook(summary, hookId));
+  if (mode === "seed") {
+    return hookMentions.find((summary) => summary.chapter === chapter)
+      ?? hookMentions.at(0)
+      ?? directChapterHit;
+  }
+
+  return [...hookMentions].reverse().find((summary) => summary.chapter === chapter)
+    ?? hookMentions.at(-1)
+    ?? directChapterHit;
+}
+
+function summaryMentionsHook(
+  summary: ReturnType<typeof parseChapterSummariesMarkdown>[number],
+  hookId: string,
+): boolean {
+  return [
+    summary.title,
+    summary.events,
+    summary.stateChanges,
+    summary.hookActivity,
+  ].some((text) => text.includes(hookId));
+}
+
+function renderHookDebtBeat(
+  summary: ReturnType<typeof parseChapterSummariesMarkdown>[number],
+): string {
+  return `ch${summary.chapter} ${summary.title} - ${summary.events || summary.hookActivity || summary.stateChanges || "(none)"}`;
+}

package/inkos/packages/core/src/agents/consolidator.ts

@@ -0,0 +1,218 @@
+import { BaseAgent } from "./base.js";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { readVolumeMap } from "../utils/outline-paths.js";
+import {
+  parsePendingHooksMarkdown,
+  renderHookSnapshot,
+} from "../utils/story-markdown.js";
+import type { StoredHook } from "../state/memory-db.js";
+
+export interface ConsolidationResult {
+  readonly volumeSummaries: string;
+  readonly archivedVolumes: number;
+  readonly retainedChapters: number;
+  /**
+   * Phase 7 hotfix 2: number of ledger hooks whose `promoted` flag flipped
+   * from false to true during this consolidation run (advanced_count rule).
+   * 0 when pending_hooks.md is absent or no hook crossed the threshold.
+   */
+  readonly promotedHookCount: number;
+}
+
+/**
+ * Consolidates chapter summaries into volume-level narrative summaries.
+ * Reduces token usage for long books while preserving critical context.
+ */
+export class ConsolidatorAgent extends BaseAgent {
+  get name(): string {
+    return "consolidator";
+  }
+
+  /**
+   * Consolidate chapter summaries by volume.
+   * - Reads outline/volume_map.md (fallback: legacy volume_outline.md) to
+   *   determine volume boundaries
+   * - For each completed volume, LLM compresses chapter summaries into a narrative paragraph
+   * - Archives detailed summaries, keeps only recent volume's per-chapter rows
+   */
+  async consolidate(bookDir: string): Promise<ConsolidationResult> {
+    const storyDir = join(bookDir, "story");
+    const summariesPath = join(storyDir, "chapter_summaries.md");
+    const volumeSummariesPath = join(storyDir, "volume_summaries.md");
+
+    const [summariesRaw, outlineRaw] = await Promise.all([
+      readFile(summariesPath, "utf-8").catch(() => ""),
+      readVolumeMap(bookDir, ""),
+    ]);
+
+    // Phase 7 hotfix 2: pre-archive re-promotion pass. Runs independently of
+    // summary consolidation so a new book (no completed volumes yet) still
+    // flips the `promoted` flag whenever a seed's advanced_count crosses the
+    // threshold.
+    const promotedHookCount = await this.rerunAdvancedCountPromotion(storyDir);
+
+    if (!summariesRaw || !outlineRaw) {
+      return { volumeSummaries: "", archivedVolumes: 0, retainedChapters: 0, promotedHookCount };
+    }
+
+    // Parse volume boundaries from outline
+    const volumeBoundaries = this.parseVolumeBoundaries(outlineRaw);
+    if (volumeBoundaries.length === 0) {
+      return { volumeSummaries: "", archivedVolumes: 0, retainedChapters: 0, promotedHookCount };
+    }
+
+    // Parse chapter summaries into rows
+    const { header, rows } = this.parseSummaryTable(summariesRaw);
+    if (rows.length === 0) {
+      return { volumeSummaries: "", archivedVolumes: 0, retainedChapters: 0, promotedHookCount };
+    }
+
+    const maxChapter = Math.max(...rows.map((r) => r.chapter));
+
+    // Determine which volumes are "completed" (all chapters written)
+    const completedVolumes: Array<{ name: string; startCh: number; endCh: number; rows: typeof rows }> = [];
+    const currentVolumeRows: typeof rows = [];
+
+    for (const vol of volumeBoundaries) {
+      const volRows = rows.filter((r) => r.chapter >= vol.startCh && r.chapter <= vol.endCh);
+      if (vol.endCh <= maxChapter && volRows.length > 0) {
+        completedVolumes.push({ ...vol, rows: volRows });
+      } else {
+        // Current/incomplete volume — keep detailed rows
+        currentVolumeRows.push(...volRows);
+      }
+    }
+
+    // Also keep any rows not covered by volume boundaries
+    const coveredChapters = new Set(volumeBoundaries.flatMap((v) => {
+      const chs: number[] = [];
+      for (let i = v.startCh; i <= v.endCh; i++) chs.push(i);
+      return chs;
+    }));
+    for (const r of rows) {
+      if (!coveredChapters.has(r.chapter)) currentVolumeRows.push(r);
+    }
+
+    if (completedVolumes.length === 0) {
+      return {
+        volumeSummaries: "",
+        archivedVolumes: 0,
+        retainedChapters: currentVolumeRows.length,
+        promotedHookCount,
+      };
+    }
+
+    // LLM consolidation for each completed volume
+    const existingVolSummaries = await readFile(volumeSummariesPath, "utf-8").catch(() => "");
+    const newSummaries: string[] = existingVolSummaries ? [existingVolSummaries.trim()] : ["# Volume Summaries\n"];
+
+    for (const vol of completedVolumes) {
+      const volSummaryRows = vol.rows.map((r) => r.raw).join("\n");
+
+      const response = await this.chat([
+        {
+          role: "system",
+          content: `You are a narrative summarizer. Compress chapter-by-chapter summaries into a single coherent paragraph (max 500 words) that captures the key events, character developments, and plot progression of this volume. Preserve specific names, locations, and plot points. Write in the same language as the input.`,
+        },
+        {
+          role: "user",
+          content: `Volume: ${vol.name} (Chapters ${vol.startCh}-${vol.endCh})\n\nChapter summaries:\n${header}\n${volSummaryRows}`,
+        },
+      ], { temperature: 0.3 });
+
+      newSummaries.push(`\n## ${vol.name} (Ch.${vol.startCh}-${vol.endCh})\n\n${response.content.trim()}`);
+    }
+
+    // Write volume summaries
+    await writeFile(volumeSummariesPath, newSummaries.join("\n"), "utf-8");
+
+    // Archive detailed summaries
+    const archiveDir = join(storyDir, "summaries_archive");
+    await mkdir(archiveDir, { recursive: true });
+    for (const vol of completedVolumes) {
+      const archivePath = join(archiveDir, `vol_${vol.startCh}-${vol.endCh}.md`);
+      await writeFile(archivePath, `# ${vol.name}\n\n${header}\n${vol.rows.map((r) => r.raw).join("\n")}`, "utf-8");
+    }
+
+    // Rewrite chapter_summaries.md with only current volume rows
+    const retainedContent = currentVolumeRows.length > 0
+      ? `${header}\n${currentVolumeRows.map((r) => r.raw).join("\n")}\n`
+      : `${header}\n`;
+    await writeFile(summariesPath, retainedContent, "utf-8");
+
+    return {
+      volumeSummaries: newSummaries.join("\n"),
+      archivedVolumes: completedVolumes.length,
+      retainedChapters: currentVolumeRows.length,
+      promotedHookCount,
+    };
+  }
+
+  /**
+   * Phase 7 hotfix 2 — re-run promotion for seeds whose advancedCount has
+   * crossed the 2-chapter threshold since architect seed time. Delegates to
+   * the shared `rerunPromotionPass` in utils/hook-promotion.ts.
+   *
+   * Returns the number of hooks that flipped from promoted=false (or
+   * undefined) to promoted=true this run.
+   */
+  private async rerunAdvancedCountPromotion(storyDir: string): Promise<number> {
+    const ledgerPath = join(storyDir, "pending_hooks.md");
+    const raw = await readFile(ledgerPath, "utf-8").catch(() => "");
+    if (!raw.trim()) return 0;
+
+    const hooks = parsePendingHooksMarkdown(raw);
+    if (hooks.length === 0) return 0;
+
+    const language: "zh" | "en" = /[\u4e00-\u9fff]/.test(raw) ? "zh" : "en";
+    const summariesRaw = await readFile(join(storyDir, "chapter_summaries.md"), "utf-8").catch(() => "");
+
+    const { rerunPromotionPass } = await import("../utils/hook-promotion.js");
+    const result = rerunPromotionPass(hooks, summariesRaw);
+    if (!result.updated) return 0;
+
+    await writeFile(ledgerPath, renderHookSnapshot([...result.hooks], language), "utf-8");
+    return result.flippedCount;
+  }
+
+  private parseVolumeBoundaries(outline: string): Array<{ name: string; startCh: number; endCh: number }> {
+    const volumes: Array<{ name: string; startCh: number; endCh: number }> = [];
+    const lines = outline.split("\n");
+    const volumeHeader = /^(第[一二三四五六七八九十百千万零〇\d]+卷|Volume\s+\d+)/i;
+    const rangePattern = /[（(]\s*(?:第|[Cc]hapters?\s+)?(\d+)\s*[-–~～—]\s*(\d+)\s*(?:章)?\s*[）)]|(?:第|[Cc]hapters?\s+)(\d+)\s*[-–~～—]\s*(\d+)\s*(?:章)?/i;
+
+    for (const rawLine of lines) {
+      const line = rawLine.replace(/^#+\s*/, "").trim();
+      if (!volumeHeader.test(line)) continue;
+
+      const rangeMatch = line.match(rangePattern);
+      if (!rangeMatch) continue;
+
+      const startCh = parseInt(rangeMatch[1] ?? rangeMatch[3] ?? "0", 10);
+      const endCh = parseInt(rangeMatch[2] ?? rangeMatch[4] ?? "0", 10);
+      if (startCh <= 0 || endCh <= 0) continue;
+
+      const rangeIndex = rangeMatch.index ?? line.length;
+      const name = line.slice(0, rangeIndex).replace(/[（(]\s*$/, "").trim();
+      if (name.length > 0) {
+        volumes.push({ name, startCh, endCh });
+      }
+    }
+    return volumes;
+  }
+
+  private parseSummaryTable(raw: string): { header: string; rows: Array<{ chapter: number; raw: string }> } {
+    const lines = raw.split("\n");
+    const headerLines = lines.filter((l) => l.startsWith("|") && (l.includes("章节") || l.includes("Chapter") || l.includes("---")));
+    const dataLines = lines.filter((l) => l.startsWith("|") && !l.includes("章节") && !l.includes("Chapter") && !l.includes("---"));
+
+    const header = headerLines.join("\n");
+    const rows = dataLines.map((line) => {
+      const match = line.match(/\|\s*(\d+)\s*\|/);
+      return { chapter: match ? parseInt(match[1]!, 10) : 0, raw: line };
+    }).filter((r) => r.chapter > 0);
+
+    return { header, rows };
+  }
+}