novel-writer-cli 0.0.1

package/skills/continue/references/context-contracts.md

@@ -0,0 +1,169 @@
+# Agent Context Manifest 字段契约
+
+## 概述
+
+入口 Skill 为每个 Agent 组装一份 **context manifest**，包含两类字段：
+
+- **inline**（内联）：由编排器确定性计算，直接写入 Task prompt——适用于需要预处理/裁剪/跨文件聚合的数据
+- **paths**（文件路径）：指向项目目录下的文件，由 subagent 用 Read 工具自行读取——适用于大段原文内容
+
+设计原则：
+- 同一输入 + 同一项目文件 = 同一 manifest（确定性）
+- paths 中的文件均为项目目录下的相对路径
+- 可选字段缺失时不出现在 manifest 中（非 null）
+- subagent 读取的文件内容不再需要 `<DATA>` 标签包裹（由 agent frontmatter 中的安全约束处理）
+
+---
+
+## ChapterWriter manifest
+
+```
+chapter_writer_manifest = {
+  # ── inline（编排器计算） ──
+  chapter: int,
+  volume: int,
+  storyline_id: str,
+  chapter_outline_block: str,           # 从 outline.md 提取的本章区块文本
+  storyline_context: {                  # 从 chapter_contract/schedule 解析
+    last_chapter_summary: str,
+    chapters_since_last: int,
+    line_arc_progress: str,
+  },
+  concurrent_state: {str: str},         # 其他活跃线一句话状态
+  transition_hint: obj | null,          # 切线过渡
+  hard_rules_list: [str],              # L1 禁止项列表（已格式化）
+  foreshadowing_tasks: [obj],          # 本章伏笔任务子集
+  foreshadow_light_touch_tasks?: [     # 可选：伏笔沉默超阈值时的“轻触提醒”（非剧透、不兑现）；为空则省略该字段
+    {id: str, scope: str, status: str, chapters_since_last_update: int, instruction: str}
+  ],
+  foreshadow_light_touch_degraded?: bool, # 可选：若为 true 表示“轻触提醒”注入降级（如伏笔数据不可读），不等同于“没有需要提醒的条目”
+  ai_blacklist_top10: [str],           # 有效黑名单前 10 词
+  style_drift_directives: [str] | null, # 漂移纠偏指令（active 时注入）
+  engagement_report_summary?: obj,     # 可选：爽点/信息密度窗口报告摘要（logs/engagement/latest.json 裁剪）
+  promise_ledger_report_summary?: obj, # 可选：承诺台账窗口报告摘要（logs/promises/latest.json 裁剪）
+  engagement_report_summary_degraded?: bool,     # 可选：为 true 表示 latest.json 存在但摘要裁剪失败
+  promise_ledger_report_summary_degraded?: bool, # 可选：为 true 表示 latest.json 存在但摘要裁剪失败
+
+  # ── paths（subagent 自读） ──
+  paths: {
+    style_profile: "style-profile.json",                              # 必读（含 style_exemplars + writing_directives）
+    platform_profile: "platform-profile.json",                        # 可选（平台字数/钩子策略/信息负载等）
+    style_drift: "style-drift.json",                                  # 可选
+    chapter_contract: "volumes/vol-{V:02d}/chapter-contracts/chapter-{C:03d}.json",
+    volume_outline: "volumes/vol-{V:02d}/outline.md",
+    current_state: "state/current-state.json",
+    world_rules: "world/rules.json",                                  # 可选
+    recent_summaries: ["summaries/chapter-{C-1:03d}-summary.md", ...], # 近 3 章
+    storyline_memory: "storylines/{storyline_id}/memory.md",           # 可选
+    adjacent_memories: ["storylines/{adj_id}/memory.md", ...],         # 可选
+    character_contracts: ["characters/active/{slug}.json", ...],       # 裁剪后选取
+    project_brief: "brief.md",
+    writing_methodology: "skills/novel-writing/references/style-guide.md",  # 可选
+    engagement_report_latest: "logs/engagement/latest.json",                # 可选（如存在；用于读取完整报告）
+    promise_ledger_report_latest: "logs/promises/latest.json",              # 可选（如存在；用于读取完整报告）
+  }
+}
+```
+
+### 修订模式追加字段
+
+```
+chapter_writer_revision_manifest = chapter_writer_manifest + {
+  # ── inline 追加 ──
+  required_fixes: [{target: str, instruction: str}],  # QualityJudge 最小修订指令（与 eval 输出格式一致）
+  high_confidence_violations: [obj],    # confidence="high" 的违约条目
+
+  # ── paths 追加 ──
+  paths += {
+    chapter_draft: "staging/chapters/chapter-{C:03d}.md",  # 待修订的现有正文
+    chapter_eval: "staging/evaluations/chapter-{C:03d}-eval.json",  # 可选（hook-fix/修订时提供的评估上下文）
+  }
+}
+```
+
+---
+
+## Summarizer manifest
+
+```
+summarizer_manifest = {
+  # ── inline ──
+  chapter: int,
+  volume: int,
+  storyline_id: str,
+  foreshadowing_tasks: [obj],
+  entity_id_map: {slug_id: display_name},
+  hints: [str] | null,                 # ChapterWriter 输出的 hints JSON（编排器从 ChapterWriter 输出末尾的 ```json{"chapter":N,"hints":[...]}``` 块解析；解析失败则为 null）
+
+  # ── paths ──
+  paths: {
+    chapter_draft: "staging/chapters/chapter-{C:03d}.md",
+    current_state: "state/current-state.json",
+  }
+}
+```
+
+---
+
+## StyleRefiner manifest
+
+```
+style_refiner_manifest = {
+  # ── inline ──
+  chapter: int,
+  style_drift_directives: [str] | null,
+  engagement_report_summary?: obj,     # 可选：爽点/信息密度窗口报告摘要（logs/engagement/latest.json 裁剪）
+  promise_ledger_report_summary?: obj, # 可选：承诺台账窗口报告摘要（logs/promises/latest.json 裁剪）
+  engagement_report_summary_degraded?: bool,
+  promise_ledger_report_summary_degraded?: bool,
+
+  # ── paths ──
+  paths: {
+    chapter_draft: "staging/chapters/chapter-{C:03d}.md",
+    style_profile: "style-profile.json",         # 必读（含 style_exemplars）
+    style_drift: "style-drift.json",             # 可选
+    ai_blacklist: "ai-blacklist.json",
+    style_guide: "skills/novel-writing/references/style-guide.md",
+    previous_change_log: "staging/logs/style-refiner-chapter-{C:03d}-changes.json",  # 仅二次润色时出现；首次润色不含此字段
+    engagement_report_latest: "logs/engagement/latest.json",                         # 可选
+    promise_ledger_report_latest: "logs/promises/latest.json",                       # 可选
+  }
+}
+```
+
+---
+
+## QualityJudge manifest
+
+```
+quality_judge_manifest = {
+  # ── inline ──
+  chapter: int,
+  volume: int,
+  chapter_outline_block: str,
+  hard_rules_list: [str],
+  blacklist_lint: obj | null,                    # scripts/lint-blacklist.sh 输出
+  ner_entities: obj | null,                      # scripts/run-ner.sh 输出
+  continuity_report_summary: obj | null,         # logs/continuity/latest.json 裁剪
+
+  # ── paths ──
+  paths: {
+    chapter_draft: "staging/chapters/chapter-{C:03d}.md",
+    style_profile: "style-profile.json",
+    ai_blacklist: "ai-blacklist.json",
+    chapter_contract: "volumes/vol-{V:02d}/chapter-contracts/chapter-{C:03d}.json",
+    world_rules: "world/rules.json",                                  # 可选
+    prev_summary: "summaries/chapter-{C-1:03d}-summary.md",           # 可选（首章无）
+    character_profiles: ["characters/active/{slug}.md", ...],          # 裁剪后选取（叙述档案）
+    character_contracts: ["characters/active/{slug}.json", ...],       # 裁剪后选取（L2 结构化契约）
+    storyline_spec: "storylines/storyline-spec.json",                  # 可选
+    storyline_schedule: "volumes/vol-{V:02d}/storyline-schedule.json", # 可选
+    cross_references: "staging/state/chapter-{C:03d}-crossref.json",
+    quality_rubric: "skills/novel-writing/references/quality-rubric.md",
+  }
+}
+```
+
+---
+
+另见：`continuity-checks.md`（NER schema + 一致性报告 schema + LS-001 结构化输入约定）。

package/skills/continue/references/continuity-checks.md

@@ -0,0 +1,187 @@
+# NER 与一致性检查（M3）
+
+本文件定义 **NER 实体抽取输出** 与 **一致性报告输出** 的最小 schema，用于：
+- `/novel:start` 的「质量回顾 / 卷末回顾」生成可回归的一致性报告；
+- `/novel:continue` 在调用 QualityJudge 时提供 LS-001 的结构化输入（摘要 + 证据）；
+- 可选确定性工具 `scripts/run-ner.sh` 的 stdout JSON 协议。
+
+## 1) 实体抽取输出 schema（`run-ner.sh` / LLM fallback）
+
+`scripts/run-ner.sh <chapter.md>` stdout JSON（exit 0）**必须**满足：
+
+```json
+{
+  "schema_version": 1,
+  "chapter_path": "chapters/chapter-048.md",
+  "entities": {
+    "characters": [
+      {
+        "text": "林枫",
+        "slug_id": null,
+        "confidence": "high",
+        "mentions": [
+          {"line": 120, "snippet": "林枫抬头望向幽暗森林深处……"}
+        ]
+      }
+    ],
+    "locations": [
+      {
+        "text": "幽暗森林",
+        "confidence": "high",
+        "mentions": [
+          {"line": 120, "snippet": "林枫抬头望向幽暗森林深处……"}
+        ]
+      }
+    ],
+    "time_markers": [
+      {
+        "text": "第三年冬末",
+        "normalized": "第三年冬末",
+        "confidence": "high",
+        "mentions": [
+          {"line": 12, "snippet": "第三年冬末，魔都风雪未歇。"}
+        ]
+      }
+    ],
+    "events": [
+      {
+        "text": "王国内战爆发",
+        "confidence": "medium",
+        "mentions": [
+          {"line": 33, "snippet": "王国内战爆发，边关烽烟四起。"}
+        ]
+      }
+    ]
+  }
+}
+```
+
+字段约定：
+- `schema_version`：当前为 `1`。
+- `chapter_path`：输入文件路径（原样回显，便于追溯）。
+- `entities.characters[].slug_id`：**可选**。`run-ner.sh` 无法可靠映射时可省略；LLM fallback 可以结合 `characters/active/*.json` 与 `state/current-state.json` 补全。
+- `confidence`：枚举值为 `"high"` / `"medium"` / `"low"`。
+- `mentions[]`：证据片段（建议最多 5 条）；`snippet` 需截断到 ≤160 字符，避免报告膨胀。
+- `run-ner.sh` 输出中 `slug_id` 为 `null`（脚本无法可靠映射名字→slug）；LLM fallback 可结合 `characters/active/*.json` 补全。
+
+> 说明：`run-ner.sh` 的目标是 **稳定可回归** 的候选实体与证据，不追求完美 NER；一致性判断由入口 Skill + QualityJudge 的语义校验兜底。
+
+## 2) 一致性报告输出 schema（周期性检查 / 卷末回顾）
+
+一致性报告建议写入 `logs/continuity/`（允许创建子目录，保持历史可追溯），stdout 展示简报即可。
+
+最小 JSON 格式：
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "2026-02-24T12:00:00Z",
+  "scope": "periodic",
+  "volume": 2,
+  "chapter_range": [39, 48],
+  "issues": [
+    {
+      "id": "location_contradiction:char=lin-feng:time=第三年冬末:loc=魔都|幽暗森林",
+      "type": "location_contradiction",
+      "severity": "high",
+      "confidence": "high",
+      "entities": {
+        "characters": ["lin-feng"],
+        "locations": ["魔都", "幽暗森林"],
+        "time_markers": ["第三年冬末"],
+        "storylines": ["main-arc"]
+      },
+      "description": "同一 time_marker 下角色位置出现矛盾或疑似瞬移。",
+      "evidence": [
+        {"chapter": 47, "source": "chapter", "line": 12, "snippet": "第三年冬末，林枫仍在魔都……"},
+        {"chapter": 48, "source": "chapter", "line": 120, "snippet": "林枫抬头望向幽暗森林深处……"}
+      ],
+      "suggestions": [
+        "确认时间标尺是否应推进（例如从'第三年冬末'推进到'翌日清晨'）。",
+        "若确为跨地移动，补一段赶路/传送的因果说明。"
+      ]
+    }
+  ],
+  "stats": {
+    "chapters_checked": 10,
+    "issues_total": 3,
+    "issues_by_severity": {"high": 1, "medium": 1, "low": 1}
+  }
+}
+```
+
+字段约定：
+- `type`：枚举值为 `"character_mapping"` / `"relationship_jump"` / `"location_contradiction"` / `"timeline_contradiction"`。
+- `severity`：枚举值为 `"high"` / `"medium"` / `"low"`。
+- `confidence`：枚举值为 `"high"` / `"medium"` / `"low"`。
+- `stats.chapters_missing`（可选）：章节文件缺失数（在 `chapter_range` 内但对应 `chapters/chapter-*.md` 不存在）。
+- `stats.ner_ok / stats.ner_failed`（可选）：NER 成功/失败的章节数（用于降级诊断；不影响 schema 最小要求）。
+- `stats.ner_failed_sample`（可选）：首个 NER 失败原因的截断字符串（便于快速定位脚本缺失/解析失败）。
+
+稳定性（回归友好）要求：
+- `issues[].id` 必须可由 **type + 关键实体 + time_marker** 确定性生成（同批次重复运行应保持一致）。
+- `issues` 输出顺序：`severity (high→low)` → `type` → `id`。
+
+### Issue 类型说明（最小集合）
+
+- `character_mapping`：同一 `display_name` 映射到多个 slug，或 state/档案 display_name 不一致。
+- `relationship_jump`：关系值单章剧烈变化（例如从 80 跳到 -50），或出现互相矛盾的关系描述（需给 evidence）。
+- `location_contradiction`：同一 time_marker 下角色在多个地点（高置信要求提供明确 time_marker + 角色 + 地点证据）。
+- `timeline_contradiction`：跨故事线并发状态（concurrent_state）与本章 time_marker/事件顺序矛盾（用于 LS-001 输入）。
+
+> 注：当前 TypeScript 确定性实现（`src/consistency-auditor.ts`）为最小可用版本，稳定产出 `location_contradiction` / `timeline_contradiction`；`character_mapping` / `relationship_jump` 为预留类型，后续再补全。
+
+## 3) 检测规则建议（实现导向）
+
+本节提供"最小但不乱报"的实现建议，避免检查逻辑断链。你可以更严格，但不得牺牲可用性（误报过多会导致用户疲劳）。
+
+### 3.1 角色一致性（`character_mapping` / `relationship_jump`）
+
+- **display_name ↔ slug 映射冲突**（高优先级）：
+  - 基于 `characters/active/*.json.display_name` + `state/current-state.json.characters.{id}.display_name` 构建 `display_name -> [slug_id...]`；
+  - 若同一 `display_name` 映射到多个 slug → `character_mapping`（severity=high, confidence=high）。
+- **state/档案 display_name 不一致**：
+  - 若 `characters/active/{id}.json.display_name != state/current-state.json.characters.{id}.display_name` → `character_mapping`（severity=medium, confidence=high）。
+- **关系值剧烈跳变（仅标记，不直接 hard gate）**：
+  - 从 `state/changelog.jsonl` 中筛选章节范围内、且 path 匹配 `characters.{id}.relationships.{other}` 的 ops；
+  - 若单章 `set` 发生**符号翻转**（例如 80 → -10）或 `inc` 的绝对值 ≥ 60 → `relationship_jump`（severity=medium, confidence=medium）；
+  - evidence：至少提供 1 条 changelog 证据（或章节片段）说明变化发生的章节与上下文。
+
+### 3.2 空间一致性（`location_contradiction`）
+
+- 为每章生成 `primary_time_marker`（优先 `confidence=high` 的 time_marker；缺失则降级为 medium；仍无则置空）。
+- 从 NER `mentions` 中提取"共现证据"：
+  - 将同一行 snippet 里同时出现的 **角色名 + 地点名** 视为一个候选"位置事实"（fact），并附带该行的 time_marker（若该行或本章存在）。
+- **高置信矛盾**（满足才输出 severity=high）：
+  - 同一角色，在相同 `primary_time_marker`（精确文本相等）下，出现两个不同地点事实（地点 text 不同），且两侧均有明确 evidence（含行号/片段）。
+- **中低置信提示**：
+  - time_marker 缺失但 1-2 章窗口内位置多次跳变 → severity=low/medium（用于提醒，避免误判"正常赶路"）。
+
+### 3.3 时间线一致性（`timeline_contradiction`，对齐 LS-001 hard 输入）
+
+优先使用 L3 契约的并发状态（`volumes/vol-{V:02d}/chapter-contracts/chapter-{C:03d}.json.storyline_context.concurrent_state`）：
+
+- 尝试从 concurrent_state 文本中解析章节号（常见格式：`（ch25）` / `(ch25)`），regex：`/[（(]\s*ch\s*(\d+)\s*[）)]/giu`。
+- 为"当前章"与"并发线引用章"分别取 `primary_time_marker`（来自各自章节的 NER time_markers）。
+- **矛盾判定**（保守）：
+  - 若双方都为高置信 time_marker，且包含明确的"年/季节"差异（例如 `第三年冬` vs `第三年夏`）→ `timeline_contradiction`（severity=high, confidence=high）
+  - 若仅相对时间词（次日/当晚）或缺失 → 降级为 medium/low（提示，不应直接硬阻断）
+
+## 4) 提供给 QualityJudge 的结构化输入（LS-001）
+
+入口 Skill 在调用 QualityJudge 前，应将"一致性报告中与当前章相关的 timeline/location issues"裁剪为小体积摘要注入：
+
+```json
+{
+  "ls_001_signals": [
+    {
+      "issue_id": "timeline_contradiction:storylines=jiangwang-dao|jinghai-plan:time=第三年冬末",
+      "confidence": "high",
+      "evidence": [{"chapter": 48, "snippet": "……"}],
+      "suggestion": "补齐并发线的时空锚点，或调整事件发生顺序。"
+    }
+  ]
+}
+```
+
+> 约束：仅 `confidence="high"` 的信号建议作为 hard gate 的强输入；`medium/low` 仅提示，不应直接阻断。

package/skills/continue/references/file-protocols.md

@@ -0,0 +1,64 @@
+# M3 风格漂移与黑名单（文件协议）
+
+**1) `style-drift.json`（项目根目录，可选）**
+
+- 用途：当检测到风格漂移时写入，用于后续章节对 ChapterWriter/StyleRefiner 进行"正向纠偏"注入
+- 注入规则：仅当 `active=true` 时注入；`active=false` 视为历史记录，不再注入
+- 注入目标：当前固定为 `["ChapterWriter", "StyleRefiner"]`；若未来新增消费方，需扩展 `injected_to` 并同步 Step 2.6 context assembly
+
+最小格式：
+```json
+{
+  "active": true,
+  "detected_chapter": 25,
+  "window": [21, 25],
+  "drifts": [
+    {"metric": "avg_sentence_length", "baseline": 18, "current": 24, "directive": "句子过长，回归短句节奏"},
+    {"metric": "dialogue_ratio", "baseline": 0.4, "current": 0.28, "directive": "对话偏少，增加角色互动"}
+  ],
+  "injected_to": ["ChapterWriter", "StyleRefiner"],
+  "created_at": "2026-02-24T05:00:00Z",
+  "cleared_at": null,
+  "cleared_reason": null
+}
+```
+
+**2) `ai-blacklist.json`（项目根目录）**
+
+- `words[]`：生效黑名单（生成时禁止、润色时替换、评估时计入命中率）
+- `whitelist[]`（可选）：豁免词条（不替换、不计入命中率、不得自动加入 words）
+- `update_log[]`（可选，append-only）：记录每次自动/手动变更（added/exempted/removed）的 evidence 与时间戳，便于审计
+
+建议扩展（兼容模板；无则视为空）：
+```json
+{
+  "whitelist": [],
+  "update_log": [
+    {
+      "timestamp": "2026-02-24T05:00:00Z",
+      "chapter": 47,
+      "source": "auto",
+      "added": [
+        {"phrase": "值得一提的是", "count_in_chapter": 3, "examples": ["例句 1", "例句 2"]}
+      ],
+      "exempted": [
+        {"phrase": "老子", "reason": "style_profile.preferred_expressions", "examples": ["例句 1"]}
+      ],
+      "note": "本次变更摘要"
+    }
+  ]
+}
+```
+
+**3) `${NOVEL_CLI_ROOT}/scripts/lint-blacklist.sh`（可选）**
+
+- 输入：`<chapter.md> <ai-blacklist.json>`
+- 输出：stdout JSON（exit 0），至少包含：
+  - `total_hits`、`hits_per_kchars`（次/千字）、`hits[]`（word/count/lines/snippets）
+- 失败回退：脚本不存在 / 退出码非 0 / stdout 非 JSON → 不阻断，QualityJudge 改为启发式估计并标注"估计值"
+
+**4) `${NOVEL_CLI_ROOT}/scripts/run-ner.sh`（可选）**
+
+- 输入：`<chapter.md>`
+- 输出：stdout JSON（exit 0），至少包含：schema_version、chapter_path、entities（characters/locations/time_markers/events + evidence）；完整 schema 见 `continuity-checks.md`
+- 失败回退：脚本不存在 / 退出码非 0 / stdout 非 JSON → 不阻断；入口 Skill/QualityJudge 走 LLM fallback（抽取实体 + 输出 confidence）

package/skills/continue/references/foreshadowing.md

@@ -0,0 +1,130 @@
+# 伏笔追踪（事实索引 + 卷内计划）
+
+> 本文用于约束 `/novel:continue` 的 **foreshadowing_tasks 注入** 与 **commit 阶段 global.json 合并**。
+> 源头定义：`docs/dr-workflow/novel-writer-tool/final/prd/09-data.md`（schema 示例）与 `docs/dr-workflow/novel-writer-tool/final/spec/06-extensions.md`（query-foreshadow.sh 扩展点）。
+
+## 1) `foreshadowing/global.json`（事实层，跨卷）
+
+最小格式（JSON object）：
+
+```json
+{
+  "foreshadowing": []
+}
+```
+
+条目 schema（每个 item）：
+
+```json
+{
+  "id": "ancient_prophecy",
+  "description": "远古预言暗示主角命运",
+  "scope": "short | medium | long",
+  "status": "planted | advanced | resolved",
+  "planted_chapter": 3,
+  "planted_storyline": "main-arc",
+  "target_resolve_range": [10, 20],
+  "last_updated_chapter": 48,
+  "history": [
+    {"chapter": 3, "action": "planted", "detail": "…"},
+    {"chapter": 15, "action": "advanced", "detail": "…"},
+    {"chapter": 48, "action": "advanced", "detail": "…"}
+  ]
+}
+```
+
+语义规则：
+
+- `status` 仅允许：`planted` → `advanced`（可多次）→ `resolved`。
+- `scope` 分层语义（用于风险提示，而不是强制门控）：
+  - `short`：卷内（约 3-10 章）应回收；**超期**规则见 §4。
+  - `medium`：跨 1-3 卷回收。
+  - `long`：全书级，无固定回收期限（**不触发超期警告**）。
+- `target_resolve_range`：
+  - 可缺失（表示未设定明确回收窗口）。
+  - 若存在，必须是 `[start, end]` 且 `start/end` 为整数、`start <= end`。
+- `history[]`：
+  - `action` ∈ `{"planted","advanced","resolved"}`。
+  - 允许多次 `advanced`（不同 chapter）。
+  - 建议按 `chapter` 升序；commit 阶段追加即可（无需重排）。
+
+## 2) `volumes/vol-{V:02d}/foreshadowing.json`（计划层，本卷）
+
+用途：
+- 提供本卷“新增 + 延续”的伏笔计划基线，用于：
+  1) 组装 `foreshadowing_tasks`（章节写作注入）
+  2) 卷末回顾对照（计划 vs 事实）
+
+建议格式（JSON object；`volume` 可选）：
+
+```json
+{
+  "volume": 2,
+  "foreshadowing": [
+    {
+      "id": "ancient_prophecy",
+      "description": "远古预言暗示主角命运",
+      "scope": "long",
+      "status": "advanced",
+      "planted_chapter": 3,
+      "target_resolve_range": [40, 55],
+      "history": []
+    }
+  ]
+}
+```
+
+说明：
+- 计划层条目字段允许与 global 结构一致（便于复用与对照），但它不是事实源：
+  - 对“本卷新增伏笔”，`planted_chapter/target_resolve_range` 表示**计划章范围**；
+  - 对“上卷延续伏笔”，`planted_chapter/status` 应与 global 事实一致，`target_resolve_range` 可被 PlotArchitect 调整为本卷计划窗口。
+
+## 3) Commit 阶段：从 `staging/state/chapter-{C:03d}-delta.json` 合并 foreshadow ops → `foreshadowing/global.json`
+
+输入：`staging/state/chapter-{C:03d}-delta.json.ops[]` 中 `op == "foreshadow"` 的记录：
+
+```json
+{"op":"foreshadow","path":"ancient_prophecy","value":"advanced","detail":"主角梦见预言碎片"}
+```
+
+合并策略（幂等、去重、不中断写作）：
+
+1. 读取 `foreshadowing/global.json`；若不存在则初始化为 `{"foreshadowing":[]}`。
+2. 读取（可选）本卷计划 `volumes/vol-{V:02d}/foreshadowing.json`，用于在 global 缺条目/缺元数据时补齐 `description/scope/target_resolve_range`（**仅在缺失时回填，不覆盖已有事实字段**）。
+3. 对每条 `foreshadow` op（按 ops 顺序处理）：
+   - `id = path`，`action = value`，`detail = detail || ""`
+   - 找到对应 item（按 `id` 精确匹配）；若不存在则创建：
+     - `id`: op.path
+     - `description/scope/target_resolve_range`: 优先从本卷计划同 ID 条目回填；否则写入占位（`description = id`，`scope = "medium"`，`target_resolve_range = null`）
+     - `planted_chapter`: 若 `action=="planted"` 则写入 `C`，否则留空
+     - `planted_storyline`: 从 delta 顶层 `storyline_id` 回填（如存在）
+     - `status`: 先设为 `action`
+     - `last_updated_chapter = C`
+     - `history = []`
+   - `history` 去重（保证重复 commit 不重复追加）：
+     - 若已存在 `{chapter: C, action: action}` 的记录 → 跳过追加
+     - 否则追加 `{chapter: C, action: action, detail: detail}`
+   - 字段更新：
+     - `last_updated_chapter = max(existing, C)`
+     - `planted_chapter`：若 `action=="planted"` 且为空 → 设为 `C`（不回退更早 planted）
+     - `planted_storyline`：若为空且 delta.storyline_id 存在 → 设为该值
+     - `status`：只允许单调推进：
+       - 若 `action=="resolved"` → 设为 `resolved`
+       - 若 `action=="advanced"` 且当前非 `resolved` → 设为 `advanced`
+       - 若 `action=="planted"` 且当前为空/`planted` → 设为 `planted`（不得把 `advanced/resolved` 降级为 `planted`）
+4. 写回 `foreshadowing/global.json`（JSON，UTF-8）。
+5. 若遇到异常数据（例如 action 非法、JSON 解析失败、global.json 结构不是 object/foreshadowing 不是 list）：
+   - 不要悄悄吞掉：输出明确错误与修复建议；
+   - 但**尽量避免阻断整章 commit**：可降级为“跳过本章 foreshadow 合并并写入 warning”，保证章节与 state 合并仍可完成。
+
+## 4) Overdue（超期）判定（用于 `/novel:status` 与回顾报告）
+
+- 仅对 `scope == "short"` 且 `status != "resolved"` 的条目做超期提示。
+- 若存在 `target_resolve_range = [start, end]` 且 `last_completed_chapter > end`：标记为 **超期**。
+- `scope == "long"`：不做超期提示。
+
+## 5) `${NOVEL_CLI_ROOT}/scripts/query-foreshadow.sh`（可选确定性扩展点）
+
+- 输入：`<chapter_num>`
+- 输出：stdout JSON（exit 0），其中 `.items` 为“本章相关伏笔条目子集”（list of objects，字段建议与 global 条目一致：`id/description/scope/status/target_resolve_range/...`）
+- 失败回退：脚本不存在 / 退出码非 0 / stdout 非 JSON / JSON 缺 `.items` → 不阻断流水线，入口 Skill 必须回退规则过滤（见 `skills/continue/SKILL.md` Step 2.5 第 6 项）

package/skills/continue/references/gate-decision.md

@@ -0,0 +1,53 @@
+# 质量门控决策引擎（Gate Decision Engine）
+
+## high_violation 函数定义与 hard gate 输入（仅认 high confidence）
+
+- high_violation(eval) := 任一 contract_verification.{l1,l2,l3}_checks 中存在 status="violation" 且 confidence="high"
+  或任一 contract_verification.ls_checks 中存在 status="violation" 且 confidence="high" 且（constraint_type 缺失或 == "hard"）
+- has_high_confidence_violation：取自 Step 4 的计算结果（关键章=双裁判 OR 合并，普通章=单裁判）
+  > confidence=medium/low 仅记录警告，不触发 hard gate（避免误报疲劳）
+
+## 固化门控决策函数（输出 gate_decision）
+
+```
+if has_high_confidence_violation:
+  gate_decision = "revise"
+else:
+  if overall_final >= 4.0: gate_decision = "pass"
+  elif overall_final >= 3.5: gate_decision = "polish"
+  elif overall_final >= 3.0: gate_decision = "revise"
+  elif overall_final >= 2.0: gate_decision = "pause_for_user"
+  else: gate_decision = "pause_for_user_force_rewrite"
+```
+
+## 自动修订闭环（max revisions = 2）
+
+- 若 gate_decision="revise" 且 revision_count < 2：
+  - 更新 checkpoint: orchestrator_state="CHAPTER_REWRITE", pipeline_stage="revising", revision_count += 1
+  - 调用 ChapterWriter 修订模式（Task(subagent_type="chapter-writer", model="opus")）：
+    - 输入: chapter_writer_revision_manifest（在 chapter_writer_manifest 基础上追加 inline 字段 `required_fixes` + `high_confidence_violations`，paths 追加 `chapter_draft` 指向 staging 中的现有正文）
+    - 修订指令：以 eval.required_fixes 作为最小修订指令；若 required_fixes 为空，则用 high_confidence_violations 生成 3-5 条最小修订指令兜底；若两者均为空（score 3.0-3.4 无 violation 触发），则从 eval 的 8 维度中取最低分 2 个维度的 feedback 作为修订方向
+    - 约束：定向修改 required_fixes 指定段落，尽量保持其余内容不变
+  - 回到步骤 2 重新走 Summarizer -> StyleRefiner -> QualityJudge -> 门控（保证摘要/state/crossref 与正文一致）
+
+- 若 gate_decision="revise" 且 revision_count == 2（次数耗尽）：
+  - 若 has_high_confidence_violation=false 且 overall_final >= 3.0：
+    - 设置 force_passed=true，允许提交（避免无限循环）
+    - 记录：eval metadata + log 中标记 force_passed=true（门控被上限策略终止）
+    - 将 gate_decision 覆写为 "pass"
+  - 否则：
+    - 释放并发锁（rm -rf .novel.lock）并暂停，提示用户在 `/novel:start` 决策下一步（手动修订/重写/接受）
+
+## 其他决策的后续动作
+
+- gate_decision="pass"：直接进入 commit
+- gate_decision="polish"：更新 checkpoint: pipeline_stage="revising" -> StyleRefiner 二次润色后进入 commit（不再重复 QualityJudge 以控成本）
+- gate_decision="pause_for_user" / "pause_for_user_force_rewrite"：释放并发锁（rm -rf .novel.lock）并暂停，等待用户通过 `/novel:start` 决策
+
+## 写入评估与门控元数据（可追溯）
+
+- 写入 staging/evaluations/chapter-{C:03d}-eval.json：
+  - 内容：eval_used（普通章=primary_eval；关键章=overall 更低的一次）+ metadata
+  - metadata 至少包含：
+    - judges: {primary:{model,overall}, secondary?:{model,overall}, used, overall_final}
+    - gate: {decision: gate_decision, revisions: revision_count, force_passed: bool}

package/skills/continue/references/periodic-maintenance.md

@@ -0,0 +1,46 @@
+# M3 周期性维护
+
+## AI 黑名单动态维护（不阻断）
+
+- 从 eval_used.anti_ai.blacklist_update_suggestions[] 读取新增候选（必须包含：phrase + count_in_chapter + examples）
+- 增长上限检查：若 `words[]` 长度 >= 80，跳过自动追加，仅记录到 `update_log[]`（source="auto_skipped_cap"），并在 `/novel:start` 质量回顾中提示用户审核黑名单规模
+- 自动追加门槛（保守，避免误伤）：
+  - `confidence in {medium, high}` 且 `count_in_chapter >= 3` -> 才允许自动追加
+  - 其余仅记录为"候选建议"，不自动写入（可在 `/novel:start` 质量回顾中提示用户手动处理）
+  - 注意：当前门槛为单章统计；跨章高频但单章 < 3 的词不会自动追加，依赖用户在质量回顾中审核候选列表
+- 更新 `ai-blacklist.json`（按文件协议；幂等、可追溯）：
+  - 确保存在 `whitelist[]` 与 `update_log[]`（不存在则创建为空）
+  - added：追加到 `words[]`（去重；若已存在于 words/whitelist 则跳过）
+  - exempted（误伤保护，自动豁免，不作为命中/不替换）：
+    - 若候选短语命中 `style-profile.json.preferred_expressions[]`（样本高频表达）或用户显式 `ai-blacklist.json.whitelist[]`：
+      - 将其加入 whitelist（若未存在）
+      - 记录为 exempted，并且**不得加入** words
+  - 更新 `last_updated`（YYYY-MM-DD）与 `version`（若存在且为合法 semver 则 patch bump；字段缺失或不可解析时仅更新 `last_updated`，不创建 `version`）
+  - 追加 `update_log[]`（append-only）：记录 timestamp/chapter/source="auto"/added/exempted + evidence（例句）
+- 用户可控入口：
+  - 用户可手动编辑 `ai-blacklist.json` 的 `words[]/whitelist[]`
+  - 若用户删除某词但不希望未来被自动再加回，请将其加入 `whitelist[]`（系统不得自动加入 whitelist 内词条）
+
+## 风格漂移检测与纠偏（每 5 章触发）
+
+- 触发条件：last_completed_chapter % 5 == 0
+- 窗口：读取最近 5 章 `chapters/chapter-{C-4..C}.md`
+- 调用 StyleAnalyzer 提取当前 metrics（仅需 avg_sentence_length / dialogue_ratio；其余字段可忽略）
+- 与 `style-profile.json` 基线对比（相对偏移，确定性公式）：
+  - 前置检查：若 `base.avg_sentence_length` 为 null/0 或 `base.dialogue_ratio` 为 null/0，跳过对应维度的漂移检测（记录日志 "baseline metric unavailable, skipping drift check"）
+  - `sentence_dev = abs(curr.avg_sentence_length - base.avg_sentence_length) / base.avg_sentence_length`
+  - `dialogue_dev = abs(curr.dialogue_ratio - base.dialogue_ratio) / base.dialogue_ratio`
+- 漂移判定：
+  - `sentence_dev > 0.20` 或 `dialogue_dev > 0.15` -> drift=true
+  - 回归判定：`sentence_dev < 0.10` 且 `dialogue_dev < 0.10` -> recovered=true
+- drift=true：
+  - 写入/更新 `style-drift.json`（按文件协议；active=true）
+  - drifts[].directive 生成规则（最多 3 条，短句可执行）：
+    - 句长偏长：强调短句/动作推进/拆句
+    - 句长偏短：允许适度长句与节奏变化（但仍以 style-profile 为准）
+    - 对话偏少：强调通过对话推进（交给 ChapterWriter；StyleRefiner 不得硬造新对白）
+    - 对话偏多：加强叙述性承接与内心活动（不删对白，仅调整段落与叙述衔接）
+- recovered=true：
+  - 清除纠偏：删除 `style-drift.json` 或标记 `active=false`，并写入 `cleared_at/cleared_reason="metrics_recovered"`
+- 超时清除：若当前章 - `style-drift.json.detected_chapter` > 15（即纠偏指令已注入超过 15 章仍未回归），自动标记 `active=false`，`cleared_reason="stale_timeout"`
+- 其余情况：保持现状（不新增、不清除），避免频繁抖动