docs: update context-minimal flow plan with Claude Code tool baseline

docs/architecture/context-minimal-writing-flow-plan-2026-06-05.md

@@ -5,8 +5,8 @@
 > 范围：重构 `skills/`、`agents/` 与 `references/` 的提示词与读取方式，减少主 agent 不必要上下文，降低 token 消耗
 > 核心原则：先保住端到端流程，再压缩提示词；Skill 只写调度合同，Agent 自带专业流程，Runtime 负责硬校验
 > 裁剪总纲：所有保留 / 下沉 / 删除决策由第 4 节四条裁剪判据（职责、token、噪音、读取方式）推导，不靠逐条拍清单
-> v3 变更：① 新增第 4 节裁剪判据；② 第 5 节不可删清单收敛为跨层红线；③ 第 6 节纳入 references 与读取方式优化（以 reference-loading-map 为基线）；④ 第 12 节验收从文案级断言改为行为 / 契约级
-> 工具能力基线：Claude Code 工具名、subagent / Skill 能力、shell 行为以官方最新文档和本机实际安装为准；不得靠记忆或经验猜测
+> v3 变更：① 新增第 4 节裁剪判据；② 第 5 节不可删清单收敛为跨层红线；③ 第 6 节纳入 references 与读取方式优化（以 reference-loading-map 为基线）；④ 第 12 节验收从文案级断言改为行为 / 契约级；⑤ 明确宿主固定为 Claude Code，工具能力以官方 docs + 本机 Claude Code 版本 + 插件注册名为准
+> 工具能力基线：本 plan 宿主固定为 Claude Code；默认使用本轮涉及的 Claude Code 内置工具（`Read` offset/limit、`Grep`、`Glob`、`Agent`、`Skill`、`AskUserQuestion`、`Write`、`Edit`、`WebSearch`、`WebFetch`）和跨平台 Bash；不建议使用 PowerShell；subagent / Skill 行为按官方 docs 固化，再复核本插件注册名
 
 ---
 
@@ -25,7 +25,7 @@
 
 - **测试是探针，不是约束。** 瘦身会让一批文案级断言（`assert "字符串" in text`）变红，这些断言本身就是要清掉的噪音；它们保护的若是真红线，就改写成行为级断言并迁到生产方，而不是为了过测试保留废话。
 - **不能删除第 3 节的端到端流程。** 任何格式化、瘦身、下沉 reference、压缩 schema、改读取方式的动作，都不得删掉第 3 节的业务步骤。第 3 节是红线来源，第 4 节是裁剪依据，二者不冲突。
-- **工具能力不靠猜。** 任何涉及 `allowed-tools`、subagent 调用方式、Skill frontmatter、Skill / subagent 是否能加载彼此、Bash / PowerShell 行为、Read / Grep / Glob 参数能力的设计，都必须先核对 Claude Code 官方最新文档与本机当前版本；若二者有差异，以本机实际可用能力为落地准绳，并把差异记录到 Phase 0 清单。
+- **工具能力以 Claude Code 为准，不臆造也不过度防御。** 本 plan 的执行宿主固定是 Claude Code；不得用临时聊天壳、其他 agent 环境或记忆里的旧工具名替代 Claude Code 官方定义。设计读取与调度时，默认使用 Claude Code 内置工具（`Read` offset/limit、`Grep`、`Glob`、`Agent`、`Skill`、`AskUserQuestion`、`Write`、`Edit`）和 Bash，不写死依赖宿主是否装了 `sed` / `jq`。PowerShell 不作为默认执行方式，避免引入 Windows-only 兼容问题；只有明确 Windows-only 兜底时才使用，并记录兼容风险。subagent / Skill 的已知行为按官方 docs 固化：subagent 不能 spawn subagent，`tools` 是 subagent allowlist，`skills` 字段可把完整 Skill 预加载进 subagent 上下文，Skill 的 `allowed-tools` 是预批准而不是限制。Phase 0 只复核当前 Claude Code 版本、当前插件的真实注册名、frontmatter 是否符合本机 plugin-dev、以及本仓库是否启用了相关工具。
 
 ---
 
@@ -83,6 +83,8 @@
 - 失败只补跑失败步骤，不全量回退。
 - 能由 runtime 确定性校验的内容，提示词只保留最小说明和阻断边界。
 - reference 只按需读取；不要为了“结构好看”新增没有真实复用价值的 reference。
+- 每个文件产物必须有唯一写入者；提示词要明确“谁写入、谁只返回、谁只校验”。禁止同一产物由主流程和 subagent/runtime 重复写，也禁止大家都只口头产出没人落盘。
+- 每章 `chapter-commit` 前必须做一次项目根内 `git diff` 变更面校验，确认可见文本 / 文件路径变更只出现当前章节和本章流程应产生的文件；它是写入所有权 sanity check，不替代 `write-gate precommit`，也不能证明 SQLite / `.webnovel/` 内部语义正确。
 
 ### 3.2 `/webnovel-init` 完整流程
 
@@ -192,7 +194,9 @@ prewrite 必备：`MASTER_SETTING.json`、`volume_{NNN}.json`、`chapter_{NNN}.j
 
 默认与 `--fast` 必须调用 `webnovel-writer:reviewer`，`--minimal` 可跳过。
 
-reviewer 输出 `.webnovel/tmp/review_results.json` 后，必须调用：
+默认写入权责：reviewer 只返回严格 JSON；主流程负责把返回值写入 `${PROJECT_ROOT}/.webnovel/tmp/review_results.json`。如果未来改成 reviewer 直接落盘，必须给 reviewer frontmatter 增加 `Write`，并删除主流程写入动作，二者不能同时存在。
+
+`review_results.json` 落盘后，必须调用：
 
 ```bash
 python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" review-pipeline \
@@ -227,6 +231,8 @@ python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" rev
 - `.webnovel/tmp/disambiguation_result.json`
 - `.webnovel/tmp/extraction_result.json`
 
+data-agent 是三份 tmp artifact 的唯一写入者。主流程只检查文件存在与 schema，不重写、不补写 artifact；若 artifact 不合格，定点要求 data-agent 重跑对应产物。
+
 data-agent 不直接写 state / index / summaries / memory / vectors，也不直接写 projection。
 
 随后运行 precommit gate：
@@ -236,6 +242,29 @@ python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
   write-gate --chapter {chapter_num} --stage precommit --format json
 ```
 
+`write-gate precommit` 通过后，运行提交前 `git diff` 最终校验，确认写入范围正确：
+
+```bash
+if git -C "${PROJECT_ROOT}" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  git -C "${PROJECT_ROOT}" diff --name-status -- .
+  git -C "${PROJECT_ROOT}" diff --check -- .
+fi
+```
+
+校验规则：
+
+- `diff --name-status` 中不得出现插件目录、其他书项目、其他章节正文或不属于本章流程的手写状态文件。
+- `git diff` 只能检查 git 可见的文件路径和文本差异；如果 `.webnovel/` 被 `.gitignore` 忽略，或 `index.db` / `vectors.db` 是二进制数据库，`git diff` 不能看见其中的表级 / 行级变化。
+- `chapter-commit` 前不应出现由 projection 独占的写入，例如 summaries / memory / vectors；这些只能由 `chapter-commit` 或 `projections retry` 产生。该规则不能只靠 `git diff` 证明，必须结合 runtime gate / read-model 查询。
+- 若项目根不是 git worktree，明确记录“跳过 git diff 校验”，不得因此跳过 `write-gate precommit`。
+- 禁止在这里执行 `git add` / `git commit`；本步骤只读。
+
+数据库 / read-model 语义另走只读校验：
+
+- `review-pipeline --save-metrics` 后，用 runtime 输出和只读查询确认 `review_metrics` 已写入目标章；不要用 `git diff` 判断 SQLite 内容。
+- `chapter-commit` 后，用 `write-gate postcommit` 的 `projection_status` 验证 state / index / summary / memory / vector 全部 `done` 或 `skipped`。
+- 需要查 SQLite 时优先用现有 runtime 查询命令；runtime 暂无命令时，可用 Python `sqlite3` 做只读查询，但不能把查询脚本变成写入路径。
+
 再运行 `chapter-commit`：
 
 ```bash
@@ -285,7 +314,7 @@ python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" bac
 2. 如目标章缺少 runtime 合同，先用真实 `CHAPTER_GOAL` 刷新 `story-system --emit-runtime-contracts`。
 3. 读取必要 reference：core constraints、review schema；其他按 issue 需要读取。
 4. 加载 `.webnovel/state.json` 兼容投影和待审正文。
-5. 调用 `webnovel-writer:reviewer` 输出 `.webnovel/tmp/review_results.json`。
+5. 调用 `webnovel-writer:reviewer` 返回严格 JSON，并由主流程写入 `.webnovel/tmp/review_results.json`。
 6. 调用 `review-pipeline --save-metrics` 生成报告与 metrics 并写入 `review_metrics`。
 7. 调用 `update-state -- --add-review ...` 写兼容审查记录。
 8. 存在 `blocking=true` 时，询问用户立即修复或稍后处理。
@@ -355,8 +384,8 @@ python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" bac
 每个“读文件”动作必须标注读取方式，不默认全文 `cat`：
 
 - **全文读**：短文件，且必须整体理解（schema、铁律、方法论总纲）。
-- **区段读**：只需某节时，使用 Claude Code 当前可用的内置读取 / 搜索工具或宿主 shell 等价能力定位稳定标题锚点后读取片段；不要在 plan 中假定某个具体命令或参数一定是内置能力。
-- **检索读**：结构化数据（CSV / JSON）优先用本项目 runtime 工具，如 `reference_search.py`、`knowledge query-*`、专用 schema/validator；只有确认宿主可用时才使用 shell 工具按字段取，绝不默认 `cat` 整表。
+- **区段读**：只需某节时，用内置 `Grep` 的 content 输出定位标题锚点行号，再用 `Read` 的 offset/limit 取片段——两者都是 Claude Code 内置工具，平台无关、不赌宿主是否装 `sed` / `jq`；提示词已点到节名的直接给锚点。
+- **检索读**：结构化数据（CSV / JSON）优先用本项目 runtime 工具（`reference_search.py`、`knowledge query-*`、专用 schema/validator）；runtime 无对应命令需临时按字段取时，优先用 Bash，绝不默认 `cat` 整表；PowerShell 仅作 Windows-only 兜底。
 - **不读**：内容已迁走或不再被消费的文件，清理（见第 6 节）。
 
 ### 4.2 职责边界
@@ -370,7 +399,116 @@ python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" bac
 
 ### 4.3 Agent 单文件约束
 
-Agent 当前只能加载自己的单个 Agent 文件，因此不新增 `agents/references/*`。Agent 需要的专业规则（含其产物的完整 schema）必须压缩后保留在单文件内——这正是判据一“字段细则归生产方”的落点。
+本项目默认不新增 `agents/references/*`，避免把 subagent 的说明书拆成不可见碎片。Agent 需要的专业规则（含其产物的完整 schema）必须压缩后保留在单文件内——这正是判据一“字段细则归生产方”的落点。
+
+Claude Code 官方能力允许 subagent 通过 `skills` 字段预加载 Skills；如果 `Skill` 工具留在 subagent 可用工具集中，subagent 也可以在执行中调用未预加载的 project / user / plugin Skills。但本轮不把这作为默认方案：
+
+- 预加载 Skill 会把完整 Skill 内容注入 subagent 上下文，可能抵消本轮上下文减负收益。
+- `skills` 是预加载上下文；`tools: Skill` 是允许运行期调用 Skill，二者不是一回事。
+- subagent 不能再 spawn 其他 subagents；多 agent 串联必须由主流程调度。
+- `Agent` 与 `AskUserQuestion` 不可作为 subagent 可用工具设计；需要用户裁决时回到主流程。
+- 若未来确实需要 subagent 使用某个 Skill，必须在 Phase 0 记录：是通过 `skills` 预加载，还是通过 `tools: Skill` 运行期调用；为什么不能内联进 Agent；增加多少上下文；是否仍低于 token 预算。
+
+### 4.4 Claude Code 工具调用最佳实践
+
+本节用于约束后续 `SKILL.md` / `agents/*.md` 的工具写法。原则：frontmatter 写官方工具名与权限规则；正文用自然语言指派工具任务；不要在提示词里伪造不稳定的内部函数 API。
+
+#### 4.4.1 frontmatter 写法
+
+Skill 的 `allowed-tools` 是预批准规则，不是工具限制。未列出的工具仍可被调用，只是继续受权限设置控制。
+
+```yaml
+allowed-tools: Read, Grep, Glob, Bash, Agent, AskUserQuestion
+```
+
+需要缩窄权限时，用官方 permission rule 格式，并先确认实际注册名：
+
+```yaml
+allowed-tools: Read, Grep, Glob, Bash(python -X utf8 *), Agent
+```
+
+不要在未核实前写猜测式规则，例如 `Agent(webnovel-writer:context-agent)`。plugin scoped agent 的真实注册名必须在 Phase 0 复核。
+
+Agent 的 `tools` 是 allowlist；省略时继承主会话工具，不适合作为生产 agent 默认。生产 agent 按职责列最小工具集，而不是套一份固定模板：
+
+```yaml
+# 只读 research，或只返回 JSON、由主流程落盘的 review
+tools: Read, Grep, Glob, Bash
+
+# 需要把 tmp JSON artifact 或 reviewer raw JSON 落盘时
+tools: Read, Grep, Bash, Write
+```
+
+如果 agent 要预加载 Skill，用 `skills:` 字段；不要把 `Skill` 当成“预加载 reference”写进 `tools`。只有确实要让 subagent 在运行时调用其他 Skills，才把 `Skill` 留在 `tools` 中，并记录原因：
+
+```yaml
+skills:
+  - api-conventions
+```
+
+#### 4.4.2 正文中的 Agent 调用写法
+
+不要写成伪函数：
+
+```text
+Agent(
+  subagent_type: "...",
+  prompt: "..."
+)
+```
+
+推荐写成任务指令：
+
+```text
+Use the Agent tool to run `webnovel-writer:context-agent`.
+
+Task:
+- chapter={chapter_num}
+- project_root=${PROJECT_ROOT}
+- scripts_dir=${SCRIPTS_DIR}
+- Return a five-part writing brief.
+- If context is insufficient, return a blocker.
+```
+
+这样保留了“必须使用 Agent 工具”的红线，但不把 Claude Code 内部 tool-call schema 写死进 Skill 文本。
+
+#### 4.4.3 工具使用表
+
+| 工具 | 默认用途 | 最佳实践 |
+|---|---|---|
+| `Read` | 读取文件正文 | 传绝对路径；长文件优先 offset/limit 区段读；先用 `Grep` 定位锚点；不要让主流程全文读大 reference |
+| `Grep` | 搜索文本和定位标题锚点 | 用 content 输出拿文件路径与行号；用 glob/type 缩小范围；不要把 `Grep -n` 当作工具 API |
+| `Glob` | 找文件 | 用窄 pattern；结果过多时继续收窄；不要用 shell 枚举替代简单文件发现 |
+| `Bash` | 运行跨平台 shell 命令和 runtime 脚本 | 每次调用是独立进程，环境变量不会跨调用保留；一组依赖同一环境变量的命令放在同一次调用里，或每次重新解析变量；优先调用 `webnovel.py` 等 runtime，不用临时脚本替代已有命令 |
+| `PowerShell` | Windows-only 兜底 | 不作为默认流程；不在插件 Skill / hook 中主动写 `shell: powershell`；只在 Bash / 内置工具无法满足且任务明确 Windows-only 时使用，并记录兼容风险 |
+| `Agent` | 调用 subagent | 主流程调度 subagent；正文使用 “Use the Agent tool to run ... / Task ...” 写法；subagent 只返回最终结果，主流程不能依赖其中间 tool 输出 |
+| `Skill` | 调用可复用 Skill | 主会话可按需调用；subagent 预加载用 `skills`，运行期调用才需要 `tools: Skill`；避免为了让 subagent 看到长参考而滥用预加载；`allowed-tools` 中的 `Skill(...)` 是 permission rule，不是正文调用模板 |
+| `AskUserQuestion` | 用户裁决与关键分歧确认 | 只在阻断、剧情裁决、初始化确认等需要用户选择时使用；不放进 subagent 设计 |
+| `Write` / `Edit` | LLM 直接写文件 | 优先让 runtime 写结构化状态和 projection；确需 LLM 写 markdown 时，先明确目标文件与最小修改范围；若提示词要求 subagent 保存 tmp JSON，frontmatter 必须给 `Write`，否则改成“subagent 返回 JSON，由主流程写入” |
+| `WebSearch` / `WebFetch` | 外部信息检索 | 只在用户要求市场趋势、平台风向或时间敏感资料时使用；先 search 后 fetch 确定来源；不得把未经用户确认的外部信息写入 canon |
+
+### 4.5 写入所有权矩阵
+
+本轮瘦身不能只写“产出某文件”，必须写清唯一写入者。默认矩阵如下；后续改任何 Skill / Agent 时必须同步检查这一表。
+
+| 产物 / 路径 | 唯一写入者 | 其他层职责 |
+|---|---|---|
+| 新项目目录、基础 `.webnovel/`、设定集骨架 | `webnovel.py init` | init Skill 只采集、确认、调用 runtime |
+| `.webnovel/idea_bank.json`、`大纲/总纲.md` 初始化补丁 | init 主流程 | deconstruction-agent 不写 canon；runtime 只校验 |
+| `.story-system/MASTER_SETTING.json`、卷 / 章 runtime contracts | `story-system --persist` | Skill / Agent 不手写合同 JSON |
+| `正文/第{chapter}章-*.md` | write 主流程 Step 2 / Step 4 | context-agent 只返回任务书；reviewer/data-agent 不改正文 |
+| `.webnovel/tmp/review_results.json` | 默认 write/review 主流程写入 reviewer 返回的 JSON | reviewer 只返回严格 JSON；若改成 reviewer 写入，必须给 `Write` 并删除主流程写入 |
+| `.webnovel/tmp/review_metrics.json`、审查报告、`review_metrics` 表 | `review-pipeline --save-metrics` | 主流程只调用；reviewer 不写 metrics / report |
+| `.webnovel/tmp/fulfillment_result.json`、`disambiguation_result.json`、`extraction_result.json` | data-agent | 主流程只检查存在与 schema；不重写 artifact |
+| accepted commit、projection、`.webnovel/state.json`、index、summaries、memory、vectors | `chapter-commit` / `projections retry` | data-agent 不直接写；主流程不手写 read-model |
+| 备份产物 | `backup --project-root "${PROJECT_ROOT}"` | 主流程只调用并检查结果 |
+
+验收口径：
+
+- 每个产物必须能回答“谁写、谁不能写、失败谁补跑”。
+- 同一产物若出现两个写入者，删到只剩默认写入者。
+- 若某 agent 被要求写文件，frontmatter `tools` 必须包含 `Write`；否则该 agent 只能返回内容，由主流程写。
+- 每章 `chapter-commit` 前用 `git diff --name-status` 做 git 可见变更面最终校验，只读、不 stage、不 commit；数据库内部变化由 runtime / SQLite 只读查询确认。
 
 ---
 
@@ -390,7 +528,9 @@ Agent 当前只能加载自己的单个 Agent 文件，因此不新增 `agents/r
 
 ### 5.2 不可删的跨层红线（穷举，由第 12 节行为测试守护）
 
-这些是跨 Skill / Agent / Runtime 的业务红线，任何瘦身都不得删，且必须有对应的行为 / 契约级断言（第 12 节）：
+这些是跨 Skill / Agent / Runtime 的业务红线，任何瘦身都不得删，且必须有对应的行为 / 契约级断言（第 12 节）。按“能否在 Phase 0 瘦身前先变绿”分两类：
+
+**A. 守护现状（行为已实现，Phase 0 补 / 强化断言即可变绿）**
 
 - 项目根保护、init 目录安全化、用户确认前不写 canon。
 - `placeholder-scan` 出现在 plan / write 关键节点。
@@ -405,6 +545,11 @@ Agent 当前只能加载自己的单个 Agent 文件，因此不新增 `agents/r
 - `backup --project-root "${PROJECT_ROOT}"`，禁止裸 `git add .`。
 - plan 的节拍表、时间线、章纲节点、设定写回、结构化总纲写回、状态更新。
 
+**B. 本轮新契约（当前无实现与断言，随对应 Phase 落地后才转绿；Phase 0 只写断言并标记待实现）**
+
+- 写入所有权矩阵必须成立：reviewer 结果、data artifacts、review metrics、commit/projection/read-model 各有唯一写入者，不重复写、不漏写；含 agent `tools` 与落盘责任一致（reviewer 不授 `Write` 只返回 JSON、data-agent 授 `Write` 写三份 artifact）。（4.5 引入；随 Phase 1–3 对齐 prompt / frontmatter 后转绿）
+- 每章 `chapter-commit` 前必须执行只读 `git diff` 变更面校验；不得出现插件目录、其他章节、其他书项目或未授权状态文件变更；数据库内部变化另用 runtime / SQLite 只读查询确认。（write Skill 当前无此步；随 Phase 1 加入后转绿）
+
 > 字段级条目（如 `planned_nodes` 等具体字段名）**不在本清单**——它们由判据一归到生产方 agent 与 runtime schema，由第 12 节契约级测试守护，不再作为主 Skill 的文案红线。
 
 ---
@@ -440,25 +585,28 @@ references 是本轮被低估的 token 面：顶层 `references/` 加各 Skill
 
 CSV 那条线已经做对了，本轮**不重做检索层**；只治“直接 Read 的 md 全文加载”，并把读取方式登记进 loading-map，使其从“读哪些文件”升级为“怎么读这些文件”。
 
-#### 6.2.2 token 靶心：`always` 全文读的大 md
+#### 6.2.2 token 靶心：`always` 全文读的大 md（行数已实测、读取方式已核结构）
 
-以下是“直接 Read 且 always / 高频触发”的大文件，是 init / plan / write 每跑必吞的常驻成本，按判据四改读取方式：
+以下是“直接 Read 且 always / 高频触发”的大文件，是 init / plan / write 每跑必吞的常驻成本。行数为逐行读取脚本实测，「读哪段」已逐个核过文件标题结构，可直接照做：
 
-| 文件 | 行数 | 谁全文读 | 目标读取方式 |
+| 文件 | 行数 | 谁全文读 | 读哪段（而非全文） |
 |---|---|---|---|
-| `references/genre-profiles.md` | 552 | init + plan 双重 always | 区段读：按目标 genre 定位该题材段 |
-| `creativity/selling-points.md` | 513 | init Step5 always | 区段读 / 条目化 |
-| `reading-power-taxonomy.md` | 268 | plan Step7 | 区段读 |
-| `outlining/chapter-planning.md` | 260 | plan Step7 | 区段读「结构化节点规范」一节 |
-| `creativity/creativity-constraints.md` | 248 | init Step5 always | 区段读 `8.1 五维评分` 等命中节 |
-| `webnovel-write/references/polish-guide.md` | 246 | write Step4 always | 区段读 / 条目化 checklist |
-| `shared/cool-points-guide.md` | 242 | plan / review 触发 | 区段读 |
+| `references/genre-profiles.md` | 696 | init + plan 双重 always | 当前 genre 的**单个** `### 2.x` 题材段（13 个题材各约 44 行，必要时加「一、字段说明」）；单本书只用 1 个题材 → 省约 90% |
+| `skills/webnovel-init/references/creativity/selling-points.md` | 687 | init Step5 always | 「## 9 核心卖点定位模板」做骨架，按需补「### 1.3 黄金公式」「## 7 实战检查清单」 |
+| `references/reading-power-taxonomy.md` | 361 | plan Step7 | 按需分析的类型段：「## 一 钩子类型」/「## 二 爽点模式」/「## 三 微兑现」 |
+| `skills/webnovel-plan/references/outlining/chapter-planning.md` | 322 | plan Step7 | 末尾「## 10 结构化节点规范（CBN/CPNs/CEN）」（+ 需模板时「## 7 章节规划模板」） |
+| `skills/webnovel-init/references/creativity/creativity-constraints.md` | 327 | init Step5 always | 展示评分只取「### 8.1 五维评分」（约 10 行）；创意采集读「一 Schema / 六 硬约束 / 八 评分」 |
+| `skills/webnovel-write/references/polish-guide.md` | 351 | write Step4 always | 按「## 2 执行顺序」走，「Phase 1 增补：Anti-AI 规范」词库段单独区段取；**不可条目化进 CSV（csv/README 硬边界）** |
+| `references/shared/cool-points-guide.md` | 313 | plan / review 触发 | 所需爽点维度段；题材适配取「## 九 题材适配」对应题材 |
+
+短文件（如 `references/shared/strand-weave-pattern.md` 111 行）维持全文读，不动。
 
-短文件（如 `strand-weave-pattern.md` 90 行）维持全文读，不动。
+> 区段读标准手法：先用内置 `Grep` 的 content 输出匹配 `^#{2,4} `，拿到标题锚点行号，再用 `Read` offset/limit 取目标段。上表锚点（含「8.1 五维评分」「结构化节点规范」）已核实真实存在，可直接定位。
+> 注：早先某次 shell 管道统计的行数系统性偏小，本表已改用逐行读取脚本实测；其余 references 入文档时同样以实测为准。
 
 #### 6.2.3 清理死 reference（处置前先核验 CSV 覆盖）
 
-`reference-gap-register.md` 记录的 `writing/*.md → CSV` 迁移已部分完成：loading-map 的「当前非直接调用项」确认 `combat-scenes`、`dialogue-writing`、`emotion-psychology`、`scene-description`、`desire-description`、`genre-hook-payoff-library` 等已不再被直接 Read（由 CSV 承担触发），但文件仍在，合计约 1400 行死内容。处置步骤：
+`reference-gap-register.md` 记录的 `skills/webnovel-write/references/writing/*.md → CSV` 迁移已部分完成：loading-map 的「当前非直接调用项」确认 `combat-scenes`、`dialogue-writing`、`emotion-psychology`、`scene-description`、`desire-description`、`genre-hook-payoff-library` 等已不再被直接 Read（由 CSV 承担触发），但文件仍在，合计约 1400 行死内容。处置步骤：
 
 1. 对每个候选 md，先核验 `场景写法.csv` / `写作技法.csv` 是否真覆盖其内容——不盲删。
 2. 已覆盖：删除，或保留为指向 CSV 的空壳。
@@ -471,10 +619,10 @@ v2 第 6.2 列的候选已与现状脱节，按现状重判：
 | v2 候选 | 现状 | 处置 |
 |---|---|---|
 | `blocking-override-guidelines.md` | 已存在并落位（gap-register 2026-04-16） | 删候选，改为“沿用现有” |
-| `chapter-node-rules.md` | 与现有 `outlining/chapter-planning.md`「结构化节点规范」重复 | 不新建，对该节做区段读 |
-| `init-flow.md` | 与现有 `init-collection-schema.md` 重复 | 不新建，沿用并改区段读 |
+| `chapter-node-rules.md` | 与现有 `skills/webnovel-plan/references/outlining/chapter-planning.md`「结构化节点规范」重复 | 不新建，对该节做区段读 |
+| `init-flow.md` | 与现有 `skills/webnovel-init/references/init-collection-schema.md` 重复 | 不新建，沿用并改区段读 |
 | `subagent-contracts.md` | 与判据一冲突（契约形状在主 Skill，schema 在生产方 agent） | 不新建 |
-| `polish-checklist.md` | 可作为 `polish-guide.md` 条目化的产物 | 仅在 6.2.2 条目化时顺带产出 |
+| `polish-checklist.md` | 可作为 `polish-guide.md` 的短 checklist 摘要 | 本轮默认不新建；如确需生成，只做 Skill 内短清单或区段读索引，不迁入 CSV |
 
 原则不变：不为“三段式结构”强行新增 reference；优先改读取方式与清死文件，而非加文件。
 
@@ -490,10 +638,10 @@ v2 第 6.2 列的候选已与现状脱节，按现状重判：
 
 1. 统计 8 个 Skill、4 个 Agent 与 references 的体量；references 直接用 reference-loading-map + 行数表（见第 6 节），不另起炉灶。
 2. 对每个文件按第 4 节判据标出归属：主 agent（契约形状）/ subagent / runtime / 下沉 references / 改读取方式 / 第 3 节红线。
-3. **token 基线**：测“主 agent 写一章实际加载的上下文”，而非文件行数——记录 webnovel-write 主链一次 default 写章，主 Skill + 内联内容 + 全文读 reference 的近似 token，作为降幅度量基准。
+3. **token 基线（方向性参考，非硬考核）**：可选地估算 webnovel-write 主链一次 default 写章时“主 agent 实际加载的上下文”（主 Skill + 内联内容 + 全文读 reference）的近似 token，仅用于判断瘦身方向，不作为通过 / 失败门槛。
 4. **读取审计**：对照 loading-map「直接 Read 的 md」，逐条标 全文 / 区段 / 检索 / 不读（第 6.2.2 靶心优先）。
-5. **先补红线测试再瘦身**：把第 5.2 跨层红线中当前只有文案级断言或无断言的，补成行为 / 契约级断言（第 12 节），使其在改动前先变绿。
-6. **工具能力复核**：核对 Claude Code 官方最新 tools / subagents / skills 文档、本机 plugin-dev 指导和当前安装版本；确认 `Agent`、`Skill`、`AskUserQuestion`、`Read`、`Grep`、`Glob`、`Bash`、`PowerShell` 等是否存在、如何授权、在 subagent 中如何表现。复核结果落盘，后续提示词不得写入未核实的工具能力。
+5. **先补红线测试再瘦身（区分 5.2 的 A / B 两类）**：A 类（守护现状）中当前只有文案级断言或无断言的，补成行为 / 契约级断言（第 12 节）并在改动前先变绿；B 类（本轮新契约：写入所有权矩阵、agent `tools` 与落盘责任一致性、提交前 `git diff` 只读校验）当前无实现，Phase 0 只写好断言并显式标记为待实现（pytest `xfail` / `skip`，或 eval 中标注 pending），随对应 Phase 落地后转正，不要求 Phase 0 通过。
+6. **工具能力确认（固化官方结论 + 复核本插件）**：记录 Claude Code 版本、官方 docs URL / 日期、Claude Code 当前运行会话的工具摘要、插件实际注册的 agent / skill 名称。内置工具（`Read` offset/limit、`Grep`、`Glob`、`Agent`、`Skill`、`AskUserQuestion`、`Write`、`Edit`）和 Bash 按官方行为设计；PowerShell 不进入默认流程，只记录是否可用、是否启用 PowerShell tool、以及 Windows-only 兜底边界；把官方结论落盘：subagent 不能 spawn subagent，`Agent` / `AskUserQuestion` 不作为 subagent 工具设计，`tools` / `disallowedTools` 控制 subagent 工具边界，`skills` 字段可预加载完整 Skill，Skill 的 `allowed-tools` 是预批准而非限制；复核本插件实际注册名、frontmatter 与 `allowed-tools` 是否符合本机 plugin-dev。
 7. 跑基线验证：
 
 ```bash
@@ -505,8 +653,9 @@ python -X utf8 webnovel-writer/scripts/validate_plugin_package.py --format json
 ### 7.3 验收
 
 - 得到每个 Skill / Agent / reference 的“保留 / 下沉 / 删除 / 读取方式”清单，**落盘为可追踪文件**，不只是口头结论。
-- token 基线数值已记录，作为后续降幅度量基准。
-- 第 5.2 全部跨层红线都有行为 / 契约级断言且通过。
+- （可选）token 基线作为方向性参考已记录；token 不作硬考核指标，缺该数值不阻断验收。
+- 第 5.2 红线都有行为 / 契约级断言：A 类（守护现状）全部通过；B 类（本轮新契约）断言已写好并标记为待实现，不要求 Phase 0 通过。
+- 写入所有权矩阵落盘为可追踪文件；其强制断言归 5.2 B 类，Phase 0 写好待实现，随对应 Phase 落地后由 prompt integrity / behavior eval 检查通过。
 - 当前验证命令通过。
 
 ---
@@ -546,41 +695,55 @@ python -X utf8 webnovel-writer/scripts/validate_plugin_package.py --format json
 context-agent：
 
 ```text
-chapter={chapter_num}
-project_root=${PROJECT_ROOT}
-scripts_dir=${SCRIPTS_DIR}
-storage_path=${PROJECT_ROOT}/.webnovel
-state_file=${PROJECT_ROOT}/.webnovel/state.json（projection/read-model，仅兼容读取）
-要求：先 research，再按 本章硬性约束 -> CBN/CPNs/CEN -> 本章禁区 -> 风格指引 -> dynamic_context 补充参考 的顺序输出五段写作任务书；上下文不足时返回 blocker。
+Use the Agent tool to run `webnovel-writer:context-agent`.
+
+Task:
+- chapter={chapter_num}
+- project_root=${PROJECT_ROOT}
+- scripts_dir=${SCRIPTS_DIR}
+- storage_path=${PROJECT_ROOT}/.webnovel
+- state_file=${PROJECT_ROOT}/.webnovel/state.json（projection/read-model，仅兼容读取）
+- 先 research，再按 本章硬性约束 -> CBN/CPNs/CEN -> 本章禁区 -> 风格指引 -> dynamic_context 补充参考 的顺序输出五段写作任务书。
+- 上下文不足时返回 blocker。
 ```
 
 reviewer：
 
 ```text
-chapter={chapter_num}
-chapter_file=${CHAPTER_FILE}
-project_root=${PROJECT_ROOT}
-scripts_dir=${SCRIPTS_DIR}
-output=${PROJECT_ROOT}/.webnovel/tmp/review_results.json
-要求：只输出结构化审查结果，不评分，不口头总结。
+Use the Agent tool to run `webnovel-writer:reviewer`.
+
+Task:
+- chapter={chapter_num}
+- chapter_file=${CHAPTER_FILE}
+- project_root=${PROJECT_ROOT}
+- scripts_dir=${SCRIPTS_DIR}
+- Return strict raw JSON only; do not write files.
+- Main flow writes the returned JSON to ${PROJECT_ROOT}/.webnovel/tmp/review_results.json.
+- 不评分，不口头总结。
 ```
 
 data-agent：
 
 ```text
-chapter={chapter_num}
-chapter_file=${CHAPTER_FILE}
-project_root=${PROJECT_ROOT}
-scripts_dir=${SCRIPTS_DIR}
-output_dir=${PROJECT_ROOT}/.webnovel/tmp
-要求：生成 fulfillment_result.json、disambiguation_result.json、extraction_result.json；不直接写 projection。
+Use the Agent tool to run `webnovel-writer:data-agent`.
+
+Task:
+- chapter={chapter_num}
+- chapter_file=${CHAPTER_FILE}
+- project_root=${PROJECT_ROOT}
+- scripts_dir=${SCRIPTS_DIR}
+- output_dir=${PROJECT_ROOT}/.webnovel/tmp
+- 生成 fulfillment_result.json、disambiguation_result.json、extraction_result.json。
+- 不直接写 state/index/summaries/memory/vectors/projection。
 ```
 
+落盘责任必须和 agent frontmatter 对齐：本 plan 默认 reviewer 不授予 `Write`，只返回 JSON，由主流程写 `review_results.json`；data-agent 授予 `Write`，直接写三份 artifact。若未来调整，必须同时改模板、frontmatter、prompt integrity，保证单产物单写入者。
+
 ### 8.5 风险控制
 
 - `write-gate precommit` 与 `artifact_validator` 兜底 schema。
-- behavior eval 检查三道 gate、三类 artifacts、chapter-commit、postcommit、backup。
-- prompt integrity 检查禁止裸 `git add .`、禁止主流程口头替代 subagent。
+- behavior eval 检查三道 gate、三类 artifacts、提交前 git diff 变更面校验、chapter-commit、postcommit、backup。
+- prompt integrity 检查禁止裸 `git add .`、禁止主流程口头替代 subagent、写入所有权矩阵与 agent `tools` 对齐。
 
 ---
 
@@ -675,7 +838,7 @@ Skill 可以更短，但必须保留第 3.2 节完整链。
 
 压缩方向：
 
-- 详细采集字段保留在现有 `init-collection-schema.md`，对其做区段读；不新建 init-flow.md（见 6.2.4）。
+- 详细采集字段保留在现有 `skills/webnovel-init/references/init-collection-schema.md`，对其做区段读；不新建 init-flow.md（见 6.2.4）。
 - 题材列表只保留 canonical 集合和少量示例。
 - CLI 参数长表可收缩为“参数来自采集对象”，但要保留执行 init 的事实。
 - 创意约束细则、反套路库、世界观设计指南按需读取。
@@ -697,7 +860,7 @@ Skill 可以更短，但必须保留第 3.3 节完整链。
 
 压缩方向：
 
-- CBN / CPN / CEN 细则保留在现有 `outlining/chapter-planning.md`「结构化节点规范」，对该节做区段读；不新建 chapter-node-rules.md（见 6.2.4）。
+- CBN / CPN / CEN 细则保留在现有 `skills/webnovel-plan/references/outlining/chapter-planning.md`「结构化节点规范」，对该节做区段读；不新建 chapter-node-rules.md（见 6.2.4）。
 - 长 reference 表可改为“按阶段触发读取”。
 - 结构化节点示例下沉。
 
@@ -813,11 +976,12 @@ Skill 可以更短，但必须保留第 3.5 节完整链。
 
 #### 必保行为（用行为 / 契约断言守，不锚具体措辞）
 
-- 写章主链：三道 gate（prewrite / precommit / postcommit）按序落地；reviewer 一轮；blocking 只定点修复或用户裁决；data-agent 三份 artifacts；`chapter-commit` 提交并驱动 projection；postcommit 五项 projection 全 done/skipped；失败只 `projections retry`；`backup --project-root`。
+- 写章主链：三道 gate（prewrite / precommit / postcommit）按序落地；reviewer 一轮；blocking 只定点修复或用户裁决；data-agent 三份 artifacts；`write-gate precommit` 后、`chapter-commit` 前执行只读 `git diff` 变更面校验；数据库 / `.webnovel/` read-model 的表级语义用 runtime / SQLite 只读查询确认；`chapter-commit` 提交并驱动 projection；postcommit 五项 projection 全 done/skipped；失败只 `projections retry`；`backup --project-root`。
 - artifact 契约：三份 artifact 字段由 runtime schema（`chapter_commit_schema` / `story_event_schema` / `schemas`）校验；**新增 precommit 负向用例**——缺 `missed_nodes` / `pending` / 关键字段时 precommit 必须拦截。这取代“主 Skill 文案里必须出现字段名”的检查。
 - 8 个 Skill 可发现、frontmatter 合法、description 可触发、中文优先。
-- 4 个 Agent 单文件、frontmatter 含 `name`/`description`/`model`/`color`、`tools` 最小集、不依赖 `agents/references/*`。
+- 4 个 Agent 单文件、frontmatter 含 `name`/`description`/`model`/`color`、`tools` 最小集且与落盘责任匹配、不依赖 `agents/references/*`。
 - Agent 边界：data-agent 不直接写 projection；reviewer 只输出结构化 JSON 且覆盖 5 维；context-agent 输出五段任务书、用 `load-context`；deconstruction-agent 不写文件、产 `init_reference_research`、防 canon 污染、保留 Step 1.5 与确认门。
+- 写入所有权：`review_results.json`、三份 data artifacts、review metrics/report、state/index/summaries/memory/vector 都有唯一写入者；prompt 中不得同时要求两个层写同一文件，也不得只要求“生成”而不说明落盘方；对 SQLite / 二进制 read-model，验收看 runtime 查询结果，不看 `git diff` 内容。
 - plan 保留 `.story-system/` 主链与节拍表/时间线/章纲节点/总纲写回/状态更新；query / dashboard / doctor 只读不写项目文件。
 
 #### 该删 / 该迁 / 该松绑的现有断言
@@ -851,7 +1015,8 @@ python -m pytest webnovel-writer/scripts/data_modules/tests webnovel-writer/scri
 - 插件结构符合官方 `plugin-structure`；Skill / Agent 修改符合 `plugin-dev`。
 - behavior eval、package validator、prompt integrity 全过（在退役文案断言、补齐行为 / 契约断言之后）。
 - 第 5.2 跨层红线全部有行为 / 契约级断言守护。
-- **token：写章主链“主 agent 写一章加载的上下文”相对 Phase 0 基线下降，并给出数值**，不是“明显下降”的主观判断。
+- 写入所有权矩阵通过检查：每个产物唯一写入者明确，agent `tools` 与写入责任一致，提交前 git diff 校验存在且只读；数据库语义校验通过 runtime / SQLite 只读查询覆盖。
+- token：写章主链“主 agent 写一章加载的上下文”方向上应较 Phase 0 下降；token 为方向性参考，不作硬性数值门槛，不因缺数值或降幅不足而判定验收失败。
 - 主 Skill 不再携带 subagent 长流程与 data schema；schema 真源唯一在生产方 agent + runtime。
 - references：第 6.2.2 靶心大文件已改按需读；死 reference 已核验并处置。
 - 第 3 节端到端流程未被瘦身删掉。
@@ -886,6 +1051,10 @@ C:\Users\lcy\.claude\plugins\marketplaces\claude-plugins-official\plugins\plugin
 | 主 Skill 过度精简 | Agent 输入不足 | Skill 保留 Agent 最小输入合同 |
 | schema 压缩后 agent 漏字段 | commit 前失败 | `artifact_validator` 与 `write-gate precommit` 阻断 |
 | Agent 单文件过短 | 专业执行质量下降 | 单文件保留最小必要流程、边界和输出合同 |
+| subagent 落盘责任与 `tools` 不一致 | reviewer / data-agent 产物缺失，后续 runtime 找不到 tmp JSON | 要么给对应 agent `Write`，要么由主流程接收 JSON 后写文件；prompt integrity 检查两者一致 |
+| 产物重复写入或没人写入 | 结果互相覆盖，或后续 runtime 找不到文件 | 第 4.5 写入所有权矩阵；行为测试检查每个产物唯一写入者 |
+| `git diff` 校验误变成 git 提交流程 | 污染工作区或把无关文件 stage | 只允许 `git diff --name-status` / `git diff --check`；禁止 `git add` / `git commit` |
+| 误以为 `git diff` 能检查数据库内容 | SQLite / 向量库 / ignored `.webnovel/` 的内部错误漏检 | `git diff` 只查文件面；数据库与 read-model 必须由 runtime gate、projection_status、SQLite 只读查询验证 |
 | reference 下沉过多 | 执行时忘记读取 | reference 只给长细则，主流程保留触发条件 |
 | 区段读锚点漂移 | 读到错段或空内容 | reference 用稳定标题锚点；区段读失败时回退全文读并告警 |
 | 文案级断言阻碍瘦身 | 误把测试当约束 | 退役文案断言、改行为 / 契约级（第 12 节）；删 / 迁前确认非红线 |
@@ -897,7 +1066,7 @@ C:\Users\lcy\.claude\plugins\marketplaces\claude-plugins-official\plugins\plugin
 
 ## 15. 推荐施工顺序
 
-1. Phase 0：基线统计、读取审计、token 基线，**先把第 5.2 红线补成行为测试形成绿色基线**。
+1. Phase 0：基线统计、读取审计、token 基线，**先把第 5.2 A 类红线补成行为测试形成绿色基线（B 类新契约写好断言、标记待实现）**。
 2. `webnovel-write`：先保全写章主链，再瘦主 Skill；同步退役锚文案的 schema 断言。
 3. `context-agent`：稳定五段任务书和上下文压缩。
 4. `data-agent`：schema 作为单文件唯一真源，删长 payload 教程；加 precommit 负向用例。