docs(v7): M4 review P2——spec 回填(表/原子/责任方/版本,含 deep S7/S8)

按 review backlog P2 段回填规范空白,让后续实现有据、不再和代码打架:

- P2-1 database-guidelines:§2.4 列全六表(补 entity_aliases);§4.5 钉死"未知字段保留"
  边界(仅平铺标量/列表,嵌套走修复确认,不再与 §4.1 禁嵌套矛盾);新增 §5 重建器事务性
  (单事务/硬错回滚/软失败跳过,名册非必需)。
- P2-2 error-handling:§3.3 多文件原子边界(writeAtomicBatch 文件批 + 事务 + 豁免);
  §3.4 回滚收窄到 written 集合;§5 退出码 0/1 + {ok,error} 契约 + 回滚 try/catch。
- P2-3 quality-guidelines:§2.2 AI 预算(完整两审 2 次/降级 1 次);§3.3 责任方=建书流程
  (git init+quotepath+.gitignore);§6 工具链(node:test/drift/退出码/commit 前缀/版本号)。
- P2-4(deep S8) 版本号:v7/package.json 设预发版号 7.0.0-alpha(version CI 不查此文件,
  安全);README/marketplace/CHANGELOG 留 M5 发版同步(§6.5 钉死流程)。
- 附 directory-structure §3.3(S7):补 .gitignore 归位与 .cache/+工作区/ 必 ignore。

测试:263 绿;drift check 通过;--version = 7.0.0-alpha。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.trellis/spec/backend/database-guidelines.md

@@ -18,7 +18,7 @@
 
 2.3 **重建器即格式的参考实现**：重建器能完整重建，即证明源文件格式自洽。修改任何源文件格式时必须同步修改重建器。
 
-2.4 表名属机器域，用英文：`chapters`、`threads`、`secrets`、`entities`、`fingerprints`。表设计必须支撑精准读取接口（PRD §3.6）的全部查询。
+2.4 表名属机器域，用英文：`chapters`、`threads`、`secrets`、`entities`、`entity_aliases`、`fingerprints`。`entity_aliases` 是 `entities` 的别名索引表（alias → entity_id），供别名解析与唯一性校验。表设计必须支撑精准读取接口（PRD §3.6）的全部查询。
 
 ## 3. 禁止事项
 
@@ -38,9 +38,15 @@
 
 4.4 缩进统一两空格；编码 UTF-8 无 BOM。
 
-4.5 读取必须**容错**：遇到未知字段必须保留原样写回，禁止丢弃或报错。
+4.5 读取必须**容错**：遇到未知字段必须保留原样写回，禁止丢弃或报错。边界——"未知字段保留"仅限**平铺标量与平铺列表**；遇到作者写入的**嵌套映射**字段时不适用：嵌套映射违反 §4.1，防呆序列化器拒绝写出，读到嵌套字段视为格式错误，走修复确认（序0），不静默丢弃也不强行平铺写回。
 
-## 5. 待增量补充
+## 5. 重建器事务性
+
+5.1 全量重建必须在**单事务**内完成（`BEGIN` → DELETE 全表 → 扫描 INSERT → `COMMIT`），中途任何失败（含名册别名冲突等数据完整性违反）必须 `ROLLBACK`，禁止留半填库。
+
+5.2 软失败不回滚：名册缺失或格式解析不动属"best-effort 跳过"，记 warning、不阻断重建、不回滚已写的 chapters/threads/secrets；只有别名冲突等硬错才回滚。名册非必需（角色卡可独立入 `entities`）。
+
+## 6. 待增量补充
 
 - [ ] 各表的列定义与索引（实现 O4 精准读取接口时定稿）
 - [ ] 重建器的增量更新策略（全量重建 vs 按 commit 增量）

.trellis/spec/backend/directory-structure.md

@@ -33,6 +33,7 @@ webnovel-writer/                # 仓库根
 
 - 工作目录 ⊃ 书目录；插件本体住 `工作目录/.webnovel/`（Node 脚本、角色定义、模板哈希清单、`books.jsonl`）。
 - 书仓库内必须**零工程文件**（唯一例外：指路 `AGENTS.md`）；作者可见的目录名、文件名一律中文。
+- 书仓库根必须有 `.gitignore`（建书流程写入，见质量规范 §3.3），至少 ignore `.cache/`（派生物，见数据规范 §2.1）与 `工作区/`（草稿/审稿等临时产物，不入档）。二者被跟踪即违反"零工程文件"与"缓存可删"不变量。
 
 3.4 文件排序必须依赖零填充数字前缀（`0152-`、`第05卷`、`伏笔-031`），禁止依赖中文字典序。
 

.trellis/spec/backend/error-handling.md

@@ -29,6 +29,14 @@
 
 3.2 中断恢复：状态机启动时必须能识别"工作区有未完成流程"并从中断的阶段继续，禁止要求作者重来。
 
+3.3 多文件写入的原子边界（实现在 `src/storage/atomic.js` 的 `writeAtomicBatch`）：
+- **定稿/建书/卷复盘/修复落盘**等多文件写入：全部先写 `.tmp` 再 `rename`，任一失败删全部 `.tmp`、原文件不动。"要么全成要么原样"。
+- **审稿报告**（事实审查/编辑审/审稿单 + 原始 raw）：同上原子批。
+- **缓存重建**多表写入：走数据库事务（`BEGIN/COMMIT/ROLLBACK`，见数据规范 §5），不走文件 rename。
+- 豁免：工作区内纯临时单文件草稿（如 `细纲.md`）无原子要求。
+
+3.4 定稿回滚范围必须**收窄到本次写入文件集合**（`written`），逐文件 `restore`（已跟踪）+ `clean`（未跟踪新文件），禁止对整棵 `定稿/`+`大纲/` 子树 `restore`/`clean`，以免误伤同子树其他章的未登记手改。
+
 ## 4. 面向作者的错误文案
 
 4.1 必须全中文、自然流畅；禁止出现堆栈、错误码、英文术语，也不强求口语化。
@@ -37,7 +45,14 @@
 
 4.3 提醒与错误必须区分："悬了太久"等账面提醒不是错误，禁止用错误语气呈现。
 
-## 5. 待增量补充
+## 5. 退出码与错误类型
+
+5.1 CLI 退出码：`0` = 命令成功；`1` = 命令失败（已落入人话提示，非堆栈崩溃）。`bin/webnovel-writer.js` 统一用 `process.exitCode`，禁止 `process.exit(n)` 硬退（except 版本门槛/`--version` 早退）。
+
+5.2 所有面向作者的执行路径返回 `{ ok: boolean, error: string }` 结构化结果，禁止抛未捕获异常（总原则 §1.1）。`{ok:false}` 携带中文 `error`，调用方据 `ok` 决定退出码。
+
+5.3 `git.clean` / `git.restore` 等回滚操作必须内部 `try/catch` 吞错（尽力而为，不破坏 `{ok,error}` 契约），残余不一致由 git 健康检查兜底。
+
+## 6. 待增量补充
 
-- [ ] Node 脚本层的错误类型定义与退出码约定（首个代码任务时定）
 - [ ] git 健康检查的完整异常清单与修复动作映射

.trellis/spec/backend/quality-guidelines.md

@@ -16,7 +16,7 @@
 
 2.1 **脚本能做的归脚本，做不到的归 AI 语义判断**：可计数项（字数、频次、格式校验、关键词命中）必须用脚本实现，禁止让模型估算；语义判断（是否真泄密、正文是否写到了某事）必须归 AI，**禁止用正则硬凑语义判断**。
 
-2.2 机检必须零 token；AI 调用次数每章有预算上限（实现时定数）。
+2.2 机检必须零 token；AI 调用每章预算：**完整两审 = 2 次**（事实审查 1 + 编辑审 1，各自独立上下文）；**降级模式 = 1 次**（单上下文顺序审）。超预算由宿主壳/编排层拒绝，不在 `runReviews` 内硬凑。
 
 2.3 **精准读取**：每类数据文件必须配"定位读到所需一段"的脚本接口；写作材料组装默认用片段，禁止默认整文件读取。
 
@@ -26,7 +26,7 @@
 
 3.2 Windows 中文环境是一等公民：CI 必须含 Windows 中文路径全链路测试（建库→写章→定稿→重建缓存）。中文路径、中文文件名在任何代码路径上都必须正确处理。
 
-3.3 书仓库初始化必须设置 `git config core.quotepath false`。
+3.3 书仓库工程化由**建书流程**（`persistCreateBook`，序1）负责：`git init` + `git config core.quotepath false` + `.gitignore`（必含 `.cache/` 与 `工作区/`）。`git init` 幂等可重复；`.gitignore` 追加不覆盖既有条目。M5 安装器只负责宿主侧环境，不再代行书仓库初始化。
 
 3.4 缩进两空格。
 
@@ -49,8 +49,14 @@
 - [ ] 可计数逻辑在脚本里，语义判断不在正则里
 - [ ] 行为变更先改了文档（PRD/spec），代码与文档一致
 
-## 6. 待增量补充
+## 6. 工具链与约定（已定）
 
-- [ ] lint / 格式化工具选型与配置（首个代码任务时定）
-- [ ] 测试框架选型（Node 内置 test runner 候选）与覆盖率要求
-- [ ] commit message 在开发仓库（本仓库）的前缀约定沿用现状：feat/fix/docs/chore
+6.1 测试框架：Node 内置 `node:test` + `node:assert/strict`（`npm test` = `node --test`）。无第三方测试依赖。
+
+6.2 lint / 格式化：**零依赖铁律下不引入 ESLint/Prettier**。语法用 `node --check` 兜底；确定性用宿主壳 drift check（`node scripts/build-host-shells.mjs --check`）+ package validator 兜底。缩进两空格、行尾 LF 由评审清单人工把关。
+
+6.3 退出码：`0` 成功 / `1` 失败（见错误处理规范 §5）。
+
+6.4 commit message 前缀沿用现状：`feat` / `fix` / `docs` / `chore`（本仓库开发用）。发布产物（marketplace/CHANGELOG）版本走 `docs/operations/plugin-release.md` 流程。
+
+6.5 版本号：`v7/package.json` 在 M5 发版前为预发版号（`7.0.0-alpha`）；发版时升 `7.0.0` 并与 README 徽章、`.claude-plugin/marketplace.json`、`plugin.json`、`CHANGELOG.md` 一致——README 版本表是 `plugin-version.yml` CI 硬约束，发版必须同步。

.trellis/tasks/06-27-m4-ai-roles/implement.md

@@ -115,10 +115,11 @@ merged 收敛版之外的 deep 报告独有项（作者手改丢失、回滚范
 
 ### P2 spec 回填
 
-- [ ] P2-1 `.trellis/spec/backend/database-guidelines.md`:补 `entity_aliases` 和表定义边界。
-- [ ] P2-2 `.trellis/spec/backend/error-handling.md`:补多文件原子性边界,以及未知字段保留和嵌套字段处理边界。
-- [ ] P2-3 `.trellis/spec/backend/quality-guidelines.md`:钉死 `core.quotepath` 责任方、AI 调用预算、退出码约定。
-- [ ] P2-4 (deep) 版本号对齐:README 版本徽章 6.2.0(v6/master)与 `v7/package.json` `0.0.0` 不一致;README 版本表是 CI 硬约束(Plugin Version Check),M5 发版前必须对齐,否则 CI 红。
+- [x] P2-1 `.trellis/spec/backend/database-guidelines.md`:补 `entity_aliases` 和表定义边界。✅ §2.4 列全六表含 `entity_aliases`;§4.5 钉死"未知字段保留"边界(仅平铺标量/列表,嵌套走修复确认);新增 §5 重建器事务性(单事务/硬错回滚/软失败跳过)。
+- [x] P2-2 `.trellis/spec/backend/error-handling.md`:补多文件原子性边界,以及未知字段保留和嵌套字段处理边界。✅ §3.3 多文件原子边界(writeAtomicBatch/事务/豁免);§3.4 回滚收窄到 written 集合;§5 退出码(0/1)+{ok,error}契约+回滚 try/catch。
+- [x] P2-3 `.trellis/spec/backend/quality-guidelines.md`:钉死 `core.quotepath` 责任方、AI 调用预算、退出码约定。✅ §2.2 AI 预算(完整两审2次/降级1次);§3.3 责任方=建书流程(git init+quotepath+.gitignore);§6 工具链(test runner/drift/退出码/commit 前缀/版本号)。
+- [x] P2-4 (deep) 版本号对齐:README 版本徽章 6.2.0(v6/master)与 `v7/package.json` `0.0.0` 不一致;README 版本表是 CI 硬约束(Plugin Version Check),M5 发版前必须对齐,否则 CI 红。✅ v7/package.json 设预发版号 `7.0.0-alpha`(version CI 不查此文件,安全);README/marketplace/CHANGELOG 留 M5 发版同步(quality §6.5 钉死流程)。
+- [x] (附) `.trellis/spec/backend/directory-structure.md` §3.3:补 `.gitignore` 归位与 `.cache/`+`工作区/` 必 ignore(S7),与 P0-2 紧耦合。
 
 ### P3 保留项
 

v7/package.json

@@ -1,7 +1,7 @@
 {
   "name": "webnovel-writer",
-  "version": "0.0.0",
-  "description": "AI 网文写作工作流（v7 重写，M0 骨架）",
+  "version": "7.0.0-alpha",
+  "description": "AI 网文写作工作流（v7 重写，M5 发版前预发版号）",
   "type": "module",
   "engines": {
     "node": ">=22.13.0"