Loom converge

After implementation and before final verification, compare current code/tests against the intent inventory (requirements.json + traceability.json). Classify each requirement/behavior as covered, missing, partial, contradicts, or unrequested. Append missing/partial/contradicts as new tasks back to executing. Repeat until converged: zero blocker findings. Outputs convergence-report.json. Use when: executing produced test-report.md but before loom-verification-before-completion.From its SKILL.md

Install

npx -y skills add xiqin/loom --skill loom-converge

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.1 KB, as published. Nobody here has run it

收敛（converge）

触发条件

executing 阶段已产出 test-report.md 且 verdict 为 PASS。
即将进入 verification，但尚未把代码事实对照意图清单做收敛。
requirements.json 与 traceability.json 存在。

非触发条件

test-report.md 仍为 FAIL 或未产出。
quickfix / chore 等无 spec 的流程。

执行流程

Step 1：运行收敛

调用 loom MCP 工具 loom_converge（参数 spec_dir、round）。

工具读取 requirements.json、traceability.json，对每个 behavior 分类为 covered/missing/partial/contradicts/unrequested，输出 convergence-report.json。返回 ok:false 表示有 blocker（missing/contradicts），需要回流 executing。

说明：scripts/converge.mjs 是该工具的实现，运行在 loom MCP 服务器进程内。不要在用户项目里用 node skills/... 调用（部署后路径会断裂）。

Step 2：逐 behavior 分类

对每个 REQ-xxx-Bnn behavior，依据 traceability.json 的 tests/evidence 与实际代码/测试文件，分类为：

covered：tests 引用真实存在的测试文件，且 evidence 引用真实日志，且 behavior 的 acceptance 被测试覆盖。
missing：traceability 中无 tests 或 evidence，或引用文件不存在。
partial：有 tests 但未覆盖 acceptance 全部分支（例如只测 happy-path，未测 invalid-input）。
contradicts：实现与 spec/requirements 描述冲突，或测试断言与 acceptance 相反。
unrequested：代码中实现了 requirements.json 没有声明的行为或公开 API 变更。

Step 3：生成 findings

每个 missing / partial / contradicts / unrequested 生成一条 finding：

{
  "id": "F-conv-001",
  "kind": "missing",
  "severity": "blocker",
  "message": "REQ-001-B03 (authorization) has no test reference in traceability.json",
  "requirement_id": "REQ-001",
  "behavior_id": "REQ-001-B03",
  "artifact": "traceability.json",
  "suggested_fix": { "action": "create_task", "details": "add task T2 to implement authorization test for REQ-001-B03" }
}

Step 4：追加新 task 回流

对所有 missing / partial / contradicts，生成新 task 文件 tasks/T*.md，frontmatter 包含：

requirements: 对应 REQ-xxx
behavior_ids: 对应 REQ-xxx-Bnn
owns: 建议修改的文件（从 finding 的 location 或现有代码推断）
depends_on: 依赖的原 task

把新 task 追加到 plan.md 的 task 表。更新 traceability.json 把新 task 加入对应 behavior 的 tasks。

Step 5：更新 `convergence-report.json`

{
  "stage": "converge",
  "round": 1,
  "status": "converged|needs_another_round",
  "classification": {
    "REQ-001-B01": "covered",
    "REQ-001-B02": "covered",
    "REQ-001-B03": "missing"
  },
  "findings": ["..."],
  "new_tasks": ["T2", "T3"],
  "coverage": {
    "behavior_coverage": "67%",
    "acceptance_coverage": "55%"
  },
  "created_at": "2026-07-20T18:30:00Z"
}

Step 6：回流判定

若存在任何 blocker finding（missing / contradicts）：状态为 needs_another_round，状态机不允许进入 verification；回到 executing 处理新 task。
若只有 partial 且用户显式接受：可标记 accepted_partial 并进入 verification，但必须在报告中记录。
若全部 covered 且无 unrequested blocker：状态为 converged，允许进入 verification。

Step 7：迭代

回到 executing 实现新 task 后，重新运行 loom-converge。每轮 round 递增。建议最多 3 轮；超过 3 轮未收敛时 escalate。

产物根目录

convergence-report.json 写入 specs/<date+feature>/。新 task 写入 specs/<date+feature>/tasks/。

约束

不得删除或修改 requirements.json 中已确认的 behavior；只能追加 task。
不得用"代码看起来覆盖了"作为 covered 判定；必须有 tests + evidence 引用真实文件。
unrequested 若涉及必要的基础设施或重构，可降级为 info，但必须在报告中说明。
每轮 converge 必须记录 round 号与 findings 变化，便于审计。
新 task 不得复用已有 T 号；递增分配。

完成条件

convergence-report.json 状态为 converged，无 blocker findings。
所有 behavior 分类为 covered 或显式接受的 partial。
无 contradicts 残留。
handoff 记录收敛轮次与最终 coverage。