document-reference-guard

文档引用留痕与级联更新规则（document-reference-guard）

设计依据：F-033（引用留痕）+ F-034（引用级联更新），2026-03-20 核心原则：依赖可追溯，变动必传播。

---

触发条件

以下任一情况触发本规则：

场景A：新引用一个文档

• AI 在 Skill/Rule/文档中写下某个文件路径并引用其内容
• 例：role-后端开发 Step 1 新增「Read: 某个新文档.md」

场景B：被引用的文档发生变动

• 移动路径（迁移到其他目录）
• 更新内容（重大修改，如新增章节/更改格式要求）
• 版本化（创建 v2.0，旧版归档）
• 归档（移到 history/ 目录）

---

激活后执行

场景A：新引用一个文档

Step 1  在被引用的文档末尾，追加或更新 ## 引用记录 节：
        格式：
        ## 引用记录
        | 引用方路径 | 引用位置（章节/步骤）| 引用日期 | 引用用途 |
        |---|---|---|---|
        | .cursor/skills/role-后端开发/SKILL.md | Step 1 | 2026-03-20 | 读取技术架构 |

Step 2  若被引用文档不存在 ## 引用记录 节，自动创建（在文件末尾追加）
Step 3  告知用户：「✅ 引用留痕已更新：[文档路径] 的引用记录已追加」

场景B：被引用文档发生变动

Step 1  读取该文档的 ## 引用记录 节（若不存在，跳到 Step 4）
Step 2  列出所有引用方：
        「此文档被以下位置引用，变动后需要同步更新：
         - [引用方1]（[引用位置]）
         - [引用方2]（[引用位置]）」
Step 3  对每个引用方：
        IF AI 可以自动更新（路径变更/文件名变更）→ 直接更新，告知用户
        IF 需要人工判断（内容语义变化）→ 标注「⚠️ 需人工确认是否需要更新引用方」
Step 4  若无引用记录节 → 告知用户：
        「此文档没有引用记录，无法自动追踪引用方。建议手动检查是否有其他文件引用了它。」

---

引用记录节格式（模板）

被引用文档的末尾应包含此节：

## 引用记录

> 本节由 document-reference-guard 规则自动维护
> 最后更新：YYYY-MM-DD

| 引用方路径 | 引用位置 | 引用日期 | 引用用途 | 状态 |
|---|---|---|---|---|
| .cursor/skills/[Skill名]/SKILL.md | Step N | YYYY-MM-DD | [用途说明] | ✅ 有效 |

---

与现有体系的关系

现有组件	关系
cognitive-update-knowledge Step 6	本规则补充：Step 6 更新「联动文档」，本规则追加「反向引用方更新」
RULE-04（创建文件时声明关联关系）	本规则补充：RULE-04 是「单向出向声明」，本规则补充「双向引用追踪」
cognitive-structure-write-guard	并列：写 L1 文档时两个规则都会激活，互不冲突

---

变更记录

v1.0 — 2026-03-20 — 初始创建

根因：用户 20260320 提出 F-033（引用留痕）+ F-034（引用级联更新）原则，当前体系任何文档被引用/变动都不会触发级联检查，导致长期积累引用断链。文档被移动后，引用方如 Skills 里的 Read 路径会失效但无法感知。

设计决策：

• 约束类型：场景触发（非 alwaysApply），避免每次对话都执行此检查
• 触发时机：只在「发生引用行为」或「引用的文档变动」时激活
• 实现策略：渐进式——先从高频引用文档（写作手册/公共模块注册表等）开始补录 ## 引用记录 节

验证状态：🔵 待验证（下次文档引用/移动时验证）