jiapuapp/docs/superpowers/plans/2026-07-15-handoff-evidence-simplification.md

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

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: 一个可重复运行的文档状态与技能说明契约

• Step 1: 写入预期失败的契约测试

测试必须断言：

$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"
}

• Step 2: 运行测试并确认 RED

Run:

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: 快速入口、详细恢复手册、低噪声证据归档和早期报告边界说明

• Step 1: 重写快速交接入口

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

# 家谱 APP 交接记录

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

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

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

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

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

• Step 2: 修正详细手册中的陈旧停点

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

• Step 3: 新建视觉证据索引

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

# 视觉证据索引

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

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

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

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

• Step 4: 标注早期专项报告的职责边界

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

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

• Step 5: 运行契约并确认 GREEN

Run:

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: 可交接的验证证据

• Step 1: 检查陈旧表述和技能清单

Run:

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: 第一条无匹配；第二条六类能力全部有匹配。

• Step 2: 确认规划计数未改变

Run:

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

Expected: approved=7、candidate=47。

• Step 3: 确认没有删除 PNG

Run:

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

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

• Step 4: 最终格式检查

Run:

git diff --check

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