pdlc-relate

name	pdlc-relate
description	管理 feature 关系链（set/query/impact/orphans/rebuild/validate）
argument-hint	<set|query|impact|orphans|rebuild|validate> [args]
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
layer	3
stage	ops
produces	["docs/.pdlc-state/_relations.json","docs/.pdlc-state/_graph.md"]
requires	[]
next_step	null
terminal_state	null

Feature 关系链管理

管理 PDLC feature 之间的关系链。维护反向索引 docs/.pdlc-state/_relations.json 和全局图 docs/.pdlc-state/_graph.md。

段一：执行子命令

从 $ARGUMENTS 解析子命令：

set <fid> <type> <target-fid> [target-fid...]

为 feature <fid> 添加 <type> 关系，指向一或多个目标。

1. 读 docs/.pdlc-state/<fid>.json；若无 relations 块（旧状态文件 / Phase 1 关系块可选），先初始化六类空块（extends/depends_on/supersedes/resolves/conflicts_with/relates_to），再在 relations.<type> 数组追加目标（去重）
2. 若 <type> 是对称类型（conflicts_with / relates_to）→ 同时在每个目标的 <fid>.json 镜像写入
3. 写回后调用本命令 rebuild 流程刷新 _relations.json + _graph.md

query <fid>

显示 <fid> 的全部关系（出边 + 从 _relations.json 读入边）。

impact <fid> ⭐ 杀手锏

分析改动 <fid> 的影响半径。读 _relations.json：

• 🔴 直接影响（depth 1 入边）：直接 extends / depends_on 本 feature 的，必须协调
• 🟡 间接影响（depth ≥2 传递入边）：通过中间 feature 传递依赖的，应 review
• 🟢 历史（指向 terminal-state feature 的边 / resolves 的缺陷）：仅审计 输出树状结构 + 建议（先 review 哪些 PRD / 是否该新建 supersedes feature 而非就地改）。

orphans

列出 _relations.json 中 inbound + outbound 均为空的 feature（可能是孤立 / 死代码候选）。

rebuild

扫描所有 docs/.pdlc-state/<id>.json 的 relations 块 + 文档追溯头的 关系: 行，重建：

• _relations.json：nodes（id→name/stage/terminal）+ edges（flat 有向列表）+ index（每节点预计算 inbound/outbound）
• _graph.md：mermaid 图，边样式按类型区分（supersedes 虚线 / conflicts_with 粗线 / 其余实线），顶部加 <!-- AUTO-GENERATED by /pdlc-relate · do not edit by hand -->

validate

按 relations.md 的校验规则检查：悬空引用 / 自引用 / extends·depends_on 成环 / 矛盾对 / 对称一致性。报告问题清单。

段二：自检（强制）

关系链自检清单

• _relations.json 是合法 JSON（jq . 通过）
• 所有 edge 的 from/to ID 在 nodes 中存在（无悬空）
• 对称类型（conflicts_with / relates_to）两端互含
• extends / depends_on 无环
• _graph.md 含 AUTO-GENERATED 头且 mermaid 语法成对闭合
• set 操作的目标 ID 格式合法（F/B 开头）

段三：修复（单次，不递归）

• 可自动修复（对称缺失补镜像 / index 不一致 → 重跑 rebuild）→ 直接修
• 无法自动修复（真实的循环依赖 / 用户意图矛盾）→ 记录到报告，提示人工介入

段四：交接

状态机豁免：本命令非 feature-scoped（不推进单个 feature 的阶段），不更新 <feature-id>.json 的 history，只维护关系索引文件。同 /pdlc-changelog。

本命令的 handoff 输出：

✅ 关系操作完成：<子命令> <参数>
📦 已更新：docs/.pdlc-state/_relations.json + _graph.md
👉 下一步：/pdlc-relate impact <fid> 查影响 | /pdlc-status 看全景

---

关系操作: $ARGUMENTS