sr-design-gate

Files (5)

• SKILL.md
• openai.yaml · agents/
• crypto-gate-checklist.md · references/
• gate-checklist.md · references/
• gate-result-template.md · references/

SKILL.md (first lines)

## 前置操作：工作流编排检查

若本 skill 是由 aaw-workflow 的工作单调用的，跳过本节，直接执行正文。

否则，在执行正文之前，先向用户发起一次二选一确认：

> 是否回到 aaw-workflow 工作流中执行？
> - 是，回到工作流（推荐）——进度会被跟踪和上报
> - 否，单独执行本 skill——本次执行将不纳入流程跟踪

- 用户选“是” → 加载 `aaw-workflow` skill，按其流程执行（其入口意图判定会引导继续已有工作流或新建），不再单独执行本 skill 正文。
- 用户选“否” → 继续执行本 skill 正文，之后不再提及工作流。

本节最多询问一次，不得重复打扰。

若工作单输出已存在，仍按当前要求完整执行：先读取并评估已有成果，复用仍有效的信息和已确认答案，可局部修改或整体重写，并写回原路径。

# SR 设计门禁

## 职责边界

- 直接在当前主会话执行，不要委托给子 Agent。
- 读取并审查正式 `SR-design.md`、`.sdd/software_architecture.md`（可选输入，缺失时按「架构基线缺失降级」处理）和原始需求 `original-requirement.md`，但不得修改它们。
- 完整执行门禁检查，并按“门禁报告”规则生成或更新工作单 `output` 指定的 `SR-design-gate.md`。
- 不替用户裁决范围、架构、契约或验收阈值冲突；AR 边界由下游 `ar-split` 决定；需要外部决策时结论为 `阻塞`。
- 不自动 rollback。整改后在同一个 Gate step 上重新执行。

## 输入与路径解析

- 从当前工作单读取 `input`、`output`、`data_file.path` 和 `commands.done`，不得自行猜测工作流路径。
- SR 设计模板固定从相邻 Skill 的 `<skill-dir>/../sr-design/reference/design-template.md` 读取。
- 门禁规则从 `<skill-dir>/references/gate-checklist.md` 读取；密码学适用性判定为涉及时，追加执行 `<skill-dir>/references/crypto-gate-checklist.md`；门禁报告模板固定从 `<skill-dir>/references/gate-result-template.md` 读取。
- 任一 required input、SR 设计模板、门禁规则清单或报告模板缺失、不可读时，结论必须为 `阻塞`。不得改用记忆中的旧模板或仓库相对路径继续检查。
- `.sdd/software_architecture.md` 为可选输入，缺失或不可读不构成 `阻塞`，按下节「架构基线缺失降级」执行。

## 架构基线缺失降级

`.sdd/software_architecture.md` 缺失或不可读时，按以下口径执行，不得因此判 `阻塞`，也不得默认放行：

- 「架构一致性」维度改判为 `降级检查（无架构基线）`：仅依据 `SR-design.md` 自身的架构章节做内部一致性检查（分层图、模块职责表与模块交互是否自洽），不执行与架构文档的交叉核对。
- 该维度不因缺少交叉核对而记未达标；但内部自洽性问题仍按原分级口径记录。
- 固定记一条 P2 待补项：`架构基线缺失，进入 AR 拆分前需补 repo-init 生成 .sdd/software_architecture.md`。该条不阻断本轮结论。
- 在门禁报告中写明降级依据（架构文档路径与缺失事实），以及 `SR-design.md` 中「软件架构」章节是否已按情况 B 说明基线缺失。
- 下游 `ar-init`、`task-dev` 等步骤要求该文件存在，报告需提示该待补项将在后续步骤成为硬约束。

## 强制检查流程

开始时使用 todo-list 工具建立检查计划，并按顺序完成：

1. 解析工作单路径，读取架构、SR 设计、当前模板、门禁规则和已有门禁报告。架构文档缺失时记录该事实并转入「架构基线缺失降级」口径，继续后续步骤。
2. 如有历史门禁报告，先恢复上一轮问题编号、状态和关闭证据。
3. 执行密码学适用性判定：对照 `crypto-gate-checklist.md` 的算法类别口径检索 SR 设计正文，形成涉及/不涉及结论并记录检索依据；判定为涉及时，后续步骤追加执行该清单。
4. 以当前模板作为章节、占位符和表格结构的唯一依据，逐章节检查完整性、残留占位符、空表格以及未闭合的 Markdown/Mermaid fence。
5. 在本轮分析上下文中建立临时关键事实台账，抽取模块、接口、数据、状态、配置和指标；判定涉及密码算法时同步标记传递敏感参数的接口。该台账不是独立交付物，只有触发报告规则时才随问题和证据写入门禁报告。
6. 执行原始需求反查：读取完整 `original-requirement.md`，抽取明确的功能、约束和可验收行为；
   每项明确需求必须在 `SR-design.md` 的功能、接口、数据、异常、模块设计或验收章节中有可定位的
   实质设计落点，明确可验收行为还必须在 SR 验收标准中有覆盖。背景、动机、示例和参考信息可判为
   非需求，但必须在门禁报告中记录判定依据。明确需求不得标为范围外、延期或不实现。
7. 逐项检查 checklist 定义的全部准入维度；其中外部依赖与对外接口必须按「接口契约完整性判定」逐接口检查并填写门禁报告的接口审计表，不得只确认接口存在；涉及密码算法时按密码学专项清单逐节复核。
8. 逐对象执行全部跨章节一致性链，并反向追踪需求、契约、状态、配置、DFX 与验收；不得抽样。
9. 汇总未达标维度、P0/P1/P2、待确认项和阻断项，按“结论判定”生成一致的结论与 `summary`。
10. 按“门禁报告”生成或更新门禁报告，再按“完成后回调”提交工作流数据。

## 结论判定

内部结论只判定一次，并按以下固定映射提交：

| 中文结论 | `gate_result` | 判定条件 |
|---|---|---|
| 通过 | `pass` | 所有适用维度达标，P0/P1、待确认项和阻断项均为 0，SR 级设计完整并可进入 ar-split |
| 不通过 | `fail` | 存在可通过修改 SR 设计解决的未达标维度、P0/P1 冲突或其他阻断性设计缺陷；包括明确原始需求没有设计落点或被标为范围外、延期或不实现（记 P1），以及涉及密码算法但未完成敏感参数识别 |
| 阻塞 | `blocked` | 缺少必要输入（含原始需求 `original-requirement.md` 缺失或不可读），或必须由用户、上游系统提供事实或作出决策（含无法判断某段原文是否属于本次范围且没有用户确认），当前无法完成判断 |

- 任一适用维度未达标或存在任一 P0/P1 冲突，均不得通过。
- 无法确认差异是否仅属于表达差异时，记录为待确认项，不得降为 P2。
- P2 不阻断通过。
- `pass` 时 `summary.unqualified_dimensions`、`p0_conflicts`、`p1_conflicts`、`pending_questions` 和 `blocking_issues` 必须全部为 0；`p2_findings` 可以大于 0。
- 所有 `summary` 数值必须与本轮报告和最终结论一致。

## 门禁报告

完整检查始终必须执行。每一轮检查都必须生成或更新工作单 `output` 指定的 `SR-design-gate.md`，`report` 恒为实际报告路径，不允许为 `null`：

- 本轮存在任意问题，包括不阻断通过的 P2：使用报告模板创建或更新报告，逐项记录问题和证据。
- 本轮零问题：同样创建或更新报告，至少写入 `summary` 六项计数和原始需求反查结论；逐项列出明确需求及其在 `SR-design.md` 中的设计落点，并列出被判定为背景、动机、示例或参考信息的原文内容及非需求判定依据。该清单归入“需求完整性”，不构成 SR 文档中的独立追溯章节。
- 密码学适用性判定为涉及时，专项复核结果和适用性判定依据必须一并留档。
- 存在历史门禁报告时，即使本轮问题已全部修复，也要更新原报告，逐项关闭历史问题并记录最终结论。
- `fail` 或 `blocked` 时同样必须生成或更新报告，不允许只在会话中输出整改清单。

## 多轮复检

- 保留上一轮问题编号并逐项给出 `已关闭`、`转为非阻断`、`仍阻断` 或 `阻塞` 状态。
- 只有文档位置或用户确认能作为关闭证据。
- 不得删除、重编号或用新的概括描述掩盖历史问题。
- 例外：文档简洁性维度的 P2 零散项按 `gate-checklist.md` 的「发现记录规则」合并为一条聚合项追踪，逐处清单写入非阻断改进项；该维度的结构级发现不适用本例外，仍须逐条编号闭环。
- 复检仍须执行全量检查，不能只检查历史问题。

## 完成后回调

> 若不处于 `aaw-workflow` 编排中，请忽略本节，直接在当前会话返回门禁结论，并按“门禁报告”规则处理报告。

本 Skill 由 `aaw-workflow` 编排调用时，按以下顺序衔接：

1. 先按“门禁报告”规则处理工作单 `output`：生成或更新门禁结果文件。该文件是 required 交付件，缺失时 `done` 会被 CLI 拒绝。
2. 根据中文结论构造完整门禁数据，将 JSON 写入工作单提供的 `data_file.path`，再执行工作单提供的 `commands.done`。
3. 结论为 `通过` 时提交 `gate_result=pass`。执行 `done` 前先向用户输出 `summary` 六项计数、原始需求反查结论和报告路径；这只是告知，不要等待用户答复，也不要因此暂停推进到 `ar-split`。
4. 结论为 `不通过` 时提交 `gate_result=fail`。CLI 的 `reject` 及非零退出是预期结果；停止本轮执行，保持当前 Gate step 未完成，修正 SR 设计后在同一步骤复检。
5. 结论为 `阻塞` 时提交 `gate_result=blocked`。CLI 的 `reject` 及非零退出是预期结果；停止本轮执行，保持当前 Gate step 未完成，补齐必要输入或外部决策后在同一步骤复检。
6. 不要自动执行 `aaw rollback`。只有用户明确要求重走上游节点，或已经生成需要废弃的下游 step 时，才使用 rollback。

零问题通过的 `pass` 数据示例：

```json
{
  "gate_result": "pass",
  "recommendation": "可进入 AR 拆分",
  "report": ".sdd/SR-001/SR-design-gate.md",
  "summary": {
    "unqualified_dimensions": 0,

From pi-ixel/Awesome-Agent-Workflow, MIT.

More from pi-ixel/Awesome-Agent-Workflow