cognitive-os / rules

---
description: 认知结构写保护规则：写入L1/L1.5文档时，强制执行历史备份+归因标注+级联写入（变更记录+L0更新+系统日志）。当任务涉及修改 cognitive/L1_ 或 cognitive/L1.5_ 目录下的文件时自动激活。
globs:
alwaysApply: false
---

# 认知结构写保护规则（Cognitive Structure Write Guard）

## 核心原则

**写入L1或L1.5文档，不是一个简单的文件修改操作，而是对「系统唯一真相」的变更，必须完整执行下面的流程。**

---

## 触发条件

当 AI 准备对以下路径中的文件执行 Write 操作时，本规则强制生效：
- `cognitive/L1_knowledge/` 下的任何 `.md` 文件
- `cognitive/L1.5_principles/principles.md`

**⚠️ 写入前路径合法性检查（新增，2026-03-20）**：

在执行任何写入之前，先验证路径：
1. 目标路径是否在 `cognitive/` 的合法子目录内？
   - 合法：`L1_系统性文档/[维度]/`、`L1.5_底层原则层/`、`L2_碎片化思考/`、`L3_原始记录/`、`[维度]/知识库/`
   - **不合法（常见错误路径）**：`projects/`、`work/`、工作区根目录下的其他非 `cognitive/` 目录
2. 若路径不合法 → **立即停止写入**，提示：
   「⚠️ 路径合法性检查失败：[目标路径] 不在认知结构合法目录内。请确认是否应该写入认知结构，或选择正确的路径（项目目录或其他工作目录）」

**例外（不触发本规则）**：
- `cognitive/L1_knowledge/[任意维度]/知识库/` 路径下的文件
  → 这些是 REF-EXT 外部参考知识，遵循「维护协议_自洽规范.md → 新增REF-EXT文档时」规则，无需版本快照/归因标注/L0更新
  → 本规则的强制5步骤**不适用于知识库/目录**

---

## 强制执行流程（不可跳过任何一步）

### 写入前

**检查1：版本快照与变更记录**

**第一次写入该文档（文档刚迁入认知结构）：**
→ 创建 v1.0 快照：`历史版本/[文档名]_v1.0_YYYYMMDD.md`
→ 新建 `[文档名]_变更记录.md`（记录 v1.0 的建立时间和背景）

**非第一次写入（文档已有 x.0 快照）：**
→ 判断此次修改是否为「重大变更」（核心论点变化/结构重组）：
  - 是重大变更 → 先创建新的 x.0 快照（v2.0/v3.0...），再修改
  - 是增量修改 → 直接修改，修改完成后必须在变更记录中追加一条
→ 不允许跳过记录直接修改

**检查2：归因标注**
- 写入的内容必须包含归因标记：
  - 🔵 = 用户原始思考（用户直接说的内容）
  - 🟢 = AI整理（AI对用户思考的结构化提炼）
  - 🟡 = AI生成（AI基于已有文档推导的新内容）
- 如果 AI 发现自己准备写入的内容没有归因标记，**先标注再写入**

### 写入后（并行执行，顺序不限，但全部必须完成）

**强制1：追加变更记录**
查找或新建 `[文档名]_变更记录.md`（与文档同目录），追加一条：
```
## [YYYY-MM-DD] [操作类型]
**修改位置**：[章节]
**修改摘要**：[一句话]
**归因**：[🔵/🟢/🟡]
**触发来源**：[用户指令 | Skill名称 | 矛盾消解]
```

**强制2：更新L0大脑总地图（必须同步 L0 内所有计数引用）**
- Write: `cognitive/L0_brain_map.md`
- 更新该文档的「最后更新时间」字段
- 如果本次修改修复了某个 Gap，更新 Gap 状态为 ✅
- ⚠️ 若新增了 L1 文档，必须同步更新以下所有位置（不允许只改其中一处）：
  ① 框架关系图（ASCII art）中的维度篇数标注
  ② 目录树区段中的维度篇数标注（如「产品理论维度/（5篇）」）
  ③ L1 总计数标注（如「L1_系统性文档/（18篇，6个维度）」）
  ④ 知识图谱版本引用（如「知识图谱_正式文档.md（v1.2，18节点22边）」）

**强制3：追加系统日志**
- Write: `cognitive/L3_logs/system_log.md`（append-only）
- 格式：`[LOG-YYYYMMDD-NN] [Skill名称 | 直接修改] | [操作摘要] | [文档名]`

**强制4：更新文档分类清单（迁移操作时必须执行）**
- 触发条件：当操作是「将文档从原始位置复制/迁移到认知结构」时
- Write: `cognitive/document_catalog.md`
- 将该文档的状态从 `◑ PENDING` 更新为 `★ CURRENT`，并注明认知结构中的实际路径
- **不允许跳过**：迁移后分类清单状态不更新 = C5 违规，必须立即修复

**强制5：更新知识图谱（新增 L1 文档时必须执行）**
- 触发条件：当操作是「新建一篇 L1 文档（首次写入）」时
- Write: `cognitive/knowledge_graph.md`
- 在「三、文档定位总表」的 L1 表格中追加一行（文档ID / 简称 / 聚类 / 核心主张 / 认知结构位置）
- 在「二、完整关系边图」中追加新文档与现有文档的关系边（至少1条）
- 更新文件末尾的「图谱版本行」（更新篇数计数 + 关系边计数）
- **不允许跳过**：新增 L1 文档后知识图谱未更新 = C3 违规，必须立即修复

---

## 违规场景（如果 AI 准备跳过，必须停下来）

- ❌ 直接修改L1文档而没有先看是否需要备份
- ❌ 写入了🟡 AI生成的内容而没有标注
- ❌ 写入后没有追加变更记录
- ❌ 写入后没有更新L0
- ❌ 写入后没有追加系统日志
- ❌ **新建L1文档后没有更新知识图谱**（C3违规，导致图谱与实际文档数不一致）

如果 AI 发现自己正在跳过任何一步，立即停止，先补完前置步骤，再继续。

---

## 变更记录

### 2026-03-19 — 新增「知识库/目录」例外条款

**根因**：新建 `research-output` Skill 后，关卡B发现：write-guard 触发条件覆盖 `L1_系统性文档/[维度]/知识库/` 路径，导致 REF-EXT 文件写入时被 write-guard 拦截，要求做版本快照/归因标注/L0更新，与 REF-EXT 规范（维护协议明确不需要这些操作）直接冲突，AI 收到矛盾指令。

**修改内容**：
- 新增：「触发条件」中的例外条款——`知识库/` 路径下的文件不触发本规则，遵循 REF-EXT 规范

**验证结果**：
- 正向：写 `知识库/file.md` 时 write-guard 不触发，不要求版本快照
- 负向：写 `认知科学基础维度/human_cognition_loops.md`（L1正式文档）时 write-guard 正常触发

### 2026-03-19 — 加入强制5：新增L1文档时必须更新知识图谱

**根因**：用户发现新建「三大闭环架构」L1文档后，知识图谱未更新。排查发现规则只有4个强制步骤，遗漏了知识图谱更新（该义务仅在C3一致性检查中被动发现，缺乏主动写入约束）。

**修改内容**：
- 新增「强制5：更新知识图谱」——触发条件为新建L1文档，要求追加L1表格一行、关系边至少1条、更新版本计数行

**验证结果**：
- 正向验证：下次新建L1文档时，AI应在完成L0/系统日志更新后，同时更新知识图谱
- 负向验证：修改已有L1文档（不新建）时，不触发强制5，减少无意义的图谱变更