从 Allium 规格生成测试：把规格义务映射为可执行测试并…

当需要根据 Allium 规格（.allium 文件）生成测试、编写属性测试或状态机测试、并核对测试是否覆盖规格全部义务时使用。

适用场景

解决思路

1. 先确认前置条件：一份 Allium 规格（.allium 文件）、目标代码库、来自 `allium plan <spec>` 的测试义务 JSON、来自 `allium model <spec>` 的领域模型 JSON；若 CLI 工具不可用，则参照 references/test-generation.md 中的测试生成分类法手动推导测试义务。
2. 区分交互模式：交互模式下直接向用户提问并等待回答；非交互模式（作为 `propagate` 子代理运行，例如在 Allium 循环内）下无法联系用户，把需要人工决策的事项（规格过于粗糙、实现桥接有歧义、未覆盖义务）写入最终输出，并继续执行不依赖该决策的工作。
3. Surface 模式（测试 API、UI 契约或集成边界）时，对规格中每个 surface 生成：exposure 测试（验证 `exposes` 中每项对指定 actor 可访问，包括对集合的 `for` 迭代）、provides 测试（验证操作在其 `when` 条件为真时出现、否则隐藏，包括对应规则 `requires` 子句不满足时）、actor 限制测试（验证其他 actor 类型无法访问）、actor 识别测试（验证只有匹配 actor `identified_by` 谓词的实体可交互；对有 `within` 的 actor 验证交互限定在声明上下文内）、context 作用域测试（验证无实体匹配 `context` 谓词时 surface 实例不存在）、契约义务测试（验证 `demands` 被对方满足、`fulfils` 由本 surface 提供，包括所有带类型签名）、guarantee 测试（验证 `@guarantee` 注解在边界上成立）、超时测试（验证引用的时序规则在 surface 上下文内触发）、关联导航测试（验证导航到相关 surface 解析到正确的上下文实体）。
4. Spec 模式（追求整个规格的全面覆盖）时，遍历完整测试义务文档，按分类法覆盖：实体与值类型测试（字段、类型、可选 `?` 空值处理、`when` 子句的状态相关存在性、关系、join 查找、相等性）；枚举测试（命名枚举间可比性、成员测试、内联枚举隔离）；和类型测试（变体字段、类型守卫、穷尽性、通过变体名创建、基类 `.created` 触发器收窄）；派生值与投影测试（计算、过滤、`-> field` 提取、参数化派生值、`now` 易变性、集合操作）；默认实例测试（无条件存在、字段值、默认值间交叉引用）；配置测试（默认值、覆盖、必填参数、表达式形式默认值、限定引用、配置链）；不变式测试（规则后验证、边界情况、蕴含逻辑、实体级不变式）；规则测试（成功/失败/边界情况、条件分支（确保 `if` 守卫读取结果状态）、实体创建、删除、批量更新、规则级 `for` 迭代、`let` 绑定、链式触发器）；状态转换测试（有效/无效转换、终态、`transitions_to` 与 `becomes` 语义）；时序测试（截止边界、重复触发防护、可选字段空值行为）；surface 测试（暴露、可用性、带 `within` 作用域的 actor 识别、上下文作用域、关联导航）；契约测试（签名满足、`@invariant` 遵守、`demands`/`fulfils` 方向）；跨模块测试（限定实体引用、外部触发器响应、类型占位符替换）；跨规则交互测试（重复创建防护、provides 可用性）；转换图测试（每条声明边可通过其见证规则到达、未声明转换被拒绝、终态无出边规则、非终态至少一个出口、枚举值与图边精确对应）；状态相关字段测试（处于合格状态时存在、状态外时缺失、进入 `when` 集合时的存在义务、离开时的缺失义务、在集合内或集合外移动时无义务、收敛转换都设置该字段、访问 `when` 限定字段需要守卫、通过输入交集推断派生值 `when`）；场景测试（happy path、边界情况、顺序无关性）；数据流链测试（对每条链（surface 提供触发器 → 规则确保字段 → 下游规则要求字段）生成集成测试，通过 surface 提交数据并验证其到达下游前置条件）；可达性测试（从每个初始状态（经 `.created()`）沿转换图中的有效路径走到每个终态，每个测试覆盖完整生命周期）；死锁场景测试（对 `allium analyse` 识别出潜在死锁的状态，生成测试把实体置于卡住状态并验证能否推进）；跨实体流程测试（对跨多个实体的流程，生成覆盖所有参与实体从开始到终态的完整流程的集成测试）。
5. 若 `allium analyse` 可用，用其结果优先排序测试生成：`missing_producer` 或 `dead_transition` 发现表示值得用测试检验的缺口；`deadlock` 发现应生成记录实体无法逃离卡住状态的测试；查阅 references/actioning-findings.md 了解发现类型分类法。
6. 按义务性质选择测试输出类型：确定性义务（字段存在性、枚举成员、转换有效性、surface 暴露、状态相关字段存在与缺失）用断言式测试；不变式和规则属性用属性测试（PBT），每个含表达式的不变式成为一个 PBT 属性——用生成器规格生成有效实体状态，应用规则序列（有转换图时按图，否则仅从规则推导有效序列），在每一步检查不变式成立；有状态枚举的实体用状态机测试。
7. 使用项目已有的 PBT 框架：TypeScript 用 fast-check（查 `package.json`）、Python 用 Hypothesis（查 `pyproject.toml`）、Rust 用 proptest（查 `Cargo.toml`）、Go 用 rapid（查 `go.mod`）、Elixir 用 StreamData（查 `mix.exs`）；若项目没有 PBT 框架则回退到断言式测试。
8. 构建状态机测试所需的 action map：对转换图中每条边，在规格中找到见证规则；找到实现该规则的代码（实现桥接）；编写测试动作，设置前置条件（`requires` 子句）、调用代码、返回目标状态实体；以 `(from_state, to_state)` 为键注册该动作。有了 action map 后，PBT 框架可随机走有效路径：从任意非终态开始，随机选一条出边，应用其动作，检查所有实体级不变式，重复；路径长度和起始状态随机生成。
9. 建立实现桥接：surface 测试中把 surface 映射到实现（API surface 映射到端点如 REST 路由、GraphQL resolver、gRPC 服务；UI surface 映射到组件或页面；集成 surface 映射到消息处理器或 SDK 方法），通过阅读代码库、查找命名模式、路由定义和处理器注册来发现映射。
10. 内部测试中，对规格中每条规则：找到实现该规则的代码（服务方法、事件处理器、状态机转换）；确定如何实例化涉及的实体（工厂、builder、fixture）；确定如何调用该规则（API 调用、方法调用、事件派发）；确定如何断言后置条件（数据库查询、返回值、事件断言）。
11. 时序测试前，检查组件是否接受注入的时钟或时间参数（构造函数上的 `Clock` 参数、方法上的 epoch 毫秒参数、`TimeProvider` 接口）；若存在该接缝则注入可控时间源；若不存在，标记为测试基础设施缺口——在组件支持时间注入前无法生成时序测试；不要试图用 sleep 或与墙钟时间赛跑来测试时序行为。
12. 跨模块触发器链测试前：从 plan 输出追踪触发器发射图（哪些规则发射触发器、其他规格中哪些规则接收）；检查代码库是否已有连接参与组件的集成测试 fixture（流水线测试、端到端测试辅助、测试 harness 类）；若 fixture 存在则复用，跨模块测试应组合已有接线而非重建；若无 fixture 但代码库结构足够清晰（服务构造函数、依赖注入、事件总线配置），生成 fixture 和测试；若接线过于复杂或不透明，生成带 TODO 标记组件接线位置的测试骨架。
13. 探索代码库时记录哪些规格义务已被现有测试覆盖；当现有测试覆盖某义务时引用它而非生成重复测试；propagate 在集成层面的价值是核对覆盖率是否完整、识别缺口并生成测试填补缺口。
14. 对延迟规格（deferred specs）：当目标代码库不包含延迟规格的模块时，生成带占位符的测试桩，例如 `// TODO: deferred spec — InterviewerMatching.suggest` 并注明该行为被指定为延迟，提供 mock 或跳过。
15. 按流程执行：读规格（理解实体、规则、surface、不变式、转换图、状态相关字段、契约、配置、默认值；读 references/assessing-specs.md 评估规格成熟度；若规格过于粗糙（只有实体和转换图而无规则）则建议先用 `elicit` 或 `distill` 技能完善再传播测试）；读测试义务（来自 `allium plan` 输出或手动推导）；读领域模型（来自 `allium model` 输出或手动推导）；探索代码库（现有测试、测试框架、实体实现、规则实现）；把构造映射到代码（关联规格实体/规则/surface 与实现类/函数/端点）；生成测试（按项目约定生成测试文件）；验证测试可编译/运行；核对义务（确认每个义务映射到覆盖它的测试，并自动补齐缺口）。
16. 生成测试前完成发现清单：测试框架与运行器（Jest、pytest、cargo test 等）；PBT 框架（若有：fast-check、Hypothesis、proptest 等）；测试文件位置约定（同目录、`__tests__/`、`tests/` 等）；实体/模型位置与模式（类、接口、结构体）；测试数据的工厂/fixture 模式；状态转换的实现方式（方法、事件、状态机）；surface 的实现方式（路由、控制器、resolver）；现有测试辅助或工具；组件是否接受注入的时间源以支持时序测试；是否存在用于跨模块触发器链的集成测试 fixture；哪些规格义务已被现有测试覆盖。
17. 利用生成器规格产生有效测试数据：遵守字段类型和约束；对有转换图的实体，生成处于特定生命周期状态且字段存在性符合 `when` 子句的实体（例如 `shipped` 的 Order 有 `tracking_number` 和 `shipped_at`，`pending` 的 Order 没有）；对不变式，生成能检验边界条件的状态；对配置参数，除非测试覆盖否则使用声明的默认值。
18. 生成测试后执行义务核对：遍历完整义务列表（来自 `allium plan` 输出或手动推导），把每个义务映射到覆盖它的测试（本次生成或已有）；核对过程保持静默——义务是内部工作数据，一切正常时不要叙述映射、打印义务列表或展示覆盖率报告。
19. 对没有覆盖测试的义务尝试覆盖：生成缺失测试，或扩展部分覆盖它的现有测试；验证新测试可编译并运行；对照结果重新检查该义务。这是个小循环，需要与外部 Allium 循环相同的守卫：尝试上限——每个义务最多 2 次尝试，第二次仍未产生覆盖它的可编译测试则搁置该义务；无进展上限——若对剩余缺口完整走一遍没有覆盖任何新内容则停止，继续走会空转。
20. 守卫触发时仍未覆盖的义务是核对中唯一让用户看到的部分；对每个报告分类和一行原因：基础设施缺口（测试需要代码未提供的接缝，如时序义务无可注入时钟、跨模块链无集成 fixture）；无法映射的构造（在 code-first 流程中，没有实现代码与规格构造关联，实现桥接无法建立）。缺失实现不是残留类别：在 spec-first 流程中按设计尚无代码，应针对预期接口编写测试并让它失败——失败的测试覆盖其义务，循环的 implement 阶段会把它变绿；只有当完全无法编写测试时义务才算未覆盖。
21. 以单行摘要收尾：`N obligations, M covered, K uncovered`；全部覆盖时这一行就是核对面向用户的全部输出；对单个义务保持沉默意味着它已覆盖，任何被逐项列出的都需要人工决策；在 Allium 循环内运行时，这一行汇入循环的合并摘要，且只要义务未覆盖且无报告原因，循环就不得视规格为已收敛。
22. 在循环内运行时记录篡改基线：在 ledger（`.allium-loop/<goal-slug>.json`）中，把每个生成的测试文件的内容哈希（如 sha256）按路径写入 `generated_test_hashes`，并把核对摘要行记入 `reconciliation`；该哈希是 `witness` 技能重新推导的基准事实——生成的测试若在无中间 propagate 运行的情况下哈希变化，即为手工编辑的测试，是循环绝不能带着收敛的反作弊违规；这是廉价记账而非报告，不要叙述它。
23. 作为 Allium 循环内的 `propagate` 子代理运行时，只返回一个符合 propagate-result.schema.json 的 JSON 对象，不返回其他内容；循环依据结构化字段路由：`obligations` 和 `uncovered_obligations` 决定覆盖是否完整（`uncovered_obligations` 非空时循环不得收敛），`generated_tests` 携带 witness 重新推导的路径与哈希基线；`summary` 字段保持 `N obligations, M covered, K uncovered` 一行；每个字段都要输出，空列表用 `[]`，不要省略；交互运行时摘要行仍是面向用户的全部输出，类型化记录用于机器交接而非对话。
24. 与其他工具协作：`distill` 从代码产生规格，其规格喂给 propagate；`weed` 检查对齐，传播测试后由 weed 验证规格与代码匹配；`tend` 演进规格，规格变更后再次运行 propagate 更新测试；`elicit` 通过对话构建规格，规格就绪后 propagate 生成测试。

适用边界 · 注意事项

• 规格过于粗糙（例如只有实体和转换图而无规则）时，只能产生有限的结构性测试义务，应先使用 `elicit` 或 `distill` 技能完善规格再传播测试。
• 实现使用墙钟时间（`Instant.now()`、`System.currentTimeMillis()`）且组件没有可注入时钟或时间参数时，无法可靠生成时序测试，应标记为测试基础设施缺口而非用 sleep 或竞速方式测试。
• 跨模块触发器链的组件接线过于复杂或不透明、无法自信生成时，只能生成带 TODO 的测试骨架，需人工完成接线。