@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/core/src/__tests__/planner-context.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  composeCurrentArcProse,
+  extractCollaboratorRows,
+  extractOpponentRows,
+  extractProtagonistRow,
+  extractRelevantThreads,
+} from "../agents/planner-context.js";
+
+// Real column layouts match the production truth-file schemas under story/.
+// Keeping these literal samples in tests guards against the kind of
+// off-by-one column bug that slipped past Phase 3 review.
+const EMOTIONAL_ARCS_SAMPLE = `
+| 角色 | 章节 | 情绪状态 | 触发事件 | 强度(1-10) | 弧线方向 |
+|------|------|----------|----------|-------------|----------|
+| 周谨川 | 36 | 紧绷 | 门前对峙 | 8 | 升级 |
+| 周谨川 | 37 | 克制发热 | 逼对方亮身份 | 9 | 升级 |
+| 周谨川 | 38 | 骤亮后阴冷 | 看见顾明诚收 | 10 | 顶点 |
+`;
+
+const CHARACTER_MATRIX_SAMPLE = `
+| 角色 | 核心标签 | 反差细节 | 说话风格 | 性格底色 | 与主角关系 | 核心动机 | 当前目标 |
+|------|----------|----------|----------|----------|------------|----------|----------|
+| 周谨川 | 带伤守证者 | 起不来身却硬顶 | 短、硬 | 克制耐痛 | 主角本人 | 不让资料被收走 | 守现场 |
+| 草帽男 | 止损执行节点 | 明对手却急坏 | 装熟翻脸 | 控场欲 | 敌对监视者 | 护住七号门 | 顶住门边 |
+| 修锁老师傅 | 一线手艺证人 | 不抢话却硬护场 | 平、稳 | 老练 | 临时协力 | 看锁说锁 | 守住现场事实 |
+`;
+
+const SUBPLOT_BOARD_SAMPLE = `
+| S001 | 三担保排查 | 主角 | ch1 | ch38 | 0 | 推进 | 核心旧账线 | 1章 |
+| S007 | 货款线 | 主角 | ch3 | ch4 | 34 | 暂挂 | 冻结 | 4-6章 |
+`;
+
+describe("composeCurrentArcProse reads chapter from emotional_arcs column 1", () => {
+  it("filters rows by chapter from column index 1 (章节), not column 0 (角色)", () => {
+    // Previously the function filtered where row[0] matched /^\d+$/.
+    // Since row[0] is "周谨川" here, the old predicate produced zero matches
+    // and "近期情感线" fell out of the composed prose entirely.
+    const prose = composeCurrentArcProse(
+      SUBPLOT_BOARD_SAMPLE,
+      EMOTIONAL_ARCS_SAMPLE,
+      39,
+    );
+    expect(prose).toContain("近期情感线");
+    expect(prose).toContain("紧绷");
+    expect(prose).toContain("克制发热");
+    expect(prose).toContain("骤亮后阴冷");
+  });
+
+  it("excludes rows at or beyond the current chapter", () => {
+    const prose = composeCurrentArcProse(
+      SUBPLOT_BOARD_SAMPLE,
+      EMOTIONAL_ARCS_SAMPLE,
+      37,
+    );
+    expect(prose).toContain("紧绷");
+    expect(prose).not.toContain("克制发热");
+    expect(prose).not.toContain("骤亮后阴冷");
+  });
+
+  it("still composes active subplots when emotional arcs are empty", () => {
+    const prose = composeCurrentArcProse(SUBPLOT_BOARD_SAMPLE, "", 39);
+    expect(prose).toContain("活跃支线");
+    expect(prose).toContain("S001");
+    expect(prose).not.toContain("S007");
+  });
+
+  it("returns the empty-state sentinel only when nothing is extractable", () => {
+    const prose = composeCurrentArcProse("", "", 1);
+    expect(prose).toContain("暂无 arc 数据");
+  });
+});
+
+describe("extractProtagonistRow", () => {
+  it("matches the real convention '主角本人', not only the exact token '主角'", () => {
+    const row = extractProtagonistRow(CHARACTER_MATRIX_SAMPLE);
+    expect(row).toContain("周谨川");
+    expect(row).toContain("主角本人");
+  });
+
+  it("falls back to the first data row when no protagonist marker is found", () => {
+    const noMarker = `
+| 角色 | 核心标签 | 与主角关系 |
+|------|----------|------------|
+| 李沉 | 重生者 | — |
+| 王一 | 对手 | 敌对 |
+`;
+    const row = extractProtagonistRow(noMarker);
+    expect(row).toContain("李沉");
+  });
+
+  it("returns the sentinel only when the matrix has zero data rows", () => {
+    const empty = `
+| 角色 | 核心标签 |
+|------|----------|
+`;
+    const row = extractProtagonistRow(empty);
+    expect(row).toContain("未找到主角行");
+  });
+});
+
+describe("extractOpponentRows / extractCollaboratorRows", () => {
+  it("picks opponents by 与主角关系 semantic keywords", () => {
+    const rows = extractOpponentRows(CHARACTER_MATRIX_SAMPLE, 3);
+    expect(rows).toContain("草帽男");
+    expect(rows).not.toContain("周谨川");
+  });
+
+  it("picks collaborators by 与主角关系 semantic keywords", () => {
+    const rows = extractCollaboratorRows(CHARACTER_MATRIX_SAMPLE, 3);
+    expect(rows).toContain("修锁老师傅");
+    expect(rows).not.toContain("草帽男");
+  });
+});
+
+describe("extractRelevantThreads", () => {
+  it("selects active hooks and subplots, filtering dormant/stale", () => {
+    const hooks = `
+| hook_id | 状态 | 最近推进 |
+|---------|------|----------|
+| H001 | activating | ch38 |
+| H002 | dormant | ch20 |
+| H003 | partial_payoff | ch37 |
+`;
+    const subplots = `
+| S001 | 主线追查 | 推进 |
+| S007 | 旁线 | 暂挂 |
+`;
+    const threads = extractRelevantThreads(hooks, subplots);
+    expect(threads).toContain("H001");
+    expect(threads).toContain("H003");
+    expect(threads).not.toContain("H002");
+    expect(threads).toContain("S001");
+    expect(threads).not.toContain("S007");
+  });
+});

package/inkos/packages/core/src/__tests__/planner-prompts-ratio.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { PLANNER_MEMO_SYSTEM_PROMPT, PLANNER_MEMO_SYSTEM_PROMPT_EN } from "../agents/planner-prompts.js";
+
+describe("planner prompt line-ratio handling", () => {
+  it("requires user-specified plot proportions to become visible chapter beats", () => {
+    expect(PLANNER_MEMO_SYSTEM_PROMPT).toContain("用户设定的内容比例必须落成场面");
+    expect(PLANNER_MEMO_SYSTEM_PROMPT).toContain("权谋/感情各半");
+    expect(PLANNER_MEMO_SYSTEM_PROMPT_EN).toContain("User-specified content proportions must become scenes");
+    expect(PLANNER_MEMO_SYSTEM_PROMPT_EN).toContain("politics 50% / romance 50%");
+  });
+});

package/inkos/packages/core/src/__tests__/planner-prompts.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect } from "vitest";
+import {
+  PLANNER_MEMO_SYSTEM_PROMPT,
+  PLANNER_MEMO_USER_TEMPLATE,
+  buildPlannerUserMessage,
+  buildGoldenOpeningGuidance,
+} from "../agents/planner-prompts.js";
+
+describe("PLANNER_MEMO_SYSTEM_PROMPT", () => {
+  it("contains key methodology phrases from new.txt", () => {
+    expect(PLANNER_MEMO_SYSTEM_PROMPT).toContain("1 主线 + 1 支线");
+    expect(PLANNER_MEMO_SYSTEM_PROMPT).toContain("三连问");
+    expect(PLANNER_MEMO_SYSTEM_PROMPT).toContain("YAML frontmatter");
+    expect(PLANNER_MEMO_SYSTEM_PROMPT).toContain("goal 字段不超过 50 字");
+    expect(PLANNER_MEMO_SYSTEM_PROMPT).toContain("## 当前任务");
+    expect(PLANNER_MEMO_SYSTEM_PROMPT).toContain("## 不要做");
+  });
+
+  it("is not accidentally empty", () => {
+    expect(PLANNER_MEMO_SYSTEM_PROMPT.length).toBeGreaterThan(500);
+  });
+});
+
+describe("PLANNER_MEMO_USER_TEMPLATE", () => {
+  it("contains all placeholders", () => {
+    const placeholders = [
+      "{{chapterNumber}}",
+      "{{previous_chapter_ending_excerpt}}",
+      "{{recent_summaries}}",
+      "{{current_arc_prose}}",
+      "{{protagonist_matrix_row}}",
+      "{{opponent_rows}}",
+      "{{collaborator_rows}}",
+      "{{relevant_threads}}",
+      "{{recyclable_hooks}}",
+      "{{isGoldenOpening}}",
+      "{{book_rules_relevant}}",
+    ];
+    for (const ph of placeholders) {
+      expect(PLANNER_MEMO_USER_TEMPLATE).toContain(ph);
+    }
+  });
+});
+
+describe("buildPlannerUserMessage", () => {
+  it("fills placeholders in order", () => {
+    const out = buildPlannerUserMessage({
+      chapterNumber: 12,
+      previousChapterEndingExcerpt: "上一屏结尾原文",
+      recentSummaries: "| ch9 | ... |",
+      currentArcProse: "主线推进七号门",
+      protagonistMatrixRow: "| 阿泽 | 主角 | ... |",
+      opponentRows: "| 老李 | 对手 | ... |",
+      collaboratorRows: "| 小白 | 盟友 | ... |",
+      relevantThreads: "- H03: 未解码信\n- S004: 七号门异常",
+      recyclableHooks: "（暂无陈旧 hook——账本干净）",
+      isGoldenOpening: false,
+      bookRulesRelevant: "- 禁止主角降智",
+    });
+
+    expect(out).toContain("# 第 12 章 memo 请求");
+    expect(out).toContain("上一屏结尾原文");
+    expect(out).toContain("| ch9 | ... |");
+    expect(out).toContain("主线推进七号门");
+    expect(out).toContain("| 阿泽 | 主角 | ... |");
+    expect(out).toContain("| 老李 | 对手 | ... |");
+    expect(out).toContain("| 小白 | 盟友 | ... |");
+    expect(out).toContain("- H03: 未解码信");
+    expect(out).toContain("是否黄金三章：否");
+    expect(out).toContain("- 禁止主角降智");
+    expect(out).not.toContain("{{");
+  });
+
+  it("translates isGoldenOpening true to 是", () => {
+    const out = buildPlannerUserMessage({
+      chapterNumber: 1,
+      previousChapterEndingExcerpt: "",
+      recentSummaries: "",
+      currentArcProse: "",
+      protagonistMatrixRow: "",
+      opponentRows: "",
+      collaboratorRows: "",
+      relevantThreads: "",
+      recyclableHooks: "",
+      isGoldenOpening: true,
+      bookRulesRelevant: "",
+    });
+    expect(out).toContain("是否黄金三章：是");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Phase 6.5 — Golden Opening Guidance prose
+// ---------------------------------------------------------------------------
+
+describe("buildGoldenOpeningGuidance", () => {
+  it("emits zh slot prose for chapter 1 (confront core conflict)", () => {
+    const out = buildGoldenOpeningGuidance(1, "zh");
+    expect(out).toContain("黄金三章规划指引");
+    expect(out).toContain("第 1 章");
+    // Ch1 slot: throw protagonist into core conflict
+    expect(out).toContain("核心冲突");
+    expect(out).toContain("主角出场即面对主线矛盾");
+    // Opening economy
+    expect(out).toContain("场景 ≤ 3");
+    expect(out).toContain("人物 ≤ 3");
+    // Information layering
+    expect(out).toContain("信息分层");
+  });
+
+  it("emits zh slot prose for chapter 2 (demonstrate the edge)", () => {
+    const out = buildGoldenOpeningGuidance(2, "zh");
+    expect(out).toContain("第 2 章");
+    expect(out).toContain("金手指");
+    // Must demand a concrete event, not narration
+    expect(out).toContain("一次具体事件");
+  });
+
+  it("emits zh slot prose for chapter 3 (lock the short-term goal)", () => {
+    const out = buildGoldenOpeningGuidance(3, "zh");
+    expect(out).toContain("第 3 章");
+    expect(out).toContain("短期目标");
+    expect(out).toContain("3-10 章");
+  });
+
+  it("emits en slot prose for chapter 1 with all three slot descriptions", () => {
+    const out = buildGoldenOpeningGuidance(1, "en");
+    expect(out).toContain("Golden Opening Guidance");
+    expect(out).toContain("Chapter 1");
+    expect(out).toContain("core conflict");
+    expect(out).toContain("concrete event");
+    expect(out).toContain("short-term goal");
+  });
+
+  it("returns empty string for ch>=4 in both languages", () => {
+    expect(buildGoldenOpeningGuidance(4, "zh")).toBe("");
+    expect(buildGoldenOpeningGuidance(5, "zh")).toBe("");
+    expect(buildGoldenOpeningGuidance(4, "en")).toBe("");
+    expect(buildGoldenOpeningGuidance(99, "en")).toBe("");
+  });
+
+  it("renders as cohesive prose, not a numbered or bulleted checklist", () => {
+    const zh = buildGoldenOpeningGuidance(1, "zh");
+    // Heading is allowed; body must not contain enumerated lines.
+    expect(zh).not.toMatch(/^\s*1\.\s/m);
+    expect(zh).not.toMatch(/^\s*-\s/m);
+    expect(zh).not.toMatch(/^\s*\*\s/m);
+  });
+
+  it("buildPlannerUserMessage appends guidance for ch<=3 and omits it for ch>=4", () => {
+    const base = {
+      previousChapterEndingExcerpt: "",
+      recentSummaries: "",
+      currentArcProse: "",
+      protagonistMatrixRow: "",
+      opponentRows: "",
+      collaboratorRows: "",
+      relevantThreads: "",
+      recyclableHooks: "",
+      isGoldenOpening: false,
+      bookRulesRelevant: "",
+    };
+
+    const ch2 = buildPlannerUserMessage({ ...base, chapterNumber: 2 });
+    expect(ch2).toContain("黄金三章规划指引");
+    expect(ch2).toContain("第 2 章");
+
+    const ch4 = buildPlannerUserMessage({ ...base, chapterNumber: 4 });
+    expect(ch4).not.toContain("黄金三章规划指引");
+  });
+});

package/inkos/packages/core/src/__tests__/planner.test.ts

@@ -0,0 +1,362 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PlannerAgent } from "../agents/planner.js";
+import * as llmProvider from "../llm/provider.js";
+import type { LLMClient } from "../llm/provider.js";
+import type { BookConfig } from "../models/book.js";
+import { PlannerParseError } from "../utils/chapter-memo-parser.js";
+
+const VALID_BODY = `
+## 当前任务
+主角进入七号门现场，比对锁芯刮痕与监控时间线，把"被动过手脚"从猜测钉成实证。
+
+## 读者此刻在等什么
+1) 读者在等七号门是否有异常实锤
+2) 本章完全兑现，钉成现场实证
+
+## 该兑现的 / 暂不掀的
+- 该兑现：七号门异常 → 钉成现场实证
+- 暂不掀：幕后主使 → 压到第 20 章
+
+## 日常/过渡承担什么任务
+不适用 - 本章为高压实证章，无日常过渡段。
+
+## 关键抉择过三连问
+- 主角本章最关键的一次选择：
+  - 为什么这么做？线索只剩这一条
+  - 符合当前利益吗？符合
+  - 符合他的人设吗？符合
+- 对手/配角本章最关键的一次选择：
+  - 为什么这么做？掩盖踪迹
+  - 符合当前利益吗？符合
+  - 符合他的人设吗？符合
+
+## 章尾必须发生的改变
+- 信息改变：主角掌握实证，可以面对幕后主使前先压住对手的退路
+
+## 本章 hook 账
+advance:
+- H03 "七号门异常" → 从 pressured → near_payoff（本章钉成实证）
+resolve:
+- S004 "锁芯刮痕" → 核验完毕，本章结清
+defer:
+- H07 "幕后主使" → 第 20 章再动
+
+## 不要做
+- 不要让对手突然降智
+- 不要直接点破幕后主使
+`.trim();
+
+function validMemoRaw(chapter: number): string {
+  return `---\nchapter: ${chapter}\ngoal: 把七号门被动过手脚钉成现场实证\nisGoldenOpening: false\nthreadRefs:\n  - H03\n  - S004\n---\n${VALID_BODY}\n`;
+}
+
+const ZERO_USAGE = {
+  promptTokens: 0,
+  completionTokens: 0,
+  totalTokens: 0,
+} as const;
+
+const STUB_CLIENT: LLMClient = {
+  provider: "openai",
+  apiFormat: "chat",
+  stream: false,
+  defaults: { temperature: 0.7, maxTokens: 2048, thinkingBudget: 0, maxTokensCap: null, extra: {} },
+};
+
+function makeBook(): BookConfig {
+  return {
+    id: "book-plan-1",
+    title: "Test Book",
+    genre: "urban",
+    platform: "qidian",
+    status: "active",
+    language: "zh",
+    targetChapters: 120,
+    chapterWordCount: 3000,
+    createdAt: "2026-04-01T00:00:00.000Z",
+    updatedAt: "2026-04-01T00:00:00.000Z",
+  };
+}
+
+async function seedStoryFiles(bookDir: string): Promise<void> {
+  const storyDir = join(bookDir, "story");
+  await mkdir(storyDir, { recursive: true });
+  await Promise.all([
+    writeFile(join(storyDir, "author_intent.md"), "# Intent\n- Tell a taut mystery.", "utf-8"),
+    writeFile(join(storyDir, "current_focus.md"), "# Focus\n- Keep pressure on the seventh gate.", "utf-8"),
+    writeFile(join(storyDir, "story_bible.md"), "# Bible\n- Protagonist: 阿泽", "utf-8"),
+    writeFile(join(storyDir, "volume_outline.md"), "# Outline\n- 第 1 章：开场", "utf-8"),
+    writeFile(join(storyDir, "chapter_summaries.md"), "# Summaries\n", "utf-8"),
+    writeFile(join(storyDir, "book_rules.md"), "# Rules\n- 禁止反派降智", "utf-8"),
+    writeFile(join(storyDir, "current_state.md"), "# State\n- 主角在七号门附近", "utf-8"),
+    writeFile(join(storyDir, "pending_hooks.md"), "# Hooks\n", "utf-8"),
+    writeFile(join(storyDir, "subplot_board.md"), "# Subplot\n", "utf-8"),
+    writeFile(join(storyDir, "emotional_arcs.md"), "# Arcs\n", "utf-8"),
+    writeFile(join(storyDir, "character_matrix.md"), "# Matrix\n", "utf-8"),
+  ]);
+}
+
+describe("PlannerAgent.planChapter memo generation", () => {
+  let root: string;
+  let bookDir: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "planner-memo-"));
+    bookDir = join(root, "book");
+    await seedStoryFiles(bookDir);
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  function makePlanner(): PlannerAgent {
+    return new PlannerAgent({
+      client: STUB_CLIENT,
+      model: "test-model",
+      projectRoot: root,
+      bookId: "book-plan-1",
+    });
+  }
+
+  it("produces a valid ChapterMemo when the LLM returns well-formed output", async () => {
+    const chatSpy = vi.spyOn(llmProvider, "chatCompletion").mockResolvedValue({
+      content: validMemoRaw(1),
+      usage: ZERO_USAGE,
+    } as unknown as Awaited<ReturnType<typeof llmProvider.chatCompletion>>);
+
+    const result = await makePlanner().planChapter({
+      book: makeBook(),
+      bookDir,
+      chapterNumber: 1,
+    });
+
+    expect(chatSpy).toHaveBeenCalledTimes(1);
+    expect(result.memo.chapter).toBe(1);
+    expect(result.memo.isGoldenOpening).toBe(true); // ch1 zh → golden opening, authoritative over LLM
+    expect(result.memo.goal).toBe("把七号门被动过手脚钉成现场实证");
+    expect(result.memo.threadRefs).toEqual(["H03", "S004"]);
+    expect(result.memo.body).toContain("## 当前任务");
+  });
+
+  it("does not hard-cap memo generation below the configured model output budget", async () => {
+    const chatSpy = vi.spyOn(llmProvider, "chatCompletion").mockResolvedValue({
+      content: validMemoRaw(1),
+      usage: ZERO_USAGE,
+    } as unknown as Awaited<ReturnType<typeof llmProvider.chatCompletion>>);
+
+    await makePlanner().planChapter({
+      book: makeBook(),
+      bookDir,
+      chapterNumber: 1,
+    });
+
+    const callArgs = chatSpy.mock.calls[0]!;
+    const options = callArgs[3] as { temperature?: number; maxTokens?: number } | undefined;
+    expect(options).toEqual(expect.objectContaining({ temperature: 0.7 }));
+    expect(options).not.toHaveProperty("maxTokens");
+  });
+
+  it("passes per-chapter user context into the memo prompt as a high-priority instruction", async () => {
+    const chatSpy = vi.spyOn(llmProvider, "chatCompletion").mockResolvedValue({
+      content: validMemoRaw(1),
+      usage: ZERO_USAGE,
+    } as unknown as Awaited<ReturnType<typeof llmProvider.chatCompletion>>);
+
+    await makePlanner().planChapter({
+      book: makeBook(),
+      bookDir,
+      chapterNumber: 1,
+      externalContext: "本章标题：雨夜账本\n必须围绕账本失窃后的当面对质展开。",
+    });
+
+    const callArgs = chatSpy.mock.calls[0]!;
+    const messages = callArgs[2] as ReadonlyArray<{ role: string; content: string }>;
+    const userMsg = messages.find((m) => m.role === "user");
+    expect(userMsg?.content).toContain("本章用户指令");
+    expect(userMsg?.content).toContain("本章标题：雨夜账本");
+    expect(userMsg?.content).toContain("当面对质");
+  });
+
+  it("retries when the first response is malformed and succeeds on retry", async () => {
+    const chatSpy = vi.spyOn(llmProvider, "chatCompletion")
+      .mockResolvedValueOnce({
+        content: "no frontmatter here",
+        usage: ZERO_USAGE,
+      } as unknown as Awaited<ReturnType<typeof llmProvider.chatCompletion>>)
+      .mockResolvedValueOnce({
+        content: "still no frontmatter",
+        usage: ZERO_USAGE,
+      } as unknown as Awaited<ReturnType<typeof llmProvider.chatCompletion>>)
+      .mockResolvedValueOnce({
+        content: validMemoRaw(4),
+        usage: ZERO_USAGE,
+      } as unknown as Awaited<ReturnType<typeof llmProvider.chatCompletion>>);
+
+    const result = await makePlanner().planChapter({
+      book: makeBook(),
+      bookDir,
+      chapterNumber: 4,
+    });
+
+    expect(chatSpy).toHaveBeenCalledTimes(3);
+    expect(result.memo.chapter).toBe(4);
+    expect(result.memo.isGoldenOpening).toBe(false);
+
+    // Retry prompts must include the failure feedback
+    const secondCallArgs = chatSpy.mock.calls[1]!;
+    const secondMessages = secondCallArgs[2] as ReadonlyArray<{ role: string; content: string }>;
+    const userMsg = secondMessages.find((m) => m.role === "user");
+    expect(userMsg?.content).toContain("上次输出的错误");
+  });
+
+  // Phase hotfix 4: English books must receive English system + user prompts
+  // and English golden-opening guidance for chapters ≤ 3.
+  it("uses English prompts end-to-end when book.language is en", async () => {
+    const VALID_EN_BODY = `
+## Current task
+Pin the Door 7 tampering from suspicion to live evidence.
+
+## What the reader is waiting for right now
+1) Reader expects to learn whether Door 7 is really compromised.
+2) This chapter pays it off in full — live evidence on stage.
+
+## To pay off / to keep buried
+- Pay off: Door 7 anomaly → live evidence
+- Keep buried: the mastermind → push to chapter 20
+
+## What the slow / transitional beats carry
+n/a — pressure chapter, no transitional beats.
+
+## Three-question check on the key choice
+- Protagonist's most important choice this chapter:
+  - Why this choice? It is the only remaining lead.
+  - Does it match current interest? Yes.
+  - Does it match their persona? Yes.
+- Antagonist / supporting cast's most important choice this chapter:
+  - Why this choice? To cover their tracks.
+  - Does it match current interest? Yes.
+  - Does it match their persona? Yes.
+
+## Required end-of-chapter change
+- Information change: protagonist holds live evidence.
+
+## Hook ledger for this chapter
+advance:
+- H03 "Door 7 anomaly" → pressured → near_payoff (pinned as live evidence this chapter)
+defer:
+- H07 "the mastermind" → hold until chapter 20
+
+## Do not
+- Do not let the antagonist suddenly turn dumb.
+- Do not directly name the mastermind.
+`.trim();
+
+    const validEnRaw = `---\nchapter: 1\ngoal: Pin Door 7 tampering as live evidence\nisGoldenOpening: false\nthreadRefs:\n  - H03\n---\n${VALID_EN_BODY}\n`;
+
+    const chatSpy = vi.spyOn(llmProvider, "chatCompletion").mockResolvedValue({
+      content: validEnRaw,
+      usage: ZERO_USAGE,
+    } as unknown as Awaited<ReturnType<typeof llmProvider.chatCompletion>>);
+
+    const enBook = { ...makeBook(), language: "en" as const };
+    const result = await makePlanner().planChapter({
+      book: enBook,
+      bookDir,
+      chapterNumber: 1,
+    });
+
+    expect(chatSpy).toHaveBeenCalledTimes(1);
+    expect(result.memo.chapter).toBe(1);
+    expect(result.memo.isGoldenOpening).toBe(true); // ch1 en → also golden (≤5)
+
+    // System prompt must be the English variant
+    const callArgs = chatSpy.mock.calls[0]!;
+    const messages = callArgs[2] as ReadonlyArray<{ role: string; content: string }>;
+    const systemMsg = messages.find((m) => m.role === "system");
+    const userMsg = messages.find((m) => m.role === "user");
+
+    // English system prompt markers
+    expect(systemMsg?.content).toContain("editor-in-chief");
+    expect(systemMsg?.content).toContain("Output format (strict)");
+    expect(systemMsg?.content).not.toContain("你是这本小说的创作总编");
+
+    // English user template markers
+    expect(userMsg?.content).toContain("# Chapter 1 memo request");
+    expect(userMsg?.content).toContain("Last screen of previous chapter");
+    expect(userMsg?.content).toContain("Golden opening chapter: yes");
+    expect(userMsg?.content).not.toContain("# 第 1 章 memo 请求");
+
+    // English golden-opening guidance appended for ch ≤ 3
+    expect(userMsg?.content).toContain("Golden Opening Guidance");
+    expect(userMsg?.content).toContain("Chapter 1");
+    expect(userMsg?.content).not.toContain("黄金三章规划指引");
+  });
+
+  it("throws PlannerParseError when all 3 attempts fail", async () => {
+    vi.spyOn(llmProvider, "chatCompletion").mockResolvedValue({
+      content: "permanently broken",
+      usage: ZERO_USAGE,
+    } as unknown as Awaited<ReturnType<typeof llmProvider.chatCompletion>>);
+
+    await expect(
+      makePlanner().planChapter({
+        book: makeBook(),
+        bookDir,
+        chapterNumber: 2,
+      }),
+    ).rejects.toBeInstanceOf(PlannerParseError);
+  });
+
+  // Phase hotfix 5: planner.intent.mustAvoid must come from the Phase 5
+  // authoritative loader (story_frame frontmatter), not from raw
+  // book_rules.md — for new-layout books the legacy file is just a shim.
+  it("derives intent.mustAvoid from outline/story_frame.md frontmatter (new layout)", async () => {
+    // Replace book_rules.md with a Phase 5 compat shim (no YAML, just pointer)
+    // and put the authoritative YAML on outline/story_frame.md.
+    const storyDir = join(bookDir, "story");
+    await mkdir(join(storyDir, "outline"), { recursive: true });
+    await writeFile(
+      join(storyDir, "outline/story_frame.md"),
+      [
+        "---",
+        "version: \"1.0\"",
+        "protagonist:",
+        "  name: 阿泽",
+        "  personalityLock: []",
+        "  behavioralConstraints: []",
+        "prohibitions:",
+        "  - 禁止主角降智",
+        "  - 禁止神化反派",
+        "---",
+        "",
+        "## 主题与基调",
+        "调查与压制。",
+      ].join("\n"),
+      "utf-8",
+    );
+    await writeFile(
+      join(storyDir, "book_rules.md"),
+      "# 本书规则（兼容指针——已废弃）\n\n> 本文件仅为外部读取保留。",
+      "utf-8",
+    );
+
+    vi.spyOn(llmProvider, "chatCompletion").mockResolvedValue({
+      content: validMemoRaw(2),
+      usage: ZERO_USAGE,
+    } as unknown as Awaited<ReturnType<typeof llmProvider.chatCompletion>>);
+
+    const result = await makePlanner().planChapter({
+      book: makeBook(),
+      bookDir,
+      chapterNumber: 2,
+    });
+
+    expect(result.intent.mustAvoid).toContain("禁止主角降智");
+    expect(result.intent.mustAvoid).toContain("禁止神化反派");
+  });
+});