swain-test 是 swain-sync 提交前和 swain-release 发布前调用的自动化两阶段测试门禁，智能体也可在声明完成前直接调用以验证工作。
用途与门禁流程：第 1 阶段运行脚本驱动的确定性集成测试；第 2 阶段由智能体执行冒烟测试，验证可观察行为是否满足规格验收标准、变更的技能和项目声明的冒烟项。
输入：可选的 --artifacts SPEC-NNN[,SPEC-NNN...]，为智能体认为与当前工作相关的制品 ID 逗号分隔列表，门禁将其解析为文件路径以驱动第 2 阶段的规格派生验证。若不确定适用哪些制品，可传入近期提交、当前聚焦通道及工作中认领工单上的 spec 标签中的 ID。
第 1 阶段——集成测试（脚本驱动）： REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" bash "$REPO_ROOT/.agents/bin/swain-test.sh" --artifacts "$ARTIFACT_IDS"
读取退出码：exit 1 表示集成测试失败，需向操作者报告失败输出，修复并重新暂存后从第 1 阶段重新调用门禁，不得进入第 2 阶段；exit 0 表示通过或被跳过，继续读取 stdout 进入第 2 阶段。stdout 会输出以下小节：## INTEGRATION 始终存在，显示命令、状态、耗时及失败时的输出尾部；## ARTIFACTS 在传入 --artifacts 且 ID 解析成功时出现，列出规格路径；## SKILLS 在分支中 skills/、.agents/skills/ 或 .claude/skills/ 下文件变化时出现，列出变更的技能文件；## SMOKE 在 .agents/testing.json 声明冒烟项时出现；## FALLBACK 仅当上述上下文小节均未出现时存在。
第 2 阶段——冒烟测试（智能体执行），按序执行已输出的小节，跳过未输出的小节： 步骤 1 规格派生验证（## ARTIFACTS）：对每条规格路径，读取规格文件，定位验收标准部分，逐条执行相关组件并观察结果，为每条标准写一行简短证据（做了什么、观察到什么、通过或失败）。若某标准无法执行（如外部依赖不可用），明确记录，不得静默跳过。 步骤 2 行为验证（## SKILLS）：当显示 detected: true 时，对每个变更技能文件，派发子智能体并给出应触发该技能的代表性提示词，观察技能是否激活并产生预期输出，记录所用提示词、是否确认激活、输出简短摘要。推荐使用 haiku 模型以控制成本，但不强制。目标不是穷尽覆盖，每个变更技能一个代表性提示词即可捕捉结构性回归（如 frontmatter 损坏、缺少必需小节、文件路径错误）。 步骤 3 常规冒烟测试（## SMOKE）：.agents/testing.json 中每个冒烟条目都是声明式指令，作为智能体任务执行并记录结果。 步骤 4 回退（## FALLBACK）：若 ## ARTIFACTS、## SKILLS 和 ## SMOKE 均未出现，则遵循回退指令：描述工作区中的变更，启动受影响组件（运行脚本、启动服务器、调用函数），执行正常路径，报告观察结果。
失败处理：任何第 2 阶段失败，均需修复、重新暂存并从第 1 阶段重新调用完整门禁；绝不在中途恢复第 2 阶段，因为第 1 阶段重跑可确认修复未破坏集成测试。两次完整门禁尝试均失败后，不要进行第三次修复，应升级给操作者并提交结构化报告：每次观察到的失败、每次尝试的修复、每次尝试后的可观察状态；双次规则用于防止无收敛、耗 token 的失控修复循环。操作者可说明理由绕过门禁，需在证据摘要中原样记录 operator override: <reason>，并在提交时写入提交信息。
证据摘要：门禁通过（或被绕过）后，为下游消费者（SPEC-226 证据记录、回顾、提交信息）生成结构化证据摘要，包含第 1 阶段状态（PASS / FAIL / SKIP）与命令；第 2 阶段每步执行情况（由哪个小节驱动、做了什么、观察到什么、通过或失败）；任何绕过及其理由。
示例流程：智能体调用 swain-test.sh --artifacts SPEC-220；脚本退出 0，输出 ## INTEGRATION（PASS）、## ARTIFACTS（SPEC-220 路径）、## SKILLS（detected: true）；智能体读取 SPEC-220 并逐条执行验收标准记录证据；派发 haiku 子智能体用应触发变更技能的提示词并确认激活；未输出 ## FALLBACK 故跳过；最后写入证据摘要。
限制：资料未提供该工具的具体依赖版本、安装方式、支持平台及收费信息。