loom-detail-expansion

行为义务展开（detail-expansion）

触发条件

• specs/<date+feature>/spec.md 与 specs/<date+feature>/requirements.json 已存在并经用户批准。
• requirements.json 中某些 REQ 的 behaviors 仍为默认 REQ-xxx-B01（happy-path 占位），未按需求 types 覆盖全部必需维度。
• 即将进入 loom-writing-plans，需要先把每个 REQ 拆成可独立验证、可分配到 task 的行为义务。

非触发条件

• requirements.json 已显式覆盖每个 REQ 的所有 required_categories，且每个 behavior 都有具体 description 与 acceptance。
• quickfix / chore / hotfix 等无 spec 的轻量流程。

执行流程

Step 0：运行校验

调用 loom MCP 工具 loom_detail_expansion_check（参数 spec_dir）。

工具会读取 requirements.json，对每个 REQ 检查：所有 required_categories 都有对应 behavior、每个 behavior 有 test_plan、无 requires-clarification 残留、description 非占位文案。返回 ok:false 表示有缺口需要补齐。

说明：scripts/check-detail-expansion.mjs 是该工具的实现，运行在 loom MCP 服务器进程内，可直接 import loom 仓库的 core 模块。不要在用户项目里用 node skills/... 调用（部署后路径会断裂）。

Step 1：读取现有账本

读取 specs/<date+feature>/spec.md、specs/<date+feature>/requirements.json、必要时的 specs/<date+feature>/handoffs/brainstorming.json。禁止重新展开用户已显式确定的 behavior；只补充缺失维度或细化占位 description。

Step 2：按需求类型确定必需维度

对每个 REQ，根据其 types 与 required_categories，合并出必须覆盖的 category 集合：

• functional → happy-path
• input → invalid-input
• authorization / auth → authorization
• write / mutation → atomicity
• state → state-transition
• idempotent → idempotency
• concurrent → concurrency
• external → external-failure
• security → security
• performance → performance
• observable → observability
• recovery → recovery
• forbidden-behavior：所有涉及写、权限、外部副作用或旧 API 的 REQ 都应额外考虑一个 forbidden-behavior 维度，用于"不应发生"的负空间。

Step 3：逐维度展开 Behavior Obligation

对每个必需维度，若 requirements.json 中没有对应 category 的 behavior，追加新的 REQ-xxx-Bnn：

• id：递增 Bnn，保持 REQ-xxx-Bnn 格式。
• category：固定维度之一。
• description：具体到可被代码实现与测试验证的单一行为。禁止"系统应正常"、"接口应稳定"等模糊描述。
• status：初始 failing。
• acceptance：可测量、可观察的验收项列表。每个 acceptance 必须可由一个或多个测试用例证明，例如：
  • 正常路径：输入 X 时返回 Y，状态 Z 为 W。
  • 边界：输入 N-1/0/N 时分别返回 A/B/C。
  • 幂等：同一请求重复调用 K 次，副作用计数为 1。
  • 失败回滚：外部依赖超时后，已写入的部分记录被回滚，数据库无脏数据。