# 交接文档与视觉证据精简实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` to implement this plan task-by-task. The user explicitly forbids subagents and worktrees. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 把当前交接整理为一个无陈旧状态、低图片阅读负担、能让新 GPT 直接恢复技能和审核流程的入口。

**Architecture:** `docs/交接记录.md` 是快速入口，`docs/design/视觉设计交接手册.md` 承担详细操作说明，新增 `docs/design/视觉证据索引.md` 集中保存截图路径；契约测试负责阻止旧状态和技能说明缺失。所有现有 PNG 原地保留。

**Tech Stack:** Markdown、PowerShell 契约测试、Git 只读检查。

## Global Constraints

- 仅修改交接、证据索引、早期报告说明和对应测试，不修改页面、路由、接口或运行资产。
- 54 条最终路由保持 7 个 `[x]`、47 个 `[~]`；候选不能写成用户已验收。
- 不删除、不移动任何现有 PNG。
- 不使用 worktree、多代理、`git add`、commit、push、上传、reset 或 checkout。
- 正文默认每页只指向一张 360×800 代表图；复杂状态优先使用一张状态联系表；历史对比图只进入归档索引。

---

### Task 1: 建立交接文档契约

**Files:**
- Create: `tests/handoff-documentation-contract.ps1`

**Interfaces:**
- Consumes: `docs/交接记录.md`、`docs/design/视觉设计交接手册.md`、`docs/规划.md`
- Produces: 一个可重复运行的文档状态与技能说明契约

- [x] **Step 1: 写入预期失败的契约测试**

测试必须断言：

```powershell
$handoff = Get-Content -Raw -Encoding UTF8 'docs/交接记录.md'
$manual = Get-Content -Raw -Encoding UTF8 'docs/design/视觉设计交接手册.md'
$planning = Get-Content -Raw -Encoding UTF8 'docs/规划.md'

foreach ($required in @(
  '54 条最终路由', '7 个已验收', '47 个待审核候选',
  'product-design:index', 'product-design:audit', 'imagegen',
  'superpowers:test-driven-development',
  'superpowers:systematic-debugging',
  'superpowers:verification-before-completion',
  'docs/design/视觉证据索引.md'
)) {
  if ($handoff -notmatch [regex]::Escape($required)) {
    throw "handoff missing: $required"
  }
}

foreach ($stale in @(
  '六个已验收',
  '结果态和无结果态的同版重新截图尚未完成',
  '结果态/无结果态的同版截图和用户审美确认尚未完成',
  '下一项按 F、R、N、M 推进'
)) {
  if (($handoff + $manual) -match [regex]::Escape($stale)) {
    throw "stale handoff text remains: $stale"
  }
}

$approved = ([regex]::Matches($planning, '- \[x\]')).Count
$candidate = ([regex]::Matches($planning, '- \[~\]')).Count
if ($approved -ne 7 -or $candidate -ne 47) {
  throw "planning counts changed: approved=$approved candidate=$candidate"
}
```

- [x] **Step 2: 运行测试并确认 RED**

Run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tests/handoff-documentation-contract.ps1
```

Expected: FAIL，至少报告当前交接缺少 `docs/design/视觉证据索引.md` 或仍包含陈旧 G06 表述。

### Task 2: 精简快速入口并建立证据索引

**Files:**
- Modify: `docs/交接记录.md`
- Modify: `docs/design/视觉设计交接手册.md`
- Create: `docs/design/视觉证据索引.md`
- Modify: `.superpowers/sdd/task-1-report.md`

**Interfaces:**
- Consumes: `docs/规划.md` 的 7/47 审核状态、现有 `docs/design/screens/runtime/` 证据目录
- Produces: 快速入口、详细恢复手册、低噪声证据归档和早期报告边界说明

- [x] **Step 1: 重写快速交接入口**

`docs/交接记录.md` 只保留以下五节：

```markdown
# 家谱 APP 交接记录

## 1. 当前准确停点
54 条最终路由；7 个已验收；47 个待审核候选；下一步逐页审核，不对接接口。

## 2. 新 GPT 启动顺序
必读文件、`git status --short`、中文复述停点、禁止修改冻结页。

## 3. 必须调用的能力
Product Design、ImageGen、TDD、系统化排错、完成前验证的触发条件。

## 4. 视觉审核降噪规则
每页一张代表图；复杂状态一张联系表；历史对比按需展开。

## 5. 禁止事项与验证
Git、多代理、worktree、接口对接禁令，以及测试、截图和 `git diff --check`。
```

- [x] **Step 2: 修正详细手册中的陈旧停点**

将 `docs/design/视觉设计交接手册.md` 中的数量统一为 7/47；删除 G06 三态截图未完成和“继续推进 F/R/N/M”的旧描述；保留 G06 未获用户视觉验收、H5 不能替代 Android 真机复核两条边界。

- [x] **Step 3: 新建视觉证据索引**

`docs/design/视觉证据索引.md` 按以下层级组织，所有条目只链接现有文件或目录：

```markdown
# 视觉证据索引

## 默认审核入口
- 全页面候选联系表目录
- 根页面联系表
- G、T 模块联系表

## 已验收基准
- A01、A02、A04、A05、A06、G01、G03 的代表证据

## 候选设计记录
- G、T、F/R/N/M 设计记录

## 历史审计证据
- before/after、多尺寸和废稿目录；仅在回归或争议时展开
```

- [x] **Step 4: 标注早期专项报告的职责边界**

在 `.superpowers/sdd/task-1-report.md` 标题下增加：

```markdown
> 历史说明：本文件仅记录早期 A02 Task 1 的 RED 验证，不是当前项目总交接入口。当前停点以 `docs/交接记录.md` 和 `docs/规划.md` 为准。
```

- [x] **Step 5: 运行契约并确认 GREEN**

Run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tests/handoff-documentation-contract.ps1
```

Expected: `HANDOFF-DOCUMENTATION-CONTRACT PASS`

### Task 3: 收口验证

**Files:**
- Verify only: `docs/交接记录.md`
- Verify only: `docs/design/视觉设计交接手册.md`
- Verify only: `docs/design/视觉证据索引.md`
- Verify only: `.superpowers/sdd/task-1-report.md`
- Verify only: `tests/handoff-documentation-contract.ps1`

**Interfaces:**
- Consumes: Task 1 与 Task 2 的文档和契约
- Produces: 可交接的验证证据

- [x] **Step 1: 检查陈旧表述和技能清单**

Run:

```powershell
rg -n "六个已验收|结果态和无结果态.*未完成|下一项按 F、R、N、M 推进" docs/交接记录.md docs/design/视觉设计交接手册.md
rg -n "product-design:index|product-design:audit|imagegen|test-driven-development|systematic-debugging|verification-before-completion" docs/交接记录.md
```

Expected: 第一条无匹配；第二条六类能力全部有匹配。

- [x] **Step 2: 确认规划计数未改变**

Run:

```powershell
$text = Get-Content -Raw -Encoding UTF8 'docs/规划.md'
"approved=$(([regex]::Matches($text, '- \[x\]')).Count)"
"candidate=$(([regex]::Matches($text, '- \[~\]')).Count)"
```

Expected: `approved=7`、`candidate=47`。

- [x] **Step 3: 确认没有删除 PNG**

Run:

```powershell
git diff --name-status -- '*.png'
```

Expected: 不出现以 `D` 开头的 PNG 记录。

- [x] **Step 4: 最终格式检查**

Run:

```powershell
git diff --check
```

Expected: exit code 0。允许 Git 输出 LF/CRLF 提示，但不允许 whitespace error。