spec-direction-gate git:20260930.87567b6A

Immutable. This exact content never changes and is served at /api/v1/blob/eaa7cf2333d73047.

---
name: spec-direction-gate
description: 技术方案文档的方向确认关卡。在 specs/<id>/TECH.md 草稿完成、进入实施之前，先确认方向、再确认内容，两次确认分开且有序；把关卡结论写回 TECH.md 作为批准状态的显式记录。拒绝语义：没有人在场就停止并报告，绝不自动放行。用于任何"文档获批才能开始写代码"的环节之前。
disable-model-invocation: true
---

# 方向确认关卡（B）

一条流程只有在"方向"这一格真的会挡住它的时候才算成立。这个技能就是那一格。

输入是 `specs/<id>/TECH.md` 的草稿，输出是写回 `TECH.md` 的批准状态记录。中间没有任何自动放行的路径。

## 何时使用

- `TECH.md` 草稿已写完，尚未开始实施
- 需要在实施前留下"谁在什么时候批准了方向"的可核验记录
- 复盘时需要确认某个实施是否真的经过方向批准，而不是默认通过

## 何时不使用

- 纯 UI 改动、单文件修复等低复杂度变更，`TECH.md` 本身就不必产出
- 方向已经单独确认过、这次只是修订若干小节时，改用下面的"增量修订"路径

## 硬性约束

1. **两次确认，不合并。** 先确认方向，确认通过之后才确认内容。合并这一步会破坏关卡：把大纲和方向放在同一次确认里，人会锚定在已经看到的具体大纲上，而不再重新考虑它上位的那个问题。
2. **拒绝语义。** 没有人在场就停止并报告这个技能需要人，不要"先按草稿往下走，回头再确认"。
3. **批准要落盘。** 两次确认的结论写进 `TECH.md`，不只留在对话里。实施阶段的验收要能读到"批准后文档仍存活"的证据。
4. **批准的是方向，不是逐字内容。** 方向确认通过后，作者仍可改实现细节；实施者不得改方向。

## 流程

### 第 0 步：确认在场

先确认当前是有人可以回答的交互会话。

不是交互式会话时：**停下并报告**"这个关卡需要人在场确认方向"，然后结束。不要用默认值代替确认，也不要因为草稿看起来已经足够好就跳过。

### 第 1 步：确认方向

读 `TECH.md`，然后只向人提出**方向层面**的问题，不要展示具体大纲或章节结构：

- 这份文档要解决的问题，和仓库当前状态对得上吗
- 选定的方案，是这几个候选里最合适的那个吗
- 哪些明确不在这次范围内
- 还有什么上位问题，是这份文档答不了的

把问题一次问完，然后等回答。

**方向被拒时的处理**：记录被拒的方向和原因，停止。不要改写成新的大纲再问第二遍——那等于把第一次确认作废。修改草稿后必须从第 1 步重来。

### 第 2 步：确认内容

只有在第 1 步通过后才进入这一步。展示文档的实际章节和每节承担的内容，然后等确认。

内容被拒时：按意见修订，同样从第 1 步重新开始（内容修订可能改变方向）。

### 第 3 步：写回批准状态

两次都通过后，把结论追加到 `TECH.md` 末尾：

```markdown
## Approval

- 方向确认：通过 / 拒绝（时间：YYYY-MM-DD HH:MM CST，确认人：__）
- 内容确认：通过 / 拒绝（时间：YYYY-MM-DD HH:MM CST，确认人：__）
- 本次确认的范围：仅方向与结构。实现细节可由作者调整，方向变更须重新过本关卡。
```

批准状态是**显式记录**，不是推断依据。没有这段内容，验收阶段必须按"未批准"处理。

写完用同目录的校验脚本自查：

```bash
python3 check-approval.py specs/<id>/TECH.md
```

退出码 `0` = 已批准可进入实施；`1` = 挡住（缺 `## Approval`、结论仍是 `通过 / 拒绝` 模板、缺时间戳、方向被拒、结论无法判定）；`2` = 用法错误。

模板里的 `通过 / 拒绝` 必须二选一写死。**两个候选都留着会被判为未批准**——这是有意的，模板没填就等于没确认。

## 实施前的机械检查

上面的约束是文字。文字挡不住无人值守运行，所以本技能附带一个退出码校验：

```bash
python3 check-approval.py specs/<id>/TECH.md
```

进入实施之前跑一次，退出码非 `0` 就不要开始写代码。脚本只读不写，不会改文档。

被挡住的常见情况：

- 文件不存在
- 没有 `## Approval` 段
- 有 `## Approval` 段但里面没有方向确认结论（**摄入技能产出的就是这个状态**）
- 结论仍是 `通过 / 拒绝` 模板
- 通过但没写时间戳（批准必须可核验到"谁在什么时候批准"）
- 方向被明确拒绝
- 既不是通过也不是拒绝——按未批准处理

`## Approval` 之后如果还有别的章节，脚本只读到下一个章节标题为止；把"方向确认：通过"藏在后面的章节里不算数。`## Source draft` 之类段落里出现的"通过"也不会被误读成批准。

## 增量修订路径

只改了措辞、补充了行级引用、调整了不影响方向的实施顺序时，不必重走两次确认。在现有的 `## Approval` 段下面追加一条修订记录，写明改了什么、为什么不需要重新确认方向。

判断权在人手上。拿不准就走完整路径。

## 与其他技能的衔接

- 上游：`write-tech-spec` 产出 `TECH.md`（`specs/<id>/` 目录约定）
- 下游：`implement-specs` 的前置条件只是"approved enough"这种软条件，**不构成关卡**。真正的关卡在这里，跑完本技能才算进入实施
- 实施期间：`write-tech-spec` 的 *Keep the spec current* 要求 `TECH.md` 随实施同 PR 更新，且**不得删掉 `## Approval` 段**——批准状态是验收阶段要核验的东西
- 验收阶段：新会话中对照文档验收，不对照对话

## 验收用例

要能构造"方向被拒"的用例，流程必须停止并报告，不得自动续跑。判定依据是对照 `write-feature-docs` 第 449–454 行的拒绝语义：不得重新加入无人值守路径，须停下并报告该技能需要人工在场。