loom-analyze-artifacts

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 }。

1. 重复需求：spec.md 中两个 REQ-xxx 实际描述同一行为。
2. 歧义需求：spec.md 有两种解释且未选定一种。
3. 欠规格：requirements.json 缺少 spec 中的 REQ-xxx，或某 REQ 的 required_categories 未覆盖。
4. behavior 缺失：requirements.json 的 required_categories 没有 behavior 实现。
5. task 未映射：plan.md 引用的 task 文件不存在，或 tasks/ 中文件未在 plan.md 列出。
6. behavior 未映射到 task：requirements.json 的某 behavior 在所有 task frontmatter behavior_ids 中都未出现。
7. task 引用未知 behavior：task 的 behavior_ids 不在 requirements.json 中。
8. task 引用未知 requirement：task 的 requirements 不在 spec.md 中。
9. traceability 缺 REQ/behavior：traceability.json 缺少 spec.md / requirements.json 中的 REQ 或 behavior。
10. traceability 引用未知 REQ/behavior：traceability.json 出现 requirements.json 没有的 REQ/behavior。
11. traceability task 引用不存在：traceability.json 的 tasks 不对应真实 tasks/T*.md。
12. 依赖环：task depends_on 构成环。
13. owns 冲突：多个 task 声明同一 owns 文件。
14. constitution 冲突：task 计划修改的路径与 .loom/rules/constitution.md 的分层/禁止目录冲突。
15. 非功能要求遗漏：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 记录分析结果。