# M3 状态机单入口 + git 隐身全套

## Goal

给作者**一个入口和「继续」**：单入口状态机先跑 git 健康检查（作者永不直面 git 报错，不变量 8），再按序判定当前该做什么（spec §10 序 0-6，命中即停），把 v6 的 8 个命令全部内化为状态流转。状态机只管编排，不判业务、不调 AI（AI 动作备好 DTO 交 M4）。

> 上游法律文本：story-repo-spec §9（中环/外环/例外）、§10（启动序列与状态机）、不变量 8（作者不碰 git）。架构原则 v7-implementation-plan §1.5（状态机只管流程编排）。

## Background（已确认事实，来自 spec §9/§10 + M1/M2 成果）

**启动序列**（§10）：第 0 步前先跑 **git 健康检查**——半提交、合并冲突、锁文件、`.git` 损坏、网盘冲突副本（`xxx (1).md`），每种配自动修复或人话指引。然后按序判定，命中即停：

| 序 | 条件 | 动作 | 执行体 |
|----|------|------|--------|
| 0 | 任一源文件解析失败 | 修复确认（定位到行 + AI 提议修复 + 作者确认；全角冒号/逗号在结构位 = 确定性错误，预修复后只报不问；永不带栈崩） | 检测=脚本，提议=AI(M4) |
| 1 | 无书 / 当前书不存在 | 建书引导（问答生成 book.yaml/总纲/第一卷卷纲 + 指路 AGENTS.md + 登记 books.jsonl） | 问答=AI(M4)，脚手架=脚本 |
| 2 | 定稿/大纲有未登记手改 | 提议 fix 补登（`fix(设定): …`） | 脚本（git diff vs 缓存） |
| 3 | 工作区有未完成流程（含待定稿批次） | 从中断阶段继续 | 脚本（检测工作区状态） |
| 4 | 刚定稿是卷末章 | 卷复盘 | 清账=脚本，对谈=AI(M4) |
| 5 | 章号到体检周期 | 体检 | 条目活跃率/时间线孤儿=脚本，文体指纹=M3+/M4 |
| 6 | 其余 | 起草新章细纲（内环第 1 步） | 全书近况=脚本(M2 已有)，拟提案=AI(M4) |

**外环/例外流程**（§9）：
- 影响分析（**纯脚本**）：grep 正文+条目履历+时间线，列「哪些章建立在这个事实上」，分已发布/未发布两清单。
- 回到第 N 章（人话命令）：git 回滚包装，执行前展示影响范围 + 作者确认。
- 吃书 retcon：改定稿，commit `retcon(N): 原因`，设定/条目同步，留痕。
- 手改检测：即序 2。
- 分支试写：AI 代开 git 分支 `what-if/…`（git=脚本，推演=AI M4）。

**不变量 8**：作者全程不碰 git 命令，不直面 git 报错。

**M1/M2 已就绪可复用**：M1 读接口（grep-story 给影响分析、reports 给体检/近况）+ `.cache` 重建器；M2 `assembleBookStatus`（序 6 近况）、`finalizeChapter`（git 操作范式 + git.js 封装可扩展）、机检/备料。

**现有空壳**：`v7/src/state-machine/`、`v7/src/installer/`（M0 占位）。

## Requirements（待 brainstorm 收敛，先列骨架）

- R1 git 健康检查：检测半提交/冲突/锁/损坏/网盘副本，各配自动修复或中文指引，永不抛 git 原始报错
- R2 状态机单入口：按 §10 序 0-6 命中即停判定，返回「当前态 + 该做什么」；状态机不判业务、不调 AI
- R3 各态检测逻辑（脚本部分）：解析失败(0)、无书(1)、未登记手改(2)、工作区未完成(3)、卷末章(4)、体检周期(5)、其余(6)
- R4 外环纯脚本流程：影响分析、回到第 N 章、吃书 retcon、（分支试写 git 部分）
- R5 AI 态 DTO 缝：AI 动作（建书问答/修复提议/卷复盘对谈/细纲提案/推演）备好上下文 DTO，返回「需 AI」结果交 M4

## Acceptance Criteria（来自 §10 M3 出口，待细化）

- [ ] 7 个态各有端到端测试（构造命中各序的仓库样本，断言状态机判定正确）
- [ ] git 异常样本库逐个演练（半提交/冲突/锁/损坏/网盘副本），作者可见输出**零英文堆栈**
- [ ] 影响分析/回到第 N 章/吃书 纯脚本流程有测试
- [ ] 不破坏 M1/M2 不变量（删缓存可重建、定稿原子）

## Out of Scope

- ❌ AI 态的真实动作（建书问答/修复提议/卷复盘对谈/细纲提案/分支推演/圆设定）→ M4（M3 只备 DTO + 返回「需 AI」）
- ❌ 体检的文体指纹提取 → M3+/M4（M3 体检只做条目活跃率/时间线孤儿等脚本项）
- ❌ 自动模式连写/批次/污染传播 → M6
- ❌ SessionStart hook 注入实现 → M4/M5（M3 提供状态机入口等价路径）

## 决策记录（brainstorm）

- **D1 范围与粒度**：单任务分期（同 M1/M2）。M3 做满**全部脚本面**——git 健康检查（5 类异常 + 中文指引）、状态机路由器（序 0-6 命中即停）、7 态的检测逻辑、外环纯脚本流程（影响分析 / 回到第N章 / 吃书 retcon / 手改补登 / 分支试写 git 部分）。**AI 态动作（建书问答/修复提议/卷复盘对谈/细纲提案/推演/圆设定）→ 只做「检测 + 备 DTO + 返回需 AI」交 M4**；体检文体指纹提取推 M3+（M3 体检只做条目活跃率/时间线孤儿脚本项）。单入口 = 库函数 `determineNextState(ctx)` + 一个 CLI 命令，SessionStart hook 注入留 M4/M5。分期：git健康 → 路由+7态检测 → 外环脚本流程 → AI 态 DTO 缝。

- **D2 git 健康检查 = 激进自动修复（B）+ 可恢复安全网**：尽量自动修、少打扰作者，但**每个改 git 状态的修复前先做可恢复快照**（stash / 备份 ref / 文件挪到 `工作区/.救援/` 而非删除），修复后给中文小结「修了什么 + 怎么撤」。映射：陈旧锁文件→自动删；网盘副本→自动归档（不删）；半提交→自动 stash（可恢复）；merge 冲突→先备份再 `merge --abort`；`.git` 损坏→**例外**，无安全自动修，只检测 + 中文指引。激进但零数据丢失。

## Open Questions（brainstorm 待答）

- 无（DTO 形态、手改检测机制、影响分析「已发布」边界等技术细节于 design.md 决，按 M1/M2 风格）。