# ACK 回归目录与运行

本文件是回归用例目录、收获时机和运行模式的 SSOT。三角色闭环仍见
`closed-loop.md`；测试环境部署见 `delivery.md` 与 deployer skill。

回归不是新 skill，也不写入 `knowledge.yaml`。知识是护栏；回归是可观测的黑盒
用例清单。

## 1. 目录

项目状态是 `docs/ack/regression.yaml`。任务板用
`project.regressionFile: docs/ack/regression.yaml` 声明，运行证据写在
`tasks.yaml.regressionRuns`。新项目初始化会生成空目录；旧项目没有该文件时，
「运行回归」先停下来，用户授权后再从模板补齐。

只有 Coordinator 写 `regression.yaml`。Test 在复测报告里提名
`regressionCandidates`；用户确认后 Coordinator 落盘，并把 case id 写入任务的
`regressionRefs`。不要把用例散落到第二份文档，也不要让 Test 直接改
`docs/ack/`。

`tests/browser/**` 仍可由 Test 维护可执行脚本。用例可用可选 `automationRef`
指向那些脚本；没有脚本时 Test worker 按目录里的步骤和验收信号执行。

## 2. 用例

每条用例是给独立 Test worker 的说明书，复用
`optimization-method.md` §1 的可观测信号。ACK 不提供 YAML-DSL 解释器，也不强制
Playwright。

读取时用 `scripts/select_regression.py`，不要把完整目录注入上下文：

```bash
python3 <ack-skill-dir>/scripts/select_regression.py docs/ack/regression.yaml
python3 <ack-skill-dir>/scripts/select_regression.py docs/ack/regression.yaml \
  --suite full
python3 <ack-skill-dir>/scripts/select_regression.py docs/ack/regression.yaml \
  --case-id REG-login-001
```

默认 `--suite smoke` 只返回 `status: active` 且 `suite: smoke` 的用例。
`--suite full` 返回全部 active 用例。写回前仍运行
`scripts/validate_regression.py`。

`surface: browser` 的用例必须走真实页面交互，不能改成只打 API。
`surface: api` 以 HTTP 状态和字段为证据。

## 3. 收获

任务进入 `verified` 且改了用户可见行为或 API 后，闭环结束前 Coordinator 必须给出
四选一，不能跳过：

- 新增
- 更新已有用例
- 退役（功能已删除）
- 无回归（纯内部重构、leftover、无用户可见变化）

草案来自任务验收信号和 Test 的独立证据，按 `path + expected` 去重。用户确认后
才写入目录。P0 / 主路径默认 `suite: smoke`，其余 `full`。

## 4. 运行

用户说「回归」「跑回归测试」时执行本模式，不要求当前有 `verified` 任务。

1. 目录存在且有选中的 active 用例；否则停止。
2. 先按「运行测试环境」调用 deployer，拿到 Base URL。
3. Coordinator 派独立 Test worker，只带选中用例、Base URL 和 surface。
4. Test 逐条对照 `expected` 回报证据。Coordinator 终检后写入 `regressionRuns`。
5. 失败只报告，不自动派 Developer，不占任务三轮预算。用户明确要求修复时，按
   「修 bug」为每条失败开一个任务。

环境失败（没有浏览器、打不开部署地址、deployer 失败）记环境事件，不记产品失败。

默认跑 smoke。用户点名 full 或具体 case id 时按点名范围执行。