# AC Lifecycle and Delivery Definition

## AC 验收生命周期

```
product-lead 定义 AC（PRD）→ 任务分配时把具体 AC 写进 SendMessage
       ↓
开发者实现 + Unit + SIT（API+DB+external 单边集成）→ 逐条自验 AC → append 到 progress/<role>.md → SendMessage 完成报告
       ↓
product-lead 触发 code-reviewer 审查代码质量 + SIT 证据 audit
       ↓
code-review 通过（approve / approve with changes）后进入 E2E
       ↓
qa-engineer 执行 E2E → 通过后进入 UAT
       ↓
product-lead 对照 AC 最终判定 → 归档 progress/ → 汇报用户
```

**AC 可测试性标准**：每条 AC 必须有触发条件（"当…时"）+ 可观察结果（"显示…"/"返回…"/"跳转至…"）。

## Self-Reporting Pattern（自报告模式）

**核心思想**：teammate 完成任务时，先把过程证据**追加写入 `progress/<role>.md` 文件**（持久化），再 SendMessage 给 product-lead 一份摘要。这样 lead session 关闭、压缩、跨机器恢复后，依然能从文件系统读出"做到哪了 / 跑过什么 / 验过什么"。行业等价物：Anthropic Agent Teams 文档中描述的 idle notification + SendMessage + shared task list 组合（官方未单独命名）。

**三要素**（缺一不可）：
1. **报告格式**：固定 8 段（见下文「完整条目格式」）
2. **写入位置**：`progress/<role>.md`，append 到文件末尾（chronological）
3. **验证标准**：每条记录必须含**实际跑过的命令 + 命令的真实输出**，不允许只写"已通过"

**强制约束**：
- 适用对象：所有执行层 teammate（`backend-dev` / `frontend-dev` / `ai-agent-dev` / `ml-engineer` / `miniapp-dev`）
- 强制时机：每完成一个 task 单（不论是否阻塞），先 append 到 `progress/<role>.md`，再 SendMessage
- Hook 兜底：`SubagentStop` 与 `TeammateIdle` 触发 [`check-progress-file.sh`](../hooks/check-progress-file.sh)；该 role 的 `progress/<role>.md` 不存在或空 → exit 2 阻断退出
- 豁免：当前 team 没有 pending/in_progress task 分给该 role 时（standby 角色）放行
- 其他角色（`product-lead` / `code-reviewer` / `qa-engineer` / `tech-lead` / `uiux-designer` / `content-writer` / `growth-analyst` / `miniapp-code-reviewer` / `miniapp-qa-engineer`）由各自的产物（`docs/{prd,reviews,qa,design,content,growth}/`）兜底，不强制写 `progress/`，写了也不会被 hook 拦

### 完整条目格式（progress/<role>.md 内）

每完成一个 task 单 append 一段，格式如下：

```markdown
## [任务名 / Task ID] - [YYYY-MM-DD HH:MM]
**状态**: 已完成 / 阻塞 / 进行中
**任务类型**: 新功能 / bugfix / 重构 / 文档 / 测试
**Skills used**: superpowers:test-driven-development, superpowers:verification-before-completion, ...
**验证命令**:
  $ <实际跑过的命令 1>
  $ <实际跑过的命令 2>
**验证输出**:
  <命令的真实输出片段，至少能看到关键断言点；不允许写"通过"二字了事>
**SIT 证据**（按 AC 列出，pass 一行简写，fail/blocked 展开）:
  - ✅ AC-1 (integration): 用户注册 — POST /register 写库成功
  - ❌ AC-2 (integration): webhook 签名
    - 测试用例: backend/tests/sit/test_webhook.py::test_signature
    - 执行命令: $ pytest backend/tests/sit/test_webhook.py::test_signature -v
    - 输出:
      AssertionError: signature mismatch (expected HMAC-SHA256, got plain)
    - 偏差: 实现用 SHA1, PRD 要求 HMAC-SHA256
**AC 自验**:
  - [x] AC-1: ✅ [验证说明]
  - [ ] AC-2: ⚠️ [偏差说明]
**涉及文件**:
  - <path/to/file/1>
  - <path/to/file/2>
**下一步**: 等待分配 / 等待 review / 阻塞: <具体阻塞点>
```

**阻塞场景**：状态写 `阻塞`，"下一步"段写明阻塞原因 + 已尝试方案 + 需要什么解锁。**不要在阻塞状态下继续 SendMessage 假装在推进**。

### SendMessage 完成报告（写完 progress/ 之后发）

```
SendMessage({to: "product-lead", message: "完成: [功能名]\n\nProgress 详情: progress/<role>.md (条目: <任务名> - <时间>)\n\nSIT 结论: ✅ 全部 AC integration 层覆盖 / ⚠️ 部分 fail [一行说明] / ❌ blocked [一行说明]\n\nAC 自验摘要:\n- [x] AC-1: ✅\n- [ ] AC-2: ⚠️ [一行说明]\n\n涉及文件: <主要文件>\n下一步: <一行>", summary: "完成: [功能名]"})
```

`progress/<role>.md` 的条目是事实底稿；SendMessage 是给 lead 的摘要，**不能取代**底稿。如有偏差，product-lead 以底稿为准。

### 开发者 Definition of Done

报告完成前必须满足（适用于 frontend-dev / backend-dev / ai-agent-dev / ml-engineer / miniapp-dev）：
- [ ] **TDD red-green-refactor 顺序**（核心纪律，新功能 / bugfix 强制；纯重构 / 文档可跳过）：
  - **red**：先写**失败的** Unit / SIT 测试（commit message 含 `test:` 前缀），跑 `pytest` / `vitest` 看到红
  - **green**：写**最少**实现让测试变绿（commit message 含 `feat:` / `fix:` 前缀，引用前一条 test commit hash）
  - **refactor**：保持绿的前提下整理代码（commit message 含 `refactor:` 前缀）
  - PR commit history **必须能看出 red → green 顺序**（first test commit 早于 first impl commit）
- [ ] Unit 测试已编写并通过（pytest / vitest 全绿 + lint + typecheck 全绿）
- [ ] 已跑 SIT (API+DB+external 单边集成) 并 append 证据到 `progress/<role>.md` SIT 段
- [ ] 每条 AC 已逐一本地验证（不是"看起来像"，是真正跑过）
- [ ] 实现前已调用 `superpowers:test-driven-development`（与上面 red-green-refactor 顺序绑定）
- [ ] 完成前已调用 `superpowers:verification-before-completion`
- [ ] **已 append 一条完整条目到 `progress/<role>.md`**（含验证命令 + 真实输出 + SIT 证据 + AC 自验 + Skills used）
- [ ] SendMessage 完成报告引用了 `progress/<role>.md` 对应条目
- [ ] code-review (含 SIT Audit) 结论达到 `approve` 或 `approve with changes` 后才能进入 E2E
- [ ] UAT 报告提交后，必须由 product-lead 对照 PRD AC 做最终业务签字才算交付完成

各角色差异项见对应 agent 文件的 `## Definition of Done` 章节。

### 归档（UAT 签字后由 product-lead 执行）

UAT 业务签字 → product-lead 把 `progress/*.md` 归档到 `docs/qa/<feature>-process-log.md`（cat 拼接），然后 `git rm progress/*.md` 留 `.gitkeep`。详见 [`product-lead.md` Step 5](../agents/product-lead.md)。
