# AC 交互遗漏闭环（docs-closed 前）设计

> 状态：已确认（用户 2026-07-16）  
> 方案：方案 1 — 增强 `ac-review` + 新 `docs-closed` 门禁项 + `--auto-remediate` 拟补闭环  
> 仓库：`sdd-flow-kit`

## 1. 问题

现有 `gate docs-closed` 即使 `prd-ac-coverage=100%`、五层标签/交互矩阵通过，仍可能出现：

- 05 用笼统 AC 包住多模块（如「交互齐全」），**过弱**无法 1:1 验收 PRD 交互
- **明确遗漏**（筛选面板、导入历史、状态历史 hover、详情子模块 toast 等）未被独立 AC 覆盖
- Intentional 偏差表「确认来源」质量差（粘贴验收标准正文，而非 `03 Qx`）

导致 `GATE PASS` / `phase docs-done` / propose 过早推进。

## 2. 目标

在 **`gate docs-closed` PASS 与 `phase advance --to docs-done` 之前**，强制：

1. 对比 05 vs PRD 交互/功能，检出 **明确遗漏** 与 **过弱**（P0/P1）
2. 检查 Intentional 偏差表质量
3. 失败时自动拟补 AC（`--auto-remediate`），再检，直到清零或达最大重试
4. 未清零不得进入 propose

## 3. 非目标

- 不替代 `prd-ac-coverage` / `ac-layer-coverage` / `interaction-state-matrix`
- 不在 `impl-allowed` 再加第二道同类门禁（本期仅 docs-closed 前）
- 不保证纯机械 100% 语义完备；逃逸项可进争议闭环登记册

## 4. 流水线位置

```text
写 05 → ac-review（提示词增强）
         ↓
gate docs-closed
  ├─ …现有检查保持…
  ├─ ★ ac-interaction-gap
  └─ ★ intentional-table-quality
         ↓ 失败 + --auto-remediate
AI 拟补 05 → 重跑 gate（≤ N 轮）
         ↓ 全 PASS
phase advance --to docs-done → propose
```

## 5. 新 gate 检查

### 5.1 `ac-interaction-gap`

| 项 | 规则 |
|----|------|
| 输入 | `05-验收清单.md`、`source/PRD.md`、`.prd-review-atoms.json`（可选）、`.page-state-model.json`（可选）、`03-待确认问题清单.md`（范围边界） |
| 输出 | `.ac-interaction-gap-report.json`；可选渲染 `14-AC交互遗漏清单.md` |
| P0 遗漏/过弱 | **FAIL**（阻断 docs-closed）并纳入 auto-remediate 拟补 |
| P1 遗漏/过弱 | **FAIL**（同样阻断）并纳入 auto-remediate 拟补（与 P0 同等闭环，直到清零） |
| 跳过 | `OPSX_SKIP_AC_INTERACTION_GAP=1`（须说明原因，与其它 OPSX_SKIP_* 一致） |

**过弱启发式（机械）**（示例，可扩展）：

- 验收标准含「交互齐全」「功能可用」「符合预期」「页面正常」且缺少逐步原语关键词（搜索/拖拽/toast 全文/必填提示等）
- 单条 AC 同时笼统覆盖「导入+详情+筛选」等多模块而无分步断言

**明确遗漏能力清单（可配置常量，首批）**：

当 PRD/原子命中某能力关键词，但 05 无对应可测 AC（关键词/标签匹配）时记遗漏：

| capabilityId | 触发（PRD 侧） | 05 须覆盖信号（示例） |
|--------------|----------------|------------------------|
| `filter-panel` | 筛选条件/筛选按钮 | 筛选项名或「筛选面板」+ 带参查询 |
| `import-validation` | 导入 + 文件大小/单文件/表头 | 200MB / 单文件 / 缺列 / 固定 toast |
| `import-history` | 导入历史 | 导入历史列表或详情 |
| `custom-column-steps` | 列配置/自定义列 | 搜索+全选/半选+拖拽+恢复默认+清空（逐步，非仅「齐全」） |
| `status-history-hover` | 状态变更历史/圆点 | hover 文案格式或历史记录断言 |
| `export-fail-toast` | 导出 | 失败 toast 固定文案 |
| `detail-summary-remark` | 摘要备注 | 暂无备注 / 字数 / 省略 |
| `detail-bd-estimate` | BD预估 | BD预估已保存 或蓝提示条 |
| `detail-credit-note` | 红票及其他 | 添加/编辑互斥或标签 |
| `billing-search` | 账期规则 + 搜索 | 合同编号或名称占位 |

范围边界：若 `03` 已确认某能力 Out of Scope（如移动营销仅去全选），对应遗漏不记 FAIL。

### 5.2 `intentional-table-quality`

| 项 | 规则 |
|----|------|
| 解析 | `05` 中「Intentional 偏差登记」表 |
| 通过 | 无行，或每行「确认来源」匹配 `03`、`Q\d+`、`用户确认`、`用户原话` 之一 |
| 失败 | 确认来源为空；或确认来源与「验收标准」高度雷同（如以 `[业务]`/`[UI]`/`壳层=` 开头）；或整段粘贴验收标准 |
| 跳过 | `OPSX_SKIP_INTENTIONAL_TABLE_QUALITY=1` |

## 6. 报告 schema

`.ac-interaction-gap-report.json`：

```json
{
  "reviewedAt": "<ISO8601>",
  "runId": "<runId>",
  "missing": [
    {
      "capabilityId": "filter-panel",
      "severity": "P0",
      "description": "PRD 含筛选条件全集，05 无独立可测 AC",
      "suggestedAcDraft": { "criteriaPrefix": "[交互]", "summary": "…" }
    }
  ],
  "weak": [
    {
      "acId": "AC-16",
      "severity": "P0",
      "reason": "验收标准含「交互齐全」且缺少拖拽/恢复默认逐步断言",
      "suggestedStrengthen": "…"
    }
  ],
  "intentionalIssues": [
    {
      "acId": "AC-09",
      "reason": "确认来源列疑似粘贴验收标准，未指向 03 Qx"
    }
  ],
  "status": "fail" | "pass" | "warn"
}
```

## 7. 自动拟补（`gateAutoRemediate`）

将下列 name 加入 `REMEDIABLE_CHECKS`：

- `ac-interaction-gap`
- `intentional-table-quality`

修复提示词要求：

1. 读取 `.ac-interaction-gap-report.json` + `source/PRD.md` + `03` + 当前 `05`
2. **只追加/强化** AC：不删已有 ID；新 ID 自最大号递增；保持 9 列格式
3. 修复 Intentional「确认来源」为 `03 Qx` / 用户原话摘要
4. 重跑 `docs-closed`；输出 `GATE_REMEDIATE=COMPLETE` 当对应 check 通过

最大轮次：复用现有 `MAX_GATE_FIX_RETRIES`。

## 8. `ac-review` 提示词增强

`src/templates/prompts/ac-review-prompt.md` 增加章节：

- 交互遗漏对照（能力清单 + PRD）
- 过弱 AC 识别与拆分
- Intentional 确认来源质量

并要求审查后写入/刷新 `.ac-interaction-gap-report.json`（与 gate 同 schema）。

## 9. 文档与 NEXT 同步

- `docs/QUALITY_TRIAD.md`：增加「0.5 AC 交互遗漏闭环」或并入第 1 节 docs-closed 列表
- `02-sdd-loop-prompt.md` / `NEXT-with-prd-enrich.template.md`：明确 docs-closed 含上述两项
- CLI help：`docs-closed` 说明中列出新 check；跳过环境变量文档化

## 10. 测试计划

| 类型 | 内容 |
|------|------|
| unit | 夹具 05：缺筛选 → missing；「交互齐全」→ weak；坏 Intentional → intentionalIssues；好 05 → pass |
| unit | P0/P1 遗漏均阻断 docs-closed；auto-remediate 拟补两者 |
| 集成（可选） | mock outputRoot 跑 `runGate({ expect: "docs-closed" })` 见新 check 名 |

## 11. 文件落位（实现时）

| 路径 | 职责 |
|------|------|
| `src/core/acInteractionGapGate.ts` | 检测 + 写报告 + GateCheck[] |
| `src/core/intentionalTableQuality.ts` | Intentional 表质量（可并入上一文件若过短） |
| `src/tests/acInteractionGapGate.test.ts` | 单测 |
| `src/steps/runGate.ts` | docs-closed 分支挂载 |
| `src/core/gateAutoRemediate.ts` | REMEDIABLE_CHECKS 条目 |
| `src/templates/prompts/ac-review-prompt.md` | 审查维度 |
| `docs/QUALITY_TRIAD.md` 等 | 流程说明 |

## 12. 成功标准

1. 有 P0 交互遗漏/过弱时，`gate docs-closed` exit ≠ 0，输出含 `ac-interaction-gap`
2. Intentional 确认来源不合格时 exit ≠ 0，含 `intentional-table-quality`
3. `--auto-remediate` 可将上述 check 纳入修复环（dry-run 可见）
4. 清零后现有 docs-closed 其它检查行为不变
5. ADI 类「原子 100% 覆盖但交互过弱」场景可被新门禁拦住

## 13. Spec 自检

- [x] 无 TBD/占位实现细节阻碍开工
- [x] 与现有 docs-closed / auto-remediate 边界清晰
- [x] 范围：仅 docs-closed 前；P1 默认 WARN
- [x] 与用户确认的方案 1 / 插入点 A 一致