| name | loom-analyze-artifacts |
| description | Read-only cross-artifact consistency analysis after planning and before approval. Verifies that spec.md, requirements.json, plan.md, tasks/Tn.md, traceability.json are mutually consistent: no duplicate/ambiguous requirements, every behavior mapped to a task, no orphan tasks, no coverage gaps, no contradictions. Outputs artifact-analysis.json with coverage% and severity. CRITICAL/HIGH findings block the approval gate. Use when: planning produced plan.md + tasks + traceability.json, before the user approves the plan.
|
| when_to_use | After loom-writing-plans produces plan.md and traceability.json, before the approved gate. |
| argument-hint | <spec directory containing spec.md, requirements.json, plan.md, tasks/, traceability.json> |
| user-invocable | true |
跨产物一致性分析（analyze-artifacts）
触发条件
specs/<date+feature>/plan.md、tasks/、traceability.json、requirements.json、spec.md 均已存在。- 即将进入
approved gate，但还没人做过跨产物一致性检查。
非触发条件
- quickfix / chore / hotfix 等无 spec/plan 的轻量流程。
- 已在 verification 阶段（那时改用
loom-converge）。
执行流程
Step 1：运行分析
调用 loom MCP 工具 loom_analyze_artifacts（参数 spec_dir）。
工具只读分析 spec.md、requirements.json、plan.md、tasks/T*.md、traceability.json、.loom/rules/constitution.md（若存在），执行下列检查并输出 artifact-analysis.json。返回 ok:false 表示有 blocker finding。
Step 2：跨产物一致性检查
按以下维度逐项检查，每条 finding 记录 { id, kind, severity, message, requirement_id?, behavior_id?, task_id?, artifact, suggested_fix }。
- 重复需求：
spec.md 中两个 REQ-xxx 实际描述同一行为。
- 歧义需求：
spec.md 有两种解释且未选定一种。
- 欠规格：
requirements.json 缺少 spec 中的 REQ-xxx，或某 REQ 的 required_categories 未覆盖。
- behavior 缺失：
requirements.json 的 required_categories 没有 behavior 实现。
- task 未映射：
plan.md 引用的 task 文件不存在，或 tasks/ 中文件未在 plan.md 列出。
- behavior 未映射到 task：
requirements.json 的某 behavior 在所有 task frontmatter behavior_ids 中都未出现。
- task 引用未知 behavior：task 的
behavior_ids 不在 requirements.json 中。
- task 引用未知 requirement：task 的
requirements 不在 spec.md 中。
- traceability 缺 REQ/behavior：
traceability.json 缺少 spec.md / requirements.json 中的 REQ 或 behavior。
- traceability 引用未知 REQ/behavior：
traceability.json 出现 requirements.json 没有的 REQ/behavior。
- traceability task 引用不存在：
traceability.json 的 tasks 不对应真实 tasks/T*.md。
- 依赖环：task
depends_on 构成环。
- owns 冲突：多个 task 声明同一
owns 文件。
- constitution 冲突：task 计划修改的路径与
.loom/rules/constitution.md 的分层/禁止目录冲突。
- 非功能要求遗漏：
requirements.json 声明 performance / security / observability 类型，但没有任何 task 或 behavior 覆盖对应维度。
Step 3：计算 coverage
{
"requirement_coverage": "已映射 task 的 REQ 数 / spec REQ 总数",
"behavior_coverage": "已映射 task 的 behavior 数 / requirements behavior 总数",
"required_category_coverage": "已覆盖的 required_categories 数 / 声明总数",
"traceability_req_coverage": "traceability 中 REQ 数 / requirements REQ 数",
"traceability_behavior_coverage": "traceability 中 behavior 数 / requirements behavior 数"
}
Step 4：severity 分级
blocker：缺 REQ/behavior 映射、依赖环、traceability 缺 REQ、task 引用未知 behavior、constitution 冲突。error：歧义、owns 冲突、traceability task 引用不存在、非功能要求遗漏。warning：重复描述、欠规格但已部分覆盖。info：建议改进，不阻断。
Step 5：输出 artifact-analysis.json
{
"stage": "analyze-artifacts",
"status": "pass|blocked",
"coverage": {
"requirement_coverage": "100%",
"behavior_coverage": "92%",
"required_category_coverage": "88%",
"traceability_req_coverage": "100%",
"traceability_behavior_coverage": "92%"
},
"findings": [
{
"id": "F-001",
"kind": "missing",
"severity": "blocker",
"message": "requirements.json REQ-003 required category authorization has no behavior",
"requirement_id": "REQ-003",
"artifact": "requirements.json",
"suggested_fix": {
"action": "update_requirement",
"details": "add REQ-003-B03 with category authorization"
}
}
],
"created_at": "2026-07-20T18:00:00Z"
}
Step 6：阻断规则
- 任何
blocker finding：状态为 blocked，状态机不允许进入 approved。
- 任何
error finding：默认阻断，但用户可在分析报告中显式 override（写入 overrides 字段并附理由）。
warning / info：不阻断，但必须在 handoff 中记录。
产物根目录
artifact-analysis.json 写入 specs/<date+feature>/。
约束
- 只读分析，不修改 spec/plan/tasks/traceability/requirements。
- 不 invent 新 task；只报告问题。
- 发现的问题由用户或
loom-writing-plans 修复后重新分析，直到无 blocker。
- 不得用"看起来 OK"作为结论；每项检查必须有明确 pass/fail。
完成条件
- 产出
specs/<date+feature>/artifact-analysis.json。
- coverage 字段全部填写。
- 所有 blocker findings 已被处理或显式 override。
- handoff 记录分析结果。
