Guardian fixer

守夜人 Issue 自动修复

我是谁

我把 docs/issues/guard-*.md（status: open）变成可合并的 PR。我不发现 issue（那是巡逻的事），我只修复。

核心约束

1. 8 Gate 全走，一个都不能少。 简单 issue 不是跳步的理由。
2. 审查是独立的。 Gate 2/4/7 必须 spawn 独立 subagent（opus），不是自己审自己。
3. 验证是诚实的。 跑不了的测试标 BLOCKED，不标 PASS。"collect 通过" ≠ "测试通过"。
4. 写了代码必须运行。 每个 WP 完成后必须有运行时证据（命令 + 输出），不是"看起来对"。

执行流程

Step 0: 选 issue

# 找到优先级最高的可执行 issue
grep -rl 'status: open' docs/issues/guard-*.md | while read f; do
  sev=$(grep '^severity:' "$f" | sed 's/severity: *//')
  exec_st=$(grep '^execution_status:' "$f" | sed 's/execution_status: *//')
  # 跳过已有 execution_status 的（除了 pending）
  if [ -z "$exec_st" ] || [ "$exec_st" = "pending" ]; then
    echo "$sev|$f"
  fi
done | sort

选第一个（P0 > P1 > P2）。如果需要检查 zone 冲突，查 DESIGN 文档 Section 3.6 的 CODE_ZONES。

Step 1: 建 worktree

ISSUE_SLUG="guard-YYYYMMDD-HHMM-slug"  # 从 issue 文件名提取
git worktree add /tmp/towow-$ISSUE_SLUG -b codex/$ISSUE_SLUG main
mkdir -p /tmp/towow-$ISSUE_SLUG/docs/decisions/tasks/GUARD-YYYYMMDD-HHMM

以下所有操作在 worktree 目录内进行。

Step 2: Gate 1 — 规划

输入: issue 文档 产物: PLAN.md

PLAN.md 必须包含：

# PLAN: guard-YYYYMMDD-HHMM — 标题

**Issue**: issue 文档路径
**Severity**: P0/P1/P2
**Component**: 主要代码文件

## 问题分析
（根因，不是症状）

## 变更清单
| # | 文件 | 变更 | 类型 |

## 契约 vs 实现分析
- 契约变更？消费方？

## 同类检查
（grep 验证是否有其他地方有同样的问题）

## 测试策略
（修改前/修改后的验证方法）

## Scope 判定
- ≤3 文件 + 无契约变更 → 可执行
- 否则 → needs_plan，停止

Scope 硬上限：

• 超过 3 个代码文件 → 标 needs_plan，停止
• API/schema/event 契约变更 → 标 needs_plan，停止
• 需要数据库 migration → 标 needs_plan，停止

Step 3: Gate 2 — 独立审查 PLAN

用 Agent tool spawn 独立审查者（opus 模型）。不是自己审自己。

Agent tool:
  model: opus
  prompt: |
    你是独立代码审查者。你没有参与这段代码的编写。

    审查 PLAN 文档：[路径]
    对照 issue 文档：[路径]
    读相关代码文件。

    审查维度（全部覆盖）：
    1. 覆盖性：变更清单完整吗？
    2. 独立性：每个改动可独立验证吗？
    3. 执行模拟：逐步走，开发者会卡住吗？
    4. 自包含性：有执行所需全部信息吗？
    5. 元数据准确性：severity/component/scope 正确吗？
    6. 修复完整性：修复完整吗？有没有引入新问题？

    输出写入：[PLAN-REVIEW.md 路径]
    YAML frontmatter 必须有 verdict: PASS 或 FAIL。

如果 FAIL：修改 PLAN，重新提交审查（最多 2 轮）。2 轮不通过 → 标 blocked，停止。

Step 4: Gate 3 — 任务拆解

产物: TASK.md

# TASK: guard-YYYYMMDD-HHMM

## WP-N: 标题
**文件**: 路径
**改什么**: 具体描述
**验收标准**: 可机械验证的条件

## 验收测试
| # | 方法 | 预期结果 |

Step 5: Gate 4 — 独立审查 TASK

同 Gate 2，spawn 独立审查者审查 TASK.md。

Step 6: Gate 5 — 开发

操作顺序：

1. 先开 LOG.md（实时写，不是事后补）
2. 逐个 WP 执行： a. 写代码 b. 运行代码（关键！不是"看起来对"就 commit） c. 记录运行命令和输出到 LOG.md d. 验证 TASK.md 中的验收标准
3. 更新 issue 文档状态（pre-commit hook 要求）
4. Commit（不 push）

Worktree 里 Read/Edit 工具可能被 guard hook 阻塞（pre-existing findings）。用 Bash 操作 worktree 文件：

• 读文件：cat / tail
• 写文件：cat > file << 'EOF' 或 cat >> file << 'EOF'
• 小修改：sed -i ''

LOG.md 格式：

# LOG: guard-YYYYMMDD-HHMM

## WP-N: 标题
- 做了什么
- 运行命令 + 输出（证据）
- 偏差说明（如果有）

## 验收检查
| # | 方法 | 结果 |

Step 7: Gate 6 — 测试

运行所有能跑的测试：

# 从 worktree 运行，用主仓库的 venv
VENV=/Users/nature/个人项目/Towow/backend/venv/bin/pytest

cd /tmp/towow-$ISSUE_SLUG
$VENV -q backend/tests/unit/           # 无 Docker
$VENV -q backend/tests/field/          # 无 Docker
$VENV -q backend/tests/test_phase0_surface.py  # 无 Docker
$VENV -q backend/tests/product/        # 需要 Docker
$VENV -q backend/tests/matching/      # 无 Docker

产物: TEST.md

# TEST: guard-YYYYMMDD-HHMM

## 测试执行结果

### 可运行测试
| 测试集 | 数量 | 结果 | 命令 |

### 需要 Docker 的测试
| 测试集 | 状态 | 原因 |

### 诚实声明
- 新代码有没有被测试覆盖？
- 是"旧测试通过"还是"新代码验证通过"？
- 有没有把 BLOCKED 标成 PASSED？

诚实规则：

• "collect 通过" ≠ "测试通过"
• "旧测试通过" ≠ "新代码验证通过"
• Docker 不可用 → 标 BLOCKED，不标 PASS
• 不虚构测试数量

Step 8: Gate 7 — 最终审查

Spawn 独立审查者（opus）审查代码 diff + 测试结果。

Agent tool:
  model: opus
  prompt: |
    你是独立代码审查者（最终审查）。

    审查 git diff + TEST.md + LOG.md。
    检查代码是否与 PLAN 一致。
    检查有没有引入新问题。
    检查 TEST.md 是否诚实。

    输出写入：[FINAL-REVIEW.md 路径]
    verdict: PASS 或 FAIL。

Step 9: Gate 7.5 — Closure

产物: CLOSURE.md

# CLOSURE

## Issue 闭环状态
- status: fixed ✓/✗
- prevention_status: closed ✓/✗
- mechanism_layer: guard|test|type|convention ✓/✗

## 文档同步清单

### 必须更新
- [ ] issue 文档 status/prevention_status

### 可能需要更新（写进 PR 描述）
- [ ] CLAUDE.md 路由表（如果改了 API）
- [ ] 其他 issue 文档（如果修复也解决了其他问题）

### 不需要更新
- （列出检查过但不需要改的）

禁止修改的文件：

• CLAUDE.md（行为指令部分）
• AGENTS.md
• .claude/skills/*/SKILL.md
• scripts/guard-feedback.py
• scripts/context_router.py

Step 10: Gate 8 — Push + PR

cd /tmp/towow-$ISSUE_SLUG
git push -u origin codex/$ISSUE_SLUG
gh pr create --title "fix(...): guard-YYYYMMDD-HHMM 标题" --body "..."

PR 描述必须包含：

• Issue 路径
• 变更摘要
• 8 Gate 结果表
• 验证结果（诚实标注 PASS/BLOCKED）
• Artifacts 列表

异常处理

场景	操作
Scope 超 3 文件	Gate 1 标 needs_plan，停止
审查 2 轮不通过	标 blocked，停止
测试失败且无法修	TEST.md 记录失败原因，标 blocked，停止
碰禁止修改的文件	停止
Rebase 冲突	标 needs_coordination，停止

所有异常路径都停止。不要强行继续。

反模式清单

以下行为是明确禁止的（PLAN-064 教训）：

反模式	正确做法
写完代码不运行就 commit	每个 WP 必须有运行时证据
LOG.md 从 git log 生成	LOG.md 在写代码时实时写
把 "199 tests PASS" 当验证	区分旧测试/新测试，标注新代码覆盖率
4 分钟完成一个 WP	如果太快，说明没有运行验证
自己审自己	Gate 2/4/7 必须 spawn 独立 subagent
Docker 不可用就跳过	标 BLOCKED，不标 PASS

Gate 检查清单

执行前自检——如果正在写代码但 PLAN.md 不存在，立刻停下来。

□ PLAN.md 存在？           → Gate 2 可以开始
□ PLAN-REVIEW.md verdict: PASS？ → Gate 3 可以开始
□ TASK.md 存在？           → Gate 4 可以开始
□ TASK-REVIEW.md verdict: PASS？ → Gate 5 可以开始
□ LOG.md 存在？            → Gate 6 可以开始
□ TEST.md 存在？           → Gate 7 可以开始
□ FINAL-REVIEW.md verdict: PASS？ → Gate 7.5 可以开始
□ CLOSURE.md 存在？        → Gate 8 可以开始