From 13c7f709b25a172c7ab493c5d6a76f80e209b5c3 Mon Sep 17 00:00:00 2001
From: tukuaiai <tukuaiai@users.noreply.github.com>
Date: Tue, 19 May 2026 14:32:46 +0800
Subject: [PATCH] docs: skills - document auto-tmux report review

---
 skills/auto-tmux/AGENTS.md                    |  1 +
 skills/auto-tmux/SKILL.md                     |  1 +
 skills/auto-tmux/references/AGENTS.md         |  1 +
 skills/auto-tmux/references/README.md         |  1 +
 skills/auto-tmux/references/index.md          |  1 +
 .../auto-tmux/references/iteration-roadmap.md |  5 ++-
 .../references/report-pack-review.md          | 41 +++++++++++++++++++
 .../auto-tmux/scripts/validate-auto-tmux.sh   |  3 ++
 8 files changed, 52 insertions(+), 2 deletions(-)
 create mode 100644 skills/auto-tmux/references/report-pack-review.md

diff --git a/skills/auto-tmux/AGENTS.md b/skills/auto-tmux/AGENTS.md
index 929c94d..289ea56 100644
--- a/skills/auto-tmux/AGENTS.md
+++ b/skills/auto-tmux/AGENTS.md
@@ -47,6 +47,7 @@ skills/auto-tmux/
     ├── safety-policy.md
     ├── session-safety.md
     ├── jsonl-schema.md
+    ├── report-pack-review.md
     ├── swarm-state.md
     ├── prompt-templates.md
     ├── ai-swarm-collaboration.md
diff --git a/skills/auto-tmux/SKILL.md b/skills/auto-tmux/SKILL.md
index e0a48aa..9af9600 100644
--- a/skills/auto-tmux/SKILL.md
+++ b/skills/auto-tmux/SKILL.md
@@ -285,6 +285,7 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 - `references/safety-policy.md`: 发送、广播、清理、归档和敏感信息处理的安全策略
 - `references/session-safety.md`: 本地 session、远程 SSH 和多 Agent 协作的分层安全边界
 - `references/jsonl-schema.md`: JSONL/manifest 机器可读输出字段约定
+- `references/report-pack-review.md`: report pack reviewer 最短验收路径
 - `references/swarm-state.md`: 蜂群状态、任务、锁和报告协议
 - `references/prompt-templates.md`: commander/worker/reviewer 提示词模板和下发方式
 - `references/ai-swarm-collaboration.md`: tmux 蜂群协作历史文档、架构模式、协议、案例和风险限制
diff --git a/skills/auto-tmux/references/AGENTS.md b/skills/auto-tmux/references/AGENTS.md
index bab71ed..53e9264 100644
--- a/skills/auto-tmux/references/AGENTS.md
+++ b/skills/auto-tmux/references/AGENTS.md
@@ -10,4 +10,5 @@
 - 脚本类说明优先引用 `skills/auto-tmux/scripts/auto-tmux.sh`，再给原生命令兜底。
 - SSH/远程 session 规则写入 `session-safety.md`；远程默认只读，不把只读采集扩展成控制入口。
 - 机器可读输出字段约定写入 `jsonl-schema.md`；新增 JSONL/manifest 输出必须同步维护。
+- report pack 审查路径写入 `report-pack-review.md`；新增报告文件时同步更新阅读顺序和通过标准。
 - 不确定的 tmux 行为必须给出验证命令，不编造。
diff --git a/skills/auto-tmux/references/README.md b/skills/auto-tmux/references/README.md
index bc9f2ae..97d84e0 100644
--- a/skills/auto-tmux/references/README.md
+++ b/skills/auto-tmux/references/README.md
@@ -11,6 +11,7 @@
 | [safety-policy.md](./safety-policy.md) | 发送、广播、清理、归档和敏感信息处理的安全策略 |
 | [session-safety.md](./session-safety.md) | 本地 session、远程 SSH 和多 Agent 协作的分层安全边界 |
 | [jsonl-schema.md](./jsonl-schema.md) | JSONL/manifest 机器可读输出字段约定 |
+| [report-pack-review.md](./report-pack-review.md) | report pack reviewer 最短验收路径 |
 | [swarm-state.md](./swarm-state.md) | 蜂群状态、任务、锁和报告协议 |
 | [prompt-templates.md](./prompt-templates.md) | commander/worker/reviewer 提示词模板和下发方式 |
 | [ai-swarm-collaboration.md](./ai-swarm-collaboration.md) | tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制 |
diff --git a/skills/auto-tmux/references/index.md b/skills/auto-tmux/references/index.md
index 15ce9ee..1e0b1df 100644
--- a/skills/auto-tmux/references/index.md
+++ b/skills/auto-tmux/references/index.md
@@ -8,6 +8,7 @@
 - `safety-policy.md`：发送、广播、清理、归档和敏感信息处理的安全策略
 - `session-safety.md`：本地 session、远程 SSH 和多 Agent 协作的分层安全边界
 - `jsonl-schema.md`：JSONL/manifest 机器可读输出字段约定
+- `report-pack-review.md`：report pack reviewer 最短验收路径
 - `swarm-state.md`：蜂群状态、任务、锁和报告协议
 - `prompt-templates.md`：commander/worker/reviewer 提示词模板和下发方式
 - `ai-swarm-collaboration.md`：tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制
diff --git a/skills/auto-tmux/references/iteration-roadmap.md b/skills/auto-tmux/references/iteration-roadmap.md
index c24c86c..8ae8ac3 100644
--- a/skills/auto-tmux/references/iteration-roadmap.md
+++ b/skills/auto-tmux/references/iteration-roadmap.md
@@ -48,13 +48,14 @@
 | 40 | `2824c06` | JSONL 格式治理 | `jsonl-schema.md` |
 | 41 | `a74be2c` | 交付包审计清单 | `review-checklist.sh` |
 | 42 | `01b4a6f` | 审计清单结果门禁 | `review-checklist.sh --strict` |
-| 43 | `本轮` | report pack 自检命令 | `verify-report-pack.sh` |
+| 43 | `82486a7` | report pack 自检命令 | `verify-report-pack.sh` |
+| 44 | `本轮` | report pack 自检文档 | `report-pack-review.md` |
 
 ## 后续候选方向
 
 | 优先级 | 方向 | 说明 |
 |:---|:---|:---|
-| P3 | report pack 自检文档 | 为 reviewer 写最短验收路径 |
+| P3 | 文档摘要索引 | 为 auto-tmux references 生成角色化阅读路线 |
 
 ## 每轮验收清单
 
diff --git a/skills/auto-tmux/references/report-pack-review.md b/skills/auto-tmux/references/report-pack-review.md
new file mode 100644
index 0000000..e9595e7
--- /dev/null
+++ b/skills/auto-tmux/references/report-pack-review.md
@@ -0,0 +1,41 @@
+# auto-tmux Report Pack Review
+
+本文件给 reviewer 一条最短验收路径：先跑统一门禁，再看结论文件，最后只在必要时追溯附件。
+
+## 最短验收命令
+
+```bash
+skills/auto-tmux/scripts/verify-report-pack.sh --pack /tmp/ai-swarm-report-pack
+```
+
+该命令会检查：
+
+- `review-checklist.sh --strict`：报告包必需文件是否齐全。
+- `manifest.json`：根级 manifest 类型是否正确。
+- `results.jsonl`：结果记录是否具备 `type`、`id`、`status` 字段。
+
+## 推荐阅读顺序
+
+1. `index.md`：确认报告包创建时间、状态目录和文件清单。
+2. `review-checklist.md`：按固定审计项判断能否交接。
+3. `results.md`：查看 DONE/FAIL/BLOCKED 结果。
+4. `blockers.md`：确认阻塞项是否需要人工处理。
+5. `board.md`：查看全量任务状态。
+6. `timeline.md`：追溯最近状态变化。
+7. `attachments.md`：仅在需要外部证据时查看。
+
+## 通过标准
+
+- 必需文件齐全，`verify-report-pack.sh` 通过。
+- `results.md` 能说明 worker 交付结果。
+- `blockers.md` 没有阻止交接的未处理 FAIL/BLOCKED。
+- `manifest.json` 与 `results.jsonl` 可被机器门禁读取。
+- 附件目录没有密钥、Token、密码或无关私密输出。
+
+## 不通过标准
+
+- 缺失 `manifest.json`、`results.jsonl`、`review-checklist.md` 或 `export/manifest.json`。
+- `results.md` 只有状态，没有可判断的 result。
+- `blockers.md` 存在未解释的 FAIL/BLOCKED。
+- 附件中包含未脱敏的敏感信息。
+- 结论必须依赖报告包外的口头说明才能成立。
diff --git a/skills/auto-tmux/scripts/validate-auto-tmux.sh b/skills/auto-tmux/scripts/validate-auto-tmux.sh
index b0ce42b..5d80256 100755
--- a/skills/auto-tmux/scripts/validate-auto-tmux.sh
+++ b/skills/auto-tmux/scripts/validate-auto-tmux.sh
@@ -233,12 +233,15 @@ require_contains "$skill_dir/references/index.md" "automation.md"
 require_contains "$skill_dir/references/index.md" "safety-policy.md"
 require_contains "$skill_dir/references/index.md" "session-safety.md"
 require_contains "$skill_dir/references/index.md" "jsonl-schema.md"
+require_contains "$skill_dir/references/index.md" "report-pack-review.md"
 require_contains "$skill_dir/references/README.md" "swarm-state.md"
 require_contains "$skill_dir/references/README.md" "safety-policy.md"
 require_contains "$skill_dir/references/README.md" "session-safety.md"
 require_contains "$skill_dir/references/README.md" "jsonl-schema.md"
+require_contains "$skill_dir/references/README.md" "report-pack-review.md"
 require_contains "$skill_dir/references/jsonl-schema.md" "swarm-result"
 require_contains "$skill_dir/references/jsonl-schema.md" "remote-readonly"
+require_contains "$skill_dir/references/report-pack-review.md" "verify-report-pack.sh"
 require_contains "$skill_dir/references/session-safety.md" "remote-readonly.sh"
 require_contains "$skill_dir/references/session-safety.md" "远程默认只读"
 require_contains "$skill_dir/references/session-safety.md" "metadata.jsonl"